README April 22, 1999 BIOMOC A multispecies solute-transport model with biodegradation BIOMOC - Version 1.0 1999/03/10 Instructions for installation, execution, and testing are provided below. After installation, see the file doc\biomoc.txt in the BIOMOC installation directory for summary information on BIOMOC, including documentation references. For assistance, enhancement requests, or to report bugs, contact the Hydrologic Analysis Software Support Program by sending e-mail to h2osoft@usgs.gov. For all versions of Microsoft Windows, this DOS version of BIOMOC must be installed and run using an MS-DOS Command Prompt window. TABLE OF CONTENTS A. SYSTEM REQUIREMENTS B. DISTRIBUTION FILES C. INSTALLING o Installing BIOMOC o BIOMOC directory structure o Making BIOMOC easily accessible D. COMPILING E. RUNNING THE SOFTWARE F. TESTING A. SYSTEM REQUIREMENTS For installation of BIOMOC, 4.4 megabytes of free disk space is needed. To run BIOMOC, the following are necessary: - 386 or greater processor - math coprocessor - 18.8 megabytes of combined free extended memory and free disk space on installation drive (the greater proportion available as memory, the better performance will be) B. DISTRIBUTION FILES The following self-extracting DOS distribution files (containing the software, test data sets, and information files) are currently available. bmoc1_0.exe - Compiled using Lahey Fortran F77L-EM/32 (with source code) bmoc1_0b.exe - Compiled using Lahey Fortran F77L-EM/32 (binaries only) bmoc1_0s.exe - Source code only C. INSTALLING Installing BIOMOC ----------------- These instructions assume that you are installing the software in directory c:\wrdapp, which we strongly recommend. You may use other directories or disk drives, but you must change each occurrence of "c:" and "\wrdapp" in all of the following instructions to the alternate location that you choose. Follow the steps below to install BIOMOC from a distribution file. The steps make use of DOS commands which, for all versions of Microsoft Windows, must be executed in an MS-DOS Command Prompt window. 1. Move to the directory containing the distribution file; for example: c: cd \mydir The directory biomoc1.0 is created (or overwritten) upon extracting the files contained in the distribution file. If the biomoc1.0 directory already exists, you may want to delete or rename it before performing the next step. 2. Extract the files using the command: bmoc1_0 -d -o c:\wrdapp Substitute "bmoc1_0b" or "bmoc1_0s" for "bmoc1_0" if you are installing the executable-code-only or source-code distributions, respectively. Note, be sure to include the -d (restore directory structure) and -o (overwrite existing files) options. BIOMOC directory structure -------------------------- The following directory structure will be created (the contents of each directory are shown to the right): biomoc1.0 copy of this README file `-----bin compiled executable `-----doc documentation files `-----src makefile and source code `-----test batch files to run verification tests `-----data standard data sets used in verification tests Notes: a) The bin directory is not included in the bmoc1_0s.exe distribution file (it is created during compilation). b) The source code is not included in the bmoc1_0b.exe distribution file. c) It is recommended that no user files be kept in the biomoc1.0 directory structure. If you plan to put files in the biomoc1.0 directory structure, do so only by creating subdirectories under biomoc1.0. Making BIOMOC easily accessible ------------------------------- To make the BIOMOC program accessible from any directory, without needing to type the full pathname of the software's location, the biomoc1.0\bin directory must be included in the PATH environment variable. On Windows 3.x and Windows 9x systems, add the following line to the end of AUTOEXEC.BAT: PATH=%PATH%;c:\wrdapp\biomoc1.0\bin Reboot your system after modifying AUTOEXEC.BAT. On Windows NT systems, from the Start menu, select Settings and then Control Panel. Double-click System and select the Environment tab. Enter "PATH" in the Variable field and enter "%PATH%;c:\wrdapp\biomoc1.0\bin" in the Value field. Click Set and then click OK. Initiate and use a new MS-DOS Command Prompt window after making this change. D. COMPILING The source code is provided in the bmoc1_0.exe and bmoc1_0s.exe distribution files so that users can generate the executable themselves. No support can be provided for users generating their own versions of the software. In general, the requirements are a Fortran compiler and a minimal level of knowledge of the compiler and the DOS operating system. As provided, the makefile and source code are optimized for use with the Lahey Fortran F77-EM/32 compiler and supplied make program. To generate a new executable, do the following: 1. Change directory to the source directory: cd biomoc1.0\src 2. Modify the beginning of the file named makefile to correctly specify system-dependent variables: FFLAGS Fortran compiler flags FC Fortran compiler name LINKER Fortran linker name LNKFLGS Fortran linker flags 3. Use the make program to initiate compilation of the source code and installation of the software: make [BINDIR=directory_for_executable] where the optional BINDIR variable is used to specify a directory already included in the PATH environment variable. The make will: a. create the directory biomoc1.0\bin if it does not exist, b. compile the source code, c. place the executable (biomoc.exe) in biomoc1.0\bin, and d. place a copy of the executable in BINDIR if specified. E. RUNNING THE PROGRAM After the BIOMOC executable is properly installed (see INSTALLING, above), the program can be executed with the command "biomoc". Input data for the BIOMOC model is read from the file named "input.dat". Output is written to predefined output file names, all bearing the suffix ".out". BIOMOC has been compiled using the Lahey Fortran F77-EM/32 extended memory compiler version 5.01. The file "F77L3.EER" (from the Lahey compiler) located in biomoc1.0\bin contains error messages. If an error occurs, this file is used to print error messages if the biomoc1.0\bin directory is included in the PATH environment variable; if F77L3.ERR cannot be found, the error will only be identified by number. 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 biomoc1.0\test contains the batch files to run the tests. The directory biomoc1.0\data contains the input data and expected results for each test. Tests are usually run in the directory biomoc1.0\test, but they can be run in any user directory by assigning the BIOMOC installation directory (c:\wrdapp\biomoc1.0) to the "topdir" variable in biomoc1.0\test\test.bat. To test the installation, change to the biomoc1.0\test directory and type the command: test [m [n]] If running from another directory (provided that the "topdir" variable in test.bat was modified appropriately), specify the full path to the batch file; for example: c:\wrdapp\biomoc1.0\test\test [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 runs all of the tests test n runs test 'n' through the last test test n m runs test 'n' through 'm' After the tests are completed, the results are compared to the expected results. If all goes well, there should be no differences. To clean up after the tests, with biomoc1.0\test as the current working directory, type the command: clean The tests are described in the table below. Test is the test number and the usage column indicates how a file is used, with i for input and o for output. Note that the normal file suffixes of the input and output files have been replaced with "t1," "t2," and "t3" to indicate the test to which each set of files corresponds; the input file is normally named "input.dat" and the output files normally bear a ".out" suffix. test description of test and files file name & usage ---- ------------------------------------- ----------------- 1 Steady-state zero- and first-order decay BIOMOC input file input.t1 i summary of processed data biomoc.t1 o final heads biohead.t1 o grid block velocities biovel.t1 o final concentrations for solute 1 biocon1.t1 o final concentrations for solute 2 biocon2.t1 o final concentrations for population 1 biopop1.t1 o observation location 1 concentrations bioobs1.t1 o observation location 2 concentrations bioobs2.t1 o observation location 3 concentrations bioobs3.t1 o observation location 4 concentrations bioobs4.t1 o observation location 5 concentrations bioobs5.t1 o concentration profiles bioprof.t1 o 2 Transient zero- and first-order decay BIOMOC input file input.t2 i summary of processed data biomoc.t2 o final heads biohead.t2 o grid block velocities biovel.t2 o final concentrations for solute 1 biocon1.t2 o final concentrations for solute 2 biocon2.t2 o final concentrations for population 1 biopop1.t2 o observation location 1 concentrations bioobs1.t2 o observation location 2 concentrations bioobs2.t2 o observation location 3 concentrations bioobs3.t2 o observation location 4 concentrations bioobs4.t2 o observation location 5 concentrations bioobs5.t2 o concentration profiles bioprof.t2 o 3 Aerobic degradation of toluene and benzene BIOMOC input file input.t3 i summary of processed data biomoc.t3 o final heads biohead.t3 o grid block velocities biovel.t3 o final concentrations of toluene biocon1.t3 o final concentrations of benzene biocon2.t3 o final concentrations of oxygen biocon3.t3 o final conc. of toluene degraders biopop1.t3 o final conc. of benzene degraders biopop2.t3 o outflow concentrations bioobs1.t3 o concentration profiles bioprof.t3 o