************************************************************************* *********************** TOUGH2 Version 2.1 ************************* *********************** July 2011 ************************* ************************************************************************* .......READ.ME..........READ.ME..........READ.ME..........READ.ME........ ......................................................................... ......................................................................... ......................................................................... This flyer contains a brief description of the TOUGH2 distribution as well as instructions for installing and running TOUGH2. For further instructions and information, consult the various manuals and the following web site: ************************************************************************* * http://www-esd.lbl.gov/TOUGH/ * ************************************************************************* The TOUGH2 source code is distributed in two parts: (1) The TOUGH2 Core, which consists of the main program, key subroutines for assembling and solving the governing equations, and routines with supporting functionality. (2) An equation-of-state (EOS) module, which determines the components and fluid phases considered, calculates their thermophysical properties and performs phase diagnostics. The TOUGH2 core module has to be linked to one EOS module to create a separate executable for the specific fluid system to be simulated (see compilation and linking instructions below). EOS-specific sample problems are distributed along with most EOS modules. They are described in the main TOUGH2 User's Guide (Pruess et al., 1999) or EOS-specific manuals (see references at the end). The following instructions are concerned with the installation for TOUGH2 from the Fortran source code. A suitable Fortran compiler with appropriately selected compiler and linker options is required. The following list contains the Fotran source code files: TOUGH2 Core Files ================= T2 - This is an INCLUDE file for dimensioning of major problem-size dependent arrays. It must be present when t2fm.f is compiled. t2fm.f - This is the TOUGH2 main program; it includes subroutines for reading input files and for setting up the coupled linear equations; it contains the executive routines for marching in time, and writing of some output files. t2cg22.f - This module includes the main executive routines for the linear equation solution (Moridis and Pruess, 1998). t2f.f - This includes further core routines of TOUGH2, such as the subroutines for water properties, as well as relative permeability and capillary pressure routines. meshm.f - This includes the MESHMAKER and MINC processing routines. t2solv.f - This includes a package of linear equation solvers; makefile - A Makefile for compiling TOUGH2 modules under Linux/Unix. Equation-of-state Module 1 ========================== eos1.f - Equation of state for water, or two waters. rvf - Input file for sample problem 3 (mesh generation). rvf2 - Input file for sample problem 3 (hydrostatic pressure equilibrium). rvf3 - Input file for sample problem 3 (heat sweep in a vertical fracture); rvf4 - Input file for sample problem 3 (two waters). rfp - Input file for sample problem 4 (five-spot geothermal production/injection); r1q - Input file for sample problem 5 (mesh generation). r1q2 - Input file for sample problem 5 (coupled wellbore flow). r1q3 - Input file for sample problem 5 (well on delivaribility). f725d - Table of downhole flowing wellbore pressures for r1q2. Equation-of-state Module 2 ========================== eos2.f - Equation of state for water-CO2 mixtures, for geothermal applications at modest CO2 partial pressures, up to 10-20 bar. rfp - Input file for sample problem 4 (five-spot geothermal production/injection). Equation-of-state Module 3 ========================== eos3.f - Equation of state for water-air mixtures, for applications to vadose zone hydrology with an active gas phase. sam1 - Input file for sample problem 1 (code demonstration). rhp - Input file for sample problem 2 (heat pipe in cylindrical geometry); Equation-of-state Module 4 ========================== eos4.f - Equation of state for water-air mixtures, with capability for modeling vapor pressure lowering from capillary pressures, as given by Kelvin’s equation. The version provided here was enhanced to allow “two waters.” To engage the two-waters option, set component index NK = 3 and equation index NEQ = 4 in data block MULTI, and assign mass fraction of water 2 as last - fourth - primary variable. rhp - Input file for sample problem 2 (heat pipe in cylindrical geometry); Equation-of-state Module 5 ========================== eos5.f - Equation of state for water-hydrogen mixtures. Equation-of-state Module 7 ========================== eos7.f - Equation of state for mixtures of water, brine, and air. rf1 - Input file for sample problem 6 (multiphase and non- isothermal processes in a system with variable salinity); Equation-of-state Module 7r =========================== eos7r.f - Equation of state for mixtures of water, brine, and air, plus two water-soluble tracers that may be volatile, and may be parent-daughter radionuclides. rdif7 - Input file for sample problem 7 (thermal and tracer diffusion). rdica - Input file for sample problem 8 (contamination of an aquifer from VOC vapors in the vadose zone). Equation-of-state Module 8 ========================== eos8.f - Equation of state for water - air - (dead) oil. rcol8 - Input file for sample problem 9 (flushing oil from a 1-D column). Equation-of-state Module 9 ========================== eos9.f - Equation of state for saturated-unsaturated flow (Richards’ equation). reos9a - Input file for sample problem 10 (gravity-capillary equilibrium). rpm - Input file for sample problem 11 (block-by-block permeability modification). Equation-of-state Module EWASG ============================== ewasg.f - Equation of state for three-phase mixtures of water, solid NaCl, and non-condensible gas. EWASG includes dissolution and precipitation of salt with porosity and permeability change, and also can model vapor pressure lowering due to capillary pressure and vapor adsorption effects. rhbc - Input file for sample problem 12 (geothermal reservoir with hypersaline brine and CO2). Equation-of-state Module T2VOC ============================== t2voc.f - Three-phase water/air/NAPL. rgdif - One-dimensional gas diffusion (T2VOC problem 1). rblev - Buckley-Leverett problem (T2VOC problem 2). rtce1 - TCE injection in laboratory column (T2VOC problem 3, 1). rtce2 - TCE waterflood (T2VOC problem 3, 2). rtce3 - Steam sweep of TCE (T2VOC problem 3, 3). rfs1 - 2-D gravity-capillary equilibrium (T2VOC problem 4, 1). rfs2 - Xylene spill (T2VOC problem 4, 2). rfs3 - Xylene redistribution (T2VOC problem 4, 3). rfs4 - Steam sweep of Xylene (T2VOC problem 4, 4). r3d1 - Gravity-capillary equilibrium (T2VOC problem 5, 1). r3d2 - TCE spill (T2VOC problem 5, 2). r3d3 - Redistribution (T2VOC problem 5, 3). r3d4 - Remediation (T2VOC problem 5, 4). voc.data - Compilation of thermophysical property data for selected VOCs; Equation-of-state Module TMVOC ============================== This is an enhanced version of the free-standing TMVOC code (Pruess and Battistelli, 2002) that has been ported into the general TOUGH2 V2.1 framework. The enhancements include (1) hydrogen (H2) was added to the internal data bank of non-condensible gases (NCGs), and (2) all NCGs may be subjected to decay with a half-life model. The decay constant lambda = ln(2/T1/2) for an NCG is to be entered in the input file in columns 11-20 following the name of the NCG. Leaving the NCG half-life blank corresponds to no decay. The voc.dat data file was augmented by including data for propane. TMVOC uses the core TOUGH2 V2.1 modules and an additional fluid property file emvoc.f. The TMVOC fluid property module emvoc.f includes subroutines FGTAB, RELP and PCAP. “Legacy” subroutines with the same names in t2f.f may need to be removed prior to compilation and linking to avoid “duplicate names” errors; this is most conveniently done by simply changing the names of the t2f.f routines, such as FGTAB ==> FGTABx. The files in the TMVOC package are as follows. emvoc.f - Fluid property module for TMVOC. r7c - Input file for sample problem 1 (demonstrates initialization of different phase conditions). rblm - Input file for sample problem 2 (Buckley-Leverett flow; this is an adaptation of T2VOC sample problem *rblev*). rdif2 - Input file for sample problem 3 (molecular and thermal diffusion). rtcem1 - Input file for sample problem 4, part 1 (injection of TCE into a laboratory column; an adaptation of T2VOC sample problem *rtce1* for TMVOC). rtcem2 - Input file for sample problem 4, part 2 (waterflooding of TCE from a laboratory column; an adaptation of T2VOC sample problem *rtce2*). rtcem3 - Input file for sample problem 4, part 3 (steamflooding of TCE from a laboratory column; an adaptation of T2VOC sample problem *rtce3*). rtcem3on - A variation of *rtcem3* in which air is represented as a two-component mixture of oxygen and nitrogen. rbt1 - Input file for sample problem 5, part 1 (injection of a benzene-toluene mixture into a laboratory column; an enhancement of T2VOC sample problem *rtce1* to a two-component VOC mixture). rbt2 - Input file for sample problem 5, part 2 (waterflooding of a benzene-toluene mixture from a laboratory column; an enhancement of T2VOC sample problem *rtce2* to a two-component VOC mixture). rbt3 - Input file for sample problem 5, part 3 (steamflooding of a benzene-toluene mixture from a laboratory column; an enhancement of T2VOC sample problem *rtce3* to a two-component VOC mixture). rad1 - Input file for sample problem 6, part 1 (generation of a gas-static equilibrium in a laboratory column). rad2 - Input file for sample problem 6, part 2 (injection of a NAPL into single-phase gas conditions). rad3 - Input file for sample problem 6, part 3 (redistribution of NAPL under gravity and capillary forces). rad4 - Input file for sample problem 6, part 4 (removal of NAPL from a laboratory column by air flooding). r2dl1 - Input file for sample problem 7, part 1 (preparation of steady flow conditions, subject to aquifer flow and natural recharge). r2dl2 - Input file for sample problem 7, part 2 (spill of a 6-component NAPL in the unsaturated zone). r2dl2INCON - INCON file for the r2dl2 sample problem. r2dl3 - Input file for sample problem 7, part 3 (redistribution of a NAPL in the unsaturated zone and reaching the water table). r2dl3INCON - INCON file for the r2dl3 sample problem. r2dl4 - Input file for sample problem 7, part 4 (extraction of VOCs by soil vapor extraction from the unsaturated zone, and pumping from the aquifer). r2dl4INCON - INCON file for the r2dl4 sample problem. voc.dat - Property data for a selection of frequently encountered VOCs, in a format that is compatible with input data block CHEMP. rh2l1 - A problem with four fluid components (water, propane, air, and hydrogen). The problem involves just a single grid block in single-phase aqueous conditions, with dissolved propane (mole fraction 10-6) as well as hydrogen (mole fraction 1.4x10-5). Both propane and hydrogen are subject to decay with a half-life, which was arbitrarily set to T1/2 = 2 days for propane, T1/2 = 1 day for hydrogen. (The corresponding decay constants lambda = ln(2/T1/2) are 4.011x10-6 and 8.023x10-6.) rh2l2 - This is an output file for a two-phase aqueous-gas version of the problem simulated in rh2l1. The decay constant for hydrogen was scaled by the ratio of total to aqueous phase hydrogen inventory, (Maq + Mg)/Maq = 52.350, to a value of 52.350 x 8.023x10-6 = 4.200x10-4, to achieve the same effective 1 day half-life for total hydrogen as for dissolved hydrogen in problem rh2l1. rz2d - This is a 2-D R-Z problem that involves injection of hydrogen and propane into an unsaturated zone with an initial aqueous phase saturation of approximately 25.5 %. The injected components are assumed stable (no half-life decay). The initial conditions were generated in a separate run that did not include propane or hydrogen, and included infiltration of water from the top at a constant rate of 10 cm/yr. Equation-of-state Module ECO2N ============================== ECO2N is a fluid property module for mixtures of water-NaCl-CO2, designed for applications to CO2 storage in saline aquifers (Pruess, 2005; Pruess and Spycher, 2007). The ECO2N fluid property module eco2n.f includes a subroutine FGTAB. A “legacy” subroutine with the same name in t2f.f may need to be removed prior to compilation and linking to avoid “duplicate names” errors; this is most conveniently done by simply changing the name of the t2f.f routine, such as FGTAB ==> FGTABx. The ECO2N package includes the following files. eco2n.f - Equation of state for (NaCl) brine-CO2 mixtures, with only a single CO2-rich phase present. In addition to the two fluid phases, solid halite may be present as a third active phase. CO2TAB - A CO2 property data file obtained from Altunin’s correlations that must be present when TOUGH2/ECO2N is executed. rtab - Input file for sample problem 1 (demonstrates different initialization options). rcc3 - Input file for sample problem 2 (radial flow from a CO2 injection well). rcc3MESH - MESH file for sample problem 2. rcc3a - A variation of sample problem 2 that includes permeability reduction from solids precipitation (activated by setting IE(11)=3). r1dv1 - Input file for sample problem 3 (gravity equilibrium). r1dv2 - Input file for sample problem 3 (CO2 discharge along a fault zone). r1dv2INCON - INCON file with gravity-equilibrated conditions for sample problem 3. rtp7 - Input file for sample problem 4 (CO2 injection into a 2-D layered brine formation); this file includes the MESHMAKER input data for grid generation at the end. rtp7MESH - MESH file for sample problem 4. rtp7INCON - INCON file with gravity-equilibrated conditions for sample problem 4. co2tab3.f - An auxiliary program, written in FORTRAN77, for generating a table of thermophysical properties to be used with ECO2N and ECO2M. rco2h - An input data file for co2tab3.f. Equation-of-state Module ECO2M ============================== ECO2M is a TOUGH2 fluid property module for brine-CO2 mixtures, designed for integrated modeling of CO2 storage and leakage in saline aquifers (Pruess, 2011). A successor to and upward compatible with ECO2N, ECO2M can model transitions between super- and sub-critical conditions, phase change between liquid and gaseous CO2, and three-phase flow of aqueous - liquid CO2 - gaseous CO2 mixtures. TOUGH2/ECO2M can seamlessly model CO2 storage and leakage scenarios, all the way from a deep storage reservoir to land surface conditions. ECO2M uses the t2fm.f, T2, t2cg22n.f, t2f.f, meshm.f, and t2solv.f “core” files, the CO2TAB fluid property data and related files (co2tab3.f, rco2h) from ECO2N, and includes additional files (see below). The ECO2M fluid property module eco2m.f includes subroutines FGTAB, RELP and PCAP. “Legacy” subroutines with the same names in t2f.f may need to be removed prior to compilation and linking to avoid “duplicate names” errors; this is most conveniently done by simply changing the names of the t2f.f routines, such as FGTAB ==> FGTABx. The files in the ECO2M package are as follows. eco2m.f - Equation of state for (NaCl) brine-CO2 mixtures, that allows transitions between super- and sub-critical conditions, and phase change between liquid and gaseous CO2 in sub-critical conditions. In addition to three active fluid phases (aqueous - liquid CO2 - gaseous CO2), solid halite may be present as a fourth active phase. CO2TAB - A file with thermophysical property data for CO2 that must be present when TOUGH2/ECO2M is executed. multi.f - This is a version of subroutine MULTI that includes proper treatment of molecular diffusion. When molecular diffusion is not active, this is not necessary and the version of MULTI in t2fm.f may be used. rtab - Input file for sample problem 1 (demonstrating different initialization options). rcc3 - Input file for sample problem 2 (radial flow from a CO2 injection well). rcc3MESH - MESH file for sample problem 2. rcc3a - A variation of sample problem 2 that includes permeability reduction from solids precipitation (activated by setting IE(11)=3; we also set IE(7)=1 to get more detailed printout of parameters). r1d1 - Input file for sample problem 3 (mesh generation) r1d2 - Input file for sample problem 3 (equilibrium) r1d2MESH - MESH file for sample problem 3. r1d3 - Input file for sample problem 3 (CO2 leakage from a deep fault zone). r1d3MESH - MESH file for sample problem 3. r1d3INCON - INCON file for sample problem 3. rwaf - Input file for sample problem 4 (migration of a CO2 plume in a sloping aquifer, intersected by a fault). rwafMESH - MESH file for sample problem 4. rwafINCON - INCON file for sample problem 4. co2tab3.f - This is an auxiliary program, written in FORTRAN 77, for generating a table of thermophysical properties to be used with ECO2M. rco2h - An input data file for co2tab3.f. Dispersion Module T2DM ====================== t2dm.f - Module for strongly coupled flow and transport in 2-D systems with hydrodynamic dispersion ("dispersion module;" Oldenburg and Pruess, 1993); samd1 - Input file for 1-D dispersion (T2DM/EOS7 problem 1). samd2 - Input file for 2-D dispersion (T2DM/EOS7 problem 2). r2db - Input file for salt dome flow problem: 2-D dispersion with strong dependence of brine density on salinity (T2DM/EOS7 problem 3). rdis1 - Short test problem for verifying installation of the dispersion module. samr1 - Input file for 1-D radionuclide transport with sorption and decay (problem 1 from EOS7R report; Oldenburg and Pruess, 1995). sr12ph - Input file for 1-D transport of volatile radionuclides in two-phase conditions with sorption and decay (variation of problem 1 from EOS7R report; Oldenburg and Pruess, 1995). samr2 - Input file for 1-D transport of ammonium with sorption and decay (problem 2 from EOS7R report; Oldenburg and Pruess, 1995). shan1 - Input file for 1-D transport of a volatile tracer in the vadose zone (problem 4 from EOS7R report; Oldenburg and Pruess, 1995). ************************************************************************* ************************************************************************* ************************************************************************* COMPILATION/LINKING/EXECUTION OF TOUGH2 ************************************************************************* ************************************************************************* ************************************************************************* A separate executable has to be generated for each EOS module. Certain modules contain subroutines that supercede the standard subroutines. To avoid duplicate subroutine names, which trigger an error during linking, the standard subroutine has to be renamed. The following table shows the EOS modules that require renaming of subroutines prior to compilation: Renaming Duplicate Subroutines ------------------------------ |=======================================================================| | Module | Rename subroutine ... | ... in file ... | |=======================================================================| | all | Replace CPU timing function as needed | t2cg22.f | |-----------------------------------------------------------------------| | EOS7R | FGTAB | t2f.f | |-----------------------------------------------------------------------| | EOS9 | MULTI | t2fm.f | |-----------------------------------------------------------------------| | T2VOC | MULTI, RELP, PCAP | t2fm.f | | | RELP, PCAP | t2f.f | | | Comment out "call relp" in SAVEHS | t2f.f | |-----------------------------------------------------------------------| | ECO2N | FGTAB | t2f.f | |-----------------------------------------------------------------------| | ECO2M | FGTAB, RELP, PCAP | t2f.f | | | Comment out "call relp" in SAVEHS | t2f.f | |-----------------------------------------------------------------------| | ECO2M_diff | MULTI | t2fm.f | | | RELP, PCAP | t2f.f | | | Comment out "call relp" in SAVEHS | t2f.f | |-----------------------------------------------------------------------| | TMVOC | FGTAB, RELP, PCAP | t2f.f | | | Comment out "call relp" in SAVEHS | t2f.f | |-----------------------------------------------------------------------| | T2DM | CYCIT | t2fm.f | |=======================================================================| Compiler options ---------------- TOUGH2 requires 64-bit arithmetic (8 byte word length for floating point numbers) for successful execution. Users with 32-bit machines require a compiler option that will produce 64-bit arithmetic. As an example of compilation, linking, and program execution we reproduce here the commands that would be used on a workstation, running a UNIX-based operating system. The example involves creating an executable "xt2_eos1", and then using input file "rvf" to run sample problem 3. COMPILATION/LINKING (INCLUDE-file *T2* must be present) IBM RS/6000 f77 -o xt2_eos1 -qautodbl=dblpad \ t2fm.f eos1.f t2cg22.f meshm.f t2f.f t2solv.f DEC ALPHA f90 -o xt2_eos1 -r8 -i8 \ t2fm.f eos1.f t2cg22.f meshm.f t2f.f t2solv.f LINUX/gfortran gfortran -o xt2_eos1 -g -fdefault-real-8 -falign-commons \ t2fm.f eos1.f t2cg22.f meshm.f t2f.f t2solv.f LINUX/ifort ifort -o xt2_eos1 -g -r8 -i8 -align dcommons -check none \ t2fm.f eos1.f t2cg22.f meshm.f t2f.f t2solv.f Alternatively, provide compiler name and appropriate compiler options in file makefile, set EOS = eos1 and type "make". For compilation and linking on a PC, invoke the equivalent compiler options, specifically regarding 64-bit arithmetic. Run-time checks for array bound errors need to be disabled, and alignment of COMMON blocks should be invoked. EXECUTION xt2_eos1 < rvf > rvf.out On a PC, this command is executed in a DOS Command Prompt window. TEST OF CODE INSTALLATION ========================= Users should run several of the sample problems to check on proper code installation. Due to machine-dependent roundoff, TOUGH2 may produce slightly different results on different computers. For same-size time steps, all primary variables (pressure P, temperature T, saturation S, etc.) and their changes (DX1, DX2,...) should agree to typically four digits or better. However, on different computers the iteration sequence for a time step may be slightly different because of roundoff, and occasionally a different number of iterations may be required for convergence. If automatic time stepping is used, a different number of iterations for convergence may subsequently cause different-size time steps to be taken; naturally this will then produce somewhat larger discrepancies in results because of different time truncation errors. Of all the numbers processed by TOUGH2, the most sensitive are the residuals, i.e. the differences between left-hand sides (accumulation terms) and right-hand sides (flow terms) of the governing equations. During the Newton-Raphson iteration process these residuals are reduced to smaller and smaller values, until they drop below specified conver- gence tolerances. As convergence is approached, the residuals are subject to increasingly severe numerical cancellation, arising from subtracting two numbers with diminishing difference. Maximum residuals are (optionally) printed during the iteration process as "MAX. RES.", and are also printed in the header of a full time step printout (as "MAX. RES." or "RERM"). These numbers can serve as a convenient check when evaluating reproducibility of code applications. Small numerical differences due to roundoff etc. will first show up in different values for "MAX. RES.", long before giving any visible changes in primary variables or their increments. ************************************************************************* DOCUMENTATION ************************************************************************* All TOUGH-related manuals can be downloaded from the TOUGH web site at http://esd.lbl.gov/TOUGH TOUGH2 Documentation Pruess, K., C. Oldenburg, and G. Moridis, TOUGH2 User's Guide, Version 2.0, Report LBNL-43134, Lawrence Berkeley National Laboratory, November 1999. EOS7 Documentation Pruess, K. EOS7, An Equation-of-State Module for the TOUGH2 Simulator for Two-Phase Flow of Saline Water and Air, Report LBL-31114, Lawrence Berkeley Laboratory, Berkeley, CA, 1991. EOS7R Documentation Oldenburg, C.M. and K. Pruess. EOS7R: Radionuclide Transport for TOUGH2, Report LBL-34868, Lawrence Berkeley National Laboratory, November 1995. ECO2N Documentation Pruess, K. ECO2N: A TOUGH2 Fluid Property Module for Mixtures of Water, NaCl and CO2, Report LBNL057952, Lawrence Berkeley National Laboratory, August 2005. ECO2M Documentation Pruess, K. ECO2M: A TOUGH2 Fluid Property Module for Mixtures of Water, NaCl and CO2, Including Super- and Sub-Critical Conditions, and Phase Change between Liquid and Gaseous CO2, Report LBNL, Lawrence Berkeley National Laboratory, April 2011. T2VOC Documentation Falta, R., K. Pruess, S. Finsterle, and A. Battistelli, T2VOC User's Guide, Report LBL-36400, Lawrence Berkeley National Laboratory, March 1995 TMVOC Documentation Pruess, K. and A. Battistelli. TMVOC, a Numerical Simulator for Three-Phase Non-Isothermal Flows of Multicomponent Hydrocarbon Mixtures in Saturated-Unsaturated Heterogeneous Media, Report LBNL-49375, Lawrence Berkeley National Laboratory, April 2002. T2DM Documentation Oldenburg, C. and K. Pruess, A Two-Dimensional Dispersion Module for the TOUGH2 Simulator, Report LBL-32505, Lawrence Berkeley National Laboratory Report, September 1993. Hysteresis Module Documentation Doughty, C., User's Guide for Hysteretic Capillary Pressure and Relative Permeability Functions in iTOUGH2,Report LBNL-2483E, Lawrence Berkeley National Laboratory, Berkeley, Calif., August 2009. ************************************************************************* Distribution TOUGH2/ECO2N is distributed by LBNL. Please visit: http://esd.lbl.gov/TOUGH/licensing.html or contact: Juliet Hart Licensing Analyst Technology Transfer Department Lawrence Berkeley National Laboratory 1 Cyclotron Road, MS 56A0120 Berkeley, CA 94720 E-Mail: JMHart@lbl.gov Users are requested to tell us about any bugs that may be encountered. We also like to hear about code improvements and enhancements; send e-mail to the TOUGH Developer Team ************************************************************************* * Additional information is available on the TOUGH2 homepage on the web * * * * http://esd.lbl.gov/TOUGH/ * ************************************************************************* ......................................................................... .......READ.ME..........READ.ME..........READ.ME..........READ.ME........ .........................................................................