README.TXT MODPATH_OBS (mpath_obs - Version 1.0.00) Three-dimensional multi-grid analysis package for advective transport in groundwater flow with particle tracking NOTE: Any use of trade, product or firm names is for descriptive purposes only and does not imply endorsement by the U.S. Government. This version of MODPATH_OBS is referred to as mpath_obs in order to distinguish it from other analysis codes. This version of MODPATH_OBS is packaged for personal computers using the Microsoft Windows XP or Vista operating systems. Executable files for personal computers are provided as well as the source code. The source code can be compiled to run on other computers and operating systems. IMPORTANT: Users should review the file release.txt, which describes changes that have been introduced into mpath_obs with each official release; these changes may substantially affect users. Instructions for installation, execution, and testing of mpath_obs are provided below. TABLE OF CONTENTS A. DISTRIBUTION FILE B. INSTALLING C. EXECUTING THE SOFTWARE D. TESTING E. COMPILING A. DISTRIBUTION FILE The following self-extracting distribution file is for use on personal computers: mpath_obsv1_0_00.exe The distribution file contains: Compiled runfiles and source code for mpath_obs. Supplementary mpath_obs documentation in PDF and text files. Test data sets. The distribution file is a self-extracting program. Execution of the distribution file creates numerous individual files. The extraction program allows you to specify the directory in which the files should be restored. The installation instructions assume that the files are restored into directory C:\WRDAPP. The following directory structure will be created in C:\WRDAPP: | |--mpath_obs.1_0 | |--bin ; mpath_obs, modpath6, and ancillary program executables for personal computers | |--doc ; Documentation files | |--example_model; Input files needed to run, verify, and understand new mpath_obs features with Example Models | | |--bin ; Executables needed to run the examples in the folder structure provided with this release. | | |--Example_SS ; Steady-state multi-grid example of groundwater flow and particle tracking. | | |--Example_Transient; Transient-state multi-grid example of groundwater flow and particle tracking. | | |--finegrid_ss ; Steady-state single-grid example of groundwater flow and particle tracking at the discretization of the child models. | | |--finegrid_transient; Tansient-state single-grid example of groundwater flow and particle tracking at the discretization of the child models. | |--example_model_out; Selected output file and subdirectories needed to verify the operationof new mpath_obs features with Example Models | | |--Example_SS_out ; Steady-state multi-grid example of groundwater flow and particle tracking. | | |--Example_Transient_out; Transient-state multi-grid example of groundwater flow and particle tracking. | | |--finegrid_ss_out ; Steady-state single-grid example of groundwater flow and particle tracking at the discretization of the child models. | | |--finegrid_transient_out;Tansient-state single-grid example of groundwater flow and particle tracking at the discretization of the child models. | |--src ; Mpath_obs source code for compilation on any computer or operating system | |--OtherPrograms; Mpath_obs Ancillary programs AddVolume and ModpathParam executables and source code for compilation on any computer with .NET installed and WIndows operating system It is recommended that no user files are kept in the mpath_obs.1_0 directory structure. If you do plan to put your own files in the mpath_obs.1_0 directory structure, do so only by creating additional subdirectories. Included in directory mpath_obs.1_0\doc are various documentation files. Some of them are Portable Document Format (PDF) files. The PDF files are readable and printable on various computer platforms using Acrobat Reader from Adobe. The Acrobat Reader is freely available from the following World Wide Web site: http://www.adobe.com/ B. INSTALLING To make the executable versions of mpath_obs accessible from any directory, the directory containing the executable (mpath_obs.1_0\bin) should be included in the PATH environment variable. Also, if a prior release of MODFLOW-2005 is installed on your system, the directory containing the executables for the prior release should be removed from the PATH environment variable. As an alternative, the executable files versions of mpath_obs, mpath_obs.exe, in the mpath_obs.1_0\bin directory can be copied into a directory already included in the PATH environment variable. Four versions of mpath_obs are provided that include debug and release versions for 32-bit and 64-bit versions. For example, the mpath_obs_64 is for running on 64-bit Windows operating system and is especially well suited for larger problems where the user may require more than 4GB of memory and/or faster execution. HOW TO ADD TO THE PATH ENVIRONMENT VARIABLE WINDOWS XP SYSTEMS From the Start menu, select Settings and then Control Panel. Double click System and select the Advanced tab. Click on Environment Variables. If a PATH user variable already is defined, click on it in the User Variables pane, then click Edit. In the Edit User Variable window, add ";C:\WRDAPP\mpath_obs.1_0\bin" to the end of the Variable Value (ensure that the current contents of the User Value are not deleted) and click OK. If a PATH user variable is not already defined in the User variables pane of the Environment Variables window, click New. In the New User Variable window, define a new variable PATH as shown above. Click OK. Click OK in the Environment Variables window and again in the System Properties window. Initiate and use a new Windows Command window. HOW TO ADD TO THE PATH ENVIRONMENT VARIABLE WINDOWS VISTA SYSTEMS From the Start menu, select Settings and then Control Panel. Select System & Maintenance followed by System. Choose the Advanced System option. Select the Settings Task, and then select the Environmental Variables button. In the System Variables pane, select the PATH variable followed by Edit. In the Edit window, add ";C:\WRDAPP\mpath_obs.1_0\bin" to the end of the Variable Value (ensure that the current contents of the User Value are not deleted) and click OK. Click OK in the Environment Variables window and then exit from the control panel windows. Initiate and use a new Windows Command window. C. EXECUTING mpath_obs Two mpath_obs runfiles for use on personal computers are provided. mpath_obs_32rls.exe is the 32-bit version of mpath_obs (version 1.0.00). It uses mixed single and double precision for computations and internal data storage, which was determined to be useful for a wide range of simulations. There are situations in which speed and precision are inadequate, which can be indicated by difficulty attaining solver convergence or poor budget error and excessibley long runtimes. Accordingly, a runfile that uses 64-bit precision is provided -- mpath_obs_64rls.exe. If mixed precision is suspected of causing problems in a simulation or or slow runtimes are problematic of parameter estimation settings, the same simulation can be run using the 64-bit runfile. Input for the two runfiles is the same. In fact the source code is identical for both. The 64-bit precision runfile is created by using a compiler option that raises the precision and can take advantage of increased speed and additional addressable memory of the 64-bit operating system. The advantage for using 64-bit technology is additional precision, addressable memeory, and computational speed, The disadvantage are unformatted (binary) files that are doubled in size. (Binary files are used for saving head, drawdown, and budget data.) This penalty is frequently not very significant. Typical computers have adequate memory to run most simulations in 64-bit mode, are 2 to 8 times as fast performing than 32-bit run file, and have abundant disk space for storing binary output files. After the executable files in the mpath_obs.1_0\bin directory are installed in a directory that is included in your PATH, mpath_obs is initiated in a Windows Command-Prompt window or windows batch file using one of the following commands: mpath_obs_32dbg [Fname] or mpath_obs_32rls [Fname] or mpath_obs_64dbg [Fname] or mpath_obs_64rls [Fname] Running MODFLOW, MFLGR, MPLGR, MODPATH, and MODPATH-OBS using a Batch File The batch files used to run MODFLOW-LGR and MODPATH-LGR for the example problem is called MF_RUN.bat. It runs the sequence of programs needed to produce a forward run of the model, including all particle tracking. This type of batch file is typically run by clip-on model analysis programs like PEST and UCODE_2005, and contains the sequence of programs needed for each forward model run. This batch file can also be used for stand-alone forward runs. The sequence of programs in the batch file is: mflgr modflow.lgr MPLGR MP.in MODPATH_OBS mpobs.in The MODFLOW-LGR (MFLGR) or MF-2005 or MF-FMP2, MODPATH-LGR (MPLGR)only needed if nested grids are used, and MODPATH-OBS (MODPATH_OBS) are run in sequence for each forward run, with each program specifying an input file for control and file information. The data arrays in mpath_obs are dynamically allocated, so models are not limited by hard-coded array limits. However, it is best to have enough random-access memory (RAM) available to hold all of the required data. If there is less available RAM than this, the program will use virtual memory, but this slows computations significantly. D. TESTING Example data sets are provided to verify that mpath_obs is correctly installed and running on the system. The example model may also be looked at as examples of how to use mpath_obs. The directory mpath_obs.1_0\example_model contains the input data for running each example. Directory mpath_obs.1_0\example_model_out contains the output files from running each example. The example models are described in Appendix A. The directory mpath_obs.1_0\example_model can be used to conveniently run the tests without destroying the original results in the mpath_obs.1_0\example_model_out directory. The example_model subdirectories contain mpath_obs batch files, which end with ".bat", for running the tests that can be run with the batch file such as doit.bat. The example models can be run by entering the name file for the test when executing mpath_obs. mpath_obs can be run in a command-prompt window with the current directory being the example_model directory or with the example1.bat file from any DOS window open to that folder. The output files that are created in the MPObsOutput subdirectory can then be compared to those in the subdirectories found in mpath_obs.1_0\example_model_out. E. COMPILING The executable files provided in mpath_obs.1_0\bin were created using the Intel Composer XE Fortran (13.2.149)compiler. Although executable versions of the program are provided, the source code is provided in the mpath_obs.1_0\src directory so that mpath_obs can be recompiled if necessary. However, the USGS cannot provide assistance to those compiling software. In general, the requirements are a Fortran compiler withg or without Visual Studio, and the knowledge of using the compilers. The compiler options used with the Intel Fortran compiler that were used to create these executeable versions of mpath_obs are: Debug command line for mpath_obs: /nologo /debug:full /Od /fpe:0 /module:"$(INTDIR)/" /object:"$(INTDIR)/" /traceback /check:bounds /check:stack /libs:static /threads /dbglibs /c Release command line used for mpath_obs: /nologo /Od /fpe:0 /Qsave /module:"$(INTDIR)/" /object:"$(INTDIR)/" /libs:static /threads /c