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 -xof 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 annie2.2 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                 test06.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                test12.d69     o
               output pltgen file                 test12.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     i/o  ?
               data management file               test2.dss     i/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
