*************************************************************************
***************** TOUGH2 Version 1.11 January 1994 ****************
******** with preconditioned conjugate gradient module T2CG1 ********
*************************************************************************
.......READ.ME..........READ.ME..........READ.ME..........READ.ME........
.........................................................................
..............................Update 1/98...............................
.........................................................................
This flyer contains brief instructions for installing and running TOUGH2.
TOUGH2 is distributed on magnetic tape with specifications as follows:
9-track, 1600 BPI, ASCII, no labels, Recordsize 80, Blocksize 4800. The
program is also available on 3.5'' high-density diskettes, written either
in PC-DOS format, or according to specifications of IBM RISC System/6000
workstations. The distribution includes the following 14 files.
*************************************************************************
(1) read.me - the file you're reading
(2) t2cg1.f - contains the main program of TOUGH2, with PARAMETER
statements for flexible dimensioning of all major arrays,
and initialization of disk files; also includes a revised
version of subroutine LINEQ that calls a suite of
preconditioned conjugate gradient routines;
t2cg1.f replaces the program module t2m.f of the previous
version of TOUGH2 (Version 1.0, April 1991);
(3) meshm.f - module with internal mesh generation facilities
(4) eos1.f - equation of state for water or two waters
(5) eos2.f - equation of state for water/CO2 mixtures
(6) eos3.f - equation of state for water/air (similar to TOUGH)
(7) eos4.f - equation of state for water/air with vapor pressure
lowering capability
(8) eos5.f - equation of state for water/hydrogen; otherwise similar
to eos3.f
(9) t2f.f - the core module of TOUGH2; it reads input data, initial-
izes arrays and parameters, sets up the 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
(10) 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.)
In addition there are four input files for sample problems.
(11) sam1 - input file for sample problem 1 (code demonstration and
comparison with TOUGH)
(12) rhp - input file for sample problem 2 (heat pipe in cylindrical
geometry)
(13) rvf - input file for sample problem 3 (heat sweep in a vertical
fracture)
(14) rfp - input file for sample problem 4 (five-spot geothermal
production/injection)
*************************************************************************
Files (2) - (10) contain the TOUGH2 source code. The only change in
comparison to version 1.0, April 1991, is the replacement of file t2m.f
with t2cg1.f, the preconditioned conjugate gradient module. When compiling
and linking TOUGH2, t2cg1.f should come first, then meshm.f, then the
desired EOS-module, then t2f.f, and finally ma28.f. Note that only one of
the EOS modules must be linked at a time. 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 "eos3.f",
creating an executable "x3", and then using input file rhp to run
sample problem 2.
COMPILATION
xlf -c -qautodbl=dblpad t2cg1.f meshm.f eos3.f t2f.f ma28.f
LINKING
xlf -o x3 t2cg1.o meshm.o eos3.o t2f.o ma28.o
EXECUTION
x3 rhp.out
The option "-qautodbl=dblpad" is required in order to obtain 64-bit
arithmetic.
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. There are several calls to an
external routine "SECOND" for obtaining elapsed CPU times, such as
CALL SECOND(TZERO)
Different machines have different conventions for obtaining CPU time, and
the "CALL SECOND" statements may need to be adjusted. To avoid possible
"unsatisfied external" errors we have included in t2cg1.f a dummy
subroutine SECOND, as follows.
SUBROUTINE SECOND(T)
T=0.
RETURN
END
This routine will cause all execution times to be reported as 0.0 in
the printout.
The file t2cg1.f includes the following routines:
(i) revised versions of the program units normally supplied in t2m.f,
(ii) a version of subroutine LINEQ that is appropriately modified for
interfacing with the conjugate gradient solvers, and
(iii) a set of preconditioned conjugate gradient routines.
The presence of a modified version of subroutine LINEQ in t2cg1.f will
create a situation of "duplicate names" during the linking process, as
a subroutine LINEQ is also present in standard TOUGH2 (file t2f.f). On
most computers the linker will simply use the first program unit with
a given name, and will ignore subsequent program units with the same
name. On some computers the presence of duplicate names during linking
will create a fatal error. The simplest way to avoid this is to change
the names of the unwanted program units. Specifically, the name conflict
can be avoided by renaming LINEQ in t2f.f to LINEX, say, prior to
compilation and linking.
The only user-definable input parameter associated with the conjugate
gradient module is MOP(21) in block PARAM, which selects different
solvers as follows.
MOP(21) = 0: default; is set internally to MOP(21) = 3.
1: direct solution with MA28 (as in TOUGH2, Version 1.0).
2: routine DSLUBC: biconjugate gradient solver with
incomplete LU-factorization.
3: routine DSLUCS: Lanczos-type biconjugate gradient solver
with incomplete LU-factorization.
4: routine DSLUGM: generalized minimum residual solver with
incomplete LU-factorization.
Apart from the choice of the linear equation solver, there are no user-
definable parameters, and the conjugate gradient package would be run with
unmodified TOUGH2 input files.
The computational work for iterative solvers increases much less with
problem size and matrix bandwidth than is the case for direct solvers.
Therefore, iterative solution is the method of choice for virtually all
3-D problems, and for 1-D and 2-D problems with more than a few thousand
simultaneous equations. Present dimensioning of the T2CG1 package is for
up to 10,000 grid blocks and up to 4 equations per grid block. Maximum
problem size can be easily changed in PARAMETER statements in the main
program. If the number of grid blocks exceeds 4 digits (9999), FORMAT
statement # 1505 in subroutine RFILE in t2f.f must be changed from 20I4
to 16I5.
Iterative solvers such as conjugate gradients do not, generally
speaking, have the same robustness as direct solution techniques, and the
performance of the different algorithms is problem-dependent. The default
solver option invokes the Lanczos-type biconjugate gradient solver which
often is the most computationally efficient. Our simulations of a broad
variety of flow problems indicate that each of the 3 conjugate gradient
solvers included in the T2CG1 package is optimal for certain cases, while
failing for others (Moridis et al., 1994). Therefore, for any given flow
problem, users are encouraged to experiment and try the different solvers
offered.
As mentioned before, T2CG1 requires no user-definable parameters other
than the choice of linear equation solver. Occasionally users may wish to
modify the default settings for iteration and convergence parameters.
These parameters are defined upon the first call (ICALL = 1) in subroutine
LINEQ in module T2CG1, as illustrated in the following code fragment.
IF(ICALL.EQ.1) THEN
WRITE(11,899)
899 FORMAT(6X,'LINEQ 0.91 CG 31 JANUARY 1994',6X,
X'INTERFACE FOR LINEAR EQUATION SOLVERS'/
X47X,'CAN CALL MA28 OR A PACKAGE OF CONJUGATE GRADIENT',
X' SOLVERS')
C
MATSLV=MOP(21)
IF(MATSLV.EQ.0.OR.MATSLV.GT.4) MATSLV=3
NMAXIT=MAX(20,NEL*NEQ/10)
ICLOSR=2
IF(MATSLV.EQ.4) ICLOSR=0
CLOSUR=1.E-6
ISYM=0
IUNIT=0
NVECTR=30
SEED=1.E-25
ENDIF
For very tough problems, it may be necessary to tighten the convergence
criterion CLOSUR beyond the default of 1.E-6, and to increase the maximum
number of iterations beyond the value specified in NMAXIT (NEL*NEQ is the
order of the matrix of the linear equation system). Information on
convergence behavior for each Newtonian iteration is written onto a disk
file 'LINEQ'.
TOUGH2 requires 64-bit arithmetic 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 declare
all floating point variables double precision, and to modify floating
point constants to "D" format. No modifications in function names will be
needed as TOUGH2 uses generic FORTRAN 77 function names throughout.
Files (11) - (14) contain input files for the sample problems presented
in the TOUGH2 report. 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, 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, TOUGH2 - A General-Purpose Numerical Simulator for
Multiphase Fluid and Heat Flow, Lawrence Berkeley Laboratory Report
LBL - 29400, May 1991.
The TOUGH2 report is not a self-contained free standing document. For
instructions on preparing input data, users also need the following
report:
K. Pruess, TOUGH User's Guide, Lawrence Berkeley Laboratory Report
LBL - 20700, June 1987 (also available as Nuclear Regulatory
Commission Report NUREG/CR-4645).
Information on the conjugate gradient algorithms and applications to
large 2-D and 3-D flow problems are presented in:
Moridis, G., K. Pruess, E. Antunez, and C. Oldenburg. T2CG1, A Package
of Preconditioned Conjugate Gradient Solvers for the TOUGH2 Family of
Codes, Lawrence Berkeley Laboratory Report LBL-35518, Lawrence Berkeley
Laboratory, Berkeley, CA, 1994.
Antunez, A., G. Moridis and K. Pruess. Large-Scale Geothermal Reservoir
Simulation on PCs, Lawrence Berkeley Laboratory Report LBL-35192,
presented at 19th Workshop on Geothermal Reservoir Engineering,
Stanford University, Stanford, CA, January 1994.
The DSLUBC and DSLUCS routines used in the conjugate gradient package
were written by Anne Greenbaum (Courant Institute) and Mark K. Seager
(Lawrence Livermore National Laboratory). DSLUGM was written by Peter
Brown, Alan Hindmarsh, and Mark K. Seager (all of LLNL). These routines
were adapted and improved for incorporation into the TOUGH2 code by
George Moridis (Lawrence Berkeley Laboratory). Interfacing with TOUGH2
was done by George Moridis and Karsten Pruess.
*************************************************************************
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 (423) 576-2606
fax (423) 576-6436
email: estsc@adonis.osti.gov
WorldWideWeb: http://www.osti.gov/estsc/
The address of the code developer is
Karsten Pruess
Mail Stop 90-1116
Lawrence Berkeley Laboratory
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 1/98................................
.........................................................................
go to TOUGH2 home page