************************************************************************* ******************** TMVOC Version 1.0 ******************** ******************** April 2002 ******************** ************************************************************************* .......READ.ME..........READ.ME..........READ.ME..........READ.ME........ ......................................................................... This flyer contains brief instructions for installing and running TMVOC. TMVOC is a member of the TOUGH2 family of codes. General information about TOUGH2 is available on the TOUGH2 homepage: ************************************************************************* * http://www-esd.lbl.gov/TOUGH2/ * ************************************************************************* TMVOC is a simulator for multicomponent, multiphase, nonisothermal flows of water, soil gas, and several volatile organic chemicals (VOCs). It is based on the M2NOTS-code developed by Adeyinka Adenekan as part of his PhD project at UC Berkeley (Adenekan, 1992). TMVOC is written in standard FORTRAN 77 and operates within the framework of TOUGH2, Version 2.0 (T2V2; Pruess et al., 1999). The code consists of two modules (groups of routines) named *t2fm.f* and *emvoc.f* that must be linked to several standard T2V2 modules, as described below. TMVOC includes the following 29 files. (1) read.me - the file you're reading; (2) t2fm.f - consists of a number of standard T2V2 program units that have been enhanced to accommodate additional data input and output needs for TMVOC. These modified program units function as "supersets" to their T2V2 counterparts; i.e., they are able to run standard TOUGH2, Version 2.0 applications, including T2VOC applications. t2fm.f must be compiled with an INCLUDE file *T2* present. (3) T2 - an INCLUDE file with PARAMETER statements for flexible dimensioning of all major arrays that must be present when compiling t2fm.f and t2cg22.f (file name is case-sensitive and must be "upper case"); (4) emvoc.f - the fluid properties package, consisting of subroutine EOS and satellite routines; includes routines for 3-phase relative permeabilities and capillary pressures; (5) t2cg22.f - the "front end" for the linear solver package. It 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. Must be compiled with an INCLUDE file *T2* present. (6) meshm.f - module with internal mesh generation facilities; (7) 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). (8) t2solv.f - a package of conjugate gradient solvers; (9) 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 and TMVOC requires proper license. Contact: The Harwell Subroutine Library Liaison Officer, Mr. S. Marlow, Building 8.9, Harwell Laboratory, Didcot, Oxon OX11 0RA, United Kingdom.) (10) r7c - input file for sample problem 1 (demonstrates initialization of different phase conditions); (11) rblm - input file for sample problem 2 (Buckley-Leverett flow; this is an adaptation of T2VOC sample problem *rblev*); (12) rdif2 - input file for sample problem 3 (molecular and thermal diffusion); (13) 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); (14) rtcem2 - input file for sample problem 4, part 2 (waterflooding of TCE from a laboratory column; an adaptation of T2VOC sample problem *rtce2*); (15) rtcem3 - input file for sample problem 4, part 3 (steamflooding of TCE from a laboratory column; an adaptation of T2VOC sample problem *rtce3*); (16) rtcem3on - a variation of *rtcem3* in which air is represented as a two-component mixture of oxygen and nitrogen; (17) 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); (18) 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); (19) 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); (20) rad1 - input file for sample problem 6, part 1 (generation of a gas-static equilibrium in a laboratory column); (21) rad2 - input file for sample problem 6, part 2 (injection of a NAPL into single-phase gas conditions); (22) rad3 - input file for sample problem 6, part 3 (redistribution of NAPL under gravity and capillary forces); (23) rad4 - input file for sample problem 6, part 4 (removal of NAPL from a laboratory column by air flooding); (24) m2dl - MESH file for sample problem 7 (field-scale problem of a NAPL spill in the unsaturated zone above an unconfined aquifer); (25) r2dl1 - input file for sample problem 7, part 1 (preparation of steady flow conditions, subject to aquifer flow and natural recharge); (26) r2dl2 - input file for sample problem 7, part 2 (spill of a 6-component NAPL in the unsaturated zone); (27) r2dl3 - input file for sample problem 7, part 3 (redistribution of a NAPL in the unsaturated zone and reaching the water table); (28) 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); (29) voc.dat - property data for a selection of frequently encountered VOCs, in a format that is compatible with input data block CHEMP. ************************************************************************* TMVOC 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. 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 TMVOC 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 creating an executable "ztm", and then using input file "rbt1" to run part 1 of sample problem 5. COMPILATION (INCLUDE-file *T2* must be present) f77 -c -qautodbl=dblpad t2fm.f emvoc.f t2cg22.f meshm.f t2f.f t2solv.f ma28.f LINKING f77 -o ztm t2fm.o emvoc.o t2cg22.o meshm.o t2f.o t2solv.o ma28.o EXECUTION ztm rbt1.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 t2fm.f emvoc.f t2cg22.f meshm.f t2f.f t2solv.f ma28.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 may be used. ========================================================================= DUPLICATE NAMES ========================================================================= As mentioned above, the special TMVOC modules *t2fm.f* and *emvoc.f* contain some program units with the same names as standard T2V2 units. These units supersede original T2V2 units. The linking instruction given above will encounter "duplicate names;" for example, *t2fm.f* includes a subroutine MULTI, while a standard T2V2 version of subroutine MULTI is also present in T2V2 module t2f.f. On the IBM RS/6000 the linker will automatically link the first occurrence of MULTI (from *t2fm.f*), and will ignore the additional MULTI present in *t2f.f*. This is the desired outcome. On some computers, the linking instruction will give rise to a fatal "duplicate names" error. To avoid this problem, names of unwanted standard T2V2 subroutines should be changed prior to compilation. For example, the name of routine MULTI in *t2f.f* should be changed to something like MULTIx. ========================================================================= TOUGH2 Users ========================================================================= TMVOC differs in two important respects from other TOUGH2 modules. (1) It uses a special integer index to distinguish different phase conditions. This requires an extra input of an integer in specifications of initial conditions. (2) All mass balances are set up and solved in terms of molar units (gram-moles per cubic meter of medium), rather than in terms of mass units (kilograms per cubic meter of medium) as in other TOUGH2 modules. ========================================================================= T2VOC Users ========================================================================= TMVOC input files are very similar to T2VOC input files. Slight revisions in T2VOC input files are required in data blocks CHEMP for VOC parameters. User options selectable by means of the parameter NKIN are available to initialize a TMVOC run from T2VOC-style initial conditions, with automatic internal conversion of input data prior to execution. Diffusion parameters in TMVOC are provided through a separate data block DIFFU; the gas phase diffusion parameters in record CHEMP.6 of data block CHEMP are not used. Additional input data blocks NCGAS and SELECT are used by TMVOC. ========================================================================= M2NOTS Users ========================================================================= TMVOC is an adaptation of M2NOTS to the T2V2 environment, which in many respects retains original M2NOTS methods and coding. In terms of preparing input data, the most significant changes relative to M2NOTS are as follows. (1) some data formats in the CHEMP block are different; (2) numbering of phase conditions was changed to be consistent with the long-standing convention for storing fluid data in the PAR-array; the phase conditions in TMVOC are numbered as follows: 1-gas, 2-water, 3-NAPL, 4-gas/water, 5-gas/NAPL, 6-water/NAPL, 7-gas/water/NAPL; (3) sink and source specifications in GENER are the same as in standard T2V2; and (4) different program options and matrix solvers are available. ========================================================================= TEST OF CODE INSTALLATION ========================================================================= Users should run several of the sample problems to check on proper code installation (compare with test results presented in the TMVOC report; Pruess and Battistelli, 2002). Due to machine-dependent roundoff, TMVOC may produce slightly different results on different computers. For same-size time steps, all primary variables (pressure P, mole fractions x, saturation S, temperature T) 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 TMVOC, 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 user-selectable convergence 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. 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. ************************************************************************* References K. Pruess and A. Battistelli. TMVOC, a Numerical Simulator for Three-Phase Non-isothermal Flows of Multicomponent Hydrocarbon Mixtures in Saturated-Unsaturated Heterogeneous Media, Lawrence Berkeley National Laboratory Report LBNL-49375, January 2002. K. Pruess, C. Oldenburg and G. Moridis. TOUGH2 User's Guide, Version 2.0, Lawrence Berkeley National Laboratory Report LBNL-43134, November 1999. Adenekan, A.E. Numerical Modeling of Multiphase Transport of Multicomponent Organic Contaminants and Heat in the Subsurface, PhD thesis, University of California at Berkeley, Berkeley, CA 94720, 1992. Adenekan, A.E., T.W. Patzek and K. Pruess. Modeling of Multiphase Transport of Multicomponent Organic Contaminants and Heat in the Subsurface: Numerical Model Formulation, Water Resour. Res., Vol. 29, No. 11, pp. 3727-3740, 1993. ************************************************************************* Distribution of the TMVOC 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 developers can be reached as follows Karsten Pruess Alfredo Battistelli Mail Stop 90-1116 Aquater S.p.A. Lawrence Berkeley National Lab. 61047 San Lorenzo in Campo (PU) Berkeley, CA 94720 ITALY U.S.A. phone: 1-39-721-7311 phone: (510) 486-6732 email: email: K_Pruess@lbl.gov Alfredo.Battistelli@aquater.eni.it ************************************************************************* * 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........ .........................................................................