README June 11, 1997 HSPF Hydrological Simulation Program - Fortran HSPF - Version 11.0 1996/03/01 hspf11_0.exe - self-extracting DOS distribution prepared on an IBM-compatible PC TABLE OF CONTENTS A. SYSTEM REQUIREMENTS B. DESCRIPTION C. DOCUMENTATION D. INSTALLING o Installing HSPF from self-extracting executable o Installing HSPF from distribution diskette o HSPF directory structure o Making HSPF easily accessible E. RUNNING THE PROGRAM F. TESTING G. CONTACTS A. SYSTEM REQUIREMENTS For installation of HSPF, 7.7 megabytes of free disk space is needed. To run HSPF, the following are necessary: - 386 or greater processor - math coprocessor - 17.3 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 1.5 megabytes free disk space in current working directory Because of significant memory space requirements, HSPF initialization may take a few minutes. IMPORTANT NOTE: When the full 17.3 megabytes of memory space needed to run HSPF 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 HSPF in a Windows 95 MS-DOS window, default settings will not allow virtual memory to be used and, if there is insufficient physical memory available, HSPF 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. B. DESCRIPTION The Hydrological Simulation Program--Fortran (HSPF) simulates for extended periods of time the hydrologic, and associated water quality, processes on pervious and impervious land surfaces and in streams and well-mixed impound- ments. HSPF uses continuous rainfall and other meteorologic records to compute streamflow hydrographs and pollutographs. HSPF simulates interception soil moisture, surface runoff, interflow, base flow, snowpack depth and water content, snowmelt, evapotranspiration, ground-water recharge, dissolved oxygen, biochemical oxygen demand (BOD), temperature, pesticides, conservatives, fecal coliforms, sediment detachment and transport, sediment routing by particle size, channel routing, reservoir routing, constituent routing, pH, ammonia, nitrite-nitrate, organic nitrogen, orthophosphate, organic phosphorus, phytoplankton, and zooplankton. Program can simulate one or many pervious or impervious unit areas discharging to one or many river reaches or reservoirs. Frequency-duration analysis can be done for any time series. Any time step from 1 minute to 1 day that divides equally into 1 day can be used. Any period from a few minutes to hundreds of years may be simulated. HSPF is generally used to assess the effects of land-use change, reservoir operations, point or nonpoint source treatment alternatives, flow diversions, etc. Separate programs are available for data preprocessing and for postprocessing for statistical and graphic output of any constituent at any time step for any length of time. See also the Expert System for Calibration of HSPF (hspexp2.3). The hspexp program interactively allows the user to edit the input uci file for 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. C. DOCUMENTATION 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. D. INSTALLING Installing HSPF from self-extracting executable ----------------------------------------------- To install HSPF from the self-extracting executable, follow the steps below, replacing with the drive letter where you want to install HSPF 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: hspf11_0 -d :\[directory] Note: be sure to include the -d option and ":\" in the command. Examples are: hspf11_0 -d c:\ hspf11_0 -d c:\wrdapp 3. Go to the newly-created hspf11.0 directory where the files have been extracted. For example: c: cd \wrdapp\hspf11.0 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, hspf11.0\bin\hspf.bat and hspf11.0\test\hspf.bat which are necessary for successful execution of HSPF. Be sure that no errors occur when executing the above install command. Installing HSPF from distribution diskette ------------------------------------------ To install HSPF from distribution diskette onto your hard drive, type :install : :[\directory] For example, if your floppy drive is a: and you want to install HSPF directly under the root directory on the c: drive, you would type a:install a: c: This will create the directory c:\hspf11.0. As an additional example, if you wanted to install HSPF under a directory named "wrdapp" on the c: drive, you would type a:install a: c:\wrdapp This will create the directory c:\wrdapp\hspf11.0. HSPF directory structure ------------------------ The following directory structure will be created (the contents of each directory are shown to the right): hspf11.0 copy of this README file `-----bin compiled executable, batch file to run program `-----bin_data file required during execution `-----doc documentation files `-----test batch file to run program; used to run verification tests `-----data standard data sets used in verification tests lib3.0 `-----lib_data the message file hspfmsg.wdm Note: It is recommended that no user files be kept in the hspf11.0 directory structure. If you plan to put files in the hspf11.0 directory structure, do so only by creating subdirectories under hspf11.0. Making HSPF easily accessible ----------------------------- To make the HSPF program accessible from any directory, the hspf11.0\bin directory should be included in the PATH environment variable. Add a line similar to the following to AUTOEXEC.BAT: PATH=%PATH%;C:\hspf11.0\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 hspf executable is properly installed (see INSTALLING, above), the program can be executed with the command "hspf". F. 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 hspf11.0\test directory. The directory hspf11.0\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: Some of the tests may require input generated by a previous test, so they should be run in sequential order. 1) test 1.a requires that the annie program be installed on the system. 2) tests 1.b - 13 require the wdm file created in test 1.a. Run the tests by following the steps below. Test 1.a: - Attach to the hspf11.0\test subdirectory and type "annie" to execute ANNIE (if the annieX.x\bin directory has not been included in the PATH environment variable so that ANNIE can be executed from any directory, type the full path name of annieX.x\bin\annie, where X.x is the version of ANNIE installed on your system, being sure to include the drive and directory under which ANNIE is installed). - On the opening screen, type "@". In the small panel that appears, type "..\data\testa.log". ANNIE will be run using the keystrokes in ..\data\testa.log as if they were typed in. The files test.wdm and test2.wdm will be produced and are used in the remaining tests. Tests 1.b-13: - Attach to the hspf11.0\test subdirectory and type "hspf" to execute the program. - When prompted for the name of the your input file, type "..\data\testNN.uci" where NN is the number of the test, 01-13. - The files listed below will be produced. These should be compared with the files by the same name found in the hspf11.0\data subdirectory. For example, if the fc command is available, the first file below can be compared with its counterpart in the hspf11.0\data directory by typing "fc ..\data\test01.ech test01.ech". test01.ech test06.ech test09.d65 test11.d67 test13.ech test02.ech test06.out test09.ech test11.ech test13.out test03.ech test07.d63 test09.out test11.eng test04.d61 test07.ech test09.p93 test11.met test04.ech test07.out test10.d66 test12.d68 test05.d62 test08.d64 test10.ech test12.d69 test05.ech test08.ech test10.out test12.ech test05.out test08.out test10.p94 test12.out test05.p92 test10.p95 test12.p97 test12.p98 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, o for output, and i/o for both input and output. test program description of test and files file name & usage ---- ------- --------------------------------- ----------------- 1.a annie Create the wdm files, add DSN's and attributes to test.wdm; add DSN's, attributes, and data to test2.wdm (ver 10 tests 1 & 2) annie command file testa.log i data sets for test.wdm testa1.exp i data sets for test2.wdm testa2.exp i data management file test.wdm o data management file test2.wdm o 1.b hspf MUTSIN operation to read daily data from a PLTGEN file and add it to the wdm file, 10 time series are processed (ver 10 test 3) uci file test01.uci i time-series data, PLTGEN format test01dt.p91 i data management file test.wdm i/o output/print file test01.ech o 2 hspf COPY operation to read 7 HYDHR format files and add the time series to the wdm file (ver 10 test 4) uci file test02.uci i time-series data, seq format test02dt.s31 i time-series data, seq format test02dt.s32 i time-series data, seq format test02dt.s33 i time-series data, seq format test02dt.s34 i time-series data, seq format test02dt.s35 i time-series data, seq format test02dt.s36 i time-series data, seq format test02dt.s37 i data management file test.wdm i/o output/print file test02.ech o 3 hspf COPY operation to read 2 HYDDAY (daily time step) files and add the time series to the wdm file (ver 10 test test 5) uci file test03.uci i time-series data, seq format test03dt.s57 i time-series data, seq format test03dt.s58 i data management file test.wdm i/o output/print file test03.ech o 4 hspf DISPLYs 19 hourly time series from the wdm file, the data is output to a separate file (ver 10 test 6) uci file test04.uci i data management file test.wdm i/o output/print file test04.ech o time-series DISPLYs test04.d61 o 5 hspf Simulation at an hourly time step includes 3 PERLNDs with SNOW, 1 DISPLY output to a file, and 4 time series are output to a PLTGEN file (ver 10 test 7) uci file test05.uci i data management file test.wdm i/o output/print file test05.ech o output file of monthly summary test05.out o time-series DISPLYs test05.d62 o time-series PLTGEN test05.p92 o 6 hspf The PLTGEN file from test 5 is read with a MUTSIN operation, and 2 DURANL operations are run on that data and output to a file (ver 10 test 8) uci file test06.uci i time-series PLTGEN test06dt.p92 i data management file test.wdm i/o output/print file test06.ech o duration analysis output test06.out o 7 hspf Has 3 PERLND operations that include SPEC-ACTIONS, ATEMP, SNOW, PWATER, SEDMNT, PSTEMP, PWTGAS, PQUAL, MSTLAY, and PEST; 4 DISPLY operations are output to a file (ver 10 test 9) uci file test07.uci i data management file test.wdm i/o output/print file test07.ech o output file of monthly summary test07.out o time-series DISPLYs test07.d63 o 8 hspf Has 3 PERLND operations that include SPEC-ACTIONS, SNOW, PWATER, SEDMNT, PSTEMP, MSTL, NITR, PHOS, and TRAC; 3 DISPLY operations are output to a file (ver 10 test 10) uci file test08.uci i data management file test.wdm i/o output/print file test08.ech o output file of monthly summary test08.out o time-series DISPLYs test08.d64 o 9 hspf Has 1 PERLND and 4 RCHRES with SNOW, PWATER, and FTABLES. 3 DISPLYs and 1 PLTGEN are output to a file. (ver 10 test 12) uci file test09.uci i data management file test.wdm i/o output/print file test09.ech o output file of monthly summary test09.out o time-series pltgen test09.p93 o time-series DISPLYs test09.d65 o 10 hspf Has PERLND, IMPLND, and RCHRES with sediment and water quality operations; also includes GENER, DISPLY, and PLTGEN (ver 10 test 13) uci file test10.uci i data management file test.wdm i/o output/print file test10.ech o output file of monthly summary test10.out o time-series pltgen test10.p94 o time-series pltgen test10.p95 o time-series DISPLYs test10.d66 o 11 hspf PERLND with SNOW, PWATER, COPY, DISPLY, and PLTGEN; uses metric units (ver 10 test 14, modified) uci file test11.uci i data management file test.wdm i/o output/print file test11.ech o output/print, english units test11.eng o output/print, metric units test11.met o time-series DISPLYs test11.d67 o time-series pltgen test11.p96 0 12 hspf PERLND and IMPLND with RCHRES using new features from v 11 (ver 11, new test) uci file test12.uci i data management file test.wdm i/o ? data management file test2.wdm i/o ? output/print file test12.ech o output file test12.out o output display file test12.d68 o output pltgen file test12.p97 o 13 hspf Water categories and conditional special actions (ver 11, new test) uci file test13.uci i data management file test.wdm i/o ? output/print file test13.ech o output file test13.out o output display file test13.d69 o output pltgen file test13.p98 o G. 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