June 5, 1997 Branch-Network Dynamic Flow Model BRANCH - Version: 4.3 1997/06/05 TRKPLOT - Version: 4.1 1997/03/05 SETDIMEN - Version: 4.1 1997/06/05 For assistance, enhancement requests, or bug reports contact the Hydrologic Analysis Software Support Team via email at h2osoft@usgs.gov. See the file doc/branch.txt for descriptions, references, and additional contacts for this software. Instructions for installation, execution, and testing are provided below. TABLE OF CONTENTS A. DISTRIBUTION PACKAGES B. EXTRACTING FILES C. COMPILING D. INSTALLING E. RUNNING THE SOFTWARE F. TESTING A. DISTRIBUTION PACKAGES BRANCH is distributed as a package that contains the simulation model (branch) software, a software dimensioning program (setdimen), a post- processor program (trkplot), data sets, and information files. The software is available either uncompiled (source code), or compiled for one of two operating systems (contains the executable files, but not the source code). The following distribution packages are currently available for UNIX systems: branch4.2.DGUX.tar.gz - Compiled for Data General AViiON under DG/UX 5.4 branch4.2.Solaris.tar.gz - Compiled for Sun SPARCstation 5 under Solaris 2.5 (SunOS 5.5) branch4.2.source.tar.gz - Source code See the file doc/brnupdt.pdf or doc/brnupdt.ps for the input specifications. Included in directory branch4.2/doc is a Portable Document Format (PDF) version and PostScript version of the BRANCH input specifications (brnupdt.pdf and brnupdt.ps). The PDF file is readable and printable on various computer platforms using Acrobat Reader from Adobe. The Acrobat Reader is freely available from the following World Wide Web sites: http://www.adobe.com/ http://www.shareware.com/ and by File Transfer Protocol (FTP) from the following site: ftp.adobe.com (path: /pub/adobe/acrobat) B. EXTRACTING FILES The compressed tar file, named branch4.2.OS.tar.gz, contains all the files needed to install and test BRANCH on a computer with a particular operating system, where OS is a string indicating the operating system for which the distribution is intended. If a version is not available for your operating system, the file branch4.2.source.tar.gz contains the source code and other files needed to compile, install, and test the software on a UNIX-based computer. For either type of distribution, the directory branch4.2 is created (or overwritten) when the files are extracted from the tar file. If the branch4.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. 1. If the tar file is not already in the directory under which you want the distribution installed, move it there. For example: mv branch4.2.____.tar.gz /usr/opt/wrdapp 2. If you are not in the directory where the tar file is located, go there. For example: cd /usr/opt/wrdapp 3. Uncompress the distribution file. For example: gunzip branch4.2.____.tar.gz 4. Extract the distribution files from the tar file. For example: tar -xpof branch4.2.___.tar This creates the following directory structure (the contents of each directory are shown to the right): branch4.2 ; copy of this README file `-----bin ; compiled executables `-----doc ; documentation files `-----src ; Makefile and source code `-----test ; scripts to run verification tests `-----data ; standard data sets used in verification tests Notes: a) The bin directory is not included in the branch4.2.source.tar.gz distribution (it is created during compilation). b) Source code is included only with the branch4.2.source.tar.gz distribution. c) It is recommended that no user files are kept in the branch4.2 directory structure. If you do plan to put files in the branch4.2 directory structure, do so only by creating subdirectories of branch4.2. C. COMPILING If a compiled version of the software is not available for your computer, or if you want to build the executables yourself, follow the instructions in this section. If you have retrieved a pre-compiled distribution of the software, skip to the Installing section below. The source code is provided in the branch4.2.source.tar.gz distribution so that users can generate the executables themselves. No support can be provided for users generating their own versions of the software. In general, the requirements are a Fortran compiler, utility library libutl6.0 (which includes screen prompting, device independent graphics, and Time-Dependent Data Base access routines), GKS or CalComp graphics software, optional Watershed Data Management library (lib3.1) and NetCDF software, and a minimal level of knowledge of the compiler and the UNIX operating system. As provided, the Makefile and source code are set up for use on Data General AViiON workstations running the DG/UX operating system. The BRANCH program graphics are written using CalComp calls. The LIBUTL library includes routines that translate CalComp calls to GKS calls or to INTERACTOR calls. The Makefile is coded to use the CalComp to GKS graphics library. If another CalComp library is available, BRANCH and the Makefile could easily be modified to use it, rather than the default configuration. There are three options for data base support: TDDB, WDM, and (or) NetCDF. The TDDS data base routines are included in the libutl6.0 distributions. The WDM data base routines are included in the lib3.1 distributions. The model can produce NetCDF formatted files, but if this is desired, you will need the NetCDF libraries when compiling the software. An executable is provided that supports TDDB (branch) and WDM (branchwdm) data bases. Neither of these executables support NetCDF output. (See the USGS World Wide Web page at http://h2o.usgs.gov/software/ for information on TDDS and WDM.) To generate new executables, do the following: 1. Change directory to the source directory: cd branch4.2/src 2. Modify the beginning of the file named Makefile to correctly specify system-dependent variables: LibDir Top-level directory for LIBUTL software AnnLib Top-level directory for WDM software PlotObjs Object file for including or not including graphics CalLIB Graphics library to resolve CalComp refererences GraphLib Graphics libraries NetDir Pathname of directory containing NetCDF software CDFLib Pathname of NetCDF library (optional) CDFObjs set to either cdfout.o or cdfoutdm.o F77 Fortran compiler name FFLAGS Fortran compiler flags OS Operating system name SymTbl Symbol table option AR Creation command with options You may also selectively determine the types of executables generated. See the Makefile for details. 3. Provide the file dim_xx.cmn where xx is the string that the operating system name variable (OS) is set to in the Makefile. This file sets a possibly system-dependent parameter specifying the record length of a direct-access file. Versions of dim_xx.cmn are included in the distribution for Data General, Silicon Graphics, and Sun workstations. 4. Use the make program to initiate compilation of the source code and installation of the software. make [BINDIR=directory_for_links] NOTE: see the Installing instructions below for an explanation of BINDIR. The make will: a. create the directories branch4.2/bin and BINDIR if they do not already exist, b. compile the source code, c. place the executables (branch, branchwdm, trkplot, and setdimen) in branch4.2/bin, and d. place links to the executables in BINDIR if specified. D. INSTALLING To make the executables (branch, branchwdm, trkplot, and setdimen) easy to use, they should be installed in a directory included in the user's search path. The Makefile (input instructions to the UNIX make program--located in branch4.2/src) contains instructions to optionally place links in a specified directory to the executables contained in branch4.2/bin. Use the following two commands to do this: cd branch4.2/src make install [BINDIR=directory_for_links] If BINDIR is specified, links to the executables are placed in the specified directory. For example, if your search path consists of: /usr/bin:/usr/opt/bin:/usr/local/bin use the command: make install BINDIR=/usr/local/bin to make the executables accessible from any directory without requiring the full pathname of the software's location. Notes: a) Brackets "[xxx]" are used to indicate optional arguments to commands. b) To create and delete links to the BRANCH executable files, the installer must have sufficient rights in the directory that BINDIR is set to. E. RUNNING THE SOFTWARE After BRANCH is properly installed in a directory that is included in your PATH, the program is initiated using the command: branch. BRANCH requires that the names of files be assigned. The files that were last used with BRANCH in the current directory are retained in a "master" file for subsequent use. Input files may be pre-coded or portions of one file can be modified interactively during a BRANCH session. The BRANCH master file must be maintained in an order specific to the model. It may be manually edited only if the order of records and column positions within the file are retained. The model writes the master file after all files for a particular simulation have been designated. The following is an example master file: Input computation controls : ../data/branch4.ctl Output printed flow results : branch4.prt Input cross-sectional data : ../data/potomac.geo Input initial-condition data: ../data/potomac.ici Input TDDS station reference: Input/Output TDDS data base : Output initial conditions : branch4.ico Output for TRKPLOT input : Output digital plots : branch4.plt Output instantaneous volumes: branch4.ivo Output cumulative volumes : branch4.cvo Output instantaneous flows : Output map-formatted flows : Output flows for BLTM input : Output user-table results : NOTE: Versions of the software other than Data General have been linked to XGKS (a public domain Graphical Kernel System (GKS) software library--XGKS (C) Copyright 1993 UCAR/Unidata) to resolve graphics calls. XGKS is maintained at unidata.ucar.edu. Fonts used by XGKS are dynamically loaded when first referenced. Thus, the fonts must be installed on the machine where the XGKS application executes. The font path is compiled into the XGKS library and is set to /usr/local/unidata/lib/xgksfonts. However, it is possible to have XGKS fonts installed in a different location and still execute the software without having to recompile. To do this set the environment variable "XGKSFontDir" to the new path before executing this application. This variable setting will tell XGKS at runtime where to find its fonts. For example (using C shell syntax): setenv XGKSFontDir /usr/xgks-2.5.5/lib/xgksfonts F. 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 branch4.2/test contains the scripts to run the tests. The directory branch4.2/data contains the input data and expected results for each test. Tests must be run in the directory branch4.2/test. Run the tests using any of the commands in the table below. To test the installation, change to the branch4.2/test directory and type the command: ./test.sh [m [n]] where: m = the number of the first test to perform, default=1 n = the number of the last test to perform, default=5 For example: command what happens ------------------ ------------------------------------ ./test.sh runs all of the tests ./test.sh n runs test 'n' through the last test ./test.sh n m runs test 'n' through 'm' After the tests are completed, the results are compared to the expected results. If all goes well, the only differences will be due to different processing times or pathnames. To clean up after the tests, type the command: ./clean.sh NOTE: 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. 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 branch Sacramento-Freeport model, create master file, all input in single file, output option 0, tabular function of eta demonstrated. program-control data branch1.ctl i responses to program prompts tst1 i printed results branch1.prt o screen messages branch1.log o 2 branch Sacramento-Freeport model, TWRI page 36 example, metric output, single file input, computed versus measured discharge, compare to figures 18 and 19 in TWRI. program-control data branch2.ctl i responses to program prompts go i printed results branch2.prt o screen messages branch2.log o 3 branch Sacramento-Freeport model, TWRI page 38 example, metric output, input split in two file, .ctl and .geo, compare to figure 20 in TWRI. program-control data branch3.ctl i geometry data branch3.geo i responses to program prompts go i printed results branch3.prt o screen messages branch3.log o 4 branch Potomac River model, 25 branches and 25 junctions, wind input, input split into three files-- .ctl, .geo, and .ici, constant nodal flow, 10 external boundaries-- 2 time-series 8 constant. Creates plot of computed discharge. At end of simulation outputs terminal conditions in same format as .ici. program-control data branch4.ctl i Identification and init conditions potomac.ici i geometry data potomac.geo i responses to program prompts go i Ident. and ending conditions branch4.ico o instantaneous flow volumes branch4.ivo o cumulative flow volumes branch4.cvo o printed results branch4.prt o screen messages branch4.log o PostScript file of graphics branch4.plt o 5 branch Potomac River model, 25 branches and 25 junctions, wind input, input split into three files-- .ctl, .geo, and .ici, constant nodal flow, 10 external boundaries-- 2 time-series 8 constant. Computes paths for 7 conservative particles. program-control data branch5.ctl i Identification and init conditions potomac.ici i geometry data potomac.geo i responses to program prompts go i binary file of particle paths branch5.pto o printed results branch5.prt o screen messages branch5.log o trkplot Execute particle-track plotting program, using branch5.pto as input. program-control data trkplot5.ctl i particle path file from test 5 branch5.pto i responses to program prompts go i printed results trkplot5.prt o screen messages trkplot5.log o PostScript file of graphics trkplot5.plt o 6 branch Potomac River model, 25 branches and 25 junctions, wind input, input split into three files-- .ctl, .geo, and .ici, constant nodal flow, 10 external boundaries-- 2 time-series 8 constant. Computes locations for 40 conservative particles along 4 different paths through river (10 particles in each path). program-control data branch6.ctl i branch id and initial conditions branch6.ici i geometry data potomac.geo i responses to program prompts go i binary file of particle paths branch6.pto o printed results branch6.prt o screen messages branch6.log o trkplot Execute particle-track plotting program, using branch6.pto as input. program-control data trkplot6.ctl i particle path from test 6 branch6.pto i responses to program prompts go i printed results trkplot6.prt o screen messages trkplot6.log o PostScript file of graphics trkplot6.plt o * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Good Luck! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *