README HYSEP Hydrograph Separation Program HYSEP - Version 2.2 1997/06/10 hysep2.2.DGUX.tar.gz - Distribution prepared on a Data General AViiON under DG/UX 5.4 hysep2.2.Solaris.tar.gz - Distribution prepared on a Sun UltraSPARC-II under Solaris 2.6 hysep2.2.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 Performs hydrograph separation, estimating the ground-water, or base flow, component of streamflow. The program provides an automated and consistent method for estimating base flow. Any of the three hydrograph-separation techniques of Pettyjohn and Henning (1979) can be used: fixed interval, sliding interval, or local minimum. B. DOCUMENTATION Sloto, R.A., and Crouse, M.Y., 1996, HYSEP: A computer program for streamflow hydrograph separation and analysis: U.S. Geological Survey Water-Resources Investigations Report 96-4040, 46 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 hysep2.2 are contained in the files hysep2.2.______.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 hysep2.2 will be created (or overwritten) when the files are extracted from the tar file. If the hysep2.2 directory already exists, you may want to delete or rename it before extracting the files. The following are the steps to extract the files from a distribution tar file. Steps in extracting files explanation --------------------------------------- ----------------------------------- mv hysep2.2.____.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 hysep2.2.____.tar.gz Uncompress the distribution file. tar -xof hysep2.2.____.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): hysep2.2 copy of this README file `-----bin compiled executable `-----bin_data message file required during execution `-----doc documentation files (see file Contents) `-----src Makefile (and, with source tar, the source code) `-----msg (with source tar, script & file to build message file) `-----test scripts to run verification tests `-----data standard data sets used in verification tests Notes: a) The bin and bin_data subdirectories are not included in the hysep2.2.source.tar.gz distribution; they are created during compilation. b) Source code is included only with the hysep2.2.source.tar.gz distribution. c) It is recommended that no user files be kept in the hysep2.2 directory structure. If you plan to put files in the hysep2.2 directory structure, do so only by creating subdirectories of hysep2.2. 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 lib library version 3.2 and the iowdm program version 2.3 (lib3.2.______.tar.gz and iowdm2.3_____.tar.gz), (2) ANSI-compliant Fortran 77 compiler, and (3) a Graphical Kernel System (GKS) library. 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 hysep2.2.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. A Graphical Kernel System (GKS) library is required. Libraries and data files from the lib version 3.2 and iowdm version 2.3 distributions are also required. As provided in the source distribution, the software is set up to be compiled under Solaris in the /usr/opt/wrdapp directory. To generate a new executable and message file, do the following: 1. The values for the indicated variables in the following hysep2.2 files may need to be modified (see the file hysep2.2/doc/versions.doc for more details): may need to be modified ------------------------------- version compiler file name variables flags name library --------------------- --------- ----------- ------- src/Makefile WrdA FFLAGS F77 LGks Libr LibI fhysep.inc FNAME msg/wdimex.sh WrdA Libr LibI test/test.sh WrdA 2. Run the Makefile program in the src directory to compile the source and build the message file. In the directory hysep2.2/src, run the make: cd hysep2.2/src make The hysep2.2/src/Makefile will: a. Create the directories hysep2.2/bin and hysep2.2/bin_data, if they do not already exist. b. Compile the source code and place the hysep executable in the directory hysep2.2/bin. c. Run the wdimex.sh script in hysep2.2/msg to build the message file (hyspms.wdm); the file is placed in hysep2.2/bin_data. The french.wdm file will also be built and placed in the hysep2.2/data directory. E. INSTALLING To make the hysep program easy to use, it should be installed in a directory included in the user's search path. The Makefile in hysep2.2/src contains instructions to optionally place a link in a specified directory to the executable contained in hysep2.2/bin. Use the following commands to do this: cd hysep2.2/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 (hysep2.2/bin/hysep) 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 hysep executable, the installer must have sufficient rights to the BINDIR directory. F. RUNNING THE PROGRAM After the hysep 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 "hysep". 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 hysep2.2/test contains the scripts to run the tests. The directory hysep2.2/data contains the input data and the expected results for each test. Tests are usually run in the hysep2.2/test directory, but they can be run in any user directory. Type the following command to test the program installation: [path]/test.sh [start [stop]] where: path = path to the script use "." if running the tests in the hysep2.2/test directory use full pathname if not running the test in hysep2.2/test start = the number of the first test to perform default = 1 stop = the number of the last test to perform default = 4 For example: command what happens ------------------------------------- -------------------------------- ./test.sh runs all of the test tests ./test.sh 1 1 runs the first test test ./test.sh 2 3 runs tests 2 and 3 /usr/opt/wrdapp/hysep2.2/test/test.sh runs all of the test tests After the tests are completed, the results are compared to the expected results (found in hysep2.2/data). See the file check.out; if all goes well, the only differences reported should be in the creation date of the graphical output (.ps) files. To clean up after the tests, type the command: ./clean.sh Notes: 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. Differences in test output may be present particularly in comparing flow-duration tables. As part of the computational technique employed to generate flow-duration tables, comparisons are performed between floating-point values which are often approximated with slight variations on different computer architectures. 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 hysep base-flow separation using local minimum method; ASCII input file in WATSTORE daily values format; output of annual and monthly summaries of hydrograph separation and frequency, flow-duration, and seasonal-distribution tables where base flow given in default units of Mgal/d/mi2 hysep command file test1.log i WATSTORE input file french.gsd i print file of summaries and tables test1.prt o 2 hysep base-flow separation, sliding interval method; binary input file in WDM format; output of annual and monthly summaries where base flow given in units of Mgal/d; output of base flow and surface runoff to WDM data sets hysep command file test2.log i WDM input file french.wdm i/o print file of summaries test2.prt o 3 hysep base-flow separation, fixed interval method; ASCII input file in WATSTORE daily values format; output of annual summary where base flow given in units of ft3/s/mi2; output of base flow and surface runoff to ASCII files in WATSTORE daily values format; hydrographs displayed to screen hysep command file test3.log i WATSTORE input file french.gsd i print file of annual summary test3.prt o base flow, WATSTORE format test3.bsf o surface runoff, WATSTORE format test3.sro o 4 hysep base-flow separation, local minimum method; ASCII input file in WATSTORE daily values format; starting month for analysis changed to January; out- put of annual and monthly summaries; numerical output converted to metric units; frequency-distribution plot, flow-duration plot, and seasonal bar graph generated hysep command file test4.log i WATSTORE input file french.gsd i print file of summaries test4.prt o flow-duration plot, PostScript test4fd.ps o frequency-distribution plot, PostScript test4fq.ps o seasonal bar graph, PostScript test4sb.ps o H. CONTACTS Inquiries about this software distribution should be directed to: U.S. Geological Survey Hydrologic Analysis Software Support Program 437 National Center Reston, VA 20192 e-mail: h2osoft@usgs.gov