README July, 2000 MOC3D A Three-Dimensional Method-Of-Characteristics Solute-Transport Model MOC3D - Version: 3.5 07/2000 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/nrp/gwsoftware/moc3d/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. TABLE OF CONTENTS A. DISTRIBUTION FILES B. EXTRACTING FILES C. COMPILING D. INSTALLING E. RUNNING THE SOFTWARE F. TESTING A. DISTRIBUTION FILES The following distribution packages (containing the software, test data sets, and information files) are currently available for UNIX systems: moc3d3.5.Sun.tar.gz - Compiled for Sun moc3d3.5.src.tar.gz - Source code only B. EXTRACTING FILES The directory moc3d3.5 is created (or overwritten) when the files are extracted from the tar file. If the moc3d3.5 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 moc3d3.5.src.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 moc3d3.5.src.tar.gz 4. Extract the distribution files from the tar file. For example: tar -xvpof moc3d3.5.src.tar This creates the following directory structure (the contents of each directory are shown to the right): moc3d3.5 ; copy of this README file `-----bin ; compiled executable `-----doc ; documentation files `-----src ; source code `-----test ; scripts to run verification tests `-----data ; standard data sets used in verification tests Notes: It is recommended that no user files be kept in the moc3d3.5 directory structure. If you do plan to put files in the moc3d3.5 directory structure, do so only by creating subdirectories of moc3d3.5. C. COMPILING Although executable versions of the programs are provided, the Fortran source code is also provided in the moc3d3.5\src directory so that the programs can be recompiled if necessary. However, no support can be provided for users generating their own versions of the software. In general, the requirements are a Fortran compiler and the knowledge of using the compiler. D. INSTALLING The test scripts require an executable name mf2k_gwt in the ../bin directory. To make the executable (mf2k_gwt) easy to use, it should be installed in a directory included in the user's search path. E. RUNNING THE SOFTWARE 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.5/test directory. The directory moc3d3.5/data contains the input data and expected results for each test. To test the installation, change to the moc3d3.5/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=7 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, there should be no differences. To clean up after the tests, type the command: ./clean.sh NOTE: the standard data sets included with the distribution files were created on a Sun 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. Also, slight differences in output formats may occur on other computers. 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 pnt3_moc.nam 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 fin_moc.nam i MOC3D control file fin_imp.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 3 One-dimensional, Steady Flow, No Decay, Low Dispersion: BASE CASE; ellam solver Transport Name File to designate MOC3D files fin_emoc.nam i MOC3D control file finite.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 radl_moc.nam 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 dir_moc.nam i MOC3D control file dir_imp.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 dirc_emoc.nam i MOC3D control file dirac.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) 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