README March 1, 1996 HSPF Hydrological Simulation Program - Fortran HSPF - Version 11.0 1996/03/01 hspf11.0.DGUX.tar.gz - Distribution prepared on a Data General AViiON under DG/UX 5.4 hspf11.0.source.tar.gz - Distribution that includes the source code but no compiled software TABLE OF CONTENTS A. DESCRIPTION B. DOCUMENTATION C. EXTRACTING FILES D COMPILING E. INSTALLING F. RUNNING THE PROGRAM G. TESTING H. CONTACTS A. 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. B. 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. C. EXTRACTING FILES Compressed tar files are used to distribute pre-compiled versions of the software and the source code. All of the files needed to install hspf11.0 are contained in the files hspf11.0.______.tar.gz (where ______ is a string indicating the file contains either the source code or a pre-compiled version of the program for the indicated operating system). The source version of the tar file contains the source code and all other files needed to compile and install the software on a UNIX-based computer. For either type of distribution, the directory hspf11.0 will be created (or overwritten) when the files are extracted from the tar tape. If the hspf11.0 directory already exists, you may want to delete or rename it before extracting the files. For pre-compiled versions, the file lib3.0/lib_data/hspfmsg.wdm is also included, this file is shared by a number of applications. If you already have lib3.0 installed, do not delete or move it. The following are the steps to extract the files from a distribution tar file. Steps in extracting files explanation ---------------------------------------- ----------------------------------- mv hspf11.0.____.tar.gz /usr/opt/wrdapp If the tar file is not already in the directory where you want the distribution installed, move it there. cd /usr/opt/wrdapp If you are not in the directory where the tar file is located, go there. gunzip hspf11.0.____.tar.gz Uncompress the distribution file. tar -xopf hspf11.0.____.tar Extract the distribution files from the tar file. This creates the following directory structure (the contents of each directory are shown to the right): hspf11.0 copy of this README file `-----bin compiled executable `-----doc documentation files (see file Contents) `-----src Makefile (and, with source tar, the source code) `-----test scripts to run verification tests `-----data standard data sets used in verification tests lib3.0 `-----lib_data the message file hspfmsg.wdm Notes: a) The bin subdirectory is not included in the hspf11.0.source.tar.gz distribution, it is created during compilation. b) Source code is included only with the hspf11.0.source.tar.gz distribution. c) 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. d) The software is configured for installation under the directory /usr/opt/wrdapp. The wrdapp directory may be a separate file system mounted at /usr/opt/wrdapp. If you choose to install the software elsewhere, you will need to retrieve the source version of the tar file and compile the software. e) To compile a new version of the software, you will also need: (1) libraries and other data files from the lib3.0 library (lib3.0.______.tar.gz) and (2) ANSI-compliant Fortran 77 compiler. D. COMPILING If you have retrieved a pre-compiled distribution of the software, skip to the Installing section below. If a compiled version of the software is not available for your computer, or if you want to build the executable yourself, follow the instructions in this section. The source code is provided in the hspf11.0.source.tar.gz distribution so that users can generate the executable themselves. Little or no support can be provided for users generating their own versions of the software. In general, the requirements are ANSI-compliant Fortran 77 and a minimum level of knowledge of the compiler and the UNIX operating system. Libraries and data files from the lib3.0 distribution are also required. As provided, the make file, source code, and text version of the message file are set up for use on Data General AViiON workstations running the DG/UX operating system. To generate a new executable and message file, do the following: 1. The values for the indicated variables in the following hspf11.0 files may need to be modified (see the file hspf11.0/doc/versions.doc for more details): may need to be modified ----------------------- version compiler file name variables flags name --------------------- --------- ----------- src/Makefile WrdA FFLAGS F77 fhsmes.inc HMSNAM test/test.sh WrdA 2. Run the Makefile program in the src directory to compile the source. In the directory hspf11.0/src, run the make: cd hspf11.0/src make The hspf11.0/src/Makefile will: a. Create the directory hspf11.0/bin if it does not already exist. b. Compile the source code and place the hspf executable in the directory hspf11.0/bin. E. INSTALLING To make the hspf program easy to use, it should be installed in a directory included in the user's search path. The Makefile in hspf11.0/src contains instructions to optionally place a link in a specified directory to the executable contained in hspf11.0/bin. Use the following commands to do this: cd hspf11.0/src make install [BINDIR=bin_path] where bin_path is the name of a directory in the user's search path. If BINDIR is specified, a link to the executable (hspf11.0/bin/hspf) is placed in the specified directory. If BINDIR is not specified, no link is set and the full pathname of the executable is required to run the program. For example, if the search path is /usr/bin:/usr/opt/bin:/usr/local/bin, you can use the following command to install the program: make install BINDIR=/usr/local/bin Notes: a) Brackets "[xxx]" are used to indicate optional arguments to commands. b) To create and delete links to the hspf executable, the installer must have sufficient rights to the BINDIR directory. F. RUNNING THE PROGRAM After the hspf executable is properly installed (see Installing, above) in a directory that is included in the user's PATH, the program can be executed with the command "hspf". 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. The directory hspf11.0/test contains the script to run the tests. The directory hspf11.0/data contains the input data and the expected results for each test. Tests are usually run in the hspf11.0/test directory, but they can be run in any user directory. Type the following commands to test the program installation: [path]/test.sh [start [stop]] where: path = path to the script use "." if running the tests in the hspf11.0/test directory use full pathname if not running the test in hspf11.0/test start = the number of the first test to perform, default = 1 stop = the number of the last test to perform, default = 9 For example: command what happens -------------------------------------- -------------------------------- ./test.sh runs all of the tests ./test.sh 1 1 runs the first test ./test.sh 2 4 runs tests 2, 3, and 4 /usr/opt/wrdapp/hspf11.0/test/test.sh runs all of the tests After the tests are completed, the results are compared to the expected results (found in hspf11.0/data). See the file check.out; if all goes well, the only differences will be due to different processing times. To clean up after the tests, type the command: ./clean.sh Notes: a) Some of the tests may require input generated by a previous test, so they should be run in sequential order. 1) test 1 requires that the annie program be installed on the system. 2) tests 2 - 13 require the wdm file created in test 1. b) 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. 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 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 output/print file test13.ech o output file test13.out o output display file test13.d69 o output pltgen file test13.p98 o 14 hspf Inputting data to DSS file (ver 11, new test) uci file test14.uci i time series data, pltgen format test01dt.p91 i data management file test1.dss o data management file test2.dss o H. 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 22092 fax: 703-648-5722