File: READ.ME HSCTM2D Hydrodynamic, Sediment, and Contaminant Transport Model (2 Dimensions, Vertically Integrated) Version 1.01 U.S. EPA Release, November 1998 Center for Exposure Assessment Modeling (CEAM) National Exposure Research Lab - Ecosystems Research Division Office of Research and Development (ORD) U.S. Environmental Protection Agency (U.S. EPA) 960 College Station Road Athens, Georgia 30605-2700 706/355-8400 _________________________________________________________________ CONTENTS Introduction Abstract Documentation Distribution Diskettes File Name and Content Development System Routine Execution Run Time and Performance Minimum File Configuration Modification Technical Help Contact Disclaimer _________________________________________________________________ INTRODUCTION HSCTM2D is a finite element modeling system for simulating two-dimensional, vertically-integrated, surface water flow (typically riverine or estuarine hydrodynamics), sediment transport, and contaminant transport. The modeling system consists of two modules, one for hydrodynamic modeling (HYDRO2D) and the other for sediment and contaminant transport modeling (CS2D). One example problem is included. The HSCTM2D modeling system may be used to simulate both short term (less than 1 year) and long term scour and/or sedimentation rates, and contaminant transport and fate in vertically well mixed bodies of water. For a list of modifications to the HSCTM2D model system since its last release (version 1.00, June 1998), refer to the contents of files RELEASE.TXT and UPDATE.TXT (refer to FILE NAME AND CONTENT section). NOTE: For convenience, the terms "HSCTM2D model system" and "HSCTM2D" will be used in this document to refer to the HSCTM2D model and all associated support files and programs as a single unit. Therefore, the terms "HSCTM2D" and "HSCTM2D model system" are synonymous for purposes of this document. _________________________________________________________________ ABSTRACT Refer to file ABSTRACT.TXT for an abstract of the HSCTM2D model system (refer to FILE NAME AND CONTENT section). _________________________________________________________________ DOCUMENTATION It is recommended that the user obtain and reference the documents listed below to operate and apply the HSCTM2D model system. Copies of the following documents are included on the distribution diskettes and within the Internet distribution file INSTALHC.EXE. Refer to FILE NAME AND CONTENT and MINIMUM FILE CONFIGURATION sections for further information. Document Name(s) File Name(s) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~ HSCTM2D model system general execution and READ.ME user support guide HSCTM2D Model System Release Notes RELEASE.TXT HSCTM2D Model System Update Notes UPDATE.TXT (Enhancements/updates/additions not covered in user manual file) HSCTM2D Model System Abstract ABSTRACT.TXT CEAM Software Product User Response Form RESPONSE.TXT HSCTM2D Documentation and User's Manual USERMANU.PDF "HSCTM-2D, A Finite Element Model for Depth-averaged Hydrodynamics, Sediment and Contaminant Transport" NOTE: The files READ.ME and those ending in .TXT are ASCII text (non-binary) files that can be displayed on the monitor screen by using the DOS TYPE command (e.g., TYPE READ.ME) or printed using the DOS PRINT command (e.g., PRINT READ.ME). Files ending in PDF are Adobe(*) Acrobat(*) Portable Document Format (PDF) files. To view, print, and/or navigate a PDF document, a reader program must be installed on the users computer system. A free Adobe reader allows the user to view, navigate, and/or print PDF files across all major computing platforms. Acrobat Reader is a free viewing companion to Adobe Acrobat 3.0 and is available free from the Adobe world wide web (WWW) site at Uniform Resource Locator (URL) address: http://www.adobe.com. To ensure that the user can view and/or print a PDF file in its entirety, the user must down load and install the most recent version/edition of the free Acrobat Reader. PDF files can be viewed across multiple platforms (Mac, Microcomputer, UNIX) using the appropriate reader for that platform. * Adobe, Acrobat, and Adobe Type Manager are trademarks of Adobe Systems Incorporated and may be registered in certain jurisdictions. (C) Copyright 1994 Adobe Systems Incorporated. All rights reserved. These documents should be retained by the requester for reference. _________________________________________________________________ DISTRIBUTION DISKETTES NOTE: k=1,024; m=1,048,576; b=1 byte Included are 7, 3.5 inch (1.44mb, DS/HD) DOS (Disk Operating System) formatted diskettes containing the Hydrodynamic, Sediment, and Contaminant Transport Model (HSCTM2D, Version 1.01), U.S. EPA release, dated November 1998. This model system is designed for the IBM PC family of microcomputer or compatible systems running under version 3.30 or higher of the Microsoft or PC Disk Operating Systems (PC or MS DOS--refer to DEVELOPMENT SYSTEM section). Properly configured, this model system and its support files and programs can be executed under PC DOS; MS DOS 3.30 and later versions, DOS 4.0x, DOS 5.0x, or DOS 6.x; a DOS window or a DOS level system start up (i.e., boot) under Microsoft Windows 3.1x, Microsoft Windows for WorkGroups, Windows 95, or NT operating systems. To install the HSCTM2D model system and/or related support files and programs on a hard disk, insert the first distribution diskette in a compatible diskette drive. Type A:\INSTALL or B:\INSTALL at the DOS system prompt and press the key. Then follow instructions and respond to the prompts presented on the monitor screen by the interactive installation program. This is a compressed, self-extracting, interactive installation program-- with on-line, context sensitive help--that contains the HSCTM2D model system (HSCTM2D, Version 1.01), dated November 1998. NOTE: If the HSCTM2D model system is being installed from the HSCTM2D installation file (INSTALHC.EXE) down loaded from the Internet, then the user should type INSTALHC at the DOS system prompt and press the key. This command assumes that the current default drive and sub-directory is the same drive and sub-directory that contain the file INSTALHC.EXE. For further information and to access CEAM software products through the Internet, refer to the TECHNICAL HELP CONTACT section. NOTE: The content of the distribution diskettes can be copied to another set of "backup" diskettes using the DOS DISKCOPY command. Refer to the DOS Reference Manual or on-line help for command application and use. The "backup" diskettes must be the same size and storage density as the original source diskettes. The following FILE NAME AND CONTENT section provides a brief functional description of each file by name or file name extension type. Other sections in this document contain information about o system development tools used to build the microcomputer release of the HSCTM2D model system o recommended hardware and software configuration for the execution of the model system and all support programs o program execution o sample run time o minimum file configuration o program modification o technical support _________________________________________________________________ FILE NAME AND CONTENT The self-extracting, interactive, installation executable program file exists in a compressed format to save disk space and file transfer time. This document contains a description of each file that can be decompressed from the compressed distribution diskettes and/or file. Follow the instructions shown on the interactive installation program screens and menus to install, decompress (extract), and restore file(s) to their original name and size in order to place the HSCTM2D model system in a usable format on a hard or virtual disk. For comparison purposes, the original date and time of creation are also restored with each file. NOTE: Execution of the INSTALL or INSTALHC command can extract one or more HSCTM2D model system files. These files are automatically stored into DOS sub-directories on the hard disk. The hard disk and sub-directory structure, under which the sub-directories shown below are stored, is selected (e.g., C:\HSCTM2D) by the user during execution of the INSTALL or INSTALHC program. The string "InstallationDirectory" will be used to denote the highest level default installation directory structure chosen by the user during execution of INSTALL or INSTALHC. Below the installation directory, all files are grouped and listed by the appropriate DOS sub-directory name into which they will be automatically stored. ** Sub-directory InstallationDirectory\README: NOTE: The following files are ASCII text (non-binary) files that can be displayed on the monitor screen with the DOS TYPE command or printed using the DOS PRINT command. READ.ME - HSCTM2D model system execution and general support guide. RELEASE.TXT - Summary of corrections and/or changes between release versions. UPDATE.TXT - Summary of enhancements, updates, and additions not covered in the current user's manual. ABSTRACT.TXT - HSCTM2D Model System Abstract. RESPONSE.TXT - CEAM Software Product User Response Form. ** Sub-directory InstallationDirectory\DOCUMENT NOTE: The file described within this section is NOT required to execute and/or test any model, program, or associated run time support file as provided on the distribution diskettes or the Internet installation file. For further information, refer to the MINIMUM FILE CONFIGURATION section. NOTE: The following file is the HSCTM2D Users' Manual file. The complete documentation is contained within the following binary, non-ASCII file: USERMANU.PDF This file is an Adobe(*) Acrobat(*) Portable Document Format (PDF) file. To view, print, and/or navigate a PDF document, a reader program must be installed on the users computer system. A free Adobe reader allows the user to view, navigate, and/or print PDF files across all major computing platforms. Acrobat Reader is a free viewing companion to Adobe Acrobat 3.0 and is available free from the Adobe world wide web (WWW) site at Uniform Resource Locator (URL) address: http://www.adobe.com. To ensure that the user can view and/or print a PDF file in its entirety, the user must down load and install the most recent version/edition of the free Acrobat Reader. PDF files can be viewed across multiple platforms (Mac, Microcomputer, UNIX) using the appropriate reader for that platform. * Adobe, Acrobat, and Adobe Type Manager are trademarks of Adobe Systems Incorporated and may be registered in certain jurisdictions. (C) Copyright 1994 Adobe Systems Incorporated. All rights reserved. USERMANU.PDF - HSCTM2D Documentation and User's Manual "HSCTM-2D, A Finite Element Model for Depth-averaged Hydrodynamics, Sediment, and Contaminant Transport". ** Sub-directory InstallationDirectory: F77L3.EER - Run time error message library file for Lahey FORTRAN (F77L3) (refer to DEVELOPMENT SYSTEM section). This file is read automatically during execution of the HSCTM2D model system executable task image file (*.EXE) if an error is detected during execution. RETURN1.ANS - An empty file containing a single carriage return character used to provide an key or null response to an input prompt in selected DOS batch command files. HSCTOPEN.SCR - Initial welcome and CEAM information screen displayed before the execution of the HSCTM2D model via the DOS batch command file HSCTM2D.BAT. This is an ASCII text (non-binary) file that can be displayed on the monitor screen with the DOS TYPE command or printed using the DOS PRINT command. NOTE: To execute a DOS batch command file (*.BAT)--and hence a model or program spawned (i.e., executed) buy a given batch command file--from any sub-directory located on a hard or virtual disk drive, try adding the HSCTM2D installation sub-directory (e.g., C:\HSCTM2D) to the DOS search PATH and copy appropriate run time support files to the current default sub-directory. One way to accomplish this is to add or modify the PATH statement in the system start-up file, AUTOEXEC.BAT (located in the root directory on the start-up or boot drive). For example PATH C:\;C:\DOS;C:\UTIL;C:\WP51;C:\HSCTM2D; Refer to the DOS Reference Manual for PATH command and AUTOEXEC.BAT file application and use. HSCTM2D.BAT - DOS batch command file used to execute the HSCTM2D model. To execute, type HSCTM2D at the DOS system prompt, press the key, then follow the information screens and prompts displayed on the monitor screen. For further information, refer to the ROUTINE EXECUTION section. WARNING: The executable task image file (XHSCTM2D.EXE) should only be executed using the corresponding DOS batch command file provided (HSCTM2D.BAT). XHSCTM2D.EXE - Executable task image file for the HSCTM2D model. NOTE: Unless specified as a "binary" file, HSCTM2D model input data files are ASCII (non-binary) text files that can be displayed on the monitor screen with the DOS TYPE command or printed using the DOS PRINT command. ASCII text files can be viewed or edited using any editor program that can read and save a file to disk in ASCII text (non-binary) format. NOTE: An input or output file name path specification and/or file name, as typed at a run time prompt or specified within the HSCTM2D WINYAH.FIL input file by the user, must be a unique and valid DOS path and/or file name. An input data file name must also be a valid HSCTM2D file name -- either furnished with the distribution package or created, designated, and named by the user. A file name typed at a run time prompt or specified within the HSCTM2D input file WINYAH.FIL will be processed and executed in the run of the model. Remember, a DOS file name can be from 1 to 8 characters and can have an optional 1 to 3 character file name extension. NOTE: Refer to the explanation of the OUT_TEST\*.HSO, *.OUT, and *.SOL files for a procedure to compare the contents of an output file produced by the HSCTM2D model on the users system (*.HSO, *.OUT, *.SOL) to an output file by the same name as provided within the distribution package (OUT_TEST\*.*). For a unique, user defined application and execution of the HSCTM2D model, the user must first create and enter the necessary input data into input data files. Input and output file names and their corresponding unit numbers must be specified within the HSCTM2D run-time supervisor file WINYAH.FIL. These files should only be created and/or modified using an editor program that can read and save a file to disk in ASCII text (non- binary) format. NOTE: For further explanation, information, and/or listings of example input and output data files, refer to the user's manual. WINYAH.FIL - Run time supervisor file for HSCTM2D. This file contains file name(s) and input/output (I/O) unit numbers used during the execution of the HSCTM2D model. To modify the run time supervisor file, edit the file with a text editor that saves a file to disk in ASCII (non-binary) text format. This file is read automatically by the HSCTM2D model and is an ASCII text file that can be displayed on the monitor screen with the DOS TYPE command or printed using the DOS PRINT command. The files listed below are example input data files to test the installation and demonstrate application of the HSCTM2D model. These data files are also furnished to provide instruction by example and can be used as templates for the preparation of a new or modified input file. To test the installation, execute the HSCTM2D model using the run time supervisor file (WINYAH.FIL) provided within the distribution package. This supervisor file (as contained within the distribution version of the HSCTM2D model system) is configured (1) with input and output file names and I/O unit numbers, and (2) to instruct the HSCTM2D model to automatically read and process as input the following files: WIN2-H.BC - Contains hydrodynamic boundary conditions and related input data. WINYAH2.BIN - Binary (non-ASCII) file that contains finite element grid input data. WINYAH.HSI - Binary (non-ASCII) hot-start file. WINYAH.INP - Contains sediment input data. WINYAH.SAL - Contains salinity boundary condition input data. WINYAH.SBC - Contains suspended concentration boundary condition input data. These sample input files provide examples of input for most sections and capabilities of the HSCTM2D model. For further information on executing HSCTM2D, refer to file HSCTM2D.BAT in this section or refer to the ROUTINE EXECUTION section. ** Sub-directory InstallationDirectory\OUT_TEST: NOTE: The symbol "" represents pressing the or carriage return key. Responses and key strokes that can be typed by the user are underlined with the hyphen character (-) and/or enclosed by the angle bracket characters (<>). NOTE: Unless specified as a "binary" file, HSCTM2D model output listing files are ASCII (non-binary) text files that can be displayed on the monitor screen with the DOS TYPE command or printed using the DOS PRINT command. ASCII text files can be viewed or edited using any editor program that can read and save a file to disk in ASCII text (non-binary) format. The following is a list of files produced by execution of the HSCTM2D model using the test input data files provided. The supervisor file (WINYAH.FIL) as contained within the distribution version of the HSCTM2D model system is configured (1) with input and output file names and I/O unit numbers, and (2) to instruct the HSCTM2D model to automatically produce these files as output. Therefore to test the installation, execute the HSCTM2D model using the WINYAH.FIL run time supervisor file provided with the distribution package. WINYAH.HSO - Binary (non-ASCII) hot-start output file. WINYAH.OUT - Hydrodynamic model output data file. WSED.OUT - Sediment transport model output data file. WINYAH.SOL - Binary (non-ASCII) output data file to be opened in SMS for viewing hydrodynamic solution. SEDCONC.SOL - Binary (non-ASCII) output data file to be opened in SMS for viewing suspended sediment concentration field. SALINTY.SOL - Binary (non-ASCII) output data file to be opened in SMS for viewing salinty field. DELTABED.SOL - Binary (non-ASCII) output data file to be opened in SMS for viewing change in bed elevations. After executing the HSCTM2D model using the test input data files (refer to explanation of WINYAH.FIL and other test input files above), compare the contents of the files produced (as listed above) with the corresponding output file provided and stored within the sub-directory OUT_TEST (e.g., WINYAH.OUT). To compare file contents, use the COMP (PC DOS) or FC (MS DOS) file compare command, or print both files then compare contents by hand. For further information on executing the HSCTM2D model, refer to file HSCTM2D.BAT in this section or the ROUTINE EXECUTION section. Example HSCTM2D execution and file comparison sequence: Step Description/Action ~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1) Set the default drive to the disk containing the HSCTM2D model system sub-directory: A:\> C: -- 2) Change the DOS default sub-directory to the sub-directory designated by the user during the installation program as the installation sub-directory (e.g., HSCTM2D). Use the DOS CD (change directory) command at the DOS system prompt: C:\> CD \HSCTM2D ----------- 3) Modify (and save) the WINYAH.FIL run time supervisor file to process input data files as selected by the user or provided with the distribution package: C:\HSCTM2D> EDIT WINYAH.FIL --------------- 4) Execute the HSCTM2D model with the input data file as selected in step 3 above: C:\HSCTM2D> HSCTM2D ------- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ (Initial HSCTM2D banner/registration screen displayed here...press key to clear screen and continue model execution...) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ (Next, the following screen is displayed while the HSCTM2D program is loaded into memory...) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ # #----------------------------------------------------------------------# ## Executing HSCTM2D DOS command file. #----------------------------------------------------------------------# # # ## Loading HSCTM2D model task image file...wait. # #------------------------# ## HSCTM2D run beginning. #------------------------# # ÉÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ» º 32-bit Power for Lahey Computer Systems º º Phar Lap's 386|DOS-Extender(tm) Version 4.1L º º Copyright (C) 1986-92 Phar Lap Software, Inc. º º Available Memory = xxxxx Kb º ÈÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍͼ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ (Where xxxxx is a number that represents the available RAM memory on the host system expressed in K bytes (K=1,024). This value is filled in automatically by the HSCTM2D executable task image file.) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Type control file name then press Enter key. --> WINYAH.FIL ---------- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ (HSCTM2D version 1.01 run time diagnostic and information status screens and messages displayed here while the model executes. Once execution is complete the following messages are displayed on the monitor screen.) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ # ## HSCTM2D program execution complete. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ (Compare the output files supplied to those produced. For example:) C:\HSCTM2D> COMP OUT_TEST\WINYAH.OUT WINYAH.OUT ----------------------------------- or, C:\HSCTM2D> FC OUT_TEST\WINYAH.OUT WINYAH.OUT --------------------------------- ** Sub-directory InstallationDirectory\INC_CODE: NOTE: All FORTRAN source code files (*.INC, *.FOR) and "make" command files (MAKEFILE) are NOT required to document, execute and/or test any model, program, or associated run time support file as provided on the distribution diskettes or the Internet installation file. For further information, refer to the MINIMUM FILE CONFIGURATION section. HSCTM.INC - FORTRAN source code "include" file containing FORTRAN COMMON block declarations for the HSCTM2D model source code. This file is automatically included or copied into FORTRAN source code file (HSCTM2D.FOR) during compilation as executed by the corresponding "make" (MAKEFILE) file. ** Sub-directory InstallationDirectory\HSCTCODE: NOTE: All FORTRAN source code files (*.INC, *.FOR) and "make" command files (MAKEFILE) are NOT required to document, execute and/or test any model, program, or associated run time support file as provided on the distribution diskettes or the Internet installation file. For further information, refer to the MINIMUM FILE CONFIGURATION section. MAKEFILE - Lahey "make" file that can be used to compile and/or link edit the HSCTM2D model FORTRAN source code files (*.INC, *.FOR) to incorporate changes made in the source code files by the user. Refer to the program listing for in-code documentation. The execution of this command can produce a new executable task image file (XHSCTM2D.EXE) for the HSCTM2D model. This command file only needs to be executed if changes have been made in the FORTRAN source code, not an input/output data file. To execute, type MAKE at the DOS system prompt, then press the key. HSCTM.FOR - FORTRAN source code file for the HSCTM2D model, version 1.01. Special Run Time Files ** Sub-directory InstallationDirectory: NOTE: In addition to standard output files, the HSCTM2D model system also generates a special run time file that does not store scientific results. This file, as noted below and listed by file name (HSCT_RUN.LOG), can be cleaned up (i.e., deleted) at any time by the user. NOTE: The following file(s) are not distributed with the distribution release. They are either created and/or updated (appended to) automatically when the user executes the HSCTM2D model system DOS batch command file (HSCTM2D.BAT) to process data files named within a run time supervisor file (e.g., WINYAH.FIL). This file will be stored in the sub-directory (e.g., \HSCTM2D) selected by the user during the installation of the HSCTM2D model system. HSCT_RUN.LOG - Run time log file that contains a beginning and ending date and time stamp for each execution of the HSCTM2D model. Refer to the ROUTINE EXECUTION section for further information. This file can be cleaned up (i.e., deleted) at any time by the user. _________________________________________________________________ DEVELOPMENT SYSTEM The following list describes the language and program development tools used by the U.S. EPA Center for Exposure Assessment Modeling to build version 1.01 of the microcomputer implementation of the HSCTM2D model system. Also shown are the recommended minimum hardware and software configuration and the recommended \CONFIG.SYS configuration/environment file statements for the implementation and execution of this model system and all related support files and programs. Make sure that the IBM PC or compatible system has these statements in the \CONFIG.SYS file, and re-boot the system to implement these changes before attempting to install or use the HSCTM2D model system. Development System: Hardware System: Fully IBM compatible 80386, 80486, or 80586 Language: FORTRAN 77 Operating System: DOS version 3.30 or higher. Properly configured, this model system should also work on hardware platforms with PC DOS or MS DOS versions 4.0x, 5.0x, or 6.x., to include a DOS window or box or boot under Windows 3.x, Windows for WorkGroups, Windows 95, and NT. DOS Extender: Phar Lap 386/DOS-extender; bound into application EXE file with automatic virtual memory management; distributed royalty free Memory Manager: Compatible with VDISK.SYS, QEMM386, HIMEM.SYS, RAMDRIVE.SYS, EMM386, CEMM, 386Max; compatible with DPMI, VCPI, and XMS standards Compiler: Lahey FORTRAN, F77L-EM/32 version 5.01 Link Editor: Phar Lap 386LINK version 4.1L Overlay Structure: None - linked as flat memory model and program Storage Requirements: (k=1,024; m=1,048,576) Random Access Memory: (approximate minimum free bytes needed to execute EXE file for optimum performance within extended, not expanded, memory (i.e., XMS)) 640k base (low end) memory, plus 24.81m bytes of free extended (XMS) memory and 11.5m bytes of free disk space; or, 1m byte of free extended (XMS) memory and 36.3m bytes disk space (non-optimized). Diskette Drive: Required for installation only. Hard Disk Drive: 200m byte drive recommended (minimum) with 36.3m bytes free (minimum) Installation Size: Run Time: Approx. 11.5m bytes max. Run time size: After installation, up to approximately 10m bytes plus space for user input data or command files, output, and temporary files produced by model system (refer to MINIMUM FILE CONFIGURATION section). Numerical Coprocessor: Required. \CONFIG.SYS Statements: BREAK=ON BUFFERS=20 or BUFFERS=32 FILES=20 DEVICE=C:\ANSI.SYS DEVICE=extended memory manager - and - SHELL=C:\COMMAND.COM C:\ /e:512 /p Printer: For *.PDF file only, HP LaserJet III PostScript or compatible printer (minimum). Printer Software: For *.PDF file only, Adobe Acrobat reader version 3.0 or greater. _________________________________________________________________ ROUTINE EXECUTION NOTE: The symbol "" represents pressing the or carriage return key. Responses and key strokes that can be typed by the user are underlined with the hyphen character (-) and/or enclosed by the angle bracket characters (<>). NOTE: It is possible that execution, not installation, of the HSCTM2D model system could be incompatible with MS DOS and Windows software cache files SMARTDRV.SYS or SMARTDRV.EXE loaded from the system configuration files \CONFIG.SYS and/or \AUTOEXEC.BAT on the boot drive. If any portion of the HSCTM2D model system prematurely halts, produces unusual results, and/or causes the host system to halt or hang, remove any SMARTDRV statements on the boot drive \CONFIG.SYS and/or \AUTOEXEC.BAT files, then re-boot the system to implement these changes before attempting to reuse any portion the HSCTM2D model system. Introduction ~~~~~~~~~~~~ Complete the installation process to make the full or any portion of the HSCTM2D model system and related files resident on a hard (usually designated as "C:") or virtual disk drive. Then modify the \CONFIG.SYS system environment file and restart the microcomputer system. This needs to be completed only once for a given installation and/or execution of the HSCTM2D model system. DOS Storage Path ~~~~~~~~~~~~~~~~ Verify that the HSCTM2D model system executable task image file (XHSCTM2D.EXE), DOS batch command file (HSCTM2D.BAT), other run time support files, HSCTM2D run time supervisor file, and user defined input data and/or command file(s) are in the current default DOS sub-directory. It is convenient but not required to have these files in the same sub-directory. NOTE: To execute a DOS batch command file (*.BAT)--and hence a model or program spawned (i.e., executed) buy a given batch command file--from any sub-directory located on a hard or virtual disk drive, add the HSCTM2D installation sub-directory (e.g., C:\HSCTM2D) to the DOS search PATH and copy other appropriate run time support files to the current default sub- directory. One way to accomplish this is to add or modify the PATH statement in the system start-up file, AUTOEXEC.BAT (located in the root directory on the start-up or boot drive). For example PATH C:\;C:\DOS;C:\UTIL;C:\WP51;C:\HSCTM2D If any portion of the HSCTM2D model system prematurely halts, produces unusual results, and/or causes the host system to halt or hang, copy all DOS batch and other run time support files from the HSCTM2D model system installation sub-directory to the current default sub- directory from where the HSCTM2D model system will be executed via the DOS search PATH statement. Refer to the DOS Reference Manual or on-line help for PATH command and AUTOEXEC.BAT file application and use. Routine Execution Steps ~~~~~~~~~~~~~~~~~~~~~~~ Step Description/Action ~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1) Set the default drive to the disk containing the HSCTM2D model system sub-directory. For example: A:\> C: -- 2) Change the DOS default sub-directory to the sub-directory designated by the user during the installation program as the installation sub-directory (e.g., HSCTM2D). Use the DOS CD (change directory) command at the DOS system prompt: C:\> CD \HSCTM2D ----------- NOTE: A common problem is for a DOS executable or batch command file (*.EXE, *.BAT) to be unable to locate a file because it assumes the file is on the default drive and/or sub-directory when it is not. If input and/or other run time support file(s) are not on the default drive and sub-directory, the user can type a drive and/or path name ahead of the file name. For further information refer to the "File Name and Path Specifications" sub-section later in this document or the DOS Reference Manual. 3) To execute the HSCTM2D model, type: C:\HSCTM2D> HSCTM2D ------- After an opening banner/registration screen is displayed on the monitor, press the key to clear the screen and begin model execution. The model will prompt the user for file name information needed for this run of the model. NOTE: The HSCTM2D model system is a DOS, not Windows, application and should be executed from a DOS command line prompt. NOTE: To execute the HSCTM2D model, the user must first create and enter the necessary input data into input data files. These files should only be created and/or modified using an editor program that can read and save a file to disk in ASCII text (non-binary) format. Viewing Output Results ~~~~~~~~~~~~~~~~~~~~~~ After executing a HSCTM2D model system executable task image file, exiting HSCTM2D, and returning to the DOS prompt, the user can view an output file (e.g., *.OUT), if any, produced by the execution of a program or model if and only if that file is in ASCII text (non-binary) format. Results can be viewed by scrolling through the output file that was (1) a result of model or program execution and/or (2) named by the user at a run time prompt. A word processor or text editor is convenient for this purpose, or the command TYPE filename | MORE can be used where "filename" is the name of the output file. However, the TYPE command is awkward for a file that exceeds the 80-column screen width. Alternatively, the output file can be printed. A compressed print mode (132 column) should be used to avoid awkward--wrapped around--output from lines that exceed 80 columns. The DOS MODE command can be used for this purpose. For a parallel printer assigned to LPT1, the DOS command MODE LPT1: 132 will cause most printers to print in compressed mode. For further information, refer to the DOS Reference Manual. File Name and Path Specifications ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A file name, path specification, and/or the parameter file name argument "filename" must be a unique and valid DOS path and/or file name. The user response "filename" must also be a valid HSCTM2D model system command, input, or output file name -- either furnished with the distribution package (refer to FILE NAME AND CONTENT section) or created, designated, and named by the user. A file name used as input data for a program or model in the HSCTM2D model system will be processed and executed in that run of the program or model. In general, file names used for input data, command, and/or output listing files (except for the test input and example output cases provided) are arbitrary, but must follow the rules for DOS file names. A file name should assist the user with identifying the contents or purpose of a file (e.g., INPUT.DAT, OUTPUT.LST). However the HSCTM2D model uses specific file names for input and output data (refer to explanation of files within the installation sub-directory) and a specific file name extension for all input and output files (e.g., *.OUT). Any DOS file name can be from 1 to 8 characters and can have an optional 0 to 3 character file name extension. Any characters beyond 8 in the file name or beyond 3 in the file name extension will be truncated and ignored by the DOS operating system. Refer to the DOS Reference Manual for further information on file names and disk file input/output procedures, rules, and commands. _________________________________________________________________ RUN TIME AND PERFORMANCE The following run time (approximate) was observed using the test input data file sets furnished with the distribution version of the HSCTM2D model system. Remember that this time was obtained using input test data files that may not be representative of a "real world" problem and/or data. The test data files have been furnished for testing the installation of the HSCTM2D model system and for instruction by example. In general, these input test data files are not intended to be representative of full scale model simulations. They were developed to test the installation of significant sections of model code. The run time listed in the table below was produced on a Dell OptiPlex Gn+ 200 megahertz class microcomputer running under a DOS window under Windows 95 and using 640k bytes of random access (low end) memory (RAM) with 32 megabytes of extended memory. ** HSCTM2D Model System Test Run Input Data File Name Approx. Run Time (min:sec) ~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~ WINYAH.FIL 50:35 Program run time and performance can be affected by many microcomputer system and program parameters including o available disk space o available memory o processor/CPU classification o CONFIG.SYS and AUTOEXEC.BAT file options and parameter values o disk and/or file storage and/or fragmentation _________________________________________________________________ MINIMUM FILE CONFIGURATION The following list describes the absolute minimum file configuration needed within the application sub-directory to execute and/or test--not document--the HSCTM2D model and all support command files and programs. This list assumes that o the HSCTM2D model system and all support files and programs have been successfully installed from the distribution release o the user has defined and stored all application specific run time files NOTE: Files other than those listed below can be deleted if the user needs to recover disk space. ** Sub-directory InstallationDirectory\README: NOTE: The following files are ASCII text (non-binary) files that can be displayed on the monitor screen with the DOS TYPE command or printed using the DOS PRINT command. READ.ME - HSCTM2D model system execution and general support guide. RELEASE.TXT - Summary of corrections and/or changes between release versions. UPDATE.TXT - Summary of enhancements, updates, and additions not covered in the current user's manual. ABSTRACT.TXT - HSCTM2D Model System Abstract. RESPONSE.TXT - CEAM Software Product User Response Form. ** Sub-directory InstallationDirectory: F77L3.EER - Run time error message library file. RETURN1.ANS - An empty file containing a single carriage return. HSCTOPEN.SCR - Initial welcome and CEAM information screen. HSCTM2D.BAT - DOS batch command file (executes HSCTM2D model). WARNING: Executable task image file (XHSCTM2D.EXE) should only be executed using the corresponding DOS batch command file provided (HSCTM2D.BAT). XHSCTM2D.EXE - Executable task image file for the HSCTM2D model. WINYAH.FIL - Run time supervisor file for HSCTM2D. WIN2-H.BC - Hydrodynamic boundary condition input data. WINYAH2.BIN - Finite element grid input data. WINYAH.HSI - Binary (non-ASCII) hot-start file. WINYAH.INP - Sediment input data. WINYAH.SAL - Salinity boundary condition input data. WINYAH.SBC - Suspended concentration boundary condition input data. ** Sub-directory InstallationDirectory\OUT_TEST: WINYAH.HSO - Hot-start output file. WINYAH.OUT - Hydrodynamic model output data file. WSED.OUT - Sediment transport model output data file. WINYAH.SOL - Output data file for viewing hydrodynamic solution. SEDCONC.SOL - Output data file for viewing suspended sediment concentration field. SALINTY.SOL - Output data file to be opened in SMS for viewing salinty field. DELTABED.SOL - Output data file to be opened in SMS for viewing change in bed elevations. _________________________________________________________________ MODIFICATION Included with the distribution release are o executable task image file for the HSCTM2D model system o HSCTM2D model FORTRAN source code files for IBM PC and compatible microcomputer systems (refer to DEVELOPMENT SYSTEM section). A FORTRAN compiler and link editor are NOT required to execute any portion of the HSCTM2D model system. If the user wishes to modify any portion of the HSCTM2D model system, it will be up to the user to supply and/or obtain o an appropriate text editor that saves files in ASCII text (non-binary) format o FORTRAN program development tools to recompile and link edit the HSCTM2D model The U.S. EPA CEAM cannot support, maintain, and/or be responsible for modifications that change the function of any executable task image file (*.EXE) or DOS batch command file (*.BAT) supplied with this model package. _________________________________________________________________ TECHNICAL HELP CONTACT NOTE: This section assumes that the user has successfully completed the installation process to make the full or any portion of the HSCTM2D model system and related files resident and fully operational on a hard (usually designated as "C:") or virtual disk drive. For further information on installation and execution, refer to the DISTRIBUTION DISKETTES and ROUTINE EXECUTION sections. For questions and/or information concerning o installation and/or testing of the HSCTM2D model system and/or support programs or files, call 706/355-8400 for assistance or send mail via Internet to ceam@epamail.epa.gov o HSCTM2D model and/or program content, application, and/or theory, contact Mr. Frank Stancil, U.S. EPA CEAM Manager for assistance at the address shown below o use of the CEAM Internet node, or Listserver mailing list system, contact the Web Master at 706/355-8400 o CEAM software and distribution Quality Assurance and Control, call 706/355-8400 o other environmental software products and documentation distributed through CEAM, contact the Model Distribution Coordinator at 706/355-8400 o other support available through CEAM, contact Mr. Frank Stancil, U.S. EPA CEAM Manager - by mail at the following address Center for Exposure Assessment Modeling (CEAM) National Exposure Research Laboratory - Ecosystems Research Division U.S. Environmental Protection Agency (U.S. EPA) 960 College Station Road Athens, Georgia 30605-2700 - by telephone at 706/355-8328 - by fax at 706/355-8104 - by email or Internet at ceam@epamail.epa.gov To help technical staff provide better assistance, write down a response to the following topics before calling or writing. If calling, be at the computer, with the computer on, and in the proper sub-directory (e.g., C:\HSCTM2D) when the call is placed. o program information: - describe the problem, including the exact wording of any error and/or warning message(s) - list the exact steps, command(s), and/or keyboard key sequence that will reproduce the problem o machine information: - list computer brand and model - list available RAM (as reported by DOS CHKDSK or MEM command) - list extended memory present and free (XMS) - list name and version of extended memory (XMS) manager (i.e., HIMEM, VDISK, RAMDRIVE, etc.) - list available hard disk space (as reported by DOS CHKDSK command) - list the brand and version of DOS (as reported by DOS VER command) - list the name of any memory resident (TSR) program(s) installed - printer brand and model - monitor brand and model NOTE: If contacting CEAM by mail or fax, include responses to the above information within correspondence. CEAM operates a UNIX Listserver mailing list system. The name of the list is CEAM-USERS. Listserver is an automated mailing list system. A user can add him/her-self to a selected mailing list, post messages, and/or review/read messages. Lists can be moderated (owner decides which messages are made public) or un- moderated (all incoming messages are posted). Listserver is best suited for e-mail discussion groups. It is not a file service such as for the distribution of CEAM software products. This listserver broadcasts up-to-date information concerning CEAM software products, activities, and events. This includes announcements for CEAM and/or non-CEAM supported workshops and training sessions; software product version release, updates, and documentation information; hints on software installation, operation, application, problems, and/or enhancements; and the exchange of information quickly among users, and between users and CEAM support personnel. NOTE: The CEAM-USERS list is not moderated. To subscribe, execute a mail service to send the following information: NOTE: The symbol "" represents pressing the or carriage return key. Responses and key strokes that can be typed by the user are underlined with the hyphen character (-) and/or enclosed by the angle bracket characters (<>). mail listserver@unixmail.rtpnc.epa.gov -------------------------------------- Subject: (i.e., leave subject line blank) subscribe CEAM-USERS yourfirstname yourlastname ----------------------------------------------- The user can also check the status of this model system or any other CEAM software product through Internet node ftp.epa.gov or mountain.epa.gov The HSCTM2D model system and selected other CEAM software products for microcomputer and/or UNIX installation and application can be down loaded through the Internet from the above nodes via "anonymous" ftp (File Transfer Protocol) log in and file transfer commands and options. For further information on this Internet node and ftp, refer to document files USERINFO.TXT, QREF_WWW.TXT, QUICKREF.TXT, and LISTSERV.TXT that are included in the file INTERNET.ZIP that can be down loaded from the Internet node. To access CEAM software products via Internet, start the ftp program from the user's Internet node system (type 'ftp'), establish connection (type 'open ftp.epa.gov'), log onto public access server using anonymous account (type 'anonymous'). Respond to password prompt with users e-mail or Internet address. Then, upon log in completion, type 'cd epa_ceam', read CEAM Internet Welcome Screen, then type 'get CEAMNEWS.TXT -' to view latest news and list of CEAM software products available on the Internet. The same CEAM software products as mentioned above are also available through the World Wide Web (WWW). If the user has access to the World Wide Web through a web browser, selected CEAM software products, including HSCTM2D, can be accessed at the following Uniform Resource Locator (URL): http://www.epa.gov/CEAM _________________________________________________________________ DISCLAIMER Mention of trade names or use of commercial products does not constitute endorsement or recommendation for use by the United States Environmental Protection Agency. Execution of any portion of the HSCTM2D model system, and modification to the DOS system configuration files (i.e., \CONFIG.SYS and \AUTOEXEC.BAT) must be used and/or made at the user's own risk. Neither the U.S. EPA nor the program author(s) can assume responsibility for model and/or program modification, content, output, interpretation, or usage. The HSCTM2D program and files have been extensively tested and verified. However, as for all complex software products, the programs herein may not be completely free of errors and may not be applicable for all cases. In no event will the U.S. EPA be liable for direct, indirect, special, incidental, or consequential damages arising out of the use of the programs and/or associated documentation. CEAM software products are built using FORTRAN-77, assembler, other third and forth generation symbolic reference languages, and operating system interface command languages. The code structure and logic of these products is designed for single-user, single-tasking, non-LAN environment and operating platform for microcomputer installations (i.e., single user on dedicated system). NOTE: FORTRAN source code files are NOT required to document, execute, and/or test any model, program, or associated run time support file as provided on the distribution diskettes or the Internet installation file. HSCTM2D is a large-scale complex model system. The model source code relies on multiple interdependencies. Modification and recompilation of FORTRAN source code files should be attempted only by experienced research personnel with substantial expertise in FORTRAN development tools and the HSCTM2D modeling system. Their application is mostly for additional research and development, including comparison to field or laboratory data, other theories, and further enhancements, such as graphical interfaces. THE SEPARATE USE OF THE FORTRAN SOURCE CODE OUTSIDE THE HSCTM2D SHELL IS NOT RECOMMENDED BY THE U.S. EPA FOR ROUTINE APPLICATIONS OR ENVIRONMENTAL IMPACT STATEMENTS. A user will be on their own if he/she attempts to install a CEAM product on a multi-user, multi-tasking, and/or LAN based system (i.e., Windows, DESQview, any LAN). CEAM cannot provide installation, operation, and/or general user support under any combination of these configurations. Instructions and conditions for proper installation and testing are provided with the product in a READ.ME file. While multiuser/multitasking/LAN installations could work, none of the CEAM products have been thoroughly tested under all possible conditions. CEAM can provide selected and/or limited scientific and/or application support for selected products if the user proves that a given product is installed and working correctly using the test input data files provided with the distribution release. o WordPerfect is a registered trademark of WordPerfect Corporation o Microway and Number Smasher are registered trademarks of Microway, Inc. o Intel, 386, 486, and 860 are registered trademarks of Intel Corporation. o F77L is a registered trademark of Lahey Computer Systems, Inc. All other Lahey products are trademarks of Lahey Computer Systems, Inc. o IBM, Personal Computer/XT (PC/XT), Personal Computer/AT (PC/AT), PC DOS, VDISK, and Personal System/2 (PS/2) are registered trademarks of International Business Machines Corporation o PKZIP, PKUNZIP, and PKSFX are registered trademarks and/or trademarks of PKWARE, Incorporated. o DESQview is a trademark of Quarterdeck Office Systems, Inc. o Sun and SunOS are registered trademarks of Sun Microsystems, Inc. o SPARC is a registered trademark of SPARC International, Inc. o UNIX is a registered trademark of American Telephone and Telegraph o SVS FORTRAN-77 is a trademark of Silicon Valley Software o PRIME and PRIMOS are trademarks of Prime Computers, Inc. o Microsoft, RAMDRIVE, HIMEM, MS, and MS-DOS are registered trademarks of Microsoft Corporation o Windows and Windows95 are trademarks of Microsoft Corporation o RM/FORTRAN is a trademark of Language Processors, Inc. o DEC, VAX, VMS, and DCL are trademarks of Digital Equipment Corporation o US Robotics is a registered trademark and Courier HST is a trademark of U.S. Robotics, Inc. o VP-Expert is a registered trade mark of WordTech Systems, Inc. ######################### DWD/dwd - November 1998 - E:\HSCTM2D\README\READ.ME