README APRIL 22, 1996 revised November 04, 1996 DAFLOW Streamflow Routing in Upland Channels or Channel Networks DAFLOW - Version 1.1 1996/04/22 Version 1.2 1996/11/04 daflow1.2.DGUX.tar.gz - Distribution prepared on a Data General AViiON under DG/UX 5.4 daflow1.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 DAFLOW is a digital model for routing streamflow using the diffusion analogy form of the flow equations in conjunction with a Lagrangian solution scheme. The flow model is designed to provide reasonable predictions of discharge and transport velocity using a minimum of field data and calibration. The use of hydraulic geometry coefficients for area and top width is believed to contrib- ute to the model's predictive capability. The flow model is designed to support the BLTM transport model documented by Jobson and Schoellhamer (1987), which simulated the fate and movement of dissolved water-quality constituents through a network of upland streams and rivers. It also should be useful for routine flow routing applications. Program routes flow through a system of open channels and generates output that can be used to drive a transport model such as LTM or BLTM. The program solves the diffusion analogy form of the flow equations and therefore should not be used where backwater effects are significant or where flow reversals occur. The program is very simple and stable. The model has only two adjustable coefficients per branch (the wave celerity and wave attenuation coefficient), and these must remain constant. DAFLOW input and output is to flat files, but auxiliary programs to input data and plot results are available. The program generates a file containing the discharge, cross-sectional area, top width, and tributary inflow at each grid point and time step. The following programs are part of the DAFLOW distribution: cel - interactive program for use in selecting or adjusting hydraulic geometry and wave dispersion values unit - intrp - interpolate data to an even interval bdaflo - interactive program to help construct the daflow input file daflow - diffusiona analagy flow model flwopt - optimization program for daflow wdaflo - version of daflow that uses a wdm file for the time series data flwplt - plot simulated values as well as observed values and compute the RMS errors B. DOCUMENTATION Jobson, H.E., 1989, Users manual for an open-channel streamflow model based on the diffusion analogy: U.S. Geological Survey Water-Resources Investigations Report 89-4133, 73 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 daflow1.2 are contained in the files daflow1.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 daflow1.2 will be created (or overwritten) when the files are extracted from the tar tape. If the daflow1.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 daflow1.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 daflow1.2.____.tar.gz Uncompress the distribution file. tar -xof daflow1.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): daflow1.2 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 Notes: a) The bin subdirectory is not included in the daflow1.2.source.tar.gz distribution; it is created during compilation. b) Source code is included only with the daflow1.2.source.tar.gz distribution. c) It is recommended that no user files be kept in the daflow1.2 directory structure. If you plan to put files in the daflow1.2 directory structure, do so only by creating subdirectories of daflow1.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. e) To compile a new version of the software, you will also need: (1) libraries from the lib3.0 library (lib3.0.______.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 daflow1.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 for the optional FLWPLT program. Libraries from the lib3.0 distribution are also required for the optional FLWPLT and WDAFLO programs. As provided, the make file and source code are set up for use on Data General AViiON workstations running the DG/UX operating system. To generate a new executable, do the following: 1. The values for the indicated variables in the following daflow1.2 files may need to be modified (see the file daflow1.2/doc/versions.doc for more details): may need to be modified ------------------------------- version compiler file name variables flags name library --------------------- ----------- ----------- ------- src/Makefile WrdA Objplt FFLAGS F77 LGks test/test.sh WrdA 2. Run the Makefile program in the src directory to compile the source. In the directory daflow1.2/src, run the make: cd daflow1.2/src make The daflow1.2/src/Makefile will: a. Create the directory daflow1.2/bin and daflow1.2/bin_data, if it does not already exist. b. Compile the source code and place the daflow executable in the directory daflow1.2/bin. E. INSTALLING To make the daflow program easy to use, it should be installed in a directory included in the user's search path. The Makefile in daflow1.2/src contains instructions to optionally place a link in a specified directory to the executable contained in daflow1.2/bin. Use the following commands to do this: cd daflow1.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 (daflow1.2/bin/daflow) 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 daflow executable, the installer must have sufficient rights to the BINDIR directory. F. RUNNING THE PROGRAM After the daflow 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 "daflow". G. TESTING Test data sets are provided to verify that the programs are correctly installed and running on the system. The tests may also be looked at as examples of how to use the programs. The directory daflow1.2/test contains the scripts to run the tests. The directory daflow1.2/data contains the input data and the expected results for each test. Tests are usually run in the daflow1.2/test directory, but they can be run in any user directory. Type the following to run the tests: [path]/test.sh [start [stop]] where: path = path to the script use "." if running the tests in the daflow1.2/test directory use full pathname if not running the test in daflow1.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 tests ./test.sh 1 1 runs the first test ./test.sh 2 4 runs tests 2, 3, and 4 /usr/opt/wrdapp/daflow1.2/test/test.sh runs all of the tests After the tests are completed, the results are compared to the expected results (found in daflow1.2/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. 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 shell script being used, 'no.' 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. Note that if the implementation of GKS you are using does not support postscript output, the graph_.ps files will not be output. file names and usage test step program description of test and files local saved use ---- ---- ------- ----------------------------- --------------------------- 1 Problem F1 1 cel computes coefficients for area and width terminal input file -- test_F1.cm1 i log of screen output -- test_F1.lg1 o 2 bdaflo build input file for daflow terminal input file -- test_F1.cm2 i boundary conditions (flow) bc hinton.q i output flow file flow.in test_F1.in2 o log of screen output -- test_F1.lg2 o 3 daflow compute average flow at grids input flow file (1.2 above) flow.in -- i average flows at grids bltm.flw test_F1.fl3 o flows flow.out test_F1.ot3 o log of screen output -- test_F1.lg3 o 4 flwplt plot the results terminal input file -- test_F1.cm4 i observed flows obs thurmond.q i simulated flows (1.3 above) bltm.flw -- i computed data values plotted plt.out test_F1.pl4 o plot -- test_F1.ps4 o log of screen output -- test_F1.lg4 o 2 Problem F3 1 unit build the intrp input file terminal input file -- test_F3.cm1 i stage-discharge rating table rt hinton.rt i adaps discharge, modified unt.in hinton.unt m output file out test_F3.ot1 o output written to screen -- test_F3.lg1 o 2 intrp interpolate data to even interval terminal input file -- test_F3.cm2 i input file (out, 2.1 above) in -- i boundary conditions file bc test_F3.bc2 o output written to screen -- test_F3.lg2 o 3 bdaflow build daflow input file terminal input file -- test_F3.cm3 i boundary conditons (2.2 above) bc -- i input file (in from 1.2 above) old test_F1.in2 m flow file flow.in test_F3.in3 o output written to screen -- test_F3.lg3 o 4 daflow compute flows at the grids terminal input file -- test_F3.cm4 i input flow file (2.3 above) flow.in -- i output file bltm.flw test_F3.fl4 o output file flow.out test_F3.ot4 o output written to screen -- test_F3.lg4 o 3 Problem D1 1 intrp interpolate data to even interval terminal input file -- test_D1.cm1 i input file in test_D1.in1 i boundary conditions bc test_D1.bc1 o output written to screen -- test_D1.lg1 o 2 bdaflow build input file for daflow terminal input file -- test_D1.cm2 i old input file (2.3 above) old test_F3.in3 m boundary conditions (3.1) bc test_D1.bc1 i flow file flow.in test_D1.in2 o output written to screen -- test_D1.lg2 o 3 daflow compute average flow at grids input flow file (3.2 above) flow.in test_D1.in2 i output flow file flow.out test_D1.ot3 o bltm.flw test_D1.fl3 o output written to screen -- test_D1.lg3 o 4 intrp interpolate data to an even interval terminal input file -- test_D1.cm4 i input file in sandstone.dye m boundary conditions bc test_D1.bc4 o output written to screen -- test_D1.lg4 o 5 bbltm build the input file for cbltm terminal input file -- test_D1.cm5 i boundary conditions (3.4) bc test_D1.bc4 i flow file flow.in test_D1.in5 o input file for cbltm bltm.in test_D1.bl5 o output written to screen -- test_D1.lg5 o 6 cbltm run the multiple branch estuary transport model terminal input file -- test_D1.cm6 i input file (3.5 above) bltm.in test_D1.bl5 i flow conditions (3.3 above) bltm.flw test_D1.fl3 i output file bltm.out test_D1.bl6 o parcel output parcel.out test_D1.ot6 o output written to screen -- test_D1.lg6 o 7 ctplt plot concentration vs time terminal input file -- test_D1.cm7 i flow conditions (3.5 above) bltm.in test_D1.bl5 i parcel output (3.6 above) parcel.out test_D1.ot6 i observed data obs prince.dye i data values plotted plt.out test_D1.pl7 o plot test_D1.ps7 o output written to screen -- test_D1.lg7 o 8 cxplt plot concentrations vs distance terminal input file -- test_D1.cm8 i flow conditions (3.5 above) bltm.in test_D1.bl5 i parcel output (3.6 above) parcel.out test_D1.ot6 i data values plotted plt.out test_D1.pl8 o plot test_D1.ps8 o output written to screen -- test_D1.lg8 o 4 Problem W1 1 annie build wdm file (if the wdm file is in the data directory, it is copied, rather than built) command file -- test_W1.cm1 i archive file -- test_W1.exp i wdm file -- test_W1.wdm o 2 wdaflo compute average flow at grids, input from wdm file input file flow.in test_W1.in2 i wdm file test_W1.wdm i/o output file bltm.flw test_W1.fl2 o output file flow.out test_W1.ot2 o 3 wdaflo compute average flow at grids, input from ascii file input file flow.in test_W1.in3 i output file bltm.flw test_W1.fl3 o output file flow.out test_W1.ot3 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