*************************************************************************
******************* TOUGH2 Version 1.11 for PC ********************
******** with preconditioned conjugate gradient module T2CG1 ********
*************************************************************************
************************ January 1995 ************************
*************************************************************************
.........................................................................
.......READ.ME..........READ.ME..........READ.ME..........READ.ME........
.........................................................................
...............................Update 1/98..............................
.........................................................................
This flyer contains brief instructions for installing and running TOUGH2
under DOS or WINDOWS operating systems on an IBM PC or compatible. The
TOUGH2-PC code can be executed on 386 machines or better. It can also
be used on standard workstations with 32-bit wordlength.
The TOUGH2 code as originally released in April 1991 required 64-bit
arithmetic, while the 386, 486 and 585 (Pentium) machines have 32-bit
wordlength. Accordingly, in the present TOUGH2-PC version all floating
point variables have been declared "REAL*8" (double precision), and all
floating point constants have been converted from Ew.d to Dw.d format.
Further changes in the mainframe (64-bit) version to accommodate the PC
environment are:
(1) Subroutines SECOND, ELDAYS, and ADDAYS have been appended to
module t2cg1 for obtaining CPU times.
(2) FORMAT statements with more than 127 'X' field spaces have been
modified according to 129X --> 120X,9X, to avoid a problem with
the LAHEY compiler, Version 5.XX.
No modifications in function names are needed, because TOUGH2 uses
generic FORTRAN77 function names throughout. The TOUGH2 version described
here includes a major enhancement over the April 1991 version, namely,
in addition to direct matrix solution it offers a choice of three
different preconditioned conjugate gradient solvers (see below).
Depending on the size of random-access memory, the conjugate gradient
solvers permit simulation of large 3-D problems with 10,000 or more grid
blocks.
Present dimensioning is for 4 Megabytes of RAM, allowing for up to 800
grid blocks, 2400 connections, and 3 equations per grid block when one of
the conjugate gradient solvers is being used. With the direct solver MA28
the same 4 MB of RAM will allow the execution of models with a maximum of
500 grid blocks and 1500 connections. Maximum problem size can be easily
changed in PARAMETER statements in the main program. The length of the
largest arrays increases in direct proportion to parameters MNEL and
MNCON and proportional to MNEQ*MNEQ, where MNEL = maximum number of
elements (grid blocks), MNCON = maximum number of connections, and
MNEQ = maximum number of equations per grid block. Accordingly, to solve
problems with up to 8,000 grid blocks, 24,000 connections, and
3 equations per grid block (MNEL=8000, MNCON=24000, MNEQ=3) would require
approximately 40 MB of RAM; solving only 2 equations per grid block would
then require approximately 18 MB.
TOUGH2-PC is distributed on a 3.5" high-density diskette, formatted
under the MS-DOS operating system for IBM PC's or compatibles. The
program package is set up to be compiled and linked using a LAHEY Fortran
compiler version 5.00 or better. Other compilers that can access
extended memory (memory beyond 1 MB) may be used instead with minor
changes to the CPU timing subroutines. For some compilers and computers
the CPU timing routine provided with TOUGH2 may not be operable; a quick
fix is explained in detail in the 'ADDITIONAL NOTES' section in this
flyer. A few minor coding revisions relative to the 64-bit version of
April 1991 have also been made; these are summarized in the section
titled 'REVISIONS', below.
The distribution diskette includes the following 18 files:
*************************************************************************
(1) read.me - the file you're reading
(2) t2cg1.for - replaces the program module t2m.for of the previous
version of TOUGH2 (Version 1.0, April 1991).
It 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.
(3) meshm.for - module with internal mesh generation capabilities
(4) eos1.for - equation of state for water, or two waters
(5) eos2.for - equation of state for water/CO2 mixtures
(6) eos3.for - equation of state for water/air (similar to TOUGH)
(7) eos4.for - equation of state for water/air with vapor pressure
lowering capability
(8) eos5.for - equation of state for water/hydrogen; otherwise similar
to eos3.for
(9) t2f.for - 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
relative permeability and capillary pressure functions
which are used in the equation-of-state modules
(10) ma28.for - 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.)
(11) makefile file that contains the required commands and instructions
to compile, link and create an executable file using the
LAHEY Fortran compiler Ver. 5.XX. Can be modified to
customize installation of TOUGH2, or to compile and link
the code with other equation of state (EOS) modules.
(12) install.bat file to install and create the required directories
to start using the program according to the suggested
structure in the "makefile" file
(13) delet.bat utility file to erase TOUGH2 generated output files
between runs. This file should be used with caution and
be customized to the specific needs of a user.
(14) second.for 'dummy' subroutine; can be used to avoid "unsatisfied
external" error when certain CPU-timing routines are not
available; see 'ADDITIONAL NOTES', below.
In addition there are four input files for sample problems.
(15) sam1 - input file for sample problem 1 (code demonstration and
comparison with TOUGH)
(16) rhp - input file for sample problem 2 (heat pipe in cylindrical
geometry)
(17) rvf - input file for sample problem 3 (heat sweep in a vertical
fracture)
(18) rfp - input file for sample problem 4 (five-spot geothermal
production/injection)
*************************************************************************
Files (2) - (10) contain the TOUGH2 source code. The only significant
change in comparison to version 1.0, April 1991, is the replacement of
file t2m.for with t2cg1.for, the preconditioned conjugate gradient module.
When compiling and linking TOUGH2, t2cg1.for should come first, then
meshm.for, then the desired EOS-module, then t2f.for, and finally
ma28.for. Note that only one of the EOS modules must be linked at a time.
Files (15) - (18) 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 reproducibi-
lity of code applications. Small numerical differences due to roundoff
will first show up in different values for "MAX. RES.", long before giving
any visible changes in primary variables or their increments.
INSTALLATION ON PCs
On an IBM PC, or compatible 386 machine or better with a DOS-based
operating system, using LAHEY compiler Ver. 5.00 or later, small simula-
tions may be run from DOS. The number of elements in a simulation model
will depend on the amount of extended memory (XMS) available in the
machine. For big simulation jobs using the LAHEY compiler Ver. 5.XX, it
is necessary that all extended memory (memory beyond 1 MB) must be made
available to the LAHEY compiler prior to compilation and linking. To
perform this operation all Terminate and Stay Resident Programs (TSR)
must be removed. It is recommended to use stripped-down versions of the
CONFIG.SYS and AUTOEXEC.BAT files specific for running TOUGH2. MS-DOS
Version 6.0 or later allow the use of multiple CONFIG.SYS and AUTOEXEC.BAT
files, see the MS-DOS and FORTRAN compiler manuals for details. Running
TOUGH2 under WINDOWS using the LAHEY Fortran compiler, has the advantage
of accessing virtual memory (temporary space on a hard drive). This
allows large simulation jobs to run on machines with limited amount of
RAM. The trade-off is a slower execution due to data swapping between
physical RAM and virtual memory. On machines with 16 MB of RAM and more,
it is possible to run TOUGH2 under WINDOWS in the background and use other
WINDOWS application in the foreground.
To install and run TOUGH2 using the LAHEY Fortran compiler Ver. 5.XX
proceed as follows. (This procedure assumes that the compiler is proper-
ly installed)
(1) Insert the distribution diskette in drive B:, type INSTALL and
press . The install file will create a TOUGH2 directory,
and copy TOUGH2-PC into this directory. It will also create a
DEVELOP subdirectory into which it will copy the input files
for the sample problems.
(2) Customize the "makefile" file as desired.
(3) Within the TOUGH2 directory, type the following command:
make
The code will then be compiled and linked and, if the "makefile" file
provided on the distribution diskette was not modified, an executable
"t2eos1.exe" incorporating the EOS1 fluid property module will be written
to the TOUGH2\DEVELOP directory.
As an example of code execution, sample problem No.4, five-spot
geothermal production and injection, would be run in the TOUGH2\DEVELOP
directory with the following command.
t2eos1 rfp.out
The first part of the command uploads the "t2eos1.exe" file and runs it
using the "rfp" file as the input deck. The output is redirected to the
"rfp.out" file. The ">rfp.out" part of the command is optional; if it is
not present, all output will be displayed on the screen.
PRECONDITIONED CONJUGATE GRADIENT PACKAGE
The file t2cg1.for includes the following routines:
(i) revised versions of the program units that in the April 1991
version of TOUGH2 were supplied in file t2m.for,
(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 only user-definable input parameter associated with the conjugate
gradient module is MOP(21) in data 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 is run with
unmodified TOUGH2 input files.
Computational work and memory requirements for iterative solvers
increase 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.
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.D-6
ISYM=0
IUNIT=0
NVECTR=30
SEED=1.D-25
ENDIF
For very difficult problems, it may be necessary to tighten the conver-
gence criterion CLOSUR beyond the default of 1.D-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 of the linear equation solution is written onto a
disk file 'LINEQ'. Iterations that failed to reach the convergence
criterion are identified by 'IERR=2&', while 'IERR=0&' indicates
convergence.
*************************************************************************
ADDITIONAL NOTES.
An effort was made to have the TOUGH2 source code comply with the
ANSI X3.9-1978 (FORTRAN 77) standard. On most machine and compiler
combinations the code should compile and run without modifications.
TOUGH2 makes several calls to an external routine "SECOND" for
obtaining elapsed CPU times, such as
CALL SECOND(TZERO).
The PC version of TOUGH2 includes the subroutines SECOND, ADDAYS and
ELDAYS that work together to provide the elapsed CPU times, and are compa-
tible with the LAHEY Fortran compiler. Different compilers have different
conventions for obtaining CPU time, and appropriate adjustments may be
needed. In some cases no facility for assigning CPU time may be available;
the user may then relinquish the CPU timing by replacing the subroutine
SECOND at the end of file t2cg1.for as follows.
SUBROUTINE SECOND(T)
C.....DUMMY SUBROUTINE
REAL*8 T
CHARACTER ELTIME*11, FECHA*8
COMMON/ELTIM/ELTIME,FECHA
T=0.D0
ELTIME='00:00:00.00'
FECHA ='01/01/01'
RETURN
END
An appropriate 'dummy' subroutine is provided with the TOUGH2-PC
program package (file 'second.for'). It will avoid an "unsatisfied
external" error and will cause all execution times and dates to be
reported as 0.0 and 01, respectively, in the printout.
*************************************************************************
REVISIONS
The present TOUGH2 version includes the following minor coding
changes relative to the TOUGH2 version of April 1991.
(1) Format statements 1505 in subroutines INPUT and RFILE (file 't2f.for')
have been changed from (20I4) to (16I5), to accommodate problems with
more than 9999 grid blocks.
(2) In subroutine WRZ2D (file 'meshm.for'), a bug in the assignment of
element names for radial meshes generated "by layers" (option 'RZ2DL')
was corrected.
(3) In subroutine CYCIT (file 't2f.for'), more printout is now provided
if the code stops with convergence failure after 25 consecutive
reductions of time step size.
(4) In subroutine MULTI (file 't2f.for'), advective flow between grid
blocks of which one has zero permeability is now suppressed,
regardless of interface weighting scheme. This avoids unphysical
flows for upstream-weighted permeability (MOP(11) equal to 0 or 1)
from a block of non-zero permeability into a block with zero
permeability.
(5) In subroutines QLOSS of files 'eos1.for' and 'eos2.for', an error
in the interrogation of phase conditions present in a grid block was
corrected. This error did not generate wrong results, but it could
slow down convergence rates and time stepping during phase change for
grid blocks subjected to semi-analytical heat exchange with
impermeable confining beds.
*************************************************************************
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 ins-
tructions 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. Emilio Antunez (LBL)
performed the adaptation to PC.
*************************************************************************
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........
.........................................................................
go to TOUGH2 home page