HSPEXP Expert System for Calibration of HSPF HSPEXP - Version 2.3 1996/03/01 hspex2_3.exe - self-extracting DOS distribution prepared on an IBM-compatible PC TABLE OF CONTENTS A. DESCRIPTION B. DOCUMENTATION C. SYSTEM REQUIREMENTS D. INSTALLING o Installing HSPEXP from self-extracting executable o Installing HSPEXP from distribution diskette o HSPEXP directory structure o Making HSPEXP easily accessible E. RUNNING THE PROGRAM F. SCREEN DISPLAY G. TESTING H. GRAPHICAL OUTPUT I. CONTACTS A. DESCRIPTION Interactively allows the user to edit the input uci file for the Hydrologic Simulation Program--Fortran (HSPF), simulate with HSPF, produce plots of HSPF output compared to observed values, compute error statistics for a simulation, and provide the user with expert advice on which parameters should be changed up or down to improve the calibration. In general, the user will spend time repeating the cycle of simulate, compute statistics, see plots, get advice, and edit the parameters. The expert system uses over 35 rules involving over 80 conditions to recommend parameter adjustments. The rules are divided into four phases--annual volumes, low flows, storm flows, and seasonal flows. Rules in subsequent phases are not tested until all rules in the previous phase pass. The rules are based on the experience of experts in the use of HSPF in a wide range of climates and physiographic regions. B. DOCUMENTATION Lumb, A.M., McCammon, R.B, and Kittle, J.L., Jr., 1994, Users manual for an expert system (HSPEXP) for calibration of the hydrological simulation program--Fortran: U.S. Geological Survey Water-Resources Investigations Report 94-4168, 102 p. A PostScript version of this report is available in the hspexp2.3\doc directory. See the file hspexp.ps. Bicknell, B.R., Imhoff, J.C., Kittle, J.L., Jr., Donigian, A.S., and Johanson, R.C., 1993, Hydrological Simulation Program--Fortran, Users Manual for Release 10: EPA-600/R-93/144, Environmental Research Laboratory, Athens, Ga., 660 p. C. SYSTEM REQUIREMENTS For installation of HSPEXP, 12 megabytes of free disk space is needed. To run HSPEXP, the following are necessary: - 386 or greater processor - math coprocessor - 27 megabytes of combined free extended memory and free disk space on installation drive (the greater proportion available as memory, the better performance will be) - at least 2 megabytes free disk space in current working directory Because of significant memory space requirements, HSPEXP initialization may take several minutes. IMPORTANT NOTE: When the full 27 megabytes of memory space needed to run HSPEXP is not available in physical memory, virtual memory management allows for the portions of the program that will not fit in physical memory to be written to disk. However, when running HSPEXP in a Windows 95 MS-DOS window, default settings will not allow virtual memory to be used and, if there is insufficient available physical memory, HSPEXP will terminate during initialization with an insufficient memory error. To modify the MS-DOS window settings to be able to use virtual memory, do the following: o Click on the MS-DOS icon in the upper left corner of the MS-DOS window and select the Properties menu item. o Select the Memory tab and enter 65535 (the maximum allowed value) in the "MS-DOS protected-mode (DPMI) memory" input field. The default value of "Auto" does not virtual memory to be used. D. INSTALLING Installing HSPEXP from self-extracting executable ------------------------------------------------- To install HSPEXP from the self-extracting executable, follow the steps below, replacing with the drive letter where you want to install HSPEXP and optionally replacing [directory] with the name of a directory on that drive: 1. If you are not in the directory where the distribution file is located, go there. For example: c: cd \wrdapp 2. Extract the files contained in the distribution file using the command: hspex2_3 -d :\[directory] Note: be sure to include the -d option and ":\" in the command. Examples are: hspex2_3 -d c:\ hspex2_3 -d c:\wrdapp 3. Go to the newly-created hspexp2.3 directory where the files have been extracted. For example: c: cd \wrdapp\hspexp2.3 4. Complete the installation by typing, install :[\directory] using the same drive letter and directory name as for extracting the files; however, if the files are located in the root directory of the installation drive, don't include the backslash. Examples are: install c: install c:\wrdapp The above install command must run successfully in order to create the batch files, hspexp2.3\bin\hspexp.bat and hspexp2.3\test\hspexp.bat which are necessary for successful execution of HSPEXP. Be sure that no errors occur when executing the above install command. Installing HSPEXP from distribution diskette -------------------------------------------- To install HSPEXP from distribution diskette onto your hard drive, type :install : :[\directory] For example, if your floppy drive is a: and you want to install HSPEXP directly under the root directory on the c: drive, you would type a:install a: c: This will create the directory c:\hspexp2.3. As an additional example, if you wanted to install HSPEXP under a directory named "wrdapp" on the c: drive, you would type a:install a: c:\wrdapp This will create the directory c:\wrdapp\hspexp2.3. HSPEXP directory structure -------------------------- The following directory structure will be created (the contents of each directory are shown to the right): hspexp2.3 copy of this README file `-----bin compiled executable, batch file to run program `-----bin_data files required during execution `-----doc documentation files `-----test batch files to run verification tests `-----data standard data sets used in verification tests `--huntday files specific to daily time step test `--hunthour files specific to hourly time step test Note: It is recommended that no user files be kept in the hspexp2.3 directory structure. If you plan to put files in the hspexp2.3 directory structure, do so only by creating subdirectories under hspexp2.3. Making HSPEXP easily accessible ------------------------------- To make the HSPEXP program accessible from any directory, the hspexp2.3\bin directory should be included in the PATH environment variable. Add a line similar to the following to AUTOEXEC.BAT: PATH=%PATH%;C:\hspexp2.3\bin Substitute the appropriate drive letter and pathname if not C:\ as shown above. Reboot your system after modifying AUTOEXEC.BAT. E. RUNNING THE PROGRAM After the hspexp executable is properly installed (see INSTALLING, above), the program can be executed with the command "hspexp". F. SCREEN DISPLAY The program interface requires an ANSI standard terminal. You will know immediately upon program startup if you have a properly configured ANSI standard terminal--the borders outlining the components of the program screen will be properly drawn as solid lines. If you do not see solid lines outlining the program screen, but instead see a series of dashes or other characters (which may jumble the entire appearance of the screen), the ANSI.SYS device driver is not loaded. CONFIG.SYS must contain a line such as DEVICE = C:\DOS\ANSI.SYS Determine the location of the ANSI.SYS driver on your system and substitute the path name of that location if not C:\DOS as shown above. Note that for Windows 95, the ANSI.SYS driver is normally found in C:\WINDOWS\COMMAND. Reboot your system if you modify CONFIG.SYS. G. TESTING Test data sets are provided to verify that the program is correctly installed and running on the system. The tests may also be looked at as examples of how to use the program. Tests are run in the hspexp2.3\test directory. The directory hspexp2.3\data contains the input data and the expected results for each test. After each test is completed, compare the results to the expected results using a file comparison utility such as fc. If all goes well, there should be no differences. To clean up after the tests, type the command: clean Note: The standard data sets were created on a Data General AViiON workstation. You may notice slight numeric differences in the results on other computers. These are generally due to different round-off algorithms and the different architecture of the central processing unit chip. Run the tests by following the steps below. Test 1: - Attach to the hspexp2.3\test subdirectory and run test1.bat, which will copy data files into the subdirectory and execute HSPEXP. - On the opening screen, type "@". In the small panel that appears, type "..\data\test1.log". - HSPEXP will be run using the keystrokes in ..\data\test1.log as if they were typed in. When plots are displayed on the screen, press the Enter (Return) key for the program to continue reading from ..\data\test1.log. - The files listed below will be produced. These should be compared with the files by the same name found in the hspexp2.3\data subdirectory. For example, if the fc command is available, the first file below can be compared with its counterpart in the hspexp2.3\data directory by typing "fc ..\data\test1.ech test1.ech". test1.ech test1.exs test1.ot1 test1.ot2 test1.out test1.plt test1.uci Test 2: - Attach to the hspexp2.3\test subdirectory and run test2.bat, which will copy data files into the subdirectory and execute HSPEXP. - On the opening screen, type "@". In the small panel that appears, type "..\data\test2.log". - HSPEXP will be run using the keystrokes in ..\data\test2.log as if they were types in. When plots are displayed on the screen, press the Enter key for the program to continue reading from ..\data\test2.log. - The files listed below will be produced and should be compared with the files by the same name found in the hspexp2.3\data subdirectory. test2.ech test2.exs test2.ot1 test2.ot2 test2.ot3 test2.out test2.plt test2.uci The tests are described in the table below, where 'test' is the test number, 'program' is the program used to run the test, and the 'usage' column indicates how a file is used, with i for input, m for modify, and o for output. test program description of test and files file name(s) & usage ---- ------- --------------------------------- -------------------------- 1 hspexp daily simulation hspexp command file test1.log i hunting daily wdm file hunting.wdm m hspf uci file [hunting/test1].uci m hspexp file [hunting/test1].exs m hspexp plot options [hunting/test1].plt m echo of input uci [hunting/test1].ech o simulation results [hunting/test1].out o calibration advice test1.ot1 o statistics test1.ot2 o 2 hspexp hourly simulation hspexp command file test2.log i hunting hourly wdm file hunting.wdm m hspf uci file [hunting/test2].uci m hspexp file [hunting/test2].exs m hspexp plot options [hunting/test2].plt m echo of input uci [hunting/test2].ech o simulation results [hunting/test2].out o calibration advice test2.ot1 o statistics test2.ot2 o H. GRAPHICAL OUTPUT Graphical output is generated using the INTERACTER graphics library from Interactive Software Services, which is bundled in with the program executable. Graphical output may be displayed on the screen or output to a printer or pen plotter. The file INTERACT.INI is used to identify the specific printer and (or) plotter in use with the PC. An example INTERACT.INI is included in the hspexp2.3\bin_data subdirectory and is copied into the current working directory upon execution of HSPEXP unless a file by the same name already exists. Modify the copy of INTERACT.INI in the current working directory as described below to identify the specific printer and (or) plotter in use with your PC. To identify the printer type, include a line in INTERACT.INI containing printer = n where n is one of the following values: 2 - IBM Graphics printer/80 columns 3 - Panasonic KX-P1081 4 - Amstrad DMP 3000 5 - Epson FX type/80 columns 6 - Epson FX type/wide carriage 7 - Epson MX type/80 columns 8 - Epson MX type/wide carriage 9 - Shinwa CP80 10 - HP LaserJet + 11 - HP LaserJet II 12 - IBM Graphics printer/wide carriage 13 - HP PaintJet 14 - HP DeskJet (inc. DeskJet+ and DeskJet 500) 15 - IBM Proprinter/80 columns 16 - IBM Proprinter/wide carriage 17 - Epson LQ type/80 columns 18 - Epson LQ type/wide carriage 19 - IBM Proprinter X24/80 columns 20 - IBM Proprinter X24/wide carriage 21 - HP DeskJet 500C 22 - HP DeskJet 500 23 - Epson JX type/80 columns 24 - Epson JX type/wide carriage 25 - Epson LQ/color 80 columns 26 - Epson LQ/color wide carriage 27 - DEC LN03/LN03+ (ANSI text mode) 28 - HP LaserJet III To identify the plotter type, include a line in INTERACT.INI containing plotter = n where n is one of the following values: 1 - Unspecified HP-GL compatible plotter 2 - Hewlett Packard 7475A using A4 paper 3 - Hewlett Packard 7475A using A3 paper 4 - Epson HI-80 with HP emulation ROM 5 - Facit 4550 A4 6 - Hewlett Packard 7440A A4 (HP Colorpro) 7 - Hewlett Packard 7550A using A4 paper 8 - Hewlett Packard 7550A using A3 paper 9 - Facit 4551 A4 paper 10 - Facit 4551 A3 paper 11 - HP LaserJet III in HP-GL/2 mode (the HPGL output produced will contain escape sequences at the start and end of the file to switch the printer into and out of HP-GL/2 mode) When the printer or plotter is the selected graphical output device, output will appear on the screen simultaneously and there may be some delay as the printer or plotter output is generated. Pressing the Enter key to clear the graphic from the screen is not necessary as when the screen is the selected output device. To output directly to a PostScript printer, no printer identifier need be specified. Instead, create a file named "TERM.DAT" containing the line "GKSPRT 4" in the directory in which you are running the program. Alternatively, raster graphical output will be sent to your printer if a TERM.DAT file does not exist in the directory from which you are running the program or if the TERM.DAT file does not include a line containing "GKSPRT n". Note that the printer is expected to be connected to PRN. If your printer is connected to a different port, produce the INTERACT.PLT file as described below and copy INTERACT.PLT to the port to which your printer is connected. To create a file of raster graphical output that may be copied to a printer at a later time, edit the TERM.DAT file to contain the line "GKSPRT 5". The file INTERACT.PLT will be generated. Copy INTERACT.PLT to your printer using the /B switch to indicate that it is a binary file, e.g., COPY INTERACT.PLT PRN /B. Plotter output, in HP-GL format, cannot be sent directly to your plotter but is placed in INTERACT.PLT, overwriting any previous contents. Copy the INTERACT.PLT file to the port to which the plotter is connected, e.g., COPY INTERACT.PLT COM1. I. CONTACTS Inquiries about this software distribution should be directed to: U.S. Geological Survey Hydrologic Analysis Software Support Team Kathleen M. Flynn e-mail: h2osoft@usgs.gov 437 National Center phone: 703-648-5313 Reston, VA 20192 fax: 703-648-5722