README July 14, 1999 MOC3D A Three-Dimensional Method-Of-Characteristics Solute-Transport Model MOC3D - Version: 3.01 1999/07/08 Instructions for installation, execution, and testing are provided below. After installation, see the file doc\moc3d.txt in the MOC3D installation directory for summary information on MOC3D, including documentation references. Portable Document Format (PDF) files of the documentation are found in the same location; for other formats of the documentation, see http://water.usgs.gov/software/moc3d.html. 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 MOC3D 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 MOC3D o MOC3D directory structure o Making MOC3D easily accessible D. COMPILING E. RUNNING THE SOFTWARE F. TESTING A. SYSTEM REQUIREMENTS For installation of MOC3D, 8.5 megabytes of free disk space is needed. To run MOC3D, the following are necessary: - 386 or greater processor - math coprocessor - 15.9 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. m3d3_01.exe - Compiled using Lahey Fortran F77L-EM/32 (with source code) m3d3_01s.exe - Source code only C. INSTALLING Installing MOC3D ----------------- 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 MOC3D 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 moc3d3.01 is created (or overwritten) upon extracting the files contained in the distribution file. If the moc3d3.01 directory already exists, you may want to delete or rename it before performing the next step. 2. Extract the files using the command: m3d3_01 -d -o c:\wrdapp Substitute "m3d3_01s" for "m3d3_01" if you are installing the source-code distribution. Note, be sure to include the -d (restore directory structure) and -o (overwrite existing files) options. MOC3D directory structure -------------------------- The following directory structure will be created (the contents of each directory are shown to the right): moc3d3.01 ; copy of this readme file `-----bin ; compiled executable and Lahey error file `-----doc ; documentation files (see file "contents") `-----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 m3d3_01s.exe distribution (it is created during compilation). b) Source code is included only with the m3d3_01s.exe distribution. c) It is recommended that no user files be kept in the moc3d3.01 directory structure. If you do plan to put files in the moc3d3.01 directory structure, do so only by creating subdirectories of moc3d3.01. Making MOC3D easily accessible ------------------------------- To make the MOC3D program accessible from any directory, without needing to type the full pathname of the software's location, the moc3d3.01\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\moc3d3.01\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\moc3d3.01\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 m3d3_01.exe and m3d3_01s.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 moc3d3.01\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 moc3d3.01\bin if it does not exist, b. compile the source code, c. place the executable (moc3d.exe) in moc3d3.01\bin, and d. place a copy of the executable in BINDIR if specified. E. RUNNING THE SOFTWARE MOC3D 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 moc3d3.01\bin contains error messages. If an error occurs, this file is used to print error messages if the moc3d3.01\bin directory is included in the PATH environment variable; if F77L3.ERR cannot be found, the error will only be identified by number. The X array is dimensioned to 4,000,000 and is large enough for a model having approximately 20,000 cells and 200,000 particles. After MOC3D is properly installed in a directory that is included in your PATH, the program is initiated using the command: moc3d. MOC3D uses two Name Files to indicate which files are to be used in the simulation. MOC3D prompts the user to enter the name of the MODFLOW Name File, and then it automatically opens all the files specified in that Name File and the MOC3D Name File whose name is specified in the MODFLOW Name File. Each record of the Name Files specify a file type, unit number, and file name for each file used in the MOC3D simulation. The file type is either "LIST", "DATA", "DATA(BINARY)", or a 3-character package name such as RCH. In addition to defining the file names and unit numbers, the Name Files activate packages. That is, the IUNIT elements that correspond to the packages indicated by the file types are turned "on". The IUNIT record in the BAS Package input file is ignored; packages can now only be activated through the Name Files. The Name File is read on unit 99. Units 98 and 97 are used to facilitate batch mode execution. If the file modflow.bf exists in the current directory then MOC3D reads the name of the MODFLOW Name File from it and records messages produced by MOC3D in the file modflow.rpt. Thus, units 97-99 should not be used for any other model files. The following table relates the IUNIT element to the corresponding 3-character package name. IUNIT PACKAGE NAME 1 BCF 2 WEL 3 DRN 4 RIV 5 EVT 6 7 GHB 8 RCH 9 SIP 10 DE4 11 SOR 12 OC 13 PCG 14 15 CONC 16 HFB 17 18 19 20 21 FHB 22 23 24 The first record in the MODFLOW Name File must specify file type "LIST", which is the MODFLOW listing file. All other files can be in any order. File type "DATA" is for ASCII formatted data files. File type "DATA(BINARY)" is for unformatted data files such as the file used to save heads. The lines in the Name File are read using free format, so spacing is not important as long as a comma or at least one space separates adjacent fields. The following shows an example of a Name File: list 16 radial.lst bas 95 ..\data\radial.bas data 35 ..\data\radial.hds oc 87 ..\data\radial.oc bcf 11 ..\data\radial.bcf wel 12 ..\data\radial.wel sip 19 ..\data\radial.sip conc 93 ..\data\radl_moc.nam The first record in the MOC3D Name File must specify file type "CLST", which is the MOC3D listing file. All other files can be in any order. File types "MOC" or "MOCIMP" are for the MOC3D control file; "MOC" uses the explicit transport solver, while "MOCIMP" implements the implicit solver. Other file types that end in an "A" are ASCII formatted files and those ending in a "B" are binary unformatted files. The following table gives the file types: CRCH input recharge concentrations CNCA concentration results (ASCII) CNCB concentration results (BINARY) PRTA printed results (ASCII) PRTB printed results (BINARY) VELA velocity results (ASCII) VELB velocity results (BINARY) OBS observation well data AGE age input DP double porosity input DK simple reaction input The lines in the MOC3D Name File are read using free format, so spacing is not important as long as a comma or at least one space separates adjacent fields. The following shows an example of a MOC3D Name File: clst 94 radial.out moc 96 ..\data\radial.moc cnca 90 radial.cna 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. Tests are run in the moc3d3.01\test directory. The directory moc3d3.01\data contains the MOC3D input data and expected results for each test. To test the installation, change to the moc3d3.01\test directory and type the command: 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=7 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, 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. test description of test and files file name & usage ---- -------------------------------------------- ----------------- 1 Three-dimensional Steady Flow Transport Name File to designate MOC3D files point3.mcn i MOC3D control file point3.moc i Name File to designate MODFLOW files point3.nam i BAS5 Package point3.bas i BCF5 Package point3.bcf i SIP5 Package point3.sip i WEL1 Package point3.wel i Output Control point3.oc i Listing of MODFLOW results point3.lst o Listing of MOC3D results point3.out o Concentration results (ascii) point3.cna o 2 One-dimensional, Steady Flow, No Decay, Low Dispersion: BASE CASE; implicit solver Transport Name File to designate MOC3D files finite.mcn i MOC3D control file finite.moc i MOC3D OBS data finite.obs i Name File to designate MODFLOW files finite.nam i BAS5 Package finite.bas i BCF5 Package finite.bcf i SIP5 Package finite.sip i Listing of MODFLOW results finite.lst o Listing of MOC3D results finite.out o Concentration results (ascii) finite.cna o Observation well results (ascii) finite.oba o Printed results (ascii) finite.pta o Printed results (binary) finite.ptb o Velocity results (ascii) finite.vla o Velocity results (binary) finite.vlb o 3 One-dimensional, Steady Flow, No Decay, Low Dispersion: BASE CASE; explicit solver Transport Name File to designate MOC3D files finite_e.mcn i MOC3D control file finite_e.moc i MOC3D OBS data finite.obs i Name File to designate MODFLOW files finite_e.nam i BAS5 Package finite.bas i BCF5 Package finite.bcf i SIP5 Package finite.sip i Listing of MODFLOW results finite_e.lst o Listing of MOC3D results finite_e.out o Concentration results (ascii) finite_e.cna o Observation well results (ascii) finite_e.oba o 4 Two-Dimensional Radial Flow and Dispersion Transport Name File to designate MOC3D files radial.mcn i MOC3D control file radial.moc i Name File to designate MODFLOW files radial.nam i BAS5 Package radial.bas i BCF5 Package radial.bcf i SIP5 Package radial.sip i WEL1 Package radial.wel i heads file radial.hds i Output Control radial.oc i Listing of MODFLOW results radial.lst o Listing of MOC3D results radial.out o Concentration results (ascii) radial.cna o 5 Point Initial Condition in Uniform Flow (flow at 45 degrees to grid); implicit solver Transport Name File to designate MOC3D files dirac.mcn i MOC3D control file dirac.moc i Name File to designate MODFLOW files dirac.nam i BAS5 Package dirac.bas i BCF5 Package dirac.bcf i SIP5 Package dirac.sip i Output Control dirac.oc i Listing of MODFLOW results dirac.lst o Listing of MOC3D results dirac.out o Concentration results (ascii) dirac.cna o 6 Point Initial Condition in Uniform Flow (flow at 45 degrees to grid); explicit solver Transport Name File to designate MOC3D files dirac_e.mcn i MOC3D control file dirac_e.moc i Name File to designate MODFLOW files dirac_e.nam i BAS5 Package dirac.bas i BCF5 Package dirac.bcf i SIP5 Package dirac.sip i Output Control dirac.oc i Listing of MODFLOW results dirac_e.lst o Listing of MOC3D results dirac_e.out o Concentration results (ascii) dirac_e.cna o 7 One-dimensional, Steady Flow, DK Decay, Low Dispersion (based on finite test 2) Transport Name File to designate MOC3D files finitedk.mcn i MOC3D control file finitedk.moc i MOC3D OBS data finitedk.obs i MOC3D DK data finitedk.dk i Name File to designate MODFLOW files finitedk.nam i BAS5 Package finitedk.bas i BCF5 Package finitedk.bcf i SIP5 Package finitedk.sip i Listing of MODFLOW results finitedk.lst o Listing of MOC3D results finitedk.out o Concentration results (ascii) finitedk.cna o Concentration results (binary) finitedk.cnb o Observation well results (ascii) finitedk.oba o