README May 10, 1996 revised November 04, 1996 BLTM & DAFLOW Branched Lagrangian Transport Model & Streamflow Routing in Upland Channels or Channel Networks BLTM - Version 1.1 1996/05/10 Version 1.2 1996/11/04 DAFLOW - Version 1.1 1996/04/22 Version 1.2 1996/11/04 bltm1.2.DGUX.tar.gz - Distribution prepared on a Data General AViiON under DG/UX 5.4 bltm1.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 BLTM uses Lagrangian calculations that are unconditionally stable and based upon a reference frame that moves at a velocity equal to the mean channel flow velocity. BLTM results are within the accuracy required by most water-quality studies. The BLTM is easily applied to unsteady flows in networks of one-dimensional channels with fixed geometry and tributary inflows. Reaction kinetics for up to 10 constituents are provided in a user-written decay-coefficient subroutine. Postprocessor plot programs improve the utility of the model. The model routes any number of interacting constituents through a system of one-dimensional channels. The model solves the one-dimensional convective-diffusion equation with reaction kinetics. 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. DAFLOW 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 & BLTM distribution: cel - interactive program for use in selecting or adjusting hydraulic geometry and wave dispersion values unit - reads ADAPS formated unit values and a rating table and formats data for daflow intrp - interpolate data to an even interval mrg - builds a table of data by merging parts of other tables 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 equltmp- computes equilibrium temperature from daily temperature extremes solar - compute solar radiation from empirical equations bbltm - build input file for cbltm and tbltm versions of bltm bqual2e- build input file for qbltm version of bltm cbltm - bltm model, decay coefficients provided by user qbltm - bltm model, constituent coefficients calculated using qual2e kinetics tbltm - bltm model, simplified temperature model to calculate the constituent coefficients flwplt - plot simulated values as well as observed values and compute the RMS errors ctplt - plot concentration vs time and compute RMS error cxplt - plot concentration vs distance B. DOCUMENTATION Schoellhamer, D.H., and Jobson, H.E., 1986, Programmers manual for a one-dimensional Lagrangian transport model: U.S. Geological Survey Water-Resources Investigations Report 86-4144, 101 p. Schoellhamer, D.H., and Jobson, H.E., 1986, Users manual for a one-dimensional Lagrangian transport model: U.S. Geological Survey Water-Resources Investigations Report 86-4145, 95 p. Jobson, H.E., and Schoellhamer, D.H., 1987, Users manual for a Branched Lagrangian transport model: U.S. Geological Survey Water-Resources Investigations Report 87-4163, 73 p. 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 bltm1.2 are contained in the files bltm1.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 bltm1.2 will be created (or overwritten) when the files are extracted from the tar tape. If the bltm1.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 bltm1.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 bltm1.2.____.tar.gz Uncompress the distribution file. tar -xof bltm1.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): bltm1.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 bltm1.2.source.tar.gz distribution; it is created during compilation. b) Source code is included only with the bltm1.2.source.tar.gz distribution. c) It is recommended that no user files be kept in the bltm1.2 directory structure. If you plan to put files in the bltm1.2 directory structure, do so only by creating subdirectories of bltm1.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 an ANSI-compliant Fortran 77 compiler. Libraries from the lib3.0 library (lib3.0.______.tar.gz) are required to recompile wdaflow. The graphics programs will require either (1) a Graphical Kernel System (GKS) library and libraries from the lib3.0 library (lib3.0.______.tar.gz), or (2) the Prior DISSPLA 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 bltm1.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, CTPLT, and CXPLT programs. Libraries from the lib3.0 distribution are also required for the optional FLWPLT, CTPLT, CXPLT 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 bltm1.2 files may need to be modified (see the file bltm1.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 testu.sh WrdA 2. Run the Makefile program in the src directory to compile the source. In the directory bltm1.2/src, run the make: cd bltm1.2/src make The bltm1.2/src/Makefile will: a. Create the directory bltm1.2/bin and bltm1.2/bin_data, if it does not already exist. b. Compile the source code and place the executables in the directory bltm1.2/bin. E. INSTALLING To make the programs easy to use, they should be installed in a directory included in the user's search path. The Makefile in bltm1.2/src contains instructions to optionally place a link in a specified directory to the executables contained in bltm1.2/bin. Use the following commands to do this: cd bltm1.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, links to the executables (bltm1.2/bin/______) are placed in the specified directory. If BINDIR is not specified, no links are 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 executables, the installer must have sufficient rights to the BINDIR directory. F. RUNNING THE PROGRAM After the executables are properly installed (see Installing, above) in a directory that is included in the user's PATH, the programs can be executed by name, for example daflow 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 bltm1.2/test contains the scripts to run the tests. The directory bltm1.2/data contains the input data and the expected results for each test. Tests are usually run in the bltm1.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 bltm1.2/test directory use full pathname if not running the test in bltm1.2/test start = the number of the first test to perform, default = 1 stop = the number of the last test to perform, default = 6 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/bltm1.2/test/test.sh runs all of the tests After the tests are completed, the results are compared to the expected results (found in bltm1.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 5 Problem T1 1 intrp interpolate data to even interval terminal input file -- test_T1.cm1 i input file in atlanta.flw i boundary conditions bc test_T1.bc1 o output written to screen -- test_T1.lg1 o 2 bdaflow build input file for daflow terminal input file -- test_T1.cm2 i boundary conditions (5.1) bc test_T1.bc1 i flow file flow.in test_T1.in2 o output written to screen -- test_T1.lg2 o 3 daflow compute average flow at grids input flow file (5.2) flow.in test_T1.in2 i output flow file flow.out test_T1.ot3 o average flows at grids bltm.flw test_T1.fl3 o output written to screen -- test_T1.lg3 o 4 flwplt plot the results terminal input file -- test_T1.cm4 i simulated flows (5.3) bltm.flw test_T1.fl3 i computed data values plotted plt.out test_T1.pl4 o output written to screen -- test_T1.lg4 o 5 bdaflow build input file for daflow terminal input file -- test_T1.cm5 i boundary conditions (plt.out) bc test_T1.pl4 i boundary conditions old test_T1.ol5 i (modified 5.2 flow.in) flow file flow.in test_T1.in5 o output written to screen -- test_T1.lg5 o daflow compute average flow at grids input flow file (5.5) flow.in test_T1.in5 i output flow file flow.out test_T1.ot5 o average flows at grids bltm.flw test_T1.fl5 o output written to screen -- test_T1.lg5 o 6 intrp interpolate data to an even interval terminal input file -- test_T1.cm6 i input file in rte280.tmp i boundary conditions bc test_T1.bc6 o output written to screen -- test_T1.lg6 o 7 bbltm build the input file for cbltm terminal input file -- test_T1.cm7 i boundary conditions (5.6) bc test_T1.bc6 i flow file flow.in test_T1.in7 o input file for cbltm bltm.in test_T1.bl7 o output written to screen -- test_T1.lg7 o 8 equltmp compute equilibrium temperature terminal input file -- test_T1.cm8 i output out test_T1.ot8 o output written to screen -- test_T1.lg8 o 9 tbltm run the multiple branch estuary transport model, temperature terminal input file -- test_T1.cm9 i input file temp.in test_T1.in9 i input file bltm.in test_T1.bl7 i flow conditions (5.5 above) bltm.flw test_T1.fl5 i output file bltm.out test_T1.bl9 o parcel output parcel.out test_T1.ot9 o output written to screen -- test_T1.lg9 o 6 Problem Q2a 1 intrp interpolate data to even interval terminal input file -- test_Q2a.cm1 i input file in rte280.flw i boundary conditions bc test_Q2a.bc1 o output written to screen -- test_Q2a.lg1 o 2 bdaflow build input file for daflow terminal input file -- test_Q2a.cm2 i boundary conditions (6.1) bc test_Q2a.bc1 i existing file old test_Q2a.ol2 i flow file flow.in test_Q2a.in2 o output written to screen -- test_Q2a.lg2 o 3 bdaflow terminal input file -- test_Q2a.cm3 i boundary conditions bc sweetwater.flw i existing file (6.2) old test_Q2a.in2 i flow file flow.in test_Q2a.in3 o output written to screen -- test_Q2a.lg3 o 4 daflow input flow file (6.3) flow.in test_Q2a.in3 i output flow file flow.out test_Q2a.ot4 o average flows at grids bltm.flw test_Q2a.fl4 o output written to screen -- test_Q2a.lg4 o 5 flwplt terminal input file -- test_Q2a.cm5 i simulated flows (6.4) bltm.flw Test_Q2a.fl4 i observed flows obs whitesburg.flw i computed data values plotted plt.out test_Q2a.pl5 o output written to screen -- test_Q2a.lg5 o 6 intrp terminal input file -- test_Q2a.cm6 i input file (6.5, edited) in test_Q2a.pl6 i boundary conditions bc test_Q2a.bc6 o output written to screen -- test_Q2a.lg6 o 7 bdaflow terminal input file -- test_Q2a.cm7 i boundary conditions (6.6) bc test_Q2a.bc6 i existing file old test_Q2a.ol7 i flow file flow.in test_Q2a.in7 o output written to screen -- test_Q2a.lg7 o 8 daflow input flow file (6.7) flow.in test_Q2a.in8 i output flow file flow.out test_Q2a.ot8 o average flows at grids bltm.flw test_Q2a.fl8 o output written to screen -- test_Q2a.lg8 o 7 Problem Q2b 1 intrp terminal input file -- test_Q2b.cm1 i input file in rte280.in1 i boundary conditions bc test_Q2b.bc1 o output written to screen -- test_Q2b.lg1 o 2 mrg terminal input file -- test_Q2b.cm2 i boundary conditions old.bc rte280.bc i boundary conditions in test_Q2b.bc1 i merged boundary conditons bc test_Q2b.bc2 o output written to screen -- test_Q2b.lg2 o 3 intrp terminal input file -- test_Q2b.cm3 i input file in rte280.in3 i boundary conditions bc test_Q2b.bc3 o output written to screen -- test_Q2b.lg3 o 4 mrg terminal input file -- test_Q2b.cm4 i boundary conditions old.bc test_Q2b.bc2 i boundary conditions in test_Q2b.bc3 i merged boundary conditons bc test_Q2b.bc4 o output written to screen -- test_Q2b.lg4 o 5 bbltm terminal input file -- test_Q2b.cm5 i boundary conditions (7.4) bc test_Q2b.bc4 i flow file flow.in test_Q2a.in8 i input file for cbltm bltm.in test_Q2b.bl5 o output written to screen -- test_Q2b.lg5 o 6 bbltm terminal input file -- test_Q2b.cm6 i old file (bltm.in 7.5) old test_Q2b.bl5 i boundary conditions bc grid3.bc i input file for cbltm bltm.in test_Q2b.bl6 o output written to screen -- test_Q2b.lg6 o 7 bbltm terminal input file -- test_Q2b.cm7 i old file (bltm.in 7.6) old test_Q2b.bl6 i boundary conditions bc grid5.bc i input file for cbltm bltm.in test_Q2b.bl7 o output written to screen -- test_Q2b.lg7 o 8 Problem Q2c 1 equltmp terminal input file -- test_Q2c.cm1 i output out test_Q2c.ot1 o output written to screen -- test_Q2c.lg1 o 2 solar terminal input file -- test_Q2c.cm2 i output out test_Q2c.ot2 o output written to screen -- test_Q2c.lg2 o 3 mrg terminal input file -- test_Q2c.cm3 i boundary conditions old.bc test_Q2c.ot3 i boundary conditions (8.2) in test_Q2c.ot2 i merged boundary conditons bc test_Q2c.bc3 o output written to screen -- test_Q2c.lg3 o 4 bqual2e terminal input file -- test_Q2c.cm4 i boundary conditions bc test_Q2c.bc4 i modified bc 8.3 input file for bltmq qual2e.in test_Q2c.in4 o output written to screen -- test_Q2c.lg4 o 5 qbltm terminal input file -- test_Q2c.cm5 i input file qual2e.in test_Q2c.in4 i input file bltm.in test_Q2b.bl7 i flow conditions bltm.flw test_Q2a.fl8 i output file bltm.out test_Q2c.bl5 o parcel.output parcel.out test_Q2c.ot5 o output written to screen -- test_Q2c.lg5 o ---- ---- ------- ----------------------------- --------------------------- u.1 test program options 1 cel terminal input file -- test1.cm1 i log of screen output -- test1.lg1 o 2 cel terminal input file -- test1.cm2 i log of screen output -- test1.lg2 o 3 cel terminal input file -- test1.cm3 i log of screen output -- test1.lg3 o 4 cel terminal input file -- test1.cm4 i log of screen output -- test1.lg4 o 5 cel terminal input file -- test1.cm5 i log of screen output -- test1.lg5 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