README July 30, 2004 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.zip - Compiled Compaq visual fortran (with source code) bmoc1_0b.zip - Compiled Compaq visual fortran (binaries only) bmoc1_0s.zip - 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 distribution file is a zip file. The zip files should be unzipped using a utility that preserves directory structure. One such program is PKZIP for Windows. A shareware version of PKZIP for Windows is available from PKWARE. References to commercial vendors of software products or services are provided solely for the convenience of users when obtaining or using USGS software. Such references do not imply any endorsement by the U.S. Government. 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. 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.zip distribution file (it is created during compilation). b) The source code is not included in the bmoc1_0b.zip 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.zip and bmoc1_0s.zip 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. Compiler options that set all real variables to double precision and that align common blocks must be used. 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 Compaq Visual Fortran Professional Edition 6.5.0 with the /alignment:dcommons and /real_size:64 Fortran compiler options activated. 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