June 16, 1997 MFI A Data Input Program for the U.S. Geological Survey Modular Finite-Difference Ground-Water Flow Model (MODFLOW) MFI - Version: 2.3 1996/12/06 For assistance, enhancement requests, or bug reports contact the Hydrologic Analysis Software Support Team via e-mail sent to h2osoft@usgs.gov. See the file doc\mfi.txt for descriptions, references, and additional contacts for this software. Instructions for installation, execution, and testing are provided below. This version of MFI is packaged for use on personal computers using the DOS operating system. The installation procedures and the compiled version of MFI must be run using either DOS directly or a DOS window within Microsoft Windows, Windows 95, or Windows NT. TABLE OF CONTENTS A. SYSTEM REQUIREMENTS B. DISTRIBUTION FILES C. INSTALLING o Installing MFI from self-extracting executable o MFI directory structure o Making MFI easily accessible D. COMPILING E. SPREADSHEET INTERACTION F. RUNNING THE SOFTWARE G. TESTING A. SYSTEM REQUIREMENTS For installation of MFI, 3.5 megabytes of free disk space is needed. To run MFI, the following are necessary: - 386 or greater processor - math coprocessor - 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) - at least 40K free disk space in current working directory You must also allow for at least 40 files to be opened at one time. CONFIG.SYS must contain a line such as FILES=40 where the value assigned to FILES is 40 or greater. For proper appearance of the MFI screens, the ANSI.SYS device driver must be loaded. Without it, the screens will be unreadable. CONFIG.SYS must contain a line such as DEVICE=C:\WINDOWS\COMMAND\ANSI.SYS Determine the location of the ANSI.SYS driver on your system and substitute the pathname of that location if not C:\WINDOWS\COMMAND as shown above. Note that for DOS-only and Windows 3.x systems, the ANSI.SYS driver is normally found in C:\DOS. Reboot your system if you modify CONFIG.SYS. B. DISTRIBUTION FILES The following self-extracting DOS distribution files (containing the software, test data sets, and information files) are currently available. mfi2_3.exe - Compiled using Lahey Fortran 77 with source code mfi2_3b.exe - Compiled using Lahey Fortran 77 (binaries only) mfi2_3s.exe - Source code only The program source code consists of the following files, located in the mfi2.3\src directory when extracted: mfi.for mfidmgmt.for mfimoc.for mfiriv.for mfiwel.for mfi.gbl mfidrn.for mfimp.for mfisolve.for spread2.for mfibas.for mfievt.for mfioc.for mfistr.for system4.for mfibcf.for mfighb.for mfirch.for mfiutl.for makefile -- input instructions to the Lahey "make" utility for compiling MFI Included in directory mfi2.3/doc is a Portable Document Format (PDF) version of the MFI documentation (of94_468.pdf). A PostScript version of this report is available from: http://water.usgs.gov/software/mfi.html The PDF file is readable and printable on various computer platforms using Acrobat Reader from Adobe. The Acrobat Reader is freely available from the following World Wide Web sites: http://www.adobe.com/ http://www.shareware.com/ and by File Transfer Protocol (FTP) from the following site: ftp.adobe.com (path: /pub/adobe/acrobat) C. INSTALLING Installing MFI from self-extracting executable ---------------------------------------------- For whichever MFI distribution file that you have acquired, mfi2_3.exe, mfi2_3b.exe, or mfi2_3s.exe, the directory mfi2.3 is created (or overwritten) when the files are extracted. If the mfi2.3 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 file. Note, replace with the drive letter where you want to install MFI and optionally replace [directory] with the name of a directory on that drive: 1. If you are not in the directory where the distribution file is located, go there. For example, c: cd \wrdapp 2. Extract the files using the command: mfi2_3 -d -o :\[directory] Substitute "mfi2_3b" or "mfi2_3s" for "mfi2_3" if you are installing the executable-code-only or source-code distributions, respectively. Be sure to include the -d (restore directory structure) and -o (overwrite existing files) options and ":\" in the command. Examples are: mfi2_3 -d -o c:\ mfi2_3 -d -o c:\wrdapp 3. Go to the newly-created mfi2.3 directory where the files have been extracted. For example: cd \wrdapp\mfi2.3 4. Complete the installation by typing, install :[\directory] using the same drive letter and directory name as for extracting the files; however, if the files are located in the root directory of the installation drive, don't include the backslash. Examples are: install c: install c:\wrdapp The above install command must run successfully in order to create the batch files, mfi2.3\bin\mfi.bat and mfi2.3\test\mfi.bat which are necessary for successful execution of MFI. Be sure that no errors occur when executing the above install command. MFI directory structure ----------------------- The following directory structure will be created (the contents of each directory are shown to the right): mfi2.3 ; copy of this README file `-----bin ; compiled executable, batch file to run program `-----bin_data ; screen message file, files required during execution `-----msg ; source and batch file to build screen message file `-----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 executable and screen message file are not included in the mfi2_3s.exe distribution file. b) The source code and message file components are not included in the mfi2_3b.exe distribution file. c) It is recommended that no user files are kept in the mfi2.3 directory structure. If you do plan to put files in the mfi2.3 directory structure, do so only by creating subdirectories of mfi2.3. Making MFI easily accessible ---------------------------- To make the MFI program accessible from any directory, the directory containing the batch file that executes MFI should be included in the PATH environment variable. For example, you could add a line similar to the following to the AUTOEXEC.BAT file: PATH=%PATH%;C:\mfi2.3\bin As an alternative, the batch file can be installed in a directory already included in the PATH environment variable. The makefile (input instructions to the Lahey make program--located in mfi2.3\src) contains instructions to optionally place a copy of the batch file contained in mfi2.3\bin in a specified directory. Use the following two commands to do this: cd mfi2.3\src make install BINDIR=directory_for_batch_file For example: cd C:\mfi2.3\src make install BINDIR=C:\wrdapp\bin Note that the makefile may need to be modified to be used with make programs other than the Lahey make program. D. COMPILING The source code is provided in the mfi2_3.exe and mfi2_3s.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; version 3.1 of the software libraries distributed as lib3.1; the INTERACTER graphics library from Interactive Software Services Ltd. (used for system-level routines); 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 on a personal computer using the Lahey Fortran 77 extended-memory compiler (version 5.01) with Lahey's supplied make program. To generate a new executable, do the following: 1. Change directory to the source directory: cd mfi2.3\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 LIBDIR pathname for lib3.1 3. Use the make program to initiate compilation of the source code and installation of the software: make [BINDIR=directory_for_batch_file] Note that the brackets ([]) above surround an optional argument to the make command. The INSTALLING instructions above explain the use of BINDIR. The make will: a. create the directories mfi2.3\bin, mfi2.3\bin_data, and BINDIR if they do not already exist, b. compile the source code, c. place the executable (mfi.exe) in mfi2.3\bin, d. build the screen message file (mfi.wdm) in mfi2.3\msg and place it in mfi2.3\bin_data, and e. place a copy of the batch file in BINDIR if specified. It may be necessary to modify the code if a compiler other than the Lahey F77 compiler is used. As described in the MFI documentation, subroutines in the file system4.for are system dependent. Also, the file spread2.for contains some non-standard Fortran code. E. SPREADSHEET INTERACTION When a user indicates that an array should be modified, MFI makes use of a spreadsheet program to do the editing. The user must provide this spreadsheet program and set up MFI to use it. This version of MFI requires a spreadsheet program that can read and write Lotus .WK1 files. Any version of Lotus 123 can do this as well as many other spreadsheet packages. MFI uses the spreadsheet program through the following sequence: MFI writes the current version of the array into spreadsheet file AUTO123.WK1. MFI executes MFISS.BAT and waits for MFISS.BAT to complete. When MFISS.BAT completes (i.e. after the user has modified the array using the spreadsheet program), MFI reads the updated values of the array from AUTO123.WK1. MFI deletes AUTO123.WK1. You must create a version of MFISS.BAT that will work with your spreadsheet program. MFISS.BAT should do whatever is necessary to activate the spreadsheet program and load AUTO123.WK1. Two example versions of MFISS.BAT are provided in the mfi2.3\bin_data directory: MFISS123.BAT -- starts up the spreadsheet with the command "123". This works for Lotus when running under DOS. Because Lotus 123 automatically loads file AUTO123.WK1, nothing special is needed to cause the array to be read into the spreadsheet. When the user terminates the spreadsheet after saving the modified array back into AUTO123.WK1, this BAT file will terminate, and MFI will resume processing. MFISSWIN.BAT -- executes only a DOS PAUSE command. This is useful when running MFI in a DOS window in combination with a Windows spreadsheet program. The pause causes MFI to wait while the user does the following: activate the spreadsheet program if not already running, load AUTO123.WK1, modify the array, save the modified array back into AUTO123.WK1, and close AUTO123.WK1. Then the user can respond to the DOS PAUSE command by striking any key in the DOS window where MFI is running. If one of these versions will work with your spreadsheet, delete the default MFISS.BAT in mfi2.3\bin_data, which merely serves as a place holder, and rename MFISS123.BAT or MFISSWIN.BAT as MFISS.BAT. If neither version is adequate, then you must write your own version of MFISS.BAT. F. RUNNING THE SOFTWARE After MFI is properly installed (see INSTALLING, above), the following command is used to execute MFI: mfi [dataset] where dataset = The name of the dataset to be created/updated by mfi. It may consist of up to 8 characters and must represent a valid filename for the operating system used. If the dataset name is not entered as part of the command, then the first screen will prompt for it. Output filenames are generated as the dataset name followed by a dot and a 2- or 3- character suffix. The following suffixes define some of the files that can be part of an mfi dataset: dataset.nam - Names of all files that define the dataset dataset.log - File of information generated by mfi dataset.bas - Basic Package file of modflow(1) dataset.bcf - BCF Package file for modflow(1) dataset.mpn - Name file for modpath(1) dataset.mp - Main input file for modpath(1) If the file dataset.nam exists, it is read and the specified files are read and can be updated. G. 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 mfi2.3\test directory. The directory mfi2.3\data contains the input data and expected results for each test. After each test is completed, compare the results to the expected results using a file comparison utility such as fc. If all goes well, there should be no differences. To clean up after the tests, type the command: clean Run the tests by following the steps below. Test 1: - Attach to the mfi2.3\test subdirectory and type "mfi" to execute the program. - On the opening screen, type "@". In the small panel that appears, type "..\data\mfitest1.aid". MFI will be run using the keystrokes in ..\data\mfitest1.aid as if they were typed in. - The files listed below will be produced. These should be compared with the files by the same name found in the mfi2.3\data subdirectory. For example, if the fc command is available, the first file below can be compared with its counterpart in the mfi2.3\data directory by typing "fc ..\data\mfitest1.bas mfitest1.bas". mfitest1.bas mfitest1.bcf mfitest1.evt mfitest1.pcg mfitest1.nam mfitest1.rch Test 2: - Execute the program by typing "mfi" in the mfi2.3\test subdirectory. - On the opening screen, type "@". In the small panel that appears, type "..\data\mfitest2.aid". MFI will be run using the keystrokes in ..\data\mfitest2.aid as if they were typed in. - The files listed below will be produced and should be compared with the files by the same name found in the mfi2.3\data subdirectory. mfitest2.bas mfitest2.bcf mfitest2.pcg mfitest2.oc mfitest2.nam 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 and o for output. test program description of test and files file name & usage ---- ------- --------------------------------- ----------------- 1 MFI Test problem 1 Response file for MFI AIDE screens mfitest1.aid i MODFLOW basic input mfitest1.bas o Block centered flow data mfitest1.bcf o Evapotranspiration mfitest1.evt o Preconditioned Conjugate-Gradient mfitest1.pcg o File names file mfitest1.nam o Recharge mfitest1.rch o Screen output from MFI mfitest1.log o 2 MFI Test problem 2 Response file for MFI AIDE screens mfitest2.aid i MODFLOW basic input mfitest2.bas o Block centered flow data mfitest2.bcf o Preconditioned Conjugate-Gradient mfitest2.pcg o OC data mfitest2.oc o File names file mfitest2.nam o Screen output from MFI mfitest2.log o * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Good Luck! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *