...........READ.ME..........READ.ME..........READ.ME..........READ.ME...........

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ @ @ @ @@@@@ @@ @ @ @@@ @ @ @@@@ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @@ @@@@ @@ @ @ @ @ @ @ @ @ @ @ @ @ @@ @ @ @ @ @@ @@ @@@ @ @ @@@@@@ @ @ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ Copyright 1999, Regents, University of California INTRODUCTION ++++++++++++ iTOUGH2 provides inverse modeling capabilities for the TOUGH2 family of codes. It can be used for parameter estimation by automatic model calibration, sensitivity analyses, and uncertainty propagation analyses. iTOUGH2 was developed at the Lawrence Berkeley National Laboratory, University of California, Berkeley. This flyer contains brief instructions for installing and running iTOUGH2 under Unix operating systems and PCs. Machine-dependent routines are provided for various computer systems. Installing iTOUGH2 on another computer system may require minor modifications of the subroutines provided in file mdep???.f. DOCUMENTATION +++++++++++++ Successful application of iTOUGH2 requires a user to be proficient in running the TOUGH2 simulator. TOUGH2 equation-of-state modules EOS1 - EOS5 are fully documented in Pruess [1987, 1991]. The package of conjugate gradient solvers is described in Moridis and Pruess [1995]. The EOS7r module is documented in Oldenburg and Pruess [1995]. The EOS10=T2VOC module is documented in Falta et al. [1995]. EOS modules 1 - 9 and 14 (EWASG) are also documented in Pruess et al. (1999); note, however, that not all the options available in Version 2.0 of TOUGH2 are implemented in the iTOUGH2. All reports can be downloaded from the iTOUGH2 Web Site at http://www-esd.lbl.gov/iTOUGH2. iTOUGH2 is documented in a series of three reports: (1) iTOUGH2 User's Guide: Description of inverse modeling theory, program architecture, code installation.

(2) iTOUGH2 Command Reference: Description of iTOUGH2 commands (3) iTOUGH2 Sample Problems: Discussion of illustrative sample problems.

Visit the iTOUGH2 Web Site at http://www-esd.lbl.gov/iTOUGH2 for additional information, including a comprehensive list of iTOUGH2-related publications. References

---------Finsterle, S., iTOUGH2 User's Guide, Lawrence Berkeley National Laboratory, Report LBNL-40040, 2000a. (updated) Finsterle, S., iTOUGH2 Command Reference, Lawrence Berkeley National Laboratory, Report LBNL-40041, 2000b. (updated) Finsterle, S., iTOUGH2 Sample Problems, Lawrence Berkeley National Laboratory, Report LBNL-40042, 2000c. (updated) Finsterle, S., Parallelization of iTOUGH2 Using PVM, Lawrence Berkeley National Laboratory, Report LBNL-42261, 1999. (updated) Finsterle, S., ITOUGH2 V3.2 Verification and Validation Report, Lawrence Berkeley National Laboratory, Report LBNL-42002, 1998. Falta, R. W., K. Pruess, S. Finsterle, and A. Battistelli, T2VOC User's Guide, Lawrence Berkeley Laboratory Report LBL-36400, 1995. Moridis, G. J., and K. Pruess, Flow and Transport Simulations Using T2CG1, A Package of Preconditioned Conjugate Gradient Solvers for the TOUGH2 Family of Codes, Lawrence Berkeley Laboratory Report LBL-35518, 1995. Oldenburg, C. M., and K. Pruess, EOS7R: Radionuclide Transport for TOUGH2, Lawrence Berkeley Laboratory, Report LBL-34868, 1995. Pruess, K., TOUGH User's Guide, Lawrence Berkeley Laboratory Report LBL-20700, 1987. Pruess, K., TOUGH2 - A General Purpose Numerical Simulator for Multiphase Fluid and Heat Flow, Lawrence Berkeley Laboratory Report LBL-29400, 1991. Pruess, K., C. Oldenburg, and G. Moridis, TOUGH2 User's Guide, Version 2.0, Lawrence Berkeley National Laboratory Report LBNL-43134, 1999. TRANSFER ++++++++ The following web sites contain information about obtaining a license for iTOUGH2. http://www-esd.lbl.gov/iTOUGH2 http://www-esd.lbl.gov/TOUGH+ You may also contact Stefan Finsterle (SAFinsterl@lbl.gov; 510-486-5205) The iTOUGH2 source code, various utility script files, and sample problems are contained in compressed archive files (use WinZip or gzip) itough2.tar.gz : for Unix systems itough2.zip : zip file, for PC FILES +++++ The distribution includes the source code, various utility script files, and sample problems:

Utilities --------(1) read_me.txt - The file you are reading. (2) it2install (3) Makefile (4) it2make (5) itough2 - Unix script file for installation on Unix workstation. - Unix Makefile for compiling and linking iTOUGH2. - Unix script file for creating iTOUGH2 executable. - Unix script file for running iTOUGH2. (in subdirectory ../bin). See header of file for details. - Unix script file for running TOUGH2 as a dummy iTOUGH2 run. (in subdirectory ../bin). See header of file for details. - Unix scrip file for displaying status of iTOUGH2 run. (in subdirectory ../bin). See header of file for details. - Unix script file for sending signals to iTOUGH2. (in subdirectory ../bin). See header of file for details. - Unix script file for displaying iTOUGH2 manual pages (in subdirectory ../bin). See header of file for details.

(6) tough2

(7) prista

(8) kit

(9) it2help

(10) it2help.txt - iTOUGH2 manual pages. (11) invdir y. - Example dummy iTOUGH2 input file to solve direct problem onl

(12) itough2.lnk - Link file to be used with Lahey compiler f77l3. (13) automake.fig - Automake file for Lahey compiler lf95. (14) itough2.bat - PC command file for running itough2. (15) tough2.bat - PC command file for running itough2 in forward mode.

iTOUGH2 FORTRAN source files ---------------------------(16) *.inc - FORTRAN include files containing COMMON blocks and PARAMETER statements for dimensioning major arrays (define array dimensions in maxsize.inc). - iTOUGH2 main subroutines. - Subroutines reading iTOUGH2 input file. - Subroutines for user-specified parameters, userspecified observations, user-specified boundary

(17) it2main.f (18) it2input.f (19) it2user.f

conditions, and user-specified data functions. (20) it2xxxx.f (21) it2lhs.f (22) mdep???.f (23) it2stubs.f tures (24) it2gslib.f (25) it2pvm.f - Subroutines with minimization algorithms, matrix operations, eigenanalyses, etc. - Subroutines for Lating Hypercube sampling - Machine-dependent subroutines for ??? ??? = ibm, dec, sun, hp, sgi, star, cray, lah, pc. - Various dummy subroutines for rarely implemented iTOUGH2 fea - Subroutines for GSLIB (Geostatistical Software Library) - Subroutines for PVM (Parallel Virtual Machine)

TOUGH2 FORTRAN source files --------------------------(26) t2cg1.f (27) t2cg22.f (28) t2solv.f (29) t2f.f (30) meshm.f (31) eos#.f - Conjugate gradient solvers. - Calls conjugate gradient solvers. - Conjugate gradient solvers. - Core module of TOUGH2. - Module with internal mesh generation facilities. - Equation of state module No. #.

Sample problems (subdirectory samples/sample*) --------------(32) sam*i (33) sam* - iTOUGH2 input files. - TOUGH2 input files.

(34) *.dat - Data input files. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ INSTALLATION ON A UNIX WORKSTATION ++++++++++++++++++++++++++++++++++ Installing iTOUGH2 requires basic knowledge about the Unix operating system, including shell programming, the makefile utility, changing permissions, and adding a directory to the PATH shell variable. If iTOUGH2 is installed exactly as recommended below, only very minor modifications have to be made to the Makefile and the script files, if at all. Automatic Installation Using Script it2install ---------------------------------------------(1) Make sure script file it2install is executable: type: chmod a+x it2install

(2) Type ./it2install and follow instructions. If successful, an iTOUGH2 executable for EOS3 is created. To create additional executables (e.g., for EOS9), type: ./it2make 9 or follow detailed instructions below. (3) To customize installation or compilation, follow detailed instructions below. Installation by Hand -------------------(1) Create an iTOUGH2 installation directory, e.g., ~/itough2. Type: cd; mkdir itough2 Multiple iTOUGH2 versions can be installed in subdirectories itough2v* where * is the version number used with the -v option on the itough2 command line. (2) Move the tar file itough2.tar (or itough2.tar.gz) to the iTOUGH2 installation directory, e.g.: mv itough2.tar* ~/itough2 (3) Go to the iTOUGH2 installation directory, e.g.: cd ~/itough2 (4) If file is compressed, uncompress: File extension .Z : uncompress itough2.tar.Z File extension .gz: gunzip itough2.tar.gz (5) Extract files from tar file: tar xvf itough2.tar A subdirectory ./samples is created, containing sample problem input files. (6) Copy script files itough2, tough2, prista, kit, and it2help to a directory in your command path (typically ~/bin or /usr/local/bin). Add this directory (directory_name) to the command search path (if not already defined): For C-shell, add the following line to the .cshrc or .login file: set path =($PATH directory_name) For POSIX-, bourne-, or korn-shell, add the following line to the .profile file: PATH=$PATH:directoy_name (7) You may have to customize script files prista and kit. See instructions therein.

(8) The iTOUGH2 executable can also be used to perform forward runs, i.e., to solve the forward problem without optimization. Running iTOUGH2 in forward mode makes use of a dummy iTOUGH2 input file invdir, which can be an empty file. Customize script file tough2 by setting variable script_dir, which must contain the path to script file itough2 (default: script_dir = ~/bin). (9) Check appropriate installation of script files: Go to your home directory and type "prista" or "kit". A message should appear indicating that no iTOUGH2 run is in progress. Type "tough2" or "itough2" without any arguments. The command usage should be printed. If no message is printed, make sure the scripts are in the command search path (Step 6) and properly customized (Steps 7 and 8) . Compilation ----------(1) Go to the iTOUGH2 installation directory. (2) If necessary, change the dimensions of the major TOUGH2 and iTOUGH2 arrays in file maxsize.inc. Note that different minimal array dimensions (MAXK, MAXEQ, MAXPH, and MAXB) apply depending on the EOS module being used. (3) Certain EOS modules contain duplicate subroutines which are supposed to supersede those in file it2stubs.f or t2f.f. If the presence of multiply defined subroutines creates a fatal error during linking, the subroutines in file it2stubs.f or file t2f.f must be renamed (e.g., SubroutineName_NOT_USED). The following subroutines must be renamed in t2f.f (or other source files): The following subroutines must be renamed in it2stubs.f: If If If If If If linking linking linking linking linking linking EOS7r, EOS9, EOS9ecm, EOS9nT, EOS10, EOS14, rename rename rename rename rename rename subroutine subroutine subroutine subroutine subroutine subroutine MULTI_SPECIAL MULTI_SPECIAL MULTI_SPECIAL MULTI_SPECIAL, LINEQ, CALLTOUG MULTI_SPECIAL QU

The following subroutines must be renamed in it2stubs.f: If linking EOS9nT, rename subroutine LINEQ, CALLTOUG If linking EOS14, rename subroutine QU If special modules are linked, rename the duplicate subroutines in it2stubs.f. (4) Edit file Makefile to customize the following variables: EOS = ? : Provide ID-number of the EOS module being used. COM = ? : Provide name of the COMputer system being used. Possibilities: ibm, sun, star, sgi, dec, hp, and cray. FOR = ? : Provide name of FORtran compiler. COO = ? : Provide COmpiler Options for compilation. EXS = ? : Provide file EXtension of Source files. EXO = ? : Provide file EXtension of Object files. EXE = ? : Provide file EXtension of eXecutable.

LIN = ? : Provide LINker options. LPVM = ? : Provide directory of PVM Library (if applicable) IPVM = ? : Provide directory of PVM Included files (if applicable) Typical compiler options are provided for the following machines: IBM, SUN, STARDENT, DEC ALPHA, HP, SGI, Cray. Select the appropriate block by deleting the #-signs in the first column before COM, FOR, COO, and LIN, and put #-signs elsewhere. (5) Type "make" to run the Makefile. This compiles and links iTOUGH2. The name of the executable is itough2_$EOS.$HOSTNAME, where EOS is an integer indicating which EOS module is being used, and HOSTNAME is the name of the host. NOTE: Steps (3)-(5) are automatically executed when running script file it2make. NOTE: For compilation of specific modules (e.g., PVM, GSLIB, LHS, IFS, etc.), see instructions in Makefile. RUNNING iTOUGH2 ON UNIX/LINUX WORKSTATION +++++++++++++++++++++++++++++++++++++++++ (1) Prepare a TOUGH2 and an iTOUGH2 input deck according to the user's guides. On-line support is provided through command it2help or on the Web at http://www-esd.lbl.gov/iTOUGH2 (click on Command Index). To run iTOUGH2, type: itough2 InverseFile ForwardFile EOS & where: - itough2 is the command name of the script file (or alias) - InverseFile is the file name of the iTOUGH2 input file - ForwardFile is the file name of the TOUGH2 input file - EOS is the ID-number of the EOS module being used (e.g., 3 for EOS3) Additional options are available; type "itough2" without any arguments for a list. In order to run the first sample problem, go to subdirectory InstallationDirectory/samples/sample1 and type: itough2 sam1p1i sam1 3 & It is convenient to add the "&" at the end of the command line. This sends the execution of the script file to the background, which allows you to use shell script files prista and kit (see below). The itough2 script file creates a temporary directory ~/it2_PID. All input files are copied into this temporary directory. iTOUGH2 is executed, and the result files are copied back to the working directory. This allows one to run multiple inversions at the same time without generating conflicting file names. (2) During execution, the status of the simulation can be displayed by running the prista script file. Type "prista" and Follow the instruction s. (3) If you wish to prematurely terminate an iTOUGH2 simulation or to send a signal which triggers a specific action (e.g., provides printout), type "kit" and follow the instructions on screen.

Running iTOUGH2 in Forward Mode +++++++++++++++++++++++++++++++ (1) Prepare a TOUGH2 input deck. (2) Type "tough2 ForwardFile EOS &" for execution, where: - tough2 is the command name of the script file (or alias) - ForwardFile is the file name of the TOUGH2 input deck - EOS is the ID-number of the EOS module being used (e.g., 3 for EOS3) Additional options are available; type "tough2" without any arguments for a list. DEBUGGING +++++++++ Run the sample problems to check the proper installation of the code. If no results are obtained, check: (1) whether the script file itough2 is executable and accessible from your working directory; (2) whether the iTOUGH2 executable itough2_EOS.HostName exists; (3) whether the path name to the iTOUGH2 executable is correct (see shell variable prog_dir in script file itough2); (4) error messages in the iTOUGH2 output file; (5) error messages in the TOUGH2 output file; (6) error messages from the shell script in file *.msg; You may also rerun the sample problem using the -no_delete option, and examine all the files in the temporary directory ~/it2_PID. INSTALLATION ON PC ++++++++++++++++++ iTOUGH2 can be installed on a PC without modification of the source code. (1) If running Windows, open a window with the DOS Command Prompt: start -> Programs - > Accessories -> Command Prompt (2) Create an iTOUGH2 home directory, preferrably: C:\iTOUGH2 (3) Unzip itough2.zip (or itough2.tar.gz) into the iTOUGH2 home directory; use the unzip option that maintains the directory structure. (4) If the iTOUGH2 home directory is different from C:\iTOUGH2, edit the two batch files itough2.bat and tough2.bat and replace all occurrences of C:\iTOUGH2 with the name of the iTOUGH2 home directory. (5) Add the Scripts directory (e.g., C:\iTOUGH2\Scripts) to the command search

path. For WINDOWS 2000 and WINDOWS XP: - Click on Start button - Go to Control Panel - Choose System - Choose "Advanced" tab - Click "environmental variables" button - Under "System Variable," choose PATH and edit - Add C:\itough2\Scripts at the end of the string of entries: - You might have to restart your computer For older WINDOWS systems - Add the following line to file C:\AUTOEXEC.BAT: PATH %PATH%;C:\iTOUGH2\Scripts - Type "AUTOEXEC" to make the change effective or restart your computer. If unsuccesful, move the batch files to a directory that is already in your command search path (such as C:\WINDOWS). (6) If necessary, change the dimensions of the major TOUGH2 and iTOUGH2 arrays in file maxsize.inc. Note that different minimal array dimensions (MAXK, MAXEQ, MAXPH, and MAXB) apply depending on the EOS module being used. (7) Certain EOS modules contain duplicate subroutines which are supposed to supersede those in file t2f.f or it2stubs.f. If the presence of multiply defined subroutines creates a fatal error during linking, the subroutines in file it2stubs.f or file t2f.f must be renamed (e.g., SubroutineName_NOT_USED). The following subroutines must be renamed in it2stubs.f: If If If If If If linking linking linking linking linking linking EOS7r, EOS9, EOS9ecm, EOS9nT, EOS10, EOS14, rename rename rename rename rename rename subroutine subroutine subroutine subroutine subroutine subroutine MULTI_SPECIAL MULTI_SPECIAL MULTI_SPECIAL MULTI_SPECIAL, LINEQ, CALLTOUG MULTI_SPECIAL QU

The following subroutines must be renamed in it2stubs.f: If linking EOS9nT, rename subroutine LINEQ, CALLTOUG If linking EOS14, rename subroutine QU If special modules are linked, rename the duplicate subroutines in it2stubs.f. (8) Compilation: The following files must be compiled and linked using a FORTRAN compiler: =========================================================================== ====== it2main it2input it2xxxx it2user mdeppc eos(EOS) t2cg22 t2solv t2f meshm it 2stubs =========================================================================== ====== If using the Compaq Visual Fortran compiler, link mdepcvf instead of mdeppc (see file mdepcvf.f for additional instructions). Detailed instructions for compiling iTOUGH2 using the Compaq Visual

Fortran compiler can be found on file read_me_CVF.txt If using the LAHEY compiler, link mdeplah instead of mdeppc (see files mdeplah.f and Makefile for additional instructions). For other compilers, replace machine-dependent functions (such as time and date) in mdeppc.f. The name of the executable should be iT2_(EOS).exe, where (EOS) is an integer identifying the EOS module being used. For example, if EOS3 is to be used, the executable name should be iT2_3.exe . NOTE: Provisions are made in the Makefile for the Lahey compilers f77l3 and lf90. Follow the instructions in the Makefile. An automake.fig file is enclosed for Lahey compiler lf95. (9) Execution of iTOUGH2: There are three options to run iTOUGH2: (a) Copy the executable (e.g., iT2_3.exe) to the directory containing all input files: double click on the executable; you will be prompted to enter the names of the iTOUGH2 and TOUGH2 input files; for running iTOUGH2 in foward mode only, provide file invdir (or any empty dummy fi le) as the "iTOUGH2 input file". (b) Work in the Command Prompt window, change directory to the working dire ctory (b1) Type the name of the executable and enter file names (b2) Use batch file itough2.bat, i.e., type: itough2 InverseFile ForwardFile EOS where: - InverseFile is the file name of the iTOUGH2 input file - ForwardFile is the file name of the TOUGH2 input file - EOS is the ID-number of the EOS module being used Example: Go to subdirectory C:\iTOUGH2\SAMPLES\SAMPLE2 and type: itough2 sam2p1i sam2 3 (10) Execution of iTOUGH2 in forward mode: To run iTOUGH2 in forward mode, use dummy file invdir as the iTOUGH2 input file; invdir can be an empty file. Alternatively, use batch file tough2.bat, i.e., type: tough2 ForwardFile EOS where: - ForwardFile is the file name of the TOUGH2 input file - EOS is the ID-number of the EOS module being used Example: Go to subdirectory C:\iTOUGH2\SAMPLES\SAMPLE1 and type: tough2 sam1 3 SUGGESTION: iTOUGH2 should not be executed in the iTOUGH2 home directory.

Create separate directories with input files. (11) Comment on file names: If working under the DOS Command Prompt, names of input files should be less than 8 characters (excluding file extension) to avoid truncation of output file names. SUGGESTIONS +++++++++++ The following approach is recommended to become familiar with iTOUGH2: (1) Become an expert in using TOUGH2 (i.e., run iTOUGH2 in forward mode). Appendix A in the "iTOUGH2 Command Reference" contains a description of potentially useful extensions of the TOUGH2 simulator. (2) Get acquainted with inverse modeling theory. Chapter 2 in the "iTOUGH2 Command Reference" contains a summary description. For more details, read the "iTOUGH2 User's Guide". (3) Read Chapter 3 of the "iTOUGH2 Command Reference" to understand the main concepts of the iTOUGH2 input language. (4) Run sample problems! Problems 1 and 2 are described in detail in the report "iTOUGH2 Sample Problems." They are of a tutorial nature. Problems 3 through 7 examine more specific program options. (5) To solve your own inverse problems, "iTOUGH2 User's Guide" and "iTOUGH2 specific aspects. Consult the command index (Appendix to find out about suitable commands Additional suggestions: ---------------------(1) Use option ">>> stop after INPUT" to check iTOUGH2 input without starting the optimization; check printout of input data; resolve errors and warnings. (2) Use option ">>> solve FORWARD problem only" to run one forward calculation; check whether the TOUGH2 simulation was terminated normally; draw curves of measured and computed output (see plotfile *.tec); check whether the initial guess was reasonable and whether the units and signs of the data were correct; check CPU time needed for one forward calculation. (3) Perform one iteration (">>> number of ITERATIONS: 1" or ">>> SENSITIVITY analysis") and check the sensitivity coefficients; if certain parameters are not sensitive or highly correlated with other parameters, try to define new lumped parameters, or exclude the parameter from the optimization. (4) Perform optimization; set maximum number of iterations between 5 and 15. (5) Carefully read warning and error messages in all iTOUGH2 output files. (6) Please report code errors to the code developers. consult the index in the Sample Problems" for answers regarding B in the "iTOUGH2 Command Reference") and program options.

MAILING ADDRESS OF CODE DEVELOPERS ++++++++++++++++++++++++++++++++++ Stefan Finsterle and Karsten Pruess Lawrence Berkeley National Laboratory Earth Sciences Division, Mail Stop 90-1116 Berkeley, CA 94720 U.S.A. Phone: Fax: E-mail: WWW: (510) 486-5205 (510) 486-5686 SAFinsterle@lbl.gov http://www-esd.lbl.gov/iTOUGH2

...........READ.ME..........READ.ME..........READ.ME..........READ.ME..........