.......READ.ME..........READ.ME..........READ.ME..........READ.ME........
.........................................................................
.............................Update
7/01................................
.........................................................................
This flyer contains brief instructions for installing and running TOUGH2.
TOUGH2 is distributed
on two 3.5'' high-density diskettes, written
either in PC-DOS format, or according
to specifications of IBM RISC
System/6000 workstations. Utility
programs that are useful for TOUGH2
applications, such as mesh preprocessing,
assignment of boundary
conditions, and extraction of graphics
files, are available on the TOUGH2
homepage on the web.
*************************************************************************
*
http://www-esd.lbl.gov/TOUGH2/
*
*************************************************************************
The TOUGH2 homepage
also provides information and links of interest to
TOUGH2 users.
*************************************************************************
The TOUGH2 distribution diskettes include the following 58 files.
(1) read.me - the file you're reading;
(2) t2cg2.f - contains the
main program of TOUGH2, and must be compiled
with an INCLUDE file ëT2í with PARAMETER statements for
flexible dimensioning of all major arrays. This module
includes an executive routine LINEQ for the linear
equation solution, which may call a solver package
t2solv.f, or the sparse direct matrix solver ma28.f. It
also includes routines for preconditioning of the Jacobian
matrix.
(3) T2
- an INCLUDE file needed by t2cg2.f (name is case-sensitive
and must be ìupper caseî);
(4) T2small - an alternative
INCLUDE file, with PARAMETER statements for
small problems (must be renamed T2 for use with t2cg2.f);
(5) t2solv.f - a package of conjugate gradient solvers;
(6) t2cg1.f - alternative to
t2cg2.f; contains the main program of
TOUGH2 with PARAMETER statements for flexible dimensioning
of all major arrays, and includes the conjugate gradient
package that was first released in 1994. t2cg1.f is
basically superseded by t2cg2.f, but is included in the
package because it is more extensively tested, and because
it has somewhat lower memory requirements.
(7) meshm.f - module with internal mesh generation facilities;
(8) eos1.f - equation of state for water, or two waters;
(9) eos2.f - equation of state for water/CO2 mixtures;
(10) eos3.f - equation of state for water/air (similar to TOUGH);
(11) eos4.f - equation of state
for water/air with vapor pressure
lowering capability;
(12) eos5.f - equation of state
for water/hydrogen; otherwise similar
to eos3.f;
(13) eos7.f - equation of state for mixtures of water, brine, and air;
(14) eos7r.f - equation of state
for water/brine/air, plus two tracers
(parent-daughter radionuclides);
(15) eos8.f - equation of state
for three-phase mixtures of water/air/
oil;
(16) eos9.f - equation of state
for saturated-unsaturated flow
(Richardsí equation);
(17) 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; it also has vapor pressure lowering
capability; see EWASG homepage at
http://www.iirg.pi.cnr.it/ewasg/eosindex.html
(18) t2f.f - the core
module of TOUGH2; it reads input data, initial-
izes arrays and parameters, sets up the Jacobian matrix
for Newton-Raphson iteration, and performs time stepping.
It also contains the water property routines (steam table
equations) and the relative permeability and capillary
pressure functions which are used in the equation-of-state
modules.
(19) ma28.f - linear equation
solver from the Harwell subroutine library,
written by I.S. Duff. (MA28 is subject to proprietary
restrictions, and use outside of TOUGH2 requires proper
license. Contact: The Harwell Subroutine Library Liaison
Officer, Mr. S. Marlow, Building 8.9, Harwell Laboratory,
Didcot, Oxon OX11 0RA, United Kingdom.)
(20) sam1 - input
file for sample problem 1 (code demonstration and
comparison with TOUGH);
(21) rhp
- input file for sample problem 2 (heat pipe in cylindrical
geometry);
(22) rvf
- input file for sample problem 3 (heat sweep in a vertical
fracture);
(23) rfp
- input file for sample problem 4 (five-spot geothermal
production/injection);
(24) r1q - input file for sample problem 5 (coupled wellbore flow);
(25) rf1
- input file for sample problem 6 (multiphase and non-
isothermal processes in a system with variable salinity);
(26) rdif7 - input file
for sample problem 7 (thermal and tracer
diffusion);
(27) rdica - input file
for sample problem 8 (contamination of an
aquifer from VOC vapors in the vadose zone);
(28) rcol8 - input file
for sample problem 9 (flushing oil from a
1-D column);
(29) reos9a - input file for
sample problem 10 (gravity-capillary
equilibrium);
(30) rpm
- input file for sample problem 11 (block-by-block
permeability modification);
(31) rhbc - input
file for sample problem 12 (geothermal reservoir
with hypersaline brine and CO2);
(32) f725d - table of
downhole flowing wellbore pressures;
(33) t2voc.f - 3-phase water/air/NAPL module for TOUGH2;
(34) rgdif - one-dimensional gas diffusion (T2VOC problem 1);
(35) rblev - Buckley-Leverett problem (T2VOC problem 2);
(36) rtce1 - TCE injection in laboratory column (T2VOC problem 3, 1);
(37) rtce2 - TCE waterflood (T2VOC problem 3, 2);
(38) rtce3 - steam sweep of TCE (T2VOC problem 3, 3);
(39) rfs1 - 2-D gravity-capillary equilibrium (T2VOC problem 4, 1);
(40) rfs2 - Xylene spill (T2VOC problem 4, 2);
(41) rfs3 - Xylene redistribution (T2VOC problem 4, 3);
(42) rfs4 - steam sweep of Xylene (T2VOC problem 4, 4);
(43) voc.data - compilation of thermophysical
property data for
selected VOCs;
(44) t2dm.f - module for strongly
coupled flow and transport in 2-D
systems with hydrodynamic dispersion ("dispersion module;"
Oldenburg and Pruess, 1993);
(45) samd1 - input file for 1-D dispersion (T2DM/EOS7 problem 1);
(46) samd1MSH - MESH file for samd1;
(47) samd2 - input file for 2-D dispersion (T2DM/EOS7 problem 2);
(48) samd2MSH - MESH file for samd2;
(49) r2db - input
file for salt dome flow problem: 2-D dispersion
with strong dependence of brine density on salinity
(T2DM/EOS7 problem 3);
(50) r2dbMSH - MESH file for r2db;
(51) rdis1 - short test
problem for verifying installation of the
dispersion module;
(52) samr1 - input file
for 1-D radionuclide transport with sorption
and decay (problem 1 from EOS7R report; Oldenburg and
Pruess, 1995);
(53) samr1MSH - MESH file for samr1;
(54) 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);
(55) samr2 - input file
for 1-D transport of ammonium with sorption
and decay (problem 2 from EOS7R report; Oldenburg and
Pruess, 1995);
(56) samr2MSH - MESH file for samr2;
(57) shan1 - input file
for 1-D transport of a volatile tracer in the
vadose zone (problem 4 from EOS7R report; Oldenburg and
Pruess, 1995);
(58) shan1MSH - MESH file for shan1.
*************************************************************************
An effort was made
to have the TOUGH2 source code comply with the ANSI
X3.9-1978 (FORTRAN 77) standard,
and on most machines the code should
compile and run without modifications.
When compiling and linking TOUGH2,
t2cg2.f should come first, then
meshm.f, then the desired EOS-module,
then t2f.f, then ma28.f, and finally
t2solv.f. Note that only one of the
EOS modules must be linked at a
time.
When compiling
t2cg2.f, an INCLUDE file ëT2í (upper case) must be
provided which has PARAMETER statements
for flexible dimensioning of
major problem-size dependent arrays.
The TOUGH2 package includes two
alternative T2-files for ìlargeî
and ìsmallî problems. Users should
revise PARAMETER assignments to
suit their needs in terms of problem size
and memory requirements.
As an alternative
to the new t2cg2.f module, the previously released
conjugate gradient module t2cg1.f
may be used. In t2cg1.f, the problem-
size dependent arrays are dimensioned
in PARAMETER statements in the main
program, as follows.
PARAMETER(MNEL=12000,MNCON=25000,MNEQ=4,MNK=3,MNPH=3,MNB=6)
PARAMETER(MNOGN=300,MGTAB=2000)
(Up to 12,000 elements, 25,000 connections,
etc.; see a TOUGH2 output for
a full explanation.)
No INCLUDE file is needed when using
t2cg1.f. t2cg1.f includes the solvers
it is using, and does not need the
t2solv.f module.
TOUGH2 requires
64-bit arithmetic (8 byte word length for floating
point numbers) for successful execution.
With 32-bit arithmetic, the code
may perform marginally for problems
with very weak nonlinearities, but
in general will fail to converge.
Users with 32-bit machines should
invoke a compiler option that will
produce 64-bit arithmetic. If no such
option is available it will be necessary
to edit the FORTRAN code, declare
all floating point variables double
precision, and modify floating point
constants to "D" format. No modifications
in function names will be
needed as TOUGH2 uses generic FORTRAN
77 function names throughout.
As an example of
compilation, linking, and program execution we
reproduce here the commands that
would be used on an IBM RISC System/6000
workstation, running a UNIX-based
operating system. The example involves
using the EOS-module "eos7r.f",
creating an executable "y7r", and then
using input file "rdica" to run
sample problem 8.
COMPILATION (INCLUDE-file ëT2í must be present)
f77 -c -qautodbl=dblpad t2cg2.f meshm.f eos7r.f t2f.f ma28.f t2solv.f
LINKING
f77 -o y7r t2cg2.o meshm.o eos7r.o t2f.o ma28.o t2solv.o
EXECUTION
y7r <rdica >rdica.out
The option "-qautodbl=dblpad"
is required in order to obtain 64-bit
arithmetic. On some workstations,
the same effect is achieved by
specifying the option "-r8" for
compilation. For example, on a Dec Alpha
machine with a FORTRAN 90 compiler,
compilation would be made as follows.
f90 -c -r8 -i8 t2cg2.f meshm.f eos7r.f t2f.f ma28.f t2solv.f
Here we have specified integers also
to be stored as 8 byte words. This
is necessary to avoid alignment
problems that may arise in some COMMON
blocks where floating point and
integer variables are mixed.
For a faster executable, compiler optimization should be used.
When using t2cg1.f,
no INCLUDE files are needed, and the compilation
instruction on an IBM RS/6000 would
be as follows.
COMPILATION
f77 -c -qautodbl=dblpad t2cg1.f meshm.f eos7r.f t2f.f ma28.f
Note that it is not necessary to
re-compile program modules that have
been compiled already. In our example,
if the object modules meshm.o,
eos7r.o, t2f.o, and ma28.o
were already generated in the previous
compilation that used T2CG2, these
can be used for linking with T2CG1.
The linking command with T2CG1 is
f77 -o x7r t2cg1.o meshm.o eos7r.o t2f.o ma28.o
which produces an executable x7r.
Files (20) - (31)
contain input data for the sample problems presented
in the TOUGH2 report. File (32)
is a table of flowing wellbore pressures
that is needed for sample problem
No. 5 (input file r1q, coupled wellbore
flow).
=========================================================================
T2VOC
=========================================================================
File (33) is an
adaptation of the T2VOC module for version 2.0 of
TOUGH2. To assemble T2VOC, t2voc.f
should be used just like an EOS-module
in the compilation and linking instructions,
above. Note that T2VOC comes
with its own subroutine MULTI, and
some linkers will produce a ìduplicate
namesî error because t2f.f also
has a subroutine MULTI. If this occurs,
the subroutine MULTI in t2f.f should
be renamed ëMULTIXí prior to linking
T2VOC. Files (34) through (42) are
input files for the sample problems
presented in the T2VOC Userís Guide
(Falta et al., 1995). This report
should be used as a reference for
T2VOC applications, as it contains
specialized information that is
not provided in the TOUGH2 Userís Guide.
File (43) provides thermophysical
property data for selected VOCs for the
data block CHEMP.
=========================================================================
T2DM
=========================================================================
File (44) is the
dispersion module, application of which is described
in two separate reports (Oldenburg
and Pruess, 1993, 1995). Files (45)
through (58) provide input data
and MESH files for sample problems that
are described in the cited reports.
Note that some of these problems, or
problem variations, only involve
diffusion and no hydrodynamic dispersion,
so that they could be run without
the dispersion module. t2dm.f is
compiled with the same instructions
as given above. Linking with T2CG2
and EOS7 to obtain the executable
yy7 would be made with the following
instruction
f77 -o yy7 t2dm.o t2cg2.o meshm.o eos7.o t2f.o ma28.o t2solv.o
Recall that an INCLUDE file T2 must
be present when compiling t2cg2.f. As
an alternative, T2CG1 may be used
to link an executable xx7, as follows
f77 -o xx7 t2dm.o t2cg1.o meshm.o eos7.o t2f.o ma28.o
t2dm.f includes its own version of
subroutine LINEQ1. In order for this
to supersede a program unit of that
same name in t2cg2.f, t2dm.f must
be linked before t2cg2.f. If the
linker indicates a ìduplicate nameî
conflict, subroutine LINEQ1 in t2cg2.f
should be renamed LINEQX prior
to compilation and linking. t2dm.f
also includes its own version of
subroutine CYCIT which supersedes
routine CYCIT in t2f.f, and may require
renaming of CYCIT in t2f.f to CYCITX.
The dispersion
module has considerably larger memory requirements and
execution times. Prior to compilation
and linking, it is recommended to
specify smaller values in the PARAMETER
statements for the geometry data
arrays. For example, with T2CG1
the PARAMETER statements in the main
program could be changed to something
like
PARAMETER(MNEL=2000,MNCON=4000,MNEQ=6,MNK=5,MNPH=2,MNB=8)
PARAMETER(MNOGN=50,MGTAB=200)
The rather large values for MNK and
MNEQ were chosen to accommodate the
needs of EOS7R. With T2CG2 the INCLUDE
file ëT2smallí (file (4)) can be
used, with dimensions as in the
PARAMETER statement just given. (To use
T2small, it needs to be renamed
T2.) T2DM also includes PARAMETER
statements
PARAMETER (MNI=4000)
in subroutines DISF and DOT. Parameter
MNI has the same meaning as MNCON,
namely, the maximum number of interfaces
(or connections).
=========================================================================
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.
*************************************************************************
TOUGH2 is documented in:
K. Pruess, C. Oldenburg,
and G. Moridis, TOUGH2 User's Guide,
Version 2.0, Lawrence
Berkeley National Laboratory Report LBNL-43134,
November 1999.
Separate documentation is available for the T2VOC module:
R. Falta, K. Pruess,
S. Finsterle, and A. Battistelli, T2VOC User's
Guide, Lawrence
Berkeley National Laboratory Report LBL-36400,
March 1995
T2DM is documented in the following reports:
C. Oldenburg and
K. Pruess, A Two-Dimensional Dispersion Module for
the TOUGH2 Simulator,
Lawrence Berkeley National Laboratory Report
LBL-32505, September
1993.
C. Oldenburg and
K. Pruess, EOS7R: Radionuclide Transport for TOUGH2,
Lawrence Berkeley
National Laboratory Report LBL-34868, November 1995.
Information on the EOS7 and EOS7R
fluid property modules is available in
the following reports:
Pruess, K.
EOS7, An Equation-of-State Module for the TOUGH2 Simulator
for Two-Phase
Flow of Saline Water and Air, Report No. LBL-31114,
Lawrence Berkeley
Laboratory, Berkeley, CA, 1991b.
Oldenburg, C.M.
and K. Pruess. EOS7R: Radionuclide Transport for
TOUGH2. Lawrence
Berkeley National Laboratory Report LBL-34868,
November 1995.
*************************************************************************
Distribution of the TOUGH2 code is handled by
Energy Science
and Technology Software Center
P.O. Box 1020
Oak Ridge, Tennessee
37831
U.S.A.
phone (865) 576-2606
fax
(865) 576-6436
email: estsc@adonis.osti.gov
WorldWideWeb:
http://www.osti.gov/estsc/
The code development team can be reached as follows
Karsten Pruess
Mail Stop 90-1116
Lawrence Berkeley
National Lab.
Berkeley, CA 94720
U.S.A.
fax
(510) 486-5686
email: K_Pruess@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 K_Pruess@lbl.gov.
*************************************************************************
* Additional information is available
on the TOUGH2 homepage on the web *
*
*
*
http://www-esd.lbl.gov/TOUGH2/
*
*************************************************************************
.........................................................................
.......READ.ME..........READ.ME..........READ.ME..........READ.ME........
.........................................................................
.............................Update
7/01................................
.........................................................................