README.TXT MODPATH A particle-tracking postprocessing model for MODFLOW MODPATH - Version 3.2 2000/06/14 MODPATH-PLOT - Version 3.2 2000/06/14 Instructions for installation, execution, and testing are provided below. After installation, see the modpath.txt file in the doc directory of the MODPATH installation for summary information on MODPATH. 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. SYSTEM REQUIREMENTS B. DISTRIBUTION FILE C. DOCUMENTATION D. INSTALLING o Installing MODPATH o MODPATH directory structure E. COMPILING (optional) F. RUNNING THE SOFTWARE o Out of environment space error G. GRAPHICAL OUTPUT H. TESTING I. CONTACTS A. SYSTEM REQUIREMENTS To install and run MODPATH, the following are necessary: - Pentium-class PC - Windows 9x, NT 4.0, or Windows 2000 - up to 9.0 megabytes of free disk space - 1.3 megabytes of free extended memory B. DISTRIBUTION FILE The following distribution file (containing the software, test data sets, and information files) is currently available. mpath3_2.exe - Compiled using Lahey Fortran 90, includes source C. DOCUMENTATION Pollock, D.W., 1994, User's Guide for MODPATH/MODPATH-PLOT, Version 3: A particle tracking post-processing package for MODFLOW, the U.S. Geological Survey finite-difference ground-water flow model: U.S. Geological Survey Open-File Report 94-464, 234 p. This document is available in electronic format. A Portable Document Format (PDF) version is included in the doc subdirectory of the MODPATH program distribution. This and other formats can also be found at http://water.usgs.gov/software/modpath.html. See http://water.usgs.gov/software/ordering_documentation.html for information on ordering printed copies of USGS publications. D. INSTALLING Installing MODPATH ------------------ To install the software, double-click mpath3_2.exe to execute the installation program and follow the directions on the screen. By default, the software is installed in the directory C:\Program Files\USGS\mpath3.2. This is the recommended installation directory, but you may use other directories or disk drives. Note that program components not installed initially can be installed later, and that any components damaged by, for example, being inadvertently overwritten, can be quickly reinstalled. To install additional components or reinstall previously-installed components, double-click Add/Remove Programs in the Control Panel, select MODPATH from the list of installed programs, and click the Add/Remove button. Upon uninstallation, any user files in the MODPATH installation directory--such as those created in the test or user subdirectories-- will be left behind intact. MODPATH directory structure --------------------------- The following directory structure will be created (the contents of each directory are shown to the right): mpath3.2 file NOTICE.TXT and this README.TXT `-----bin compiled executables `-----bin_data data files required during execution `-----doc documentation files `-----src Makefile and source code `-----test batch files to run verification tests `-----data standard data sets used in verification tests `-----user batch files for running executables Notes: a) Source code is not installed in the Typical installation, but can be installed by choosing the Custom installation option. b) It is recommended that any user files kept in the MODPATH directory structure be placed in the user subdirectory only. c) To compile a new version of the software, you will also need: (1) a Fortran compiler and (2) a Graphical Kernel System (GKS) library. E. COMPILING (optional) The source code is provided so that users can generate the executable themselves. Little or no support can be provided for users generating their own versions of the software. In general, to compile a new version of the software, you will need: a) a Fortran compiler, b) familiarity with the compiler and the operating system under which the compiler runs (i.e., DOS or Windows), and c) a Graphical Kernel System (GKS) library; one GKS library available without fee is GLI/GKS (available from http://iff001.iff.kfa-juelich.de/gli/). In the mpath3_2.exe distribution, the Makefile used to compile the executables, using the Lahey Fortran 90 compiler and the Opus make program, is provided as an example. Note that MODPATH and MODPATH-PLOT are written primarily in standard Fortran 77 but that a few Fortran 90 statements have been added for dynamic array allocation. The code can be compiled with any standard Fortran 90 compiler. The code can also be compiled using a standard Fortran 77 compiler when alternate Fortran 77 statements for static array dimensioning are uncommented: in mpath3.for and mplot3.for, uncomment the statements found between the "#F77 - BEGIN#" and "#F77 - END#" comments and comment out the statements between the "#F90 - BEGIN#" and "#F90 - END#" comments. Note also that the files device.dat and gks.dat in the bin_data directory are configured for the GKS software with which MODPATH-PLOT was compiled: the INTERACTER graphics library from Interactive Software Services. If you compile MODPATH-PLOT using a different GKS library, you will need to modify device.dat and gks.dat appropriately. See the documentation referenced above for details. F. RUNNING THE SOFTWARE If the option to modify the PATH environment variable was chosen during installation, MODPATH and MODPATH-PLOT can be run in an MS-DOS Command Prompt window from any directory by typing "mpath3" and "mplot3", respectively. If the option to modify the PATH environment variable was not chosen during installation, the full pathname of the programs must be typed, as in, for example, "c:\program files\usgs\mpath3.2\bin\mpath3" (note that quotation marks must be typed with and enclose any command name with spaces embedded). Alternatively, you can run MODPATH and MODPATH-PLOT by selecting the MODPATH and MODPATH-PLOT shortcuts from the Start menu. All data values displayed to the screen are written to the output files created in the user subdirectory (C:\Program Files\USGS\mpath3.2\user, if the default installation location was used). Input files must be placed in this same subdirectory. While MODPATH-PLOT is writing graphical output into a file, an additional DOS window appears on the screen. There is no information written to this window, and it automatically disappears once graphical output is complete. Out of environment space error ------------------------------ This error can occur when running MODPATH or MODPATH-PLOT, including when running the verification tests. The error occurs when there is insufficient space to hold a new environment variable definition. You can avoid this error by initiating a new command shell and specifying how much environment space you need. For example, in an MS-DOS Command Prompt window, typing command /e:1024 will initiate a new command shell with 1024 bytes of environment space. Environment space can be between 256 and 32768 bytes. The above command will increase the environment space for only the current Command Prompt window. To permanently increase your environment space, on Windows 95 and 98 machines, click the MS-DOS icon in the upper-left corner of the Command Prompt window and select Properties. Select the Memory tab and increase the value in the Initial environment field. On Windows NT machines, add the above command to C:\winnt\system32\config.nt and initiate and use a new MS-DOS Command Prompt window. G. GRAPHICAL OUTPUT When you run MODPATH-PLOT, you are asked whether you want graphical output to be saved in a Windows meta file, PostScript file, or DXF file. When created, the three different types of files are assigned names of mplot.wmf, mplot.ps, and mplot.dxf, respectively. Windows meta files can be viewed in and printed by many Windows applications. To import a Windows meta file into a word processor, choose that word processor's menu options to insert a picture/graphic from a file. H. 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 test subdirectory contains the batch files to run the tests. The data subdirectory contains the input data and the expected results for each test. If you did not run the verification tests at the end of the installation, you can run the tests by first opening an MS-DOS Command Prompt window and changing to the test subdirectory by typing the following (substitute the drive letter and directory where you installed MODPATH, if you did not install it in the default location): c: cd "program files" cd usgs\mpath3.2\test Execute the tests by typing the command: test [start [stop]] where: start = the number of the first test to perform, default = 1 stop = the number of the last test to perform, default = 8 For example: command what happens -------------------------------------- -------------------------------- test runs all tests test 1 1 runs the first test test 2 3 runs tests 2 and 3 After the tests are completed, the results are compared to the expected results (found in data subdirectory). See the file check.log; 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, where '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 ---- ------- -------------------------------------- ----------------- Tests 1-4 use the following input files in addition to the files listed below for each test: Main data file demo-s.mp i MODFLOW-generated cell-by-cell demo-s.bud i budget data MODFLOW-generated head data demo-s.hed i MODFLOW Recharge Package Input demo-s.rch i MODFLOW River Package Input demo-s.riv i MODFLOW Well Package Input demo-s.wel i IBOUND array for layer 1 ibound.1 i IBOUND array for layer 4 ibound.4 i 1 mpath3 Steady-state flow sample problem, mplot3 forward-tracking endpoint analysis MODPATH response file path-s1.rsp i Name file demo-s1.mpn i Summary of input data and simulation summary1.pth o Endpoint file endpoint.s1 i/o MODPATH-PLOT response file plot-s1.rsp i Summary of input data and plot status summary1.plt o Plot of results from MODPATH run mplot1.ps o 2 mpath3 Steady-state flow sample problem, mplot3 backward-tracking endpoint analysis MODPATH response file path-s2.rsp i Name file demo-s2.mpn i Summary of input data and simulation summary2.pth o Endpoint file endpoint.s2 i/o MODPATH-PLOT response file plot-s2.rsp i Summary of input data and plot status summary2.plt o Plot of results from MODPATH run mplot2.ps o 3 mpath3 Steady-state flow sample problem, mplot3 backward-tracking pathline analysis in cross-section MODPATH response file path-s3.rsp i Name file demo-s3.mpn i Starting locations file demo-s3.loc i Summary of input data and simulation summary3.pth o Endpoint file endpoint.s3 o Pathline file pathline.s3 i/o MODPATH-PLOT response file plot-s3.rsp i Summary of input data and plot status summary3.plt o Plot of results from MODPATH run mplot3.ps o 4 mpath3 Steady-state flow sample problem, mplot3 time-series analysis with multiple release times MODPATH response file path-s4.rsp i Name file demo-s4.mpn i Summary of input data and simulation summary4.pth o Endpoint file endpoint.s4 o Time-series file timesers.s4 i/o MODPATH-PLOT response file plot-s4.rsp i Summary of input data and plot status summary4.plt o Plot of results from MODPATH run mplot4.ps o Tests 5-8 use the following input files in addition to the files listed below for each test: Main data file demo-t.mp i MODFLOW-generated cell-by-cell demo-t.bud i budget data MODPATH-generated composite budget file demo-t.cbf i MODFLOW-generated head data demo-t.hed i MODFLOW Recharge Package Input demo-t.rch i MODFLOW River Package Input demo-t.riv i MODFLOW Well Package Input demo-t.wel i IBOUND array for layer 1 ibound.1 i IBOUND array for layer 4 ibound.4 i 5 mpath5 Transient flow sample problem, mplot5 map view backward-tracking pathline analysis MODPATH response file path-t1.rsp i Name file demo-t1.mpn i Summary of input data and simulation summary5.pth o Endpoint file endpoint.t1 o Pathline file pathline.t1 i/o MODPATH-PLOT response file plot-t1.rsp i Summary of input data and plot status summary5.plt o Drawing commands file of contours contours.dcf o Drawing commands file of pathlines paths.dcf o Plot of results from MODPATH run mplot5.ps o 6 mpath3 Transient flow sample problem, mplot3 backward-tracking endpoint analysis for well 2 MODPATH response file path-t2.rsp i Name file demo-t2.mpn i Summary of input data and simulation summary6.pth o Endpoint file endpoint.t2 i/o MODPATH-PLOT response file plot-t2.rsp i Summary of input data and plot status summary6.plt o Plot of results from MODPATH run mplot6.ps o 7 mpath3 Transient flow sample problem, mplot3 forward-tracking endpoint analysis for wells 1 and 2 MODPATH response file path-t3.rsp i Name file demo-t3.mpn i Summary of input data and simulation summary7.pth o Endpoint file endpoint.t3 i/o MODPATH-PLOT response file plot-t3.rsp i Summary of input data and plot status summary7.plt o Plot of results from MODPATH run mplot7.ps o 8 mpath3 Transient flow sample problem, mplot3 backward-tracking endpoint analysis for well 1 MODPATH response file path-t4.rsp i Name file demo-t4.mpn i Summary of input data and simulation summary8.pth o Endpoint file endpoint.t4 i/o MODPATH-PLOT response file plot-t4.rsp i Summary of input data and plot status summary8.plt o Plot of results from MODPATH run mplot8.ps o The following MODFLOW input files, used to generate the output processed by MODPATH, are also included in the MODPATH data directory: Steady-state flow sample problem input files -------------------------------------------- MODFLOW Name File demo-s.nam MODFLOW Basic Package Input demo-s.bas MODFLOW BCF Package Input demo-s.bcf MODFLOW Output Control Input demo-s.oc MODFLOW SIP Package Input demo-s.sip Transient flow sample problem input files ----------------------------------------- MODFLOW Name File demo-t.nam MODFLOW Basic Package Input demo-t.bas MODFLOW BCF Package Input demo-t.bcf MODFLOW Output Control Input demo-t.oc MODFLOW SIP Package Input demo-t.sip I. CONTACTS Inquiries about this software distribution should be directed to: U.S. Geological Survey Hydrologic Analysis Software Support Program 437 National Center Reston, VA 20192 e-mail: h2osoft@usgs.gov