March 5, 1996 FESWMS-2DH Finite-element surface-water model for two- dimensional flow in the horizontal plane Version 1.10 FLOMOD - Version: 1.10.DG1 2.5 1995/06/07 DINMOD - Version: 1.10.DG2 2.5 1995/09/05 ANOMOD - Version: 1.10.DG1 2.6 1995/09/05 HPPLOT - Version: 2.5 1995/09/05 feswms_1.10.DGUX.tar.gz - Distribution prepared on a Data General AViiON under DG/UX 5.4 feswms_1.10.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 SOFTWARE G. TESTING H. CONTACTS A. DESCRIPTION The FESWMS-2DH software is used to simulate two-dimensional, depth- integrated, surface-water flows. FESWMS-2DH consists of an input data preparation program (DINMOD), flow model (FLOMOD), simulation output analysis program (ANOMOD), and graphics conversion program (HPPLOT). The programs have been developed to analyze flow at bridge crossings where complicated hydraulic conditions exist, although they may be applied to many types of steady or unsteady flow problems. Shallow rivers, flood plains, estuaries, and coastal seas are examples of surface-water bodies in which flows may be essentially two-dimensional in the horizontal plane. The effects of bed friction and turbulent stresses are considered. Surface wind stresses and the Coriolis force are optionally considered. Flow through bridges and culverts can be modeled either as one-dimensional or two- dimensional flow. Both free-surface and confined two-dimensional flows through bridge openings may be simulated. The model is able to simulate flows with highly irregular topography and geometrical features, such as highway embankments and islands. B. DOCUMENTATION Froehlich, D.C., 1989, HW031.D - User's manual for FESWMS-2DH: U.S. Federal Highway Administrative Report. C. EXTRACTING FILES The compressed tar file, named feswms_1.10.OS.tar.gz contains all the files needed to install and test FESWMS on a computer with a particular operating system, where OS is a string indicating the operating system the distribution is intended for. If a version is not available for your operating system, the file feswms_1.10.source.tar.gz contains the source code and all other files needed to compile, install, and test the software on a UNIX-based computer. For either type of distribution, the directory feswms_1.10 is created (or overwritten) when the files are extracted from the tar file. If the feswms_1.10 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 feswms_1.10.____.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 feswms_1.10.____.tar.gz 4. Extract the distribution files from the tar file. For example: tar -xof feswms_1.10.___.tar This creates the following directory structure (the contents of each directory are shown to the right): feswms_1.10 ; copy of this README file `-----bin ; compiled executables `-----bin_data ; data file required by dinmod and anomod executables `-----doc ; documentation files (manual page, update notes) `-----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 feswms_1.10.source.tar.gz distribution (it is created during compilation). b) Source code is included only with the feswms_1.10.source.tar.gz distribution. c) It is recommended that no user files be kept in the feswms_1.10 directory structure. If you do plan to put files in the feswms_1.10 directory structure, do so only by creating subdirectories of feswms_1.10. D. 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 feswms_1.10.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, GKS or CalComp graphics software, version 3.0 of the ANNIE Interaction Development Environment (AIDE) library (aidelib.a, adwdmlib.a, utillib.a, and wdimex), optionally a DISSPLA graphics library, and a minimal level of knowledge of the compiler and the UNIX operating system. The AIDE library and a GKS graphics library are required to compile a new version of the preprocessor and postprocessor programs. A DISSPLA graphics library is required to compile the hpplot program. As provided, the makefiles and source code are set up for use on Data General AViiON workstations running the DG/UX operating system. The FESWMS-2DH program graphics are written using CalComp calls, the distribution includes routines that translate CalComp calls to GKS calls. If a CalComp library is available, FESWMS-2DH could easily be modified to use it, rather than the GKS library. A CalComp to HPGL library is included, though unsupported. To generate new executables, do the following: 1. Change directory to the source directory: cd feswms_1.10/src 2. Modify the beginning of the file named Makefile to correctly specify system-dependent variables: ALIB Pathname of directory containing AIDE libraries CalLib CalComp graphics library GraphLib Graphics libraries DissLib DISSPLA library F77 Fortran compiler name FFLAGS Fortran compiler flags 3. Use the make program to initiate compilation of the source code and installation of the software: make [BINDIR=directory_for_links] See the Installing instructions below for an explanation of BINDIR. The make will: a. create the directories feswms_1.10/bin and BINDIR if they do not already exist, b. compile the source code, c. place the executables (flomod, dinmod.exe, anomod.exe, and hpplot) in feswms_1.10/bin, d. update the pathname in the scripts (anomod and dinmod) in feswms_1.10/bin, and e. place links to the executables (flomod and hpplot) and scripts (dinmod and anomod) in BINDIR if specified. E. INSTALLING To make the programs (flomod, dinmod, anomod, and hpplot) easy to use, they should be installed in a directory included in the user's search path. FESWMS-2DH preprocessors and postprocessors are executed using UNIX scripts (dinmod and anomod) located in the feswms_1.10/bin directory. These scripts each have a hard-coded pathname that must be set to the installation directory before accessing the software. The Makefile (input instructions to the UNIX make program--located in feswms_1.10/src) contains instructions to automatically update these pathnames and to optionally place links in a specified directory to the FESWMS-2DH programs. Use the following two commands to do this: cd feswms_1.10/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 FESWMS-2DH executable files, the installer must have sufficient rights in the directory that BINDIR is set to. F. RUNNING THE SOFTWARE After the executables flomod and hpplot and the scripts dinmod and anomod are properly installed in a directory that is included in your PATH, they are initiated with the commands "flomod", "dinmod", "anomod", and "hpplot". flomod, dinmod, and anomod expect the files FLOMOD.FIL, DINMOD.FIL, and ANOMOD.FIL, respectively, to exist in your current directory and contain the names of the files to be used during the execution. The following describes the contents of these files: FLOMOD.FIL (8 file names) ________.dat (program control data & grid info) ________.prt (output print file, summary & results of execution) ________.grd (input grid file usually the .grb file from DINMOD execution) ________.int (initial condition file) ________.bon (boundary condition file) ________.wnd (wind data) ________.flw (output flow file, has velocity and water surface elevations) ________.rsr (restart recovery file) DINMOD.FIL (5 file names) ________.dat (program control data & grid info) ________.prt (output print file, summarizes program execution ________.gra (input grid file) ________.grb (output grid file, built by dinmod) ________.plt (HPGL output plot file of grid) ANOMOD.FIL (7 file names) ________.dat (program control data for plotting) ________.prt (output file run summary with messages) ________.grd (grid file, usually the .grd file used in FLOMOD execution) ________.flw (output flow file from FLOMOD execution) ________.grb (optional second grid file) ________.flb (optional second output flow file) ________.plt (HPGL plot file of either velocity vectors or water surface elevations contours) 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 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 "feswms_1.10/test" contains the scripts to run the tests. The directory "feswms_1.10/data" contains the input data and expected results for each test. Tests are usually run in the directory "feswms_1.10/test", but they can be run in any user directory if the installation procedure was completed (make install performed). Run the tests using any of the commands in the table below. To test the installation, change to the feswms_1.10/test directory and type the command: ./test.sh [m [n]] If running from another directory, specify the full path to the script; for example: /usr/opt/wrdapp/feswms_1.10/test/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=3 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 dinmod Channel-pool model, 0.5-M elements file name definition dinmod1.fil i input data dinmod1.dat i response file for interactive screens dinmod1.aide i Printed results dinmod1.prt o Processed grid file dinmod1.grd o PostScript plot file dinmod1.ps o Capture of screen messages dinmod1.log o 1 flomod 16-element test channel file name definition flomod1.fil i input data flomod1.in i Printed results flomod1.prt o Computed flow results flomod1.flw o Capture of screen messages flomod1.log o 1 anomod 16-element test channel file name definition anomod1.fil i input data anomod1.dat i response file for interactive screens anomod1.aide i Processed grid file anomod1.geo i Computed flow results flomod1.flw i Printed results anomod1.prt o PostScript plot file anomod1.ps o Capture of screen messages anomod1.log o 2 dinmod Straight trapezoidal channel file name definition dinmod2.fil i input data dinmod2.dat i response file for interactive screens dinmod2.aide i Printed results dinmod2.prt o Processed grid file dinmod2.grd o PostScript plot file dinmod2.ps o Capture of screen messages dinmod2.log o 2 flomod Straight trapezoidal channel file name definition flomod2.fil i input data flomod2.in i Grid file (same as dinmod2.grd) flomod2.geo i Initial conditions file flomod2.ini i Printed results flomod2.prt o Computed flow results flomod2.flw o Capture of screen messages flomod2.log o 2 anomod Straight trapezoidal channel file name definition anomod2.fil i input data anomod2.dat i response file for interactive screens anomod2.aide i Processed grid file dinmod2.grd i Computed flow results flomod2.flw i Printed results anomod2.prt o PostScript plot file anomod2.ps o Capture of screen messages anomod2.log o 3 dinmod Normal depth reach, straight 10 elements file name definition dinmod3.fil i input data tstrect.dat i response file for interactive screens dinmod3.aide i Printed results dinmod3.prt o Processed grid file dinmod3.grd o PostScript plot file dinmod3.ps o Capture of screen messages dinmod3.log o 3 flomod Rectangular reach file name definition flomod3.fil i input data tstrctf.dat i Grid file flomod3.geo i Printed results flomod3.prt o Computed flow results flomod3.flw o Capture of screen messages flomod3.log o 3 anomod Straight trapezoidal channel file name definition anomod3.fil i input data anomod3.dat i response file for interactive screens anomod3.aide i Processed grid file dinmod2.grd i Computed flow results flomod2.flw i Printed results anomod3.prt o PostScript plot file anomod3.ps o Capture of screen messages anomod3.log o H. CONTACTS Inquiries about this software distribution should be directed to: U.S. Geological Survey Electronic mail: h2osoft@usgs.gov Hydrologic Analysis Software Support Team Fax: 703-648-5722 R. Steve Regan Phone: 703-648-5896 437 National Center Reston, VA 22092 For questions on program content, application, and (or) theory, contact: U.S. Geological Survey Electronic mail: jfulford@usgs.gov Office of Surface Water Fax: 601-688-1577 Janice M. Fulford Phone: 601-688-1501 Building 2101 Stennis Space Center, MS 39529 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Good Luck! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *