@@@ it2help.txt: Last modification: May 24, 2000 @@@ > COMMAND INDEX Command Index ============= > PARAMETER >> ABSOLUTE PERMEABILITY >> BOTTOMHOLE PRESSURE >> CAPACITY >> CAPILLARY PRESSURE FUNCTION >> COMPRESSIBILITY >> CONDUCTIVITY (WET/DRY) >> DRIFT >> ENTHALPY >> FACTOR >> FORCHHEIMER >> GUESS (FILE: file_name) >> IFS >> INITIAL (PRESSURE/: ipv) >> KLINKENBERG >> LAG >> LIST >> MINC >> PARALLEL PLATE >> POROSITY >> PRODUCTIVITY INDEX >> PUMPING RATIO >> RATE >> RELATIVE PERMEABILITY FUNCTION >> SCALE >> SELEC >> SHIFT >> SKIN >> TIME >> USER (: anno) >>> DEFAULT >>> LIST >>> MATERIAL: mat_name (mat_name_i...) (+ iplus) >>> MODEL >>> NONE >>> ROCK: mat_name (mat_name_i...) (+ iplus) >>> SET: iset >>> SINK: sink_name (sink_name_i ...) (+ iplus) >>> SOURCE: source_name (source_name_i ...) (+ iplus) >>>> ANNOTATION: anno >>>> BOUND: lower upper >>>> DEVIATION: sigma >>>> FACTOR >>>> GAUSS >>>> GUESS: guess >>>> INDEX: index (index_i ...) >>>> LIST >>>> LOGARITHM >>>> LOG(F) >>>> NORMAL >>>> PARAMETER: index (index_i ...) >>>> PERTURB: (-)alpha (%) >>>> PRIOR: prior_info >>>> RANGE: lower upper >>>> STEP: max_step >>>> UNIFORM >>>> VALUE >>>> VARIANCE: sigma^2 >>>> VARIATION: sigma >>>> WEIGHT: 1/sigma > OBSERVATION >> CONCENTRATION (comp_name/COMPONENT: icomp) (phase_name/PHASE: iphase) >> CONTENT (phase_name/PHASE: iphase) >> COVARIANCE (FILE: filename) >> CUMULATIVE (comp_name/COMPONENT: icomp) (phase_name/PHASE: iphase) >> DRAWDOWN (phase_name/PHASE: iphase) >> ENTHALPY (phase_name/PHASE: iphase) >> FLOW (phase_name/PHASE: iphase/HEAT) >> GENERATION (comp_name/COMPONENT: icomp) (phase_name/PHASE: iphase) >> LIST >> MASS FRACTION (comp_name/COMPONENT: icomp) (phase_name/PHASE: iphase) >> MOMENT (FIRST/SECOND) (X/Y/Z) (comp_name/COMPONENT: icomp) (phase_name/PHASE: iphase) >> PRESSURE (CAPILLARY) (phase_name/PHASE: iphase) >> PRODUCTION (comp_name/COMPONENT: icomp) (phase_name/PHASE: iphase) >> RESTART TIME: ntime (time_unit) (NEW) >> SATURATION (phase_name/PHASE: iphase) >> SECONDARY (phase_name/PHASE: iphase) (: ipar) >> TEMPERATURE >> TIME: ntime (EQUAL/LOGARITHMIC) (time_unit) >> TOTAL MASS (comp_name/COMPONENT: icomp) (phase_name/PHASE: iphase) (CHANGE) >> USER (: anno) >> VOLUME (phase_name/PHASE: iphase) (CHANGE) >>> CONNECTION: elem1 elem2 (elem_i elem_j ...) (++/+-/-+ iplus) >>> ELEMENT: elem (elem_i ...) (+ iplus) >>> GRID BLOCK: elem (elem_i ...) (+ iplus) >>> INTERFACE: elem1 elem2 (elem_i elem_j ...) (++/+-/-+ iplus) >>> LIST >>> MODEL >>> NONE >>> SINK: sink_name (sink_namei ...) (+ iplus) >>> SOURCE: source_name (source_namei ...) (+ iplus) >>>> ABSOLUTE >>>> ANNOTATION: anno >>>> AUTO >>>> AVERAGE (VOLUME) >>>> COLUMN: itime idata (istd_dev) >>>> COMPONENT comp_name/: icomp >>>> DATA (time_unit) (FILE: file_name) >>>> DEVIATION: sigma >>>> FACTOR: factor >>>> FORMAT: format >>>> HEADER: nskip >>>> INDEX: index (index_i ...) >>>> LIST >>>> LOGARITHM >>>> MEAN (VOLUME) >>>> PARAMETER: index (index_i ...) >>>> PHASE phase_name/: iphase >>>> PICK: npick >>>> POLYNOM: idegree (time_unit) >>>> RELATIVE: rel_err (%) >>>> SET: iset >>>> SHIFT: shift (TIME (time_unit)) >>>> SKIP: nskip >>>> SUM >>>> USER >>>> VARIANCE: sigma^2 >>>> WEIGHT: 1/sigma >>>> WINDOW: time_A time_B (time_unit) > COMPUTATION >> CONVERGE/STOP/TOLERANCE >>> ADJUST >>> CONSECUTIVE: max_iter1 >>> DELTFACT: deltfact >>> DIRECT >>> FORWARD >>> INCOMPLETE: max_incomplete >>> INPUT >>> ITERATION: max_iter >>> LEVENBERG: lambda >>> LIST >>> MARQUARDT: nue >>> REDUCTION: max_red >>> SIMULATION: mtough2 >>> STEP (UNSCALED): max_step >>> UPHILL: max_uphill >>> WARNING >> ERROR >>> ALPHA: alpha (%) >>> EMPIRICAL ORTHOGONAL FUNCTIONS (MATRIX: ndim) (iTOUGH2) (CORRELATION) >>> EOF (MATRIX: ndim) (iTOUGH2) (CORRELATION) >>> FISHER >>> FOSM (MATRIX: ndim) (iTOUGH2) (CORRELATION) (DIAGONAL) >>> HESSIAN >>> LATIN HYPERCUBE (MATRIX: ndim) (iTOUGH2) (CORRELATION/COVARIANCE) >>> LINEARITY (: alpha (%)) >>> LIST >>> MONTE CARLO (SEED: iseed) (GENERATE) (CLASS: nclass) >>> POSTERIORI >>> PRIORI >>> TAU: (-)niter >> JACOBIAN >>> CENTER >>> FORWARD (: iswitch) >>> HESSIAN >>> LIST >>> PERTURB : (-)perturb (%) >> OPTION >>> ANDREW: c >>> ANNEAL >>>> ITERATION: max_iter >>>> LIST >>>> SCHEDULE: beta >>>> STEP: max_step >>>> TEMPERATURE: (-)temp0 >>> CAUCHY >>> DESIGN >>> DIRECT >>> FORWARD >>> GRID SEARCH (UNSORTED) (: ninval1 (ninval2 (inval3)) / FILE: filename) >>> GAUSS-NEWTON >>> L1-ESTIMATOR >>> LEAST-SQUARE >>> LEVENBERG-MARQUARDT >>> LIST >>> OBJECTIVE (UNSORTED) (: ninval1 (ninval2 (inval3)) / FILE: filename) >>> QUADRATIC-LINEAR: c >>> SELECT >>>> CORRELATION: (-)rcorr >>>> ITERATION: niter >>>> LIST >>>> SENSITIVITY: (-)rsens >>> SIMPLEX >>> SENSITIVITY >>> STEADY-STATE (SAVE) (: max_time_step) >> OUTPUT >>> BENCHMARK >>> CHARACTERISTIC >>> COVARIANCE >>> FORMAT: format (LIST) >>> INDEX >>> LIST >>> JACOBIAN >>> NEW OUTPUT >>> OBJECTIVE >>> PERFORMANCE >>> PLOTFILE: format (LIST) >>> PLOTTING: niter >>> SENSITIVITY >>> time_unit >>> UPDATE >>> RESIDUAL >>> VERSION @@@ > VERSION UPDATE iTOUGH2 Updates =============== Version 3.0: July 1996 ++++++++++++++++++++++ Reference: Finsterle, S., K. Pruess, and P. Fraser, iTOUGH2 Software Qualification Lawrence Berkeley National Laboratory, LBNL-39489, Berkeley, Calif., 1996. Date: 01-03-97 Comment: A UNIX script file "it2help" is now available for online printing of iTOUGH2 manual pages. Version 3.1: April 1997 +++++++++++++++++++++++ References: Finsterle, S., iTOUGH2 Command Reference, Version 3.1, Report LBNL-40041, Lawrence Berkeley National Laboratory, Berkeley, Calif., 1997. Finsterle, S., iTOUGH2 Sample Problems, Report LBNL-40042, Lawrence Berkeley National Laboratory, Berkeley, Calif., 1997. Version 3.2: July 1998 ++++++++++++++++++++++ Reference: Finsterle, S., iTOUGH2 V3.2 Verification and Validation Report, Report LBNL-42002, Lawrence Berkeley National Laboratory, Berkeley, Calif., 1997. Version 3.3: October 1998 +++++++++++++++++++++++++ Reference: Finsterle, S., Parallelization of iTOUGH2 Using PVM, Report LBNL-42261, Lawrence Berkeley National Laboratory, Berkeley, Calif., 1997. Version 4.0: January 1999 +++++++++++++++++++++++++ Released to Energy Science and Technology Software Center Version 5.0: July 2002 ++++++++++++++++++++++ Qualified (again!) for use wihin Yucca Mountain Project @@@ Syntax: >> ABSOLUTE Parent Command: > PARAMETER Subcommand: >>> MATERIAL Description: This command selects as a parameter the absolute permeability (TOUGH2 variable PER(ISOT,NMAT)) of the specified material. Subcommand >>>> LOGARITHM invokes estimation of a single log-value which is assigned to all selected materials; subcommand >>>> FACTOR invokes estimation of a common multiplication factor which is applied to all selected permeabilities, thus maintaining the permeability ratios between the materials; subcommand >>>> LOG(F) should be used to estimate a log-normally distributed factor with which all the permeabilities are multiplied. By default, the estimate refers to all three flow directions (ISOT=1, 2, 3). Subcommand >>>> INDEX can be used to select the permeability of a specific flow direction ISOT. Example: > PARAMETER >> ABSOLUTE permeability >>> MATERIAL: BOREH SKIN_ >>>> LOGARITHM <<<< >>> MATERIAL: SAND1 SAND2 >>>> FACTOR >>>> INDEX: 1 2 (horizontal permeability) <<<< >>> MATERIAL: SAND1 SAND2 >>>> FACTOR >>>> INDEX: 3 (vertical permeability) <<<< <<< << See Also: - @@@ Syntax: >>>> ABSOLUTE Parent Command: all third-level commands in block > OBSERVATION Subcommand: - Description: This command takes the absolute value of the calculated system response as the model output to be compared to the observed data. Example: > OBSERVATION >> CAPILLARY PRESSURE >>> ELEMENT: ELM99 >>>> take ABSOLUTE value and compare to ... >>>> ... positive DATA stored on FILE: pcap.dat >>>> the RELATIVE error is: 5 % <<<< <<< << See Also: - @@@ Syntax: >>> ADJUST Parent Command: >> CONVERGE Subcommand: - Description: The initial time step size is provided through TOUGH2 variable DELTEN or DLT(1), usually followed by automatic time stepping (see TOUGH2 variables MOP(16) and REDLT). The initial time step may be too big (i.e., is automatically reduced by TOUGH2) or too small (i.e., convergence is achieved within one Newton-Raphson iteration), depending on the parameter set supplied by iTOUGH2 during an inversion. This command allows iTOUGH2 to automatically adjust the initial time step size so that convergence is achieved within more than 1 but less than MOP(16) Newton-Raphson iterations. Automatic time step adjustment may improve the speed of an inversion, but may also make the inversion unstable if time discretization errors are significant. Example: > COMPUTATION >> CONVERGE >>> automatically ADJUST initial timestep DELTEN <<< << See Also: >>> CONSECUTIVE, >>> REDUCTION @@@ Syntax: >>> ALPHA: alpha (%) Parent Command: >> ERROR Subcommand: - Description: alpha is a probability used for a variety of statistical tests within iTOUGH2. The choice of alpha does not affect the estimated parameter set, but is used in the residual analysis, the Fisher model test, the analysis of the resulting distribution when performing Monte Carlo simulations, and the width of the error band when performing FOSM uncertainty propagation analysis. alpha is expected to assume values between 0.001 and 0.200 (default: 0.01). Instead of the risk alpha, one can also provide the confidence level (1-alpha), in which case alpha assumes values between 0.8 an 0.999. Use keyword % if alpha is given in percent. Example: > COMPUTATION >> STOP >>> number of TOUGH2 SIMULATIONS: 200 <<< >> ERROR propagation analysis >>> MONTE CARLO simulations >>> print quantile for risk ALPHA =: 5.0 % <<< << See Also: - @@@ Syntax: >>> ANDREW: c Parent Command: >> OPTION Subcommand: - Description: This command selects a robust estimator named Andrews. Given this estimator, the objective function to be minimized is the sum of the cosine functions g(y), where y is the weighted residual: S=Sum(g(y )) i=1,...,m i where: | 1-cos(y/c) |y| < c*Pi g(y ) = | i | 1 |y| > c*Pi with: y = (r /sigma ) i i i This objective function does not correspond to a standard probability density function. It has the general characteristic that the weight given individual residuals first increases with deviation, then decreases to reduce the impact of outliers. The parameter c indicates the deviation at which residuals are considered to be outliers. If the measurement errors happen to be close to a normal distribution with standard deviation sigma, then the optimal value for the constant c is c=2.1. Note that this objective function can be minimized using the standard Levenberg-Marquardt algorithm which is designed for a quadratic objective function. Since (1-cosine) can be reasonably well approximated by a quadratic function for small g, the Levenberg-Marquardt algorithm is usually quite efficient. Example: > COMPUTATION >> OPTION >>> use the robust estimator ANDREW with a constant c : 1.5 <<< << See Also: >>> CAUCHY, >>> L1-ESTIMATOR, >>> LEAST-SQUARES, >>> QUADRATIC-LINEAR @@@ Syntax: >>> ANNEAL Parent Command: >> OPTION Subcommand: >>>> ITERATION >>>> LIST >>>> SCHEDULE >>>> STEP >>>> TEMPERATURE Description: This command invokes Simulated Annealing to minimize the objective function S. The following steps are performed by iTOUGH2, controlled by a number of fourth-level commands: (1) Define the range of possible parameter values using command >>>> RANGE in block > PARAMETER. (2) Define an initial value of the control parameter tau using command >>>> TEMPERATURE. (3) iTOUGH2 generates random perturbations delta(p) of the parameter vector p. The probability density function of the perturbation is either Gaussian or uniform; the initial standard deviations of these distributions are given by command >>>> DEVIATION (p). (4) The objective function S(p ) for the new parameter set k+1 p = p + delta(p) is evaluated. k+1 k (5) If the objective function is decreased (i.e., delta(S)=S(P ) - S(p ) < 0), the change is retained. k+1 k If the objective function is increased (i.e., delta(S) > 0), the perturbation is accepted with probability P=exp(-delta(S)/tau). (6) After a sufficient number of perturbations have been accepted (see command >>>>STEP (a)), tau is lowered according to the annealing schedule (see command >>>> SCHEDULE). (7) Steps (3) through (6) are repeated until the maximum number of temperature reductions (see command >>>> ITERATION (a)) is reached. This scheme of always taking a downhill step and sometimes taking an uphill step with probability P depending on tau is known as the Metropolis algorithm. Simulated Annealing may be especially useful for the minimization of a discontinuous cost function in order to optimize operational parameters. Example: > PARAMETER >> pumping RATE >>> SINK: EXT_1 >>>> RANGE: -1E-1 -1E-4 >>>> LOGARITHM <<<< <<< << > COMPUTATION >> TIME: 1 [YEARS] 2.0 >> USER specified cost function: Extraction cost >>> SINK: EXT_1 >>>> NO DATA >>>> WEIGHT (=specific costs): 1.0 <<<< <<< << > COMPUTATION >> OPTION >>> a cost function is minimized using L1-ESTIMATOR >>> perform minimization using Simulated ANNEALing >>>> initial TEMPERATURE : -0.05 (=5 % of initial cost) >>>> update after maximum : 100 STEPS >>>> annealing SCHEDULE: 0.95 >>>> Simulated Annealing ITERATIONS: 50 <<<< <<< << See Also: >>> GAUSS-NEWTON, >>> GRID SEARCH, >>> LEVENBERG-MARQUARDT, >>>> ITERATION (a), >>>> SCHEDULE, >>>> STEP (a), >>>> TEMPERATURE @@@ Syntax: >>>> ANNOTATION: anno Parent Command: all third-level commands in block > PARAMETER and > OBSERVATION Subcommand: - Description: A fifteen-character string anno can be provided to label parameters and observations in the iTOUGH2 output file. The annotation does not have any function except for making the iTOUGH2 output more readable (exceptions are the user-specified functions; see commands >> USER (p,o). If no annotation is provided, iTOUGH2 internally generates a string which allows unique identification of the parameter or observation, respectively. The internally generated annotation can be used to check the correctness of the iTOUGH2 input. Example: > PARAMETER >> van Genuchten's CAPILLARY pressure function >>> ROCK TYPE : MATRI >>>> ANNOTATION : AIR ENTRY PRESSURE >>>> PARAMETER no. : 2 <<<< >>> ROCK TYPE : FRAC1 >>>> PARAMETER no. : 2 <<<< <<< << > OBSERVATION >> CONCENTRATION of COMPONENT No.: 3 in PHASE No.: 2 >>> ELEMENT: ELM10 >>>> NO DATA and no annotation <<<< <<< << In the iTOUGH2 output file, the first parameter is referred to as "AIR ENTRY PRESS". The annotation internally generated for the second parameter reads "CAP.PR.2 FRAC1", where "2" indicates that the second parameter of the capillary pressure ("CAP.PR.") function referring to rock type "FRAC1" is estimated. The automatically generated annotation for the observation reads "CONC.(3,2)ELM10". See Also: - @@@ Syntax: >>>> AUTO Parent Command: all third-level commands in block > OBSERVATION Subcommand: - Description: This command provides automatic weighting of observations. The standard deviation calculated by iTOUGH2 is 10 % of the mean of the observed values for a given data set. It is suggested, however, that the assumed measurement error or expected standard deviation of the final residuals be explicitly provided using command >>>> DEVIATION (o). Example: > OBSERVATION >> PRESSURE >>> ELEMENT: BH__0 >>>> AUTOmatic weighting >>>> DATA are on FILE: pres.dat <<<< <<< << See Also: >>>> DEVIATION (o) @@@ Syntax: >>>> AVERAGE (VOLUME) or >>>> MEAN (VOLUME) Parent Command: all third-level commands in block > OBSERVATION Subcommand: - Description: If multiple elements or connections are provided to indicate the location of a measurement point, iTOUGH2 takes the average of all calculated values as the model output to be compared to the data. The user must ensure that the averaging of the quantity is meaningful. If keyword VOLUME is present on the command line, the calculated values are weighted by the grid block volume. Example: > OBSERVATION >> GAS CONTENT >>> ELEMENTS: A1__1 A1__2 A1__3 A1__4 B1__1 B1__2 B1__3 B1__4 & C1__1 C1__2 C1__3 C1__4 D1__1 +3 >>>> ANNOTATION: Ave. Gas Content >>>> Take VOLUME AVERAGE >>>> NO DATA <<<< <<< << See Also: >>>> SUM @@@ Syntax: >>> BENCHMARK Parent Command: >> OUTPUT Subcommand: - Description: A short benchmark calculation is performed, and the CPU time used is compared to that on a reference machine, and a printout is generated with information about approximate relative computer performance. Example: > COMPUTATION >> OUTPUT >>> perform BENCHMARK calculation <<< On output: Computer is faster than a SUN ULTRA1 by a factor of: 2.1 See Also: - @@@ @@@ Syntax: >> BOTTOMHOLE PRESSURE Parent Command: > PARAMETER Subcommand: >>> SOURCE Description: This command selects as a parameter the bottomhole pressure for wells on deliverability (TOUGH2 variable EX). This parameter refers to a sink/source code name. The generation type must be DELV. Example: > PARAMETER >> BOTTOMHOLE PRESSURE in well of deliverability >>> SINK: WEL_1 + 5 >>>> ANNOTATION: wellb. pres. Pwb >>>> estimate VALUE >>>> RANGE : 0.5E5 5.0E5 [Pa] <<<< <<< << See Also: - @@@ Syntax: >>>> BOUND: lower upper Parent Command: all third-level commands in block > PARAMETER Subcommand: - Description: (see command >>>> RANGE) Example: (see command >>>> RANGE) See Also: >>>> RANGE @@@ Syntax: >> CAPACITY Parent Command: > PARAMETER Subcommand: >>> MATERIAL Description: This command selects as a parameter the rock grain specific heat (TOUGH2 variable SPHT(NMAT)). Example: > PARAMETER >> heat CAPACITY >>> ROCK type : GRANI >>>> VALUE >>>> RANGE : 600.0 3000.0 [J/kg/C] <<<< <<< << See Also: - @@@ Syntax: >> CAPILLARY Parent Command: > PARAMETER Subcommand: >>> DEFAULT >>> MATERIAL Description: This command selects a parameter of the capillary pressure function (TOUGH2 variable CP(IPAR,NMAT)) of a certain rock type, or a parameter of the default capillary pressure function (TOUGH2 variable CPD(IPAR)). Use command >>>> INDEX to select the parameter index IPAR. The physical meaning of the parameter depends on the type of capillary pressure function selected in the TOUGH2 input file, variable ICP and ICPD respectively. The admissible range should be specified explicitly to comply with parameter restrictions (see Pruess [1987], Appendix B). Example: > PARAMETER >> parameter of CAPILLARY pressure function >>> DEFAULT >>>> ANNOTATION : Slr >>>> INDEX CPD(: 2) >>>> VALUE >>>> RANGE : 0.01 0.99 <<<< >>> MATERIAL: SAND1 SAND2 >>>> ANNOTATION : vG alpha [Pa^-1] >>>> INDEX no. : 3 >>>> LOGARITHM >>>> RANGE : -5.0 -1.0 <<<< <<< << See Also: >> RELATIVE @@@ Syntax: >>> CAUCHY Parent Command: >> OPTION Subcommand: - Description: This command selects an objective function that corresponds to a Cauchy or Lorentzian distribution, i.e., the probability density function of the residuals r reads: phi(r )=(1+0.5*(r /sigma )^2)^(-1) i i i This distribution exhibits more extensive tails compared to the normal distribution, and leads therefore to a more robust estimation if outliers are present. The objective function to be minimized is given by the following equation: S = Sum(log(1+0.5*g ^2) i=1,...,m i with g = (r /sigma ) i i i This objective function can bE minimized using the standard Levenberg-Marquardt algorithm which is designed for a quadratic objective function. The objective function can be reasonably well approximated by a quadratic function, so that the Levenberg-Marquardt algorithm is usually quite efficient. Example: > COMPUTATION >> OPTION >>> assume measurement errors follow a CAUCHY distribution <<< << See Also: >>> ANDREW, >>> L1-ESTIMATOR, >>> LEAST-SQUARES, >>> QUADRATIC-LINEAR @@@ Syntax: >>> CENTERED Parent Command: >> JACOBIAN Subcommand: - Description: This command calculates elements of the Jacobian matrix by means of centered finite difference quotients: dz z (p +dp ) - z (p -dp ) i i j j i j j J = --- <> ----------------------- ij dp 2dp j j The evaluation of the Jacobian thus requires (2n+1) TOUGH2 simulations, where n is the number of parameters. The size of the perturbation dp can be controlled using command >>> PERTURB. Centered finite differences are more accurate than forward finite differences, but computationally twice as expensive (also see command >>> FORWARD). Example: > COMPUTATION >> JACOBIAN >>> use CENTERED finite difference quotient >>> PERTURBation factor is : 0.005 times the parameter value <<< << See Also: >>> FORWARD (j), >>> PERTURB @@@ Syntax: >>> CHARACTERISTIC Parent Command: >> OUTPUT Subcommand: - Description: This command generates a file in the format specified by command >>> FORMAT containing the characteristic curves (relative permeability and capillary pressure functions) of all rock types used in the TOUGH2 model. The file name contains the string "_ch". Example: > COMPUTATION >> OUTPUT >>> generate file with CHARACTERISTIC curves >>> in : TECPLOT FORMAT <<< << See Also: >>> FORMAT @@@ Syntax: >>>> COLUMN: itime idata (istd_dev) Parent Command: all third-level commands in block > OBSERVATION Subcommand: - Description: This command identifies the column holding the time and observed value in the data definition block (see command >>>> DATA). By default, transient observations are expected to be provided in two columns, where the first column contains the observation time, and the second column contains the corresponding measurement. Deviations from this format must be indicated by providing the numbers of the columns, itime and idata, holding time and data information, respectively. If a third integer istd_dev is provided, an additional column is expected holding the standard deviation of the corresponding measurement. This allows one to specify individual standard deviations for each data point (the subcommand >>>> DEVIATION assigns a single standard deviation to all data points of a data set). The columns following command >>>> DATA are read in free format. If a column contains non-numeric characters, command >>>> FORMAT must be used. Example: > OBSERVATION >> CAPILLARY PRESSURE >>> ELEMENT : A1__1 >>>> COLUMN : 2 3 >>>> skip : 3 HEADER lines >>>> conversion FACTOR : -100.0 [hPa] - [-Pa] >>>> DATA (time is in MINUTES) ------------------------------------------------------------ # Time [min] Cap. Pres, [hPa] FlowmeterX Flow Rate [mg/s] ------------------------------------------------------------- 1 5.0 0.1698331055E+02 FlowmeterA 0.9869399946E+01 2 10.0 0.2075763428E+02 FlowmeterA 0.1039689596E+02 3 15.0 0.2357142822E+02 FlowmeterA 0.1162893932E+02 4 20.0 0.2529052490E+02 FlowmeterA 0.1353439620E+02 5 25.0 0.2598133789E+02 FlowmeterA 0.1469761628E+02 . .... ................ .......... ................ >>>> standard DEVIATION: 0.5 [hPa] <<<< <<< See Also: >>>> DATA, >>>> DEVIATION (o), >>>> FORMAT, >>>> HEADER @@@ Syntax: >>>> COMPONENT comp_name/: icomp Parent Command: >>> ELEMENT >>> SOURCE (o) Subcommand: - Description: This command identifies a component either by its name (comp_name) or the component number (icomp). A list of allowable component names for the given EOS module can be obtained from the header of the iTOUGH2 output file. Example: > OBSERVATION >> CONCENTRATION >>> ELEMENT: ZZZ99 >>>> ANNOTATION: TCE concentration >>>> COMPONENT No.: 3 (=VOC) >>>> dissolved in LIQUID PHASE >>>> DATA on FILE: tce.dat >>>> standard DEVIATION: 1.0E-6 <<<< <<< << See Also: >>>> PHASE @@@ Syntax: >> COMPRESSIBILITY Parent Command: > PARAMETER Subcommand: >>> MATERIAL Description: This command selects as a parameter the pore space compressibility c (TOUGH2 variable COM(NMAT)) of a certain rock type. It is suggested to estimate the logarithm of c. Under fully liquid-saturated conditions, pore space compressibility estimates c can be converted to a specific storage coefficient S [1/m] as follows: s S = phi*rho*g*(c + c) s w where phi is porosity, rho is density of water, g is gravitational acceleration, and c = 4.4E-10 [1/Pa] is water compressibility. w Similarly, estimation of c for grid blocks representing a well or borehole is useful for the determination of a dimensionless wellbore storage coefficient C : bh C = phi *rho*g*V *(S * c + S * c + c) bh bh bh l w g g where phi and V are the porosity and volume of the grid block representing bh bh the well, S and S are the liquid and gas saturation, and c is gas l g g compressibility which is approximately 1/p. Example: > PARAMETER >> pore space COMPRESSIBILITY >>> MATERIAL: BOREH >>>> ANNOTATION: Wellbore storage >>>> LOGARITHM >>>> RANGE : -10.00 -7.0 <<<< >>> MATERIAL: SKIN_ ROCK_ BOUND >>>> ANNOTATION: Storativity >>>> LOGARITHM <<< << See Also: - @@@ Syntax: > COMPUTATION Parent Command: - Subcommand: >> CONVERGE >> ERROR >> JACOBIAN >> OPTION >> OUTPUT Description: This is the first-level command for specifying a number of computational parameters, convergence criteria, program options, and output formats. The general format is as follows: > COMPUTATION >> specify various program OPTIONS >> specify CONVERGEnce criteria >> specify parameters for calculating JACOBIAN matrix >> specify parameters for ERROR analysis >> specify OUTPUT formats << Example: > COMPUTATION >> CONVERGENCE criteria >>> perform : 5 ITERATIONS <<< >> JACOBIAN >>> use CENTERED finite difference quotient with >>> a relative parameter PERTURBation of : 0.5 % <<< >> program OPTIONS >>> use LEAST-SQUARES objective function (default) >>> allow the simulation to reach STEADY state <<< >> OUTPUT >>> generate PLOTFILE for: TECPLOT visualization software >>> print all times in HOURS << See Also: - @@@ Syntax: >> CONCENTRATION (comp_name/COMPONENT: icomp) (phase_name/PHASE: iphase) Parent Command: > OBSERVATION Subcommand: >>> ELEMENT Description: This command selects as an observation type the concentration [kg/m3] of a component in a given phase. Concentration is defined as the product of mass fraction of component icomp in phase iphase times density of phase iphase. This observation type refers to an element. Component number icomp or component name comp_name, and phase number iphase or phase name phase_name depend on the EOS module being used. They are listed in the header of the iTOUGH2 output file, and can be specified either on the command line or using the two subcommands >>>> COMPONENT and >>>> PHASE, respectively. Example: > OBSERVATION >> CONCENTRATION of BRINE in LIQUID >>> ELEMENT: A1__1 or > OBSERVATION >> CONCENTRATION of COMPONENT No.: 2 in PHASE No.: 2 >>> ELEMENT: A1__1 or > OBSERVATION >> CONCENTRATION >>> ELEMENT: A1__1 >>>> COMPONENT: 2 >>>> LIQUID PHASE See Also: >> MASS FRACTION @@@ Syntax: >> CONDUCTIVITY (WET/DRY) Parent Command: > PARAMETER Subcommand: >>> MATERIAL Description: This command selects as a parameter the formation heat conductivity under fully liquid- saturated (keyword WET, default, TOUGH2 variable CWET(NMAT)) or desaturated conditions (keyword DRY, TOUGH2 variable CDRY(NMAT)). Example: > PARAMETER >> heat CONDUCTIVITY under DRY conditions >>> ROCK type : GRANI >>>> VALUE >>>> RANGE : 0.5 5.0 [W/m/C] <<<< <<< << See Also: - @@@ Syntax: >>> CONNECTION: elem1 elem2 (elem_i elem_j ...) (++/+-/-+ iplus) or >>> INTERFACE: elem1 elem2 (elem_i elem_j ...) (++/+-/-+ iplus) Parent Command: >> FLOW Subcommand: all fourth-level commands in block > OBSERVATION Description: This command reads pairs of element names defining a connection. Element names are designated by a three-character/two-integer (FORTRAN format: AAAII) code name. Blanks in the element names as printed in the TOUGH2 output file must be replaced by underscores (e.g., an element name specified in the TOUGH2 input file as 'B 007' is printed as 'B 0 7' to the TOUGH2 output file. Therefore, it must be addressed in the iTOUGH2 input file as 'B_0_7'). Multiple connections can be specified, and iTOUGH2 calculates the sum or mean of all flow rates (see subcommands >>>> SUM and >>>> AVERAGE, respectively). A sequence of iplus connections can be generated where the number of the first and/or the second element is increased by 1. If only the first (second) element in a sequence of connections should be increased, use +- (-+). If both elements are to be increased, use + (or ++). The following two command lines are thus identical: >>> CONNECTION: AA__1 BB_15 -+ 2 >>> CONNECTION: AA__1 BB_15 AA__1 BB_16 AA__1 BB_17 Example: > OBSERVATION >> LIQUID FLOW RATE >>> list of CONNECTIONS: ELM_1 ELM_2 + 48 >>>> ANNOTATION : Boundary flux >>>> take the SUM of the flow rates across 49 connections >>>> DATA on FILE : flow.dat >>>> RELATIVE error: 10 % <<<< <<< << See Also: >>>> AVERAGE, >>>> SUM @@@ Syntax: >>> CONSECUTIVE: max_iter1 Parent Command: >> CONVERGE Subcommand: - Description: By default, TOUGH2 simulations are stopped if 10 consecutive time steps converge with a single Newton-Raphson iteration because no update of primary variables occurs. This command allows changing the maximum number of allowable time steps with ITER=1 to max_iter1. Consecutive time steps with no update of primary variable occur if: (1) steady-state is reached; (2) calibration or printout times are too narrowly spaced; (3) the maximum time step size (TOUGH2 variable DELTMX) is too small; (4) the initial time step (TOUGH2 variable DELTEN or DLT(1)) is too small; (5) a small time step is taken to land on a calibration or printout time. Only (1) is an acceptable TOUGH2 convergence (see command >>> STEADY-STATE). All the other reasons may lead to premature termination of a TOUGH2 simulation. Convergence problems are more often encountered in iTOUGH2 than in a standard TOUGH2 simulation because many parameter combinations are submitted. This command makes TOUGH2 more tolerant of this kind of convergence failure. It is important, however, that max_iter1 is only increased to overcome temporary convergence problems during the optimization, i.e., the final parameter set should yield a TOUGH2 simulation without convergence problems. Calibration points should not be spaced too narrowly in time (see command >> TIME). Command >>> ADJUST can be used to overcome problem (4). Note that a special time stepping procedure is incorporated in iTOUGH2 to avoid problem (5). Example: > COMPUTATION >> CONVERGE >>> accept : 20 CONSECUTIVE time steps that converge on ITER=1 <<< << See Also: >> TIME, >>> ADJUST, >>> REDUCTION @@@ Syntax: >> CONTENT (phase_name/PHASE: iphase) Parent Command: > OBSERVATION Subcommand: >>> ELEMENT Description: This command selects as a parameter the content of phase iphase as an observation type. Phase content is defined as the product of saturation and porosity. The phase name phase_name or phase number iphase, which depend on the EOS module being used, are listed in the iTOUGH2 header, and can be specified either on the command line or using subcommand >>>> PHASE. Estimating phase content and phase saturation is identical only if porosity remains constant. Porosity can be variable (i) due to compression of the pore space (i.e., if TOUGH2 variable COM(NMAT) is not zero), and (ii) if porosity is one of the parameters to be estimated and is updated during the inversion. Example: > OBSERVATION >> TIME: 1 point at steady-state 1.0E20 >> LIQUID CONTENT or CONTENT in PHASE No.: 2 >>> ELEMENT: A1__1 >>>> ANNOTATION: Water content >>>> FACTOR : 0.01 (data given in %) >>>> one steady-state DATA point 0.0 23.0 1.0E50 23.0 >>>> DEVIATION: 5.0 % <<<< >>> ELEMENT: A1__1 >>>> ANNOTATION: Gas content >>>> GAS PHASE (overwrites iphase specified on command line) >>>> NO DATA, just for plotting >>>> WEIGHT : 1.0E-20 <<<< <<< << See Also: - @@@ Syntax: >> CONVERGE or >> STOP or >> TOLERANCE Parent Command: > COMPUTATION Subcommand: >>> ADJUST >>> CONSECUTIVE >>> DELTFACT >>> FORWARD >>> INCOMPLETE >>> INPUT >>> ITERATION >>> LEVENBERG >>> LIST >>> MARQUARDT >>> REDUCTION >>> SIMULATION >>> STEP >>> UPHILL >>> WARNING Description: This is the parent command of a number of subcommands that deal with tolerance measures and convergence criteria for the inversion and, to a certain extent, the TOUGH2 simulation. Example: > COMPUTATION >> CONVERGEnce criteria >>> ignore WARNING messages, then >>> perform : 5 ITERATIONS >>> stop if more than : 5 unsuccessful UPHILL steps are proposed >>> allow for : 20 CONSECUTIVE time steps converging on ITER=1 >>> and : 20 time step REDUCTIONS >>> accept : 6 INCOMPLETE TOUGH2 runs >>> the initial LEVENBERG parameter shall be : 0.01 >>> use the default value (=: 10.0) for the MARQUARDT parameter <<< See Also: >> OPTION @@@ Syntax: >>>> CORRELATION: (-)rcorr Parent Command: >>> SELECT Subcommand: - Description: This command defines one of the criteria used for automatic parameter selection. It examines the ratio between the apparent conditional standard deviation sigma* and the joint standard deviation sigma as a measure of overall parameter correlation (since the calculation is performed far from the minimum, the standard deviations cannot be interpreted as actual estimation uncertainties): X = sigma*/sigma (O < X < 1) Those parameters with a ratio larger than |rcorr|, i.e., the most independent parameters, are selected. Strongly correlated parameters are (temporarily) excluded from the optimization process. If a negative value is given for rcorr, the selection criterion is relaxed with each iteration k, and reaches zero for the last iteration max_iter, i.e., all parameters are selected for the final step. rcorr = |rcorr|*(1-k/max_iter) k The choice for rcorr depends on the number of parameters n specified in block > PARAMETER. As more parameters are estimated simultaneously, the higher parameter interdependencies become. This fact should be acknowledged by specifying a smaller value for |rcorr| if n increases. Example: > COMPUTATION >> OPTION >>> SELECT parameter automatically every >>>> : 3 ITERATIONS >>>> based on the CORRELATION criterion with rcorr : -0.10 <<<< <<< << See Also: >>>> ITERATION (s), >>>> SENSITIVITY @@@ Syntax: >> COVARIANCE (FILE: file_name) Parent Command: > OBSERVATION Subcommand: - Description: This command reads the diagonal elements of the a priori covariance matrix C . zz Usually the variances of the observations are specified separately for each data set using command >>>> DEVIATION (o), or they are provided as a separate column along with the data (see commands >>>> COLUMN and >>>> DATA). As an alternative, one can assign or overwrite variances using the second-level command >> COVARIANCE, followed by two columns holding index i and variance c . ii Since this command addresses elements of the assembled covariance matrix, the user must provide the index that corresponds to the position of the observation in vector z. This information is best retrieved from the iTOUGH2 output file after running one forward simulation. Note that the index changes whenever the number of observations, parameters, or calibration times is changed. The variances can also be read from a covariance file which must contain three columns, holding index i, index j, and the (co-)variance c ij (this is the same format as the one on the covariance file generated by command >>> COVARIANCE). Despite the fact that two indexes must be provided, only diagonal elements, i.e., c , will be accepted as input. ii Example: > OBSERVATION >> : 30 EQUALLY space calibration TIMES in MINUTES between 3.0 90.0 >> plus : 1 steady-state TIME near 86400.0 seconds >> PRESSURE >>> ELEMENT: A1__1 >>>> transient and steady-state DATA are on FILE: pres.dat >>>> standard DEVIATION: 2000.0 Pa <<<< <<< >> change one element of COVARIANCE matrix to increase its weight 32 1.0E4 (provided that 2 parameters are estimated, the steady-state data point is observation number 32) << See Also: >>> COVARIANCE, >>>> COLUMN, >>>> DEVIATION, >>>> DATA @@@ Syntax: >>> COVARIANCE Parent Command: >> OUTPUT Subcommand: - Description: This command generates a file with extension ".cov " with the covariance matrix of the calculated system response: T C = J C J zz pp Note that C is a square matrix of dimension m*m. zz Example: > COMPUTATION >> OUTPUT >>> print COVARIANCE matrix of calculated system response <<< << See Also: - @@@ Syntax: >> CUMULATIVE (comp_name/COMPONENT: icomp) (phase_name/PHASE: iphase) Parent Command: > OBSERVATION Subcommand: >>> SOURCE Description: This command selects as an observation type the cumulative injection or production of component icomp or phase iphase. This observation type refers to a sink or source code name. It can be used when time-dependent generation rates are to be estimated where the total amount of injected or produced fluid is approximately known, or if the total generation rate is prescribed in block GENER, but the phase composition of the produced fluid is variable and sensitive to the parameters of interest. Finally, the cumulative amount of injected or produced fluid can be used as an observable variable for wells on deliverability. Note that the cumulative mass of a phase produced in an element strongly depends on the composition of the produced fluid mixture according to the options provided by TOUGH2 flag MOP(9). Component number icomp or component name comp_name, and phase number iphase or phase name phase_name depend on the EOS module being used. They are listed in the iTOUGH2 header and can be specified either on the command line or using the two subcommands >>>> COMPONENT and >>>> PHASE, respectively. If neither a phase nor component number is specified, the total, cumulative mass of all phases or components will be calculated. Example: > OBSERVATION >> CUMULATIVE METHANE produced >>> SOURCE: RW__1 >>>> ANNOTATION : Total methane [l] >>>> FACTOR : -7.67358E-04 [l] - [kg] >>>> DATA from FILE: tot_ch4.dat [HOUR] >>>> DEVIATION : 5.0 [l] <<<< <<< << < See Also: - @@@ Syntax: >>>> DATA (time_unit) (FILE: file_name) Parent Command: all third-level commands in block > OBSERVATION Subcommand: - Description: This command reads a list of observation times and the corresponding data. Each list will be referred to as a data set in the iTOUGH2 output file. An annotation is generated for each data set, or a string can be supplied by the user for its identification (see command >>>> ANNOTATION). Data can be supplied either directly following the command line or on a separate file (use keyword FILE followed by the name of the data file after a colon). Time and data must be arranged in columns. They are read in free format. Data are accepted until a FORTRAN input error occurs. The total number of data points read by iTOUGH2 is printed to the iTOUGH2 output file and should be checked for consistency. By default, the first column is expected to hold the observation times, and the second column the data values. Deviations from this format are possible (see commands >>>> COLUMN, >>>> FORMAT, >>>> SET (o), and >>>> HEADER for details). Data can also be represented by a polynomal or a user-specified function (see commands >>>> POLYNOM and >>>> USER, respectively). Observation times do not need to coincide with the calibration times defined by command >> TIME (o). Linear interpolation is performed for calibration times that fall between observation times. This requires, however, that the first observation time is earlier than the first calibration time, and that the last observation time is later than the last calibration time. If this condition is not met, command >>>> WINDOW should be used. Only one time window can be specified for each data set, i.e., multiple data sets must be provided if multiple time windows are needed. If time is not given in seconds, the appropriate time unit (MINUTE, HOUR, DAY, WEEK, MONTH, YEAR) must be specified on the command line. If the units of the data points are different from the standard units used in TOUGH2, a conversion factor must be provided through command >>>> FACTOR. If no observed data are available (e.g., when performing design calculations prior to testing, or when using iTOUGH2 for generating time series plots), a dummy data set must be supplied. Alternatively, command >>>> NO DATA can be used. Example: > OBSERVATION >> GAS PRESSURE >>> in ELEMENT: A1__1 >>>> DATA follow in default format, time (sec) vs. pressure (Pa) 1.0 100000.0 10.0 101343.8 20.0 105991.3 30.0 108965.9 60.0 115003.8 .... ........ 3600.0 218762.0 >>>> standard DEVIATION: 5000.0 Pa <<<< <<< >> LIQUID FLOW rate >>> CONNECTION B1__1 B1__2 >>>> HEADER contains : 3 lines to be skipped >>>> time and value are in COLUMNS: 3 6 >>>> conversion FACTOR is : -1.6667E-5 [ml/min] to [-kg/sec] >>>> use SET No. : 3 >>>> DATA are provided on FILE : flow.dat with time in MINUTES >>>> a RELATIVE measurement error of : 5.0 % is assumed <<<< <<< >> BRINE CONCENTRATION in LIQUID PHASE >>> ELEMENT: C1__1 >>>> NO DATA available, just for plotting >>>> assign small WEIGHT of : 1.0E-20 <<<< <<< << See Also: >>>> ANNOTATION, >>>> COLUMN, >>>> FACTOR, >>>> FORMAT, >>>> HEADER, >>>> PICK, >>>> POLYNOM, >>>> SET (o), >>>> USER, >>>> WINDOW @@@ Syntax: >>> DEFAULT or >>> MATERIAL: DEFAU Parent Command: >> CAPILLARY >> INITIAL >> RELATIVE Subcommand: all fourth-level commands in block > PARAMETER Description: Parameters of the default relative permeability and capillary pressure functions (TOUGH2 block RPCAP) or default initial conditions (TOUGH2 block PARAM.4) are addressed by command >>>> DEFAULT. Alternatively, a material name DEFAU can be provided following command >>>> MATERIAL. Example: > PARAMETER >> INITIAL PRESSURE >>> DEFAULT initial pressure (block PARAM.4) >>>> ANNOTATION: Init. Formation Pres. >>>> GUESS : 1.5E5 <<<< <<< >> RELATIVE PERMEABILITY FUNCTION >>> MATERIAL: BOREH >>>> ANNOTATION : Sgr borehole >>>> PARAMETER #: 2 <<<< >>> MATERIAL: BOUND DEFAU >>>> ANNOTATION : Sgr elsewhere >>>> PARAMETER #: 2 <<<< <<< << See Also: >>> MATERIAL, >>> MODEL @@@ Syntax: >>> DELTFACT: deltfact Parent Command: >> CONVERGE Subcommand: - Description: In TOUGH2, time step size can be controlled in various ways (see Pruess [1987] for a description of input variables DELTEN, DLT, DELTMX, NOITE, REDLT, and MOP(16)). The time step is also automatically adjusted in order for the simulation time to land on any of the specified calibration or printout times. This may lead to very small time steps or even convergence failures (see command >>> CONSECUTIVE). In iTOUGH2, the proposed time step is increased up to a factor of DELTFACT (default: 1.2) if this increase allows the simulation to reach the next calibration or printout time. This may lead to time stepping different from standard TOUGH2. Example: > COMPUTATION >> CONVERGE >>> DELTFACT: 1.0 (as in standard TOUGH2) >>> allow : 20 CONSECUTIVE time steps converging in 1 iteration <<< << See Also: >>> CONSECUTIVE @@@ Syntax: >>> DESIGN Parent Command: >> OPTION Subcommand: - Description: (synonym for command >>> SENSITIVITY) Example: (see command >>> SENSITIVITY) See Also: >>> SENSITIVITY @@@ Syntax: >>>> DEVIATION (There are two fourth-level commands >>>> DEVIATION. Check parent command.) Parent Command 1: all third-level commands in block > PARAMETER Syntax: >>>> DEVIATION: sigma Subcommand: - Description: This command specifies the standard deviation sigma of the initial parameter guess. Prior information about model parameter will be weighted by 1/sigma, i.e., the difference between the prior information value p* and the estimate p contributes to the objective function. Commands for specifying the standard deviation are: >>>> DEVIATION: sigma >>>> VARIANCE: sigma^2 >>>> WEIGHT: 1/sigma By default, prior information is not weighted, i.e. sigma=infinity. The standard deviation reflects the uncertainty associated with the initial guess. If the initial guess is to be weighted, prior information should originate from an independent source. For example, if porosity will be estimated based on transient pressure data, the prior information value should be taken from a "direct" porosity measurement, e.g. using mercury-porosimetry or oven-drying methods. In these cases, the measured parameter values P* are considered to be additional data points which serve as a physical plausibility criterion for the estimate p. The p* values, along with the observations of the system state z*, are then weighted according to their uncertainties (see >>>> DEVIATION (o)). Note that the relative weighting between prior information and the observations z* depends on the number of calibration points selected. If many transient data points are available, a smaller standard deviation sigma may be specified to increase the relative weight of prior information. In many cases, appropriately weighting the initial guess makes an ill-posed inverse problem unique. Furthermore, the solution becomes more stable if a parameter is not very sensitive. However, using 1/sigma as a regularization parameter to improve the ability to obtain a unique solution with a poorly conceptualized inverse problem inverse problem is not recommended. Erratic behavior of a parameter during the inversion should be taken as an indication that the data do not contain sufficient information for the determination of the parameter. Differences between parameter values that are independently determined from laboratory experiments and inverse modeling suggest the presence of a systematic error or scaling problem. These inconsistencies should be resolved rather than averaged out. The standard deviation sigma is also used to scale the columns of the Jacobian matrix. While the solution of the inverse problem is not affected by the choice of the scaling factor, all the qualitative sensitivity measures are directly proportional to sigma. If prior information is not weighted, the scaling factor is taken to be 10 % of the respective parameter value. Command >>>> VARIATION should be used to change the default scaling factor without concurrently assigning a weight to prior information. When performing uncertainty propagation analyses, sigma designates the parameter uncertainty affecting the model prediction. It is used to generate a set of random parameter values for Monte Carlo simulations, and it represents the standard deviation of a normal distribution if performing linear uncertainty propagation analysis (for more details see commands >>> MONTE CARLO and >>> FOSM, respectively). Example: > PARAMETER >> POROSITY >>> MATERIAL: TUFFn >>>> PRIOR information : 0.38 (laboratory measurement) >>>> standard DEVIATION: 0.04 (measurement error) <<<< >>> MATERIAL: ALLUV >>>> PRIOR information : 0.30 (from experience) >>>> VARIANCE : 0.01 (uncertainty of guess) <<<< >>> MATERIAL: FAULT >>>> initial GUESS : 0.25 (no measurements available) >>>> WEIGHT : 0.00 (default) >>>> VARIATION : 0.10 (for scaling of Jacobian) <<<< <<< << See Also: >> GUESS, >>> FOSM, >>> MONTE CARLO, >>>> DEVIATION (o), >>>> PRIOR, >>>> VARIANCE, >>>> VARIATION, >>>> WEIGHT @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ Parent Command 2: all third-level commands in block > OBSERVATION Syntax: >>>> DEVIATION: sigma Subcommand: - Description: This command specifies the standard deviation sigma of the observations. The squares of the standard deviations constitute the diagonal elements of the a priori covariance matrix C . zz The specified value sigma is assigned to all data points of the corresponding data set. It must be given in the same units as the data (see command >>>> FACTOR). Individual values for each calibration point can be explicitly specified using command >>>> COLUMN or >> COVARIANCE, or are calculated as a fraction of the measured value if using command >>>> RELATIVE. The standard deviation should represent the expected variability of the final residuals. In the absence of modeling errors, the standard deviation is equivalent to the measurement error. A reasonable value can be derived by visual examination of the data, i.e., by estimating the standard deviation of the differences between the observed values and a line representing the expected match; note that this procedure is based on the assumption that time averages can be used to calculate the ensemble average, i.e., that the data set is a result of an ergodic process. The inverse of the a priori covariance matrix is used to weight the fitting error. It also scales observations of different types and units. In the framework of maximum likelihood theory, the covariance matrix constitutes the stochastic model along with the assumption of normality and independence. The parameter estimates are not affected by the absolute values of sigma, but only by the ratios sigma /sigma . It is suggested, however, to use i j reasonable values that are related to the measurement error. If the final residuals are - on average - significantly larger than the a priori specified standard deviations, the Fisher model test fails. The a posteriori standard deviations of the final residuals are printed in the output for each data set for comparison purposes. Alternative commands are: >>>> DEVIATION: sigma >>>> VARIANCE: sigma^2 >>>> WEIGHT: 1/sigma The following command lines are thus equivalent: >>>> standard DEVIATION: 0.1 >>>> VARIANCE: 0.01 >>>> WEIGHT: 10.0 Example: > OBSERVATION >> PRESSURE >>> ELEMENT : AA412 >>>> conversion FACTOR: 1E5 from [bar] to [Pa] >>>> DATA on FILE: pressure.dat >>>> standard DEVIATION: 0.05 [bar] <<<< <<< << See Also: >> COVARIANCE, >>>> AUTO, >>>> COLUMN, >>>> DEVIATION (p), >>>> RELATIVE, >>>> VARIANCE, >>>> WEIGHT @@@ Syntax: >>> DIRECT Parent Command: >> OPTION or >> CONVERGE Subcommand: - Description: (synonym for command >>> FORWARD (o)) Example: (see command >>> FORWARD (o)) See Also: >>> FORWARD (o) @@@ Syntax: >> DRAWDOWN (phase_name/PHASE: iphase) Parent Command: > OBSERVATION Subcommand: >>> ELEMENT Description: This command selects as an observation type the pressure drawdown during a pumping test. This observation type refers to one or more elements. The drawdown is calculated from a reference pressure, which is the pressure at the specified element at the time of the first active calibration point for that data set, i.e., a calibration time greater than zero must be provided, indicating the beginning of the pumping period; the corresponding observation is a drawdown of zero. Note that the sensitivity of this calibration point is zero by definition, i.e., the first data point is not used for calibration. If drawdown is measured in meters, command >>>> FACTOR must be used to convert the units to Pascals. The phase name phase_name or phase number iphase, which depend on the EOS module being used, are listed in the header of the iTOUGH2 output file. They can be specified either on the command line or using subcommand >>>> PHASE. If no phase is specified, iTOUGH2 takes the pressure drawdown of the first phase which is usually the reference pressure. Example: > OBSERVATION >> TIMES: 1 in [MINUTES] 10.0 = beginning of pumping >> TIMES: 20 LOGARITHMICALLY spaced in [MINUTES] 11.0 120.0 >> DRAWDOWN >>> ELEMENT: AA__1 >>>> ANNOTATION : Pressure drawdown [m] >>>> FACTOR : 9810. [m] - [Pa] >>>> LOGARITHM >>>> DATA [MINUTES] 10.0 0.0 beginning of pumping 11.0 -0.1 15.0 -0.3 25.0 -0.5 .... ..... >>>> VARIANCE : 0.01 [m^2] <<<< See Also: >> PRESSURE @@@ Syntax: >> DRIFT Parent Command: > PARAMETER Subcommand: >>> NONE >>> SET Description: This command selects as a parameter the slope of a time-dependent trend. The trend is added to the TOUGH2 output referring to a specific data set: z = z + drift*time TOUGH2 where (drift*time) is the trend added to the calculated TOUGH2 output z . TOUGH2 The result z is compared to the measurement z* of the corresponding data set. This option allows removal of a trend in the data (for example, a flowmeter may exhibit an unknown offset and time-dependent trend that needs to be estimated). A non-zero value must be provided as initial guess through the iTOUGH2 input file using command >>>> GUESS. The data set is identified by number using command >>> SET (p). Example: > PARAMETER estimate coefficients of regression dz=A+B*time to correct flowmeter data >> SHIFT >>> NONE >>>> ANNOTATION: coefficient A (constant) >>>> INDEX : 2 3 4 (identifies data sets) >>>> GUESS : 4.0E-6 [kg/sec] <<<< <<< >> DRIFT >>> NONE >>>> ANNOTATION: coefficient B (slope) >>>> INDEX : 2 3 4 >>>> GUESS : 1.0E-9 [kg/sec/sec] <<<< <<< << See Also: >> FACTOR, >> LAG, >> SHIFT, >>> SET (p) @@@ Syntax: >>> ELEMENT: eleme (eleme_i ...) (+ iplus) or >>> GRID BLOCK: eleme (eleme_i ...) (+ iplus) Parent Command: all second-level commands in block > OBSERVATION requiring element names. Subcommand: all fourth-level commands in block > OBSERVATION Description: This command reads one or more element names. Most observation types refer to a variable that is associated with a grid block (as opposed to a connection or sink/source name). Element names are designated by a three-character/two-integer (FORTRAN format: AAAII) code name. Blanks in the element names as printed in the TOUGH2 output file must be replaced by underscores (e.g. an element name specified in the TOUGH2 input file as 'B 007' is printed as 'B 0 7' in the TOUGH2 output file. Therefore, it must be addressed in the iTOUGH2 input file as 'B_0_7'). Multiple elements can be specified, and iTOUGH2 calculates the sum or mean of the corresponding output variable (see subcommands >>>> SUM and >>>> MEAN, respectively). A sequence of iplus elements can be generated by increasing the number of the last element. The following two command lines are identical: >>> ELEMENT: AA__1 BB_15 +3 >>> ELEMENT: AA__1 BB_15 BB_16 BB_17 BB_18 Example: > OBSERVATION >> GAS SATURATION >>> ELEMENTS: ELM_0 + 99 >>>> ANNOTATION : Mean saturation >>>> take the MEAN of the saturation in all 100 elements >>>> DATA on FILE : Sg.dat >>>> DEVIATION : 0.05 <<<< <<< << See Also: >>> CONNECTION, >>> SINK, >>>> MEAN, >>>> SUM @@@ Syntax: >> ENTHALPY (There are two second-level commands >> ENTHALPY. Check parent command.) Parent Command 1: > PARAMETER Syntax: >> ENTHALPY Subcommand: >>> SOURCE Description: This command selects as a parameter the fixed specific enthalpy of the injected fluid (TOUGH2 variable EX) or the time-dependent specific enthalpy of the produced or injected fluid (TOUGH2 variable F3(L), LTAB>1 and ITAB non-blank). This parameter refers to a sink/source code name. Estimating a time-dependent enthalpy requires providing index L through command >>>> INDEX. Note that enthalpy is also an observation type (see command >> ENTHALPY (o)). Example: > PARAMETER >> specific ENTHALPY >>> SOURCE: INJ_1 >>>> ANNOTATION: fixed enthalpy <<<< >>> SOURCE: INJ_2 INJ_5 >>>> ANNOTATION: variable enthalpy >>>> VALUE >>>> INDEX : 1 2 3 8 9 10 <<<< <<< << See Also >> TIME (p), >> ENTHALPY (o) @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ Parent Command 2: > OBSERVATION Syntax: >> ENTHALPY (phase_name/PHASE: iphase) Subcommand: >>> SINK Description: This command selects as an observation type the flowing enthalpy in a production well. This observation type refers to a sink code name. If multiple elements are provided, the flowing enthalpy is weighted by the individual production rates. If a phase is selected either by specifying a valid phase_name or a phase number iphase or through command >>>> PHASE, only the flowing enthalpy of that phase is calculated. Note that the enthalpy of the injected fluid can also be an unknown parameter to be estimated (see command >> ENTHALPY (p)). Example: > OBSERVATION >> flowing ENTHALPY >>> SINK: WEL_1 + 5 >>>> ANNOTATION : Flowing enthalpy >>>> FACTOR : 1000.0 [kJ/kg] - [J/kg] >>>> DATA from FILE: enthalpy.dat [HOUR] >>>> DEVIATION : 10.0 [kJ/kg] <<<< <<< << < See Also: >> ENTHALPY (p) @@@ Syntax: >> ERROR Parent Command: > COMPUTATION Subcommand: >>> ALPHA >>> EMPIRICAL ORTHOGONAL FUNCTIONS >>> EOF >>> FISHER >>> FOSM >>> HESSIAN >>> LINEARITY >>> LIST >>> MONTE CARLO >>> POSTERIORI >>> PRIORI >>> TAU Description: This is the parent command of a number of subcommands that deal with the a posteriori error analysis or uncertainty propagation analysis. Example: > COMPUTATION >> ERROR analysis >>> use confidence level 1-ALPHA:= 95 % >>> use sigma as determined by FISHER model test >>> calculate finite difference HESSIAN matrix >>> check LINEARITY assumption on : 99 % level <<< << See Also: - @@@ Syntax: >> FACTOR Parent Command: > PARAMETER Subcommand: >>> NONE >>> SET Description: This command selects as a parameter a constant factor with which the calculated TOUGH2 output will be multiplied. The factor is applied to the output that refers to a specific data set: z = z * factor TOUGH2 where factor is the multiplication factor and z is the TOUGH2 output. TOUGH2 The result z is compared to the measurement z* of the corresponding data set. This option allows correcting for a systematic, but unknown relative error in the data. The data set is identified by number using command >>> SET (p). If the factor is known and does not need to be estimated, use command >>>> FACTOR (o). Example: > PARAMETER >> FACTOR >>> SET No. : 1 >>>> ANNOTATION: correct amplitude >>>> GUESS: 1.0 <<<< <<< << See Also: >> DRIFT, >> LAG, >> SHIFT, >>> SET (p), >>>> FACTOR (o) @@@ Syntax: >>>> FACTOR (There are two fourth-level commands >>>> FACTOR. Check parent command.) Parent Command 1: all third-level commands in block > OBSERVATION Syntax: >>>> FACTOR: factor Subcommand: - Description: This command provides a conversion factor with which the data are multiplied so they comply with standard TOUGH2 units. The conversion factor is also applied to the standard deviation (see command >>>> DEVIATION (o)), i.e., the measurement error must be given in the same units as the data. The standard TOUGH2 units are used throughout the iTOUGH2 output file, i.e., all observed and calculated values as well as residuals and standard deviations have been multiplied by factor. Example: > OBSERVATION >> PRESSURE >>> ELEMENT: WEL99 >>>> conversion FACTOR: 1E5 [bar] - [Pa] >>>> pressure DATA in HOURS and bar on FILE: pres.dat >>>> standard DEVIATION: 0.01 [bar] <<<< <<< << See Also: >> FACTOR @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ Parent Command 2: all third-level commands in block > PARAMETER Syntax: >>>> FACTOR Subcommand: - Description: The parameter to be estimated is a factor with which the initial parameter guess is multiplied. X=p*X0 <=> p=X/X0 Here, p is the estimated parameter, X is the TOUGH2 parameter, and X0 is the initial value of the TOUGH2 parameter. This option is useful to estimate a scaling factor for variable initial and boundary conditions, or to determine the mean of a quantity while maintaining ratios (e.g., if estimating a common factor applied to all three permeability values in a model domain, the anisotropy ratio remains constant). If the factor is log-normally distributed, add command >>>> LOGARITHM or use command >>>> LOG(F). Estimating a factor is opposed to estimating the parameter value directly (command >>>> VALUE) or its logarithm (command >>>> LOGARITHM (p)). Example: > PARAMETER >> ABSOLUTE permeability >>> MATERIAL: CLAY1 SAND1 >>>> estimate multiplication FACTOR, and maintain both the anisotropy ratio within a layer as well as the permeability ratio between clay and sand. >>>> INDEX : 1 2 3 >>>> initial GUESS: 1.0 (default) >>>> RANGE : 0.01 100.0 <<<< <<< << See Also: >>>> LOGARITHM (p), >>>> LOG(F), >>>> VALUE @@@ Syntax: >>> FISHER Parent Command: >> ERROR Subcommand: - Description: The estimated error variance s02 represents the variance of the mean weighted residual and is thus a measure of goodness-of-fit: T -1 r C r 2 zz s = -------- 0 m - n The value s02 is used in the subsequent error analysis. For example, the covariance matrix of the estimated parameters, C , is directly proportional pp to the scalar s02. Note that if the residuals are consistent with the distributional assumption about the measurement errors (i.e., matrix C ), zz then the estimated error variance assumes a value close to one. s02 is also an estimate for the true or a priori error variance sigma02. It can be shown that the ratio (s02/sigma02) follows an F-distribution with the two degrees of freedom f1=m-n, and f2=infinity. Therefore, it can be statistically tested to see whether the final match deviates significantly from the modeler's expectations, expressed by matrix C . zz This is called the Fisher Model Test. The user must decide whether the error analysis should be based on the a posteriori or a priori error variance (see commands >>> POSTERIORI and >>> PRIORI, respectively). The decision can also be delegated to the Fisher Model Test according to the following table: ------------------------------------------------------------------------------- Fisher Model Test Error Variance Comment ------------------------------------------------------------------------------- s02/sigma02 > F s02 error either in the functional or stochastic model 1 < s02/sigma02 < F s02 model test passed s02/sigma02 < 1 sigma02 probably error in stochastic model ------------------------------------------------------------------------------- Example: > COMPUTATION >> ERROR >>> let the FISHER model test decide whether the a priori or a posteriori error variance should be used >>> confidence level 1-ALPHA : 95 % <<< See Also: >>> ALPHA, >>> POSTERIORI, >>> PRIORI @@@ Syntax: >> FLOW (phase_name/PHASE: iphase/HEAT) Parent Command: > OBSERVATION Subcommand: >>> CONNECTION Description: This command selects as an observation type the flow rate of phase iphase or total fluid flow rate or heat flux. This observation type refers to a connection. The phase name phase_name or phase number iphase, which depend on the EOS module being used, are listed in the iTOUGH2 header. They can be specified either on the command line or using the subcommand >>>> PHASE. If no phase is specified, the total flow rate is selected. IF keyword HEAT is present, the total heat flux accross teh connection is selected. Note that the sign of the calculated flow rate depends on the order of the two elements in a connection. Example: > OBSERVATION >> GAS FLOW rate >>> CONNECTION: INJ_1 ELM_2 >>>> ANNOTATION : Gas flow >>>> FACTOR : -16.666667 to convert from m^3/min to kg/s >>>> DATA on FILE : inject.dat >>>> RELATIVE error: 3.0 % <<<< <<< >> FLOW rate >>> CONNECTION: A11_1 A11_2 B11_1 B11_2 C11_1 C11_2 & D11_1 D11_2 E11_1 E11_2 F11_1 F11_2 >>>> ANNOTATION: Flow across boundary >>>> LIQUID PHASE flow rate >>>> take the SUM >>>> of the ABSOLUTE values of the 6 flow rates >>>> DATA in [kg/s], time in [MINUTES] are on FILE: outflow.dat >>>> standard DEVIATION: 0.1 kg/sec <<<< <<< << See Also: - @@@ Syntax: >> FORCHHEIMER Parent Command: > PARAMETER Subcommand: >>> MODEL Description: This command selects a parameter of the Forchheimer non-Darcy flow coefficient model (TOUGH2 variable FORCH(IPAR)). Use command >>>> INDEX to select the parameter index IPAR. Example: > PARAMETER >> parameter of FORCHHEIMER non-Darcy flow coefficient model >>> MODEL >>>> ANNOTATION : Constant Beta >>>> INDEX : 1 >>>> LOGARITHM >>>> RANGE : 3.0 8.0 <<<< <<< << See Also: - @@@ Syntax: >>> FORMAT: format (LIST) or >>> PLOTFILE: format (LIST) Parent Command: >> OUTPUT Subcommand: - Description: iTOUGH2 does not directly generate graphs (except for the residual plot and correlation chart). However, it does generate a plot file with data at the calibration points and system response as calculated with the initial, intermediate (see command >>> PLOTTING), and final parameter set. A plot file with the relative permeability and capillary pressure curves can also be requested (see command >>> CHARACTERISTIC). These plot files must be processed by an external visualization package. iTOUGH2 generates plot files in PLOPO format, a visualization software developed by U. Kuhlmann at ETH, ZuŸrich. The PLOPO plot file is internally reformatted to comply with formats of other visualization programs. The string format identifies the visualization software (for a list of available formats add keyword LIST). The reformatted plot files have a file extension specific for the chosen software (for example ".tec" for TECPLOT.) A general format accepted by most commercially available plotting programs is the arrangement in columns, where the first column contains the time, and additional columns hold the data and calculated system response for various observations. This general format can be obtained by using keyword COLUMNS. The default format is TECPLOT, and can be changed to another format in file it2main.f, BLOCK DATA IT, through variable IPLOTFMT. Additional interfaces can be programmed into subroutine PLOTIF and REFORMAT. Example: > COMPUTATION >> OUTPUT >>> FORMAT of plot file : COLUMNS (print LIST of available formats) <<< << See Also: >>> CHARACTERISTIC, >>> PLOTTING @@@ Syntax: >>>> FORMAT: format Parent Command: all third-level commands in block > OBSERVATION Subcommand: - Description: This command accepts a FORTRAN format statement for reading data. By default, data are read in free format following the >>>> DATA command or directly from a data file. If a column contains non-numeric characters, formatted input can be invoked by providing a string format representing the corresponding FORTRAN format statement. The format statement must be in brackets and must not contain any blanks. Example: > OBSERVATION >> LIQUID FLOW rate >>> CONNECTION : ELM50 BOT_1 >>>> multiply measurements by FACTOR: -1.0E-06 >>>> FORMAT: (3X,F11.1,30X,E17.10) used to read time and value >>>> COLUMN: 1 2 (time is in col. 1, flow rate in col. 2 of above FORMAT statement) >>>> SKIP : 3 lines before reading values >>>> DATA in MINUTES ------------------------------------------------------------ # Time [min] Cap. Pres, [hPa] FlowmeterX Flow Rate [mg/s] ------------------------------------------------------------- 1 5.0 0.1698331055E+02 FlowmeterA 0.9869399946E+01 2 10.0 0.2075763428E+02 FlowmeterA 0.1039689596E+02 3 15.0 0.2357142822E+02 FlowmeterA 0.1162893932E+02 4 20.0 0.2529052490E+02 FlowmeterA 0.1353439620E+02 5 25.0 0.2598133789E+02 FlowmeterA 0.1469761628E+02 . .... ................ .......... ................ >>>> RELATIVE error is: 10.0 % of the individual measurement <<<< <<< See Also: >>>> DATA, >>>> COLUMN, >>>> HEADER, >>>> PICK @@@ Syntax: >>> FORWARD (There are two third-level commands >>> FORWARD. Check parent command.) Parent Command 1: >> CONVERGE or >> OPTION Syntax: >>> FORWARD or >>> DIRECT Subcommand: - Description: This command allows one TOUGH2 simulation to be performed in order to solve the forward problem. It is advantageous to perform a single TOUGH2 simulation before invoking more expensive inversions. The result from the forward run can be used to check TOUGH2 and iTOUGH2 input. Furthermore, a plotfile is generated with the results from the simulation with the initial parameter set which can be compared to the observed data. The CPU time requirement for an inversion can also be estimated from a single TOUGH2 simulation. (Note that there is another command >>> FORWARD in block >> JACOBIAN.) Example: > COMPUTATION >> STOP after >>> solving the DIRECT problem /* >>> before performing : 5 iTOUGH2 ITERATIONS */ <<< << See Also: >>> SIMULATION @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ Parent Command 2: >> JACOBIAN Syntax: >>> FORWARD (: iswitch) Subcommand: - Description: With this command the elements of Jacobian matrix are calculated by means of a forward finite difference quotient: dz z (p +dp ) - z (p ) i i j j i j J = --- = ------------------- ij dp dp j j The evaluation of the Jacobian thus requires n+1 TOUGH2 simulations, where n is the number of parameters. The size of the perturbation dp can be controlled using command >>> PERTURB. The Jacobian is used in both the minimization algorithm and the a posteriori error analysis. For the Levenberg-Marquardt minimization algorithm, the accuracy obtained by using a forward (as opposed to centered) finite difference quotient is usually sufficient, especially during the first few iterations far away from the minimum. However, if approaching the minimum and especially for the subsequent error analysis one might want to use a more accurate approximation of the Jacobian. If a colon is given on the command line followed by an integer iswitch, iTOUGH2 switches from forward to centered finite differences after iswitch iterations. Example: > COMPUTATION >> CONVERGE >>> perform a total of : 6 iTOUGH2 ITERATIONS <<< >> JACOBIAN >>> use FORWARD finite differences for : 5 iterations, i.e. a centered finite difference quotient is used for the final iteration and error analysis. >>> PERTURBation factor is : 0.005 times the parameter value <<< << See Also: >>> CENTERED, >>> PERTURB @@@ Syntax: >>> EOF (MATRIX: ndim) (iTOUGH2) (CORRELATION) Parent Command: >> ERROR Subcommand: - Description: This command must be used in combination with command >>> MONTE CARLO to invoke stochastic simulations of correlated parameters using Empirical Orthogonal Functions (EOF). EOF is a variant of Monte Carlo simulations to quantify the uncertainty of model predictions as a result of parameter uncertainty. Many parameter sets are generated, following the predefined covariance matrix Cpp. The i-th parameter set Yi is obtained by linear combination of the eigenvectors uk of Cpp and stochastic coefficients phi(xsi): n Y = SUM ( u * phi ) i k=1 k k phi (xsi ) = xsi * SQRT( a ) k i i k where xsi is a standard normal distributed random variable, and ak is the k-th eigenvalue of Cpp. For more details, see Kitterod and Gottschalk [1997]. The elements of matrix Cpp can be supplied using one of the following options: (1) Provide indices and elements of Cpp. Example: >>> EMIRICAL ORTHOGONAL FUNCTION 1 1 0.80643E-04 2 2 0.71921E-04 2 1 0.64412E-04 Use keyword CORRELATION if off-diagonal term is correlation coefficient instead of covariance. Example: >>> EMPIRICAL ORTHOGONAL FUNCTION, CORRELATION 1 1 0.80643E-04 2 2 0.71921E-04 2 1 0.864 (2) Provide keyword MATRIX, followed by a colon and the dimension ndim of the square matrix Cpp. The lower triangle of the covariance matrix is then provided on exactly ndim additional lines. If keyword CORRELATION is present, the off-diagonal terms represent correlation coefficients rather than covariances. Example: >>> EMPIRICAL ORTHOGONAL FUNCTION, dim. of CORRELATION MATRIX: 4 9.1234 -0.67 0.00413 0.80 0.213 1.3E-6 0.50 -0.155 0.90 4.3E12 (3) If calculated during a previous iTOUGH2 inversion, the covariance matrix can be taken from the iTOUGH2 output file and directly copied after the command line. This option is invoked by keyword iTOUGH2. The matrix will be read by formatted input, so it is crucial that the correct format is maintained. If ndim is greater than 6, the matrix is split in multiple submatrices. All submatrices must be copied exactly as they were printed to the iTOUGH2 output file. Example: >>> EOF error analysis, read MATRIX of dim.: 3 in iTOUGH2 format log(abs. perm.) POROSITY SAND Gas entrapped log(abs. perm.) .80643E-04 .846 -.253 POROSITY SAND .64412E-04 .71921E-04 -.500 Gas entrapped -.52623E-05 -.98296E-05 .53843E-05 Example: > COMPUTATION >> STOP >>> number of Monte Carlo SIMULATIONS: 250 <<< >> ERROR propagation analysis >>> MONTE CARLO simulations, SEED number: 777 >>> EMPIRICAL ORTHOGONAL FUNCTION, dim. of CORRELATION MATRIX: 4 9.1234 -0.67 0.00413 0.80 0.213 1.3E-6 0.50 -0.155 0.90 4.3E12 <<< << See Also: >>> FOSM, >>> MONTE CARLO @@@ Syntax: >>> FOSM (MATRIX: ndim) (iTOUGH2) (CORRELATION) (DIAGONAL) Parent Command: >> ERROR Subcommand: - Description: This command performs First-Order-Second-Moment (FOSM) uncertainty propagation analysis. FOSM quantifies the uncertainty of model predictions as result of parameter uncertainty. FOSM is the analysis of the mean and covariance of a random function based on its first order Taylor series expansion. FOSM analysis presumes that the mean and covariance are sufficient to characterize the distribution of the dependent variables, i.e., the model results are assumed to be normally distributed, and perturbations about the mean can be approximated by linear functions J. The covariance of the uncertain parameters, C , is translated into the covariance of the simulated system response, C : pp zz T C = J C J zz pp The diagonal elements of matrix C , i.e., the variances of the parameters, pp can be supplied by command >>>> VARIANCE (or related commands) in block > PARAMETER. If correlations are to be taken into account, the full covariance matrix must be provided. This is indicated by keyword MATRIX, which is followed by a colon and the dimension ndim of the square matrix C . pp The elements of matrix C can be supplied using one of the following options: pp (1) ndim lines must be provided, each line holding the lower triangle of the covariance matrix. If keyword CORRELATION is present, the off-diagonal terms represent correlation coefficients rather than covariances. Example: >>> FOSM error analysis, read CORRELATION MATRIX of dimension: 4 9.1234 -0.67 0.00413 0.80 0.213 1.3E-6 0.50 -0.155 0.90 4.3E12 (2) If calculated during a previous iTOUGH2 inversion, the covariance matrix can be taken from the iTOUGH2 output file and directly copied after the command line. This option is invoked by keyword iTOUGH2. The matrix will be read by formatted input, so it is crucial that the correct format is maintained. If ndim is greater than 6, the matrix is split in multiple submatrices. All submatrices must be copied exactly as they were printed to the iTOUGH2 output file. Example: >>> FOSM error analysis, read MATRIX of dim.: 3 in iTOUGH2 format log(abs. perm.) POROSITY SAND Gas entrapped log(abs. perm.) .80643E-04 .846 -.253 POROSITY SAND .64412E-04 .71921E-04 -.500 Gas entrapped -.52623E-05 -.98296E-05 .53843E-05 If the full matrix is provided, but only the diagonal terms (variances) shall be used in the uncertainty analysis, use keyword DIAGONAL on the command line. This option makes it easy to study the impact of correlations on the uncertainty propagation analysis. The uncertainty of the model prediction as a result of parameter uncertainty is given as a standard deviation in the residual analysis. Furthermore, the plotfile contains the system response for the mean parameter set as well as error band on the specified confidence level (see command >>> ALPHA). It is suggested to also increase the perturbation factor for calculating the Jacobian matrix, and to use a centered finite difference quotient. This yields in an more realistic the error band if the model is highly non-linear. It should be realized, however, that Monte Carlo is the preferred method if dealing with highly non-linear flow systems. Example: > COMPUTATION >> ERROR propagation analysis >>> perform First-Order-Second-Moment (FOSM) analysis >>> draw error bands on (1-ALPHA)=: 95 % confidence level <<< >> JACOBIAN >>> use CENTERED finite difference quotient >>> PERTURBATION factor at least: 5.0 % <<< << See Also: >>> ALPHA, >>> MONTE CARLO @@@ Syntax: >>>> GAUSS or >>>> NORMAL Parent Command: all third-level commands in block > PARAMETER Subcommand: - Description: This command generates normally distributed input parameters for Monte Carlo simulations. This is the default distribution. Parameter values will be generated following a normal distribution with the initial guess as the mean, and the standard deviation taken from command >>>> DEVIATION. Only values within the specified range will be accepted. If command >>>> LOGARITHM is also present, parameters follow a log-normal distribution. Example: > PARAMETER >> ABSOLUTE permeability >>> MATERIAL: SAND1 BOUND WELLB >>>> ANNOTATION : log(k) is uncertain >>>> LOGARITHM >>>> generate log-NORMAL distribution about mean... >>>> initial GUESS : -12.0 and with... >>>> standard DEVIATION : 1.0 within the... >>>> admissible RANGE : -15.0 -9.0 <<<< <<< << > COMPUTATION >> perform ERROR propagation analysis by means of... >>> MONTE CARLO simulations <<< >> STOP after... >>> : 400 TOUGH2 runs <<< << See Also: >>> MONTE CARLO, >>>> UNIFORM @@@ Syntax: >>> GAUSS-NEWTON Parent Command: >> OPTION Subcommand: - Description: This command performs Gauss-Newton steps to minimize the objective function. The Gauss-Newton algorithm assumes linearity and can be described as follows: T -1 -1 T -1 dp = (J C J) J C r zz zz (k+1) (k) p = p + dp Gauss-Newton steps are efficient if the model is linear (only one iteration required to find minimum) or nearly-linear. If the model is highly nonlinear, Gauss-Newton steps are usually too large, leading to an inefficient or even unsuccessful step. By default, iTOUGH2 uses the Levenberg-Marquardt minimization algorithm, which is a modification of the Gauss-Newton algorithm. Example: > COMPUTATION >> OPTION >>> use GAUSS-NEWTON minimization algorithm <<< >> STOP after >>> :1 ITERATION <<< << See Also: >>> ANNEAL, >>> GRID SEARCH, >>> LEVENBERG-MARQUARDT @@@ Syntax: >> GENERATION (comp_name/COMPONENT: icomp) (phase_name/PHASE: iphase) or >> PRODUCTION (comp_name/COMPONENT: icomp) (phase_name/PHASE: iphase) Parent Command: > OBSERVATION Subcommand: >>> SINK Description: This command selects as an observation type the total or fractional generation rate in a production well. This observation type refers to a sink code name. The total generation rate is usually prescribed in TOUGH2 block GENER, or can be considered a parameter to be estimated (see command >> RATE). A variable generation rate suitable for calibration is obtained only for wells on deliverability (type DELV), or if the generation rate of a specific phase is used. The fractional generation rate refers to the production of a specific phase or component. The component name comp_name or component number icomp, as well as the phase name phase_name or phase number iphase, which depend on the EOS module being used, are listed in the iTOUGH2 header. They can be specified either on the command line or using the subcommands >>>> COMPONENT and >>>> PHASE, respectively. If neither a phase nor a component is specified, the total generation rate is calculated. If a phase but no component is selected, the generation rate of that phase including all components is calculated. If a component but no phase is selected, the generation rate of that component in all phases is calculated. Finally, if a specific phase and a specific component is given, only the generation rate of that component in the specified phase is calculated. Example: > OBSERVATION >> GAS GENERATION (includes both air and vapor) >>> SINK: DLV_1 + 5 >>>> ANNOTATION : Gas generation [Nl/s] >>>> FACTOR : 1000.0 [Nl/s] - [kg/s] >>>> DATA on FILE : gasflow.dat [HOUR] >>>> RELATIVE error: 10.0 [%] <<<< <<< << < See Also: >> TOTAL MASS, >> CUMULATIVE, >> RATE, >>>> COMPONENT, >>>> PHASE @@@ Syntax: >>> GRID BLOCK: eleme (eleme_i ...) (+ iplus) Parent Command: all second-level commands in block > OBSERVATION requiring element names. Subcommand: all fourth-level commands in block > OBSERVATION Description: (synonym for command >>> ELEMENT) Example: (see command >>> ELEMENT) See Also: >>> ELEMENT @@@ Syntax: >>> GRID SEARCH (UNSORTED) (: ninval1 (ninval2 (inval3)) / FILE: filename) or >>> OBJECTIVE (UNSORTED) (: ninval1 (ninval2 (inval3)) / FILE: filename) Parent Command: >> OPTION Subcommand: - Description: This command evaluates the objective function for a number of specific parameter sets. A list of parameter sets can be provided on file filename. Alternatively, parameter sets are generated internally on a regular grid, mapping out the entire parameter space. In this case, lower and upper bounds must be defined for each parameter using command >>>> RANGE in block > PARAMETER. This range is then subdivided into ninteri intervals by inserting invali+1 equally spaced points, generating parameter sets on a regular grid in the -dimensional parameter space. The objective function is evaluated at each grid point. Evaluating the objective function throughout the entire parameter space is referred to as grid searching. The parameter set, the value of the objective function, and the contribution of each observation type to the objective function is printed to the iTOUGH2 output file. The global minimum is likely to be in the vicinity of the parameter set with the lowest objective function. Furthermore, the information listed in the output file can be used to visualy represent and study the topology of the objective function. For example, one can generate a contour plot of the objective function for n=2 which may reveal the presence local minima. If only one output variable is defined in block > OBSERVATION and no data are provided, this option can also be used in combination with command >>> L1-ESTIMATOR to examine the sensitivity of the output variable over an extensive parameter range. Keyword UNSORTED can be used in PVM applications to improve efficiency. The output list must then be sorted in a post-processing step. Example: > COMPUTATION >> OPTION >>> GRID SEARCH! subdivide 2D-parameter space into: 20 10 intervals <<< << See Also: >>> ANNEAL, >>> LEVENBERG-MARQUARDT, >>> GAUSS-NEWTON, >>> PVM, >>> SIMPLEX @@@ Syntax: >> GUESS (FILE: file_name) Parent Command: > PARAMETER Subcommand: - Description: This command identifies initial guesses of the parameters to be estimated. The initial guess vector p0 is the starting point of the minimization algorithm (iteration k=0). Usually, the initial guess vector is identical with vector p* which holds prior information about the parameters. By default, p0 and p* are identical, taken from the TOUGH2 input file, and overwritten by command >>>> PRIOR. The starting point for the minimization algorithm may be different from the prior information vector. In this case, prior information is taken from the TOUGH2 input file, or must be provided through command >>>> PRIOR. The Starting point is taken from this command which overwrites the initial guess provided through command >>>> GUESS. A parameter is identified by an integer value indicating its position in the parameter block: I XIGUESS(I) This format is identical to that of file .par. Initial guesses can be provided either following the command line, or read from a file if keyword FILE is present. The filename is given after the colon. This latter option is useful to transfer best estimates from one inversion to another if the order of the parameters is the same. Example: > PARAMETER >> GUESS 2 0.345 (initial guess for parameter no. 2) 3 -16.971 (initial guess for parameter no. 3) /* (the initial guess for parameter no. 1 is taken from the fourth-level command >>>> PRIOR, or - if not present - from the TOUGH2 input file) */ ... > PARAMETER >> read GUESS from FILE: testi.par See Also: >>>> GUESS, >>>> PRIOR @@@ Syntax: >>>> GUESS: guess Parent Command: all third-level commands in block > PARAMETER Subcommand: - Description: This command provides an initial guess of the parameter to be estimated. If neither this command or command >>ÊGUESS is used, the initial guess is taken from the TOUGH2 input file. The initial guess is the starting point for the minimization algorithm, to be distinguished from prior information (see command >>>> PRIOR). The initial guess can be overwritten by the second-level command >> GUESS. If command >>>> LOGARITHM is present, the initial guess is the logarithm of the parameter. Similarly, if command >>>> FACTOR is present, the initial guess should be a multiplication factor (default is 1.0). Example: > PARAMETER >> ABSOLUTE permeability >>> ROCK types: CLAY1 CLAY2 CLAY3 BOUND >>>> FACTOR >>>> initial GUESS : 1.0 >>>> is not WEIGHTed : 0.0 (default) <<<< >>> ROCK type : SAND1 >>>> LOGARITHM >>>> PRIOR information : -12.0 >>>> standard DEVIATION: 1.0 order of magnitude <<<< <<< >> GUESS, i.e., starting point for optimization 2 -13.0 << See Also: >> GUESS, >>>> PRIOR, >>>> DEVIATION, >>>> VARIATION @@@ Syntax: >>>> HEADER: nskip or >>>> SKIP: nskip Parent Command: all third-level commands in block > OBSERVATION Subcommand: - Description: This command identifies the number of lines to be skipped before reading data. Data reading starts nskip+1 lines after the command line >>>> DATA, or on the (nskip+1)-th line of the data file (see command >>>> DATA). Example: > OBSERVATION >> TEMPERATURE >>> ELEMENTS: ELM_10 + 4 >>>> SKIP: 3 lines before reading data >>>> DATA [HOURS] (1) ------------------------------------------------------------- (2) time [h] temperature comment (3) ------------------------------------------------------------- 0.00 21.3 mean temperature prior to experiment 1.12 21.3 heater turned on 1.15 21.9 1.20 23.4 2.00 32.8 heater turned off 2.10 29.3 2.20 26.7 2.30 24.1 4.00 21.6 end of experiment ------------------------------------------------------------- >>>> standard DEVIATION: 0.5 degrees C <<<< <<< << See Also: >>>> COLUMN, >>>> DATA, >>>> FORMAT, >>>> SET (o) @@@ Syntax: HELP (a keyword in combination with any command) Parent Command: - Subcommand: - Description: A short message about the command usage is printed to the iTOUGH2 output file if keyword HELP is present on the command line. See also LIST and >>> INDEX for further support. If command >>> INPUT is used, the help message can be retrieved without performing any iTOUGH2 calculations. Example: > COMPUTATION >> CONVERGE (what does this command do? HELP!) >>> while you're at it, print a LIST of available commands, >>> then stop after INPUT is read (HELP again!) <<< << See Also: >>> INDEX, LIST @@@ Syntax: >>> HESSIAN Parent Command: >> ERROR >> JACOBIAN Subcommand: - Description: This command computes a finite difference Hessian matrix H for the error analysis following optimization. The elements of H are given by: 2 1 dz dz d z i i i H = 2*Sum( ------ [ --- --- - r -------]) i=1,...m jk 2 i sigma dp dp dp dp i j k j k The evaluation of H by means of finite differences requires 2n+n*(n-1)/2 additional TOUGH2 simulations, where n is the number of parameters. By default, the Hessian matrix, which is the inverse of the parameter covariance matrix, is approximated by T -1 J C J zz based on the linearity assumption, i.e., the second derivative term is ignored. Evaluating the finite difference Hessian, which takes into account the non-linearities, provides a means by which to check the linearity assumption (for another approach see command >>> LINEARITY). This may lead to a more accurate calculation of the covariance matrix of the estimated parameters. However, inclusion of the second-derivative term may yield a Hessian matrix that is not positive definite due to the presence of outliers, strong non-linearities, or the fact that the minimum has not been detected accurately, i.e., when the positive and negative residuals r do not cancel each other. In this case, iTOUGH2 automatically proceeds with the linearized Hessian which is positive definite by definition. Example: > COMPUTATION >> ERROR analysis should be based on >>> finite difference approximation of the HESSIAN matrix <<< See Also: >>> LINEARITY @@@ Syntax: >>> INCOMPLETE: max_incomplete Parent Command: >> CONVERGE Subcommand: - Description: A successful iTOUGH2 run is based on the robustness and stability of the underlying TOUGH2 simulation. It is therefore imperative to develop a TOUGH2 model that is capable of completing the desired simulation for a variety of parameter combinations. The simulation must reach the time of the last calibration point, i.e., a premature termination due to convergence failures is not acceptable. The number of potential convergence failures or errors leading to premature termination is large. The type of convergence failure is indicated in the iTOUGH2 output file. It is usually impossible to continue the optimization process after a convergence failure. However, in some cases iTOUGH2 is able to retrieve information from a previous simulation which allows it to continue the inversion despite an incomplete run. iTOUGH2 always terminates if an incomplete run is encountered during the first evaluation of the Jacobian. The maximum number of incomplete simulations to be accepted by iTOUGH2 can be set by variable max_incomplete (default: 5). However, one should not rely on inversions that contain incomplete TOUGH2 runs. Note that if option >>> STEADY-STATE is invoked, all incomplete simulations are accepted by iTOUGH2 assuming that steady-state conditions have been reached. Example: > COMPUTATION >> TOLERANCE >>> perform : 10 ITERATIONS >>> or stop if : 250 TOUGH2 SIMULATIONS are executed >>> accept : 10 INCOMPLETE runs, if possible <<< << See Also: >>> STEADY-STATE @@@ Syntax: >>> INDEX Parent Command: >> OUTPUT Subcommand: - Description: Prints the iTOUGH2 command index to the iTOUGH2 output file. Example: > COMPUTATION >> OUTPUT >>> print command INDEX <<< << See Also: LIST, HELP @@@ Syntax: >>>> INDEX (There are two fourth-level commands >>>> INDEX. Check parent command.) Parent Command 1: most third-level commands in block > PARAMETER Syntax: >>>> INDEX: index (index_i...) or >>>> PARAMETER: index (index_i...) Subcommand: - Description: This command provides a list of integers for further parameter specification. The integers are usually indexes of TOUGH2 arrays, such as IPAR in arrays CP(IPAR,NMAT) or RPD(IPAR), selecting the IPAR-th parameter of the capillary pressure or default relative permeability function, respectively. If multiple indexes are provided, a single parameter will be estimated and assigned to all the corresponding array elements. Example: > PARAMETER >> estimate 2nd parameter of default CAPILLARY pressure function >>> DEFAULT >>>> PARAMETER CPD: 2 <<<< <<< >> optimize generation RATE of alternating "huff & puff" system >>> SOURCE: WEL_1 >>>> ANNOTATION : Injection >>>> INDEX of array F2 : 1 3 5 7 9 <<<< >>> SOURCE: WEL_1 >>>> ANNOTATION : Pumping >>>> INDEX of array F2 : 2 4 6 8 10 <<<< <<< << See Also: - @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ Parent Command 2: all third-level commands in block > OBSERVATION Syntax: >>>> INDEX: index (index_i...) or >>>> PARAMETER: index (index_i...) Subcommand: - Description: This command provides a list of integers for further specification of user-specified observations (see command >> USER (o)). Example: (see command >> USER (o)) See Also: >> USER(o) @@@ Syntax: >> IFS Parent Command: > PARAMETER Subcommand: >>> MODEL Description: This command selects as a parameter one of the IFS parameters. An index I must be provided through command >>>> INDEX. If I is positive, the parameter is one of the affine transform entries (variable PIFS(I)). If I is negative, the parameter is the increment parameter for property field -I (variable TINC(-I)). If I is lower than -100, the parameter is the smoothing parameter in direction (-I-100) (variable SMOOTH(-I-100)). Example: > PARAMETER >> IFS parameter >>> MODEL >>>> ANNOTATION: Diag. elements of B >>>> INDEX : 1 4 >>>> LOGARITHM <<<< >>> MODEL >>>> ANNOTATION: Increment >>>> INDEX : -1 >>>> VALUE <<<< >>> MODEL >>>> ANNOTATION: Smoothing in X- and Y direction >>>> INDEX : -101 -102 >>>> VALUE <<<< <<< << See Also: - @@@ Syntax: >> INITIAL (PRESSURE/: ipv) Parent Command: > PARAMETER Subcommand: >>> DEFAULT >>> MATERIAL Description: This command selects as a parameter the initial condition for all grid blocks associated with a certain rock type (TOUGH2 variable DEPU(ipv)) or default initial condition (TOUGH2 variable DEP(ipv)). Since boundary conditions are specified as initial conditions for inactive grid blocks or grid blocks with a large volume, this command can also be used to estimate boundary conditions. Initial conditions estimates cannot be provided for individual elements unless they have a unique material name associated with them. Estimating the first primary variable can be selected using keyword PRESSURE. All the other primary variables must be identified by number, i.e. by an integer ipv that follows a colon on the command line. Alternatively, ipv can be provided through command >>>> INDEX. The initial guess for the parameter is taken from TOUGH2 block PARAM.4, or should be provided by using commands >> GUESS or >>>> GUESS or >>>> PRIOR. Example: > PARAMETER >> INITIAL PRESSURE >>> MATERIAL: BOUND >>>> ANNOTATION: Boundary Pressure >>>> scale pressures on boundary by constant FACTOR <<<< <<< >> INITIAL condition for primary variable No.: 2 >>> MATERIAL : SAND1 DEFAU >>>> ANNOTATION : Initial Saturation >>>> VALUE >>>> initial GUESS : 10.4 >>>> admissible RANGE: 10.01 10.99 <<<< <<< << See Also: - @@@ Syntax: >>> INPUT Parent Command: >> CONVERGE Subcommand: - Description: This command makes iTOUGH2 stop immediately after the TOUGH2 and iTOUGH2 input files have been read and checked for consistency. This is useful to check input before time consuming simulations are invoked, or in combination with LIST, HELP, and >>> INDEX. Example: > COMPUTATION >> print LIST of available commands on this command level >> CONVERGE (print HELP message to iTOUGH2 output file and >>> stop immediately after INPUT is read) <<< << See Also: >>> INDEX, HELP, LIST @@@ Syntax: >>> INTERFACE: elem_1 elem_2 (elem_i elem_j ...) (+ iplus) Parent Command: >> FLOW Subcommand: all fourth-level commands in block > OBSERVATION Description: (synonym for command >>> CONNECTION) Example: (see command >>> CONNECTION) See Also: >> CONNECTION @@@ Syntax: >>> ITERATION: max_iter Parent Command: >> CONVERGE Subcommand: - Description: This command sets the maximum number of iTOUGH2 iterations to max_iter. If using the Levenberg-Marquardt minimization algorithm, an iTOUGH2 iteration consists of a number of TOUGH2 simulations and includes the following steps: (1) solution of the forward problem; (2) evaluation of the Jacobian matrix (requiring n or 2n TOUGH2 simulations depending on whether a forward or centered finite difference quotient is requested, see command >> JACOBIAN); (3) updating of the parameter vector (see also command >>> STEP); (4) check run(s) to see whether the new parameter set leads to a reduction of the objective function; if not, go back to step 3. If the objective function is successfully reduced, the iteration is completed, and the last check run is used as the solution of the forward problem (step (1) above) for the next iteration. By default, new iterations are performed until one of the following convergence criteria is met (note that different convergence criteria apply if options other than Levenberg-Marquardt optimization are used): (1) the maximum number of TOUGH2 simulations is reached (see command >>> SIMULATION); (2) the maximum number of incomplete TOUGH2 simulations is reached (see command >>> INCOMPLETE); (3) the scaled step size is smaller than the minimum relative step size 1E-9; (4) all parameters are at their user-specified bounds; (5) the objective function is smaller than the relative function tolerance; (6) the maximum number of unsuccessful uphill steps is exceeded (see command >>> UPHILL); (7) the Levenberg parameter exceeds 1E12; (8) the norm of the gradient vector is smaller than 1E-5 (optimality criterion). In most cases, however, it is sufficient to stop the inversion after a few iterations because no significant fit improvement is obtained after about 5 to 15 iterations. Generally more iterations are required with increasing number of parameters and stronger non-linearities of the flow problem. The progress of the objective function reduction can be observed by typing the command prista (see unix script file prista), and inversion can be terminated using the kit command (see unix script file kit). It is suggested to perform a single iTOUGH2 iteration or to use option >> SENSITIVITY ANALYSIS prior to running a full inversion in order to check the relative importance and sensitivity of each parameter, the parameter step size, the initial value of the Levenberg parameter, etc. Example: > COMPUTATION >> STOP after >>> : 6 ITERATIONS <<< << See Also: >>> SENSITIVITY, >>> CENTERED, >>> FORWARD, >>> INCOMPLETE, >>> SIMULATION, >>> UPHILL @@@ Syntax: >>>> ITERATION (There are two fourth-level commands >>>> ITERATION. Check parent command.) Parent Command 1: >>> ANNEAL Syntax: >>>> ITERATION: max_iter Subcommand: - Description: This command limits the maximum number of iterations performed by the Simulated Annealing minimization algorithm. An iteration is completed if: (1) the maximum number of steps mstep on a temperature level is reached (see command >>>> STEP (a)), or (2) the objective function has been reduced 0.2*mstep times Each iteration is followed by a reduction of the control parameter tau (temperature) according to the annealing schedule (see command >>>> SCHEDULE). Example: > COMPUTATION >> OPTION >>> Simulated ANNEALing >>>> maximum number of ITERATIONS: 100 >>>> maximum number of STEPS per ITERATION: 50 >>>> annealing SCHEDULE: 0.95 >>>> initial TEMPERATURE: -0.02 <<<< <<< << See Also: >>>> STEP (a), >>>> SCHEDULE @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ Parent Command 2: >>> SELECT Syntax: >>>> ITERATION: niter Subcommand: - Description: This command defines the number of iterations after which the criteria for automatic parameter selection is reevaluated (see commands >>>> CORRELATION and >>>> SENSITIVITY). A full Jacobian matrix is evaluated every multiple of niter iterations. In intermediate iterations, only the columns of the Jacobian corresponding to the selected parameters are updated. Example: > COMPUTATION >> OPTION >>> SELECT parameter automatically every >>>> : 3 ITERATIONS >>>> based on the SENSITIVITY criterion with rsens : -0.10 <<<< <<< << See Also: >>>> CORRELATION, >>>> SENSITIVITY @@@ Syntax: >> JACOBIAN Parent Command: > COMPUTATION Subcommand: >>> CENTERED >>> FORWARD >>> HESSIAN >>> LIST >>> PERTURB Description: This is the parent command of a number of subcommands that deal with the calculation of the Jacobian matrix J. The elements of the Jacobian matrix, calculated at the calibration points, are the partial derivatives of the system response with respect to the parameters to be estimated: dr d(z* - z ) dz i i i i J = - --- = - ---------- = --- ij dp dp dp j j j The Jacobian matrix discussed here must be distinguished from the one calculated in the simulation program TOUGH2. The latter is used to solve the set of non-linear algebraic iterations arising at each time step; its elements are the partial derivatives of the mass residuals with respect to the primary variables, and its numerical computation is controlled by the TOUGH2 variable DFAC. Example: > COMPUTATION... >> ...of the JACOBIAN matrix is performed... >>> ...using FORWARD finite difference quotients for : 3 iterations before switching to centered finite difference quotients. >>> Parameter PERTURBation factor is: 1 % (default) <<< << See Also - @@@ Syntax: >>> JACOBIAN Parent Command: >> OUTPUT Subcommand: - Description: This command prints the Jacobian matrix after each iteration. By default, the (scaled) Jacobian matrix is printed only once at the end of the optimization. Example: > COMPUTATION >> OUTPUT >>> print JACOBIAN after each iteration. <<< << See Also: >>> RESIDUAL @@@ Syntax: >> KLINKENBERG Parent Command: > PARAMETER Subcommand: >>> MATERIAL Description: This command selects as a parameter the Klinkenberg slip factor (TOUGH2 variable GK(NMAT)). Example: > PARAMETER >> KLINKENBERG slip factor >>> ROCK type : GRANI >>>> LOGARITHM >>>> RANGE : 1.0 10.0 >>>> VARIATION : 1.0 <<<< <<< << See Also: - @@@ Syntax: >>> L1-ESTIMATOR Parent Command: >> OPTION Subcommand: - Description: This command selects the L1-estimator, i.e., the objective function to be minimized is the sum of the weighted absolute residuals. S = Sum(|r |/sigma ) i=1,...,m i i Minimizing the mean absolute deviation leads to a maximum-likelihood estimate if the errors follow a double exponential distribution. 1 phi(r ) = -------- exp(-|r |/sigma ) i 2*sigma i i i The L1-estimator should be used, for example, to minimize a cost function for the optimization of a cleanup operation. Furthermore, it can be used whenever the objective function of interest is a linear function of the model output (e.g., in a sensitivity analysis using command >>> OBJECTIVE in block >> OPTION). Note that this objective function is usually minimized using the Levenberg-Marquardt algorithm which is designed for a quadratic objective function. Minimization is therefore rather inefficient, requiring more iterations and a high initial Levenberg parameter. The downhill simplex algorithm (see command >>> SIMPLEX) can be used as an alternative. Example: > COMPUTATION >> OPTION >>> use L1-ESTIMATOR, then draw contours of the >>> OBJECTIVE function based on : 10 points in the parameter space <<< << See Also: >>> ANDREW, >>> CAUCHY, >>> LEAST-SQUARES, >>> QUADRATIC-LINEAR @@@ Syntax: >> LAG Parent Command: > PARAMETER Subcommand: >>> NONE >>> SET Description: This command selects as a parameter a constant lag, shifting data in time. The time lag is applied to the output that refers to a specific data set: z(t) = z (t + lag) TOUGH2 Here, t is time, lag is the estimated time lag in seconds, and z is the TOUGH2 TOUGH2 output. The result z is compared to the measurement z* of the corresponding data set. A single data set is identified by number using command >>> SET (p); multiple data sets a specified with command >>>> INDEX (p). If the lag is known, i.e., does not need to be estimated, use command >>>> SHIFT TIME, a subcommand of > OBSERVATION. Example: > PARAMETER >> LAG >>> NONE >>>> ANNOTATION: time lag >>>> INDEX: 1 2 3 >>>> GUESS: 300 sec. <<<< <<< << See Also: >> DRIFT, >> FACTOR, >> SHIFT, >>> SET (p), >>>> INDEX (p), >>>> SHIFT @@@ Syntax: >>> LEAST-SQUARES Parent Command: >> OPTION Subcommand: - Description: This command selects least-squares optimization, i.e., the objective function to be minimized is the sum of the squared weighted residuals. T -1 S = r C r zz Minimizing the squared weighted residuals leads to a maximum-likelihood estimate if the errors are normally distributed with zero mean and covariance matrix C : zz -m/2 -1/2 T -1 phi(r) = (2*Pi) |C | exp(-0.5 r C r) zz zz Least-squares estimation is the default. If outliers are more prominent than described by the tail of the normal distribution, one may want to use one of the robust estimators to reduce the weight of outliers or even eliminate them (see commands >>> ANDREW, >>> CAUCHY, or >>> QUADRATIC-LINEAR). The least-squares objective function is a quadratic function if the residuals depend linearly on the parameters; it is nearly-quadratic for a non-linear model. The Levenberg-Marquardt algorithm is best suited to minimize the non-linear least-squares objective function. Example: > COMPUTATION >> OPTION >>> use LEAST-SQUARES <<< << See Also: >>> ANDREW, >>> CAUCHY, >>> L1-ESTIMATOR, >>> QUADRATIC-LINEAR @@@ Syntax: >>> LEVENBERG: lambda Parent Command: >> CONVERGE Subcommand: - Description: This command sets the initial value of the Levenberg parameter lambda (default: 0.001). During the optimization process (see command >>> LEVENBERG-MARQUARDT), the Levenberg parameter is divided by the Marquardt parameter nue (see command >>> MARQUARDT) after each successful iteration, and is multiplied by nue if the new parameter set leads to an increased value of the objective function, i.e., if an unsuccessful step was proposed. A big value for lambda means that a small step along the steepest descent direction is performed. A lambda-value of zero is equivalent to a Gauss-Newton step. The former is robust but inefficient, the latter has a quadratic convergence rate but may lead to unsuccessful steps. Example: > COMPUTATION >> CONVERGE >>> maximum number of ITERATIONS: 10 >>> set initial LEVENBERG parameter to: 0.1 to make a safe first step <<< << See Also: >>> MARQUARDT @@@ Syntax: >>> LEVENBERG-MARQUARDT Parent Command: >> OPTION Subcommand: - Description: This command selects the Levenberg-Marquardt algorithm to minimize the objective function. This is the default minimization algorithm. The Levenberg-Marquardt algorithm combines the robustness of a steepest descent method with the efficiency of a Gauss-Newton step (see command >>> GAUSS-NEWTON): T -1 -1 T -1 dp = (J C J + lambda*D) J C r zz zz T -1 where D is a diagonal matrix with elements D = (J C J) ii zz ii The Levenberg-Marquardt method switches continuously from a gradient method (large lambda, see command >>> LEVENBERG) far from the minimum to a Gauss-Newton step as the minimum is approached and lambda is reduced. Example: > COMPUTATION >> OPTION >>> use LEVENBERG-MARQUARDT minimization algorithm (default) <<< >> CONVERGE >>> initial LEVENBGERG parameter lambda is : 0.001 (default) >>> MARQUARDT parameter nue is : 10.000 (default) <<< << See Also: >>> ANNEAL, >>> GAUSS-NEWTON, >>> GRID SEARCH, >>> LEVENBERG, >>> MARQUARDT @@@ Syntax: >>> LINEARITY (: alpha (%)) Parent Command: >> ERROR Subcommand: - Description: The covariance matrix of the estimated parameters, C , is calculated using pp linear error analysis: 2 T -1 -1 C = s (J C J) pp 0 zz The confidence region around the estimated parameter set for the linearized case consists of those values p for which _ T _ (p - p) C (p - p) < n * F pp n,m-n,1-alpha _ where p is the parameter vector at the optimum. The covariance matrix C pp approximates the actual surface of the objective function at its minimum by a tangent hyperellipsoid under the assumption of normality and linearity. If the model is nonlinear, the coverage of the confidence region by the linear approximation may be very poor with respect to both its size and its shape. When using this command, it is assumed that the shape of the confidence region is close to ellipsoidal, and that the orientation of the hyperellipsoid in the n-dimensional parameter space is accurately obtained from the linear error analysis. Then, by only adjusting the size of the hyperellipsoid, we can better approximate the confidence region without losing the advantage of producing easily understandable results which are also simple to report. The procedure adopted here is based on a comparison of the actual objective function with the results from the linear approximation at discrete points in the parameter space. These test points p' are preferably located along the main axis of the hyperellipsoid, i.e.: _ 1/2 p' = p +- (n * F ) a u i=1,...,n +- n,m-n,1-alpha i i Here, p' are two test parameter sets on the i-th axis, the direction of +- which is given by the eigenvector u of the covariance matrix C . i _ pp Note that the distance from the optimal parameter set p is selected as a multiple of the corresponding eigenvalue a and the quantile of the i F-distribution. This means that the correction is tailored to approximate the confidence region on a certain confidence level (1-alpha). The eigenvalues a' which represent the length of the semiaxis are now corrected as follows: i 2 2 2 a' = a s (A + A )/2 i i 0 + - i with n * F n,m-n,1-alpha A = ------------------ +-i _ S(p') - S(p) 2 Finally, the new covariance matrix is back-calculated from the eigenvectors u i and the updated eigenvalues a' . i This correction procedure requires 2*n additional solutions of the direct problem and is thus relatively inexpensive. While the resulting confidence region is ellipsoidal by definition, the differences between S(p' ) and S(p' ) +i -i provide, as a byproduct of the correction procedure, some insight into the asymmetry of the true confidence region. The user may specify alpha or (1-alpha) in % or the quantile n * F directly, (by omitting % on n,m-n,1-alpha the command line). Note that the correction procedure fails if the minimum is not accurately identified. In this case iTOUGH2 automatically proceeds with the covariance matrix from the linear error analysis. Example: > COMPUTATION >> ERROR analysis >>> calculate finite difference HESSIAN and then >>> check LINEARITY assumption on the : 95 % confidence level <<< << See Also: >>> HESSIAN @@@ Syntax: LIST (available on all command levels) Parent Command: - Subcommand: - Description: This command provides a list of all available commands on the corresponding command level. The list contains the actual upper case spelling of the command as interpreted by the program. Potential keywords are not listed. A complete list of all commands can be obtained with command >>> command INDEX. Example: > LIST > COMPUTATION >> STOP after >>> INPUT <<< << < The following list is printed to the iTOUGH2 output file showing all first-level commands: ***** LIST OF COMMANDS ***** on level 1: * < * > OPTION * > COMPUTATION * > PARAMETER * > OBSERVATION * > MEASUREMENT * ***** LIST OF COMMANDS ***** See Also: >>> INDEX, >>> INPUT @@@ Syntax: >>>> LOGARITHM (There are two fourth-level commands >>>> LOGARITHM. Check parent command.) Parent Command 1: all third-level commands in block > PARAMETER Syntax: >>>> LOGARITHM Subcommand: - Description: The parameter p to be estimated is the logarithm of the TOUGH2 parameter X: p=log10(X) <=> X=10**p Estimation of logarithms is recommended if the parameter is expected to vary over a large range of values, suggesting a log-normal distribution of its estimate. Note that all quantities referring to this parameter are also in log-space (e.g. range, standard deviation, step length, etc.). Estimating the logarithm is chosen here over estimating the parameter value directly (command >>>> VALUE), estimating a multiplication factor (command >>>> FACTOR (p)), or estimating a log-normally distributed multiplication factor (command >>>> LOG(F)). Example: > PARAMETER >> ABSOLUTE permeability >>> MATERIAL: SAND1 >>>> estimate LOGARITHM (this is the default for this parameter) >>>> initial GUESS : -12.0 = 1 darcy >>>> admissible RANGE : -15.0 -9.0 >>>> standard DEVIATION : 1.0 order of magnitude >>>> maximum STEP size : 0.5 log-cycles per iteration <<<< <<< << See Also: >>>> FACTOR (p), >>>> VALUE @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ Parent Command 2: all third-level commands in block > OBSERVATION Syntax: >>>> LOGARITHM Subcommand: - Description: This command takes the logarithm (base 10) of an observable variable. The corresponding measurement error is assumed to be log-normally distributed. Taking the logarithm is suggested when the observation assumes values over many orders of magnitude (e.g., concentration, water potential). Note that this option emphasizes the importance of smaller values of the variable, and is not applicable to data sets that contain zero measurements. Example: > OBSERVATION >> CAPILLARY PRESSURE >>> ELEMENT: TP__1 >>>> first take the ABSOLUTE value and >>>> then the LOGARITHM >>>> standard DEVIATION of log: 1.0 >>>> DATA on FILE: wp.dat <<<< <<< << See Also: - @@@ Syntax: >>>> LOG(F) Parent Command: all third-level commands in block > PARAMETER Subcommand: - Description: The parameter to be estimated is a log-normally distributed factor with which the initial TOUGH2 parameter value is multiplied: p = log10(X/X0) <=> X = X0 * 10**p Here, p is the estimated parameter, X is the TOUGH2 parameter, and X0 is the initial value of the TOUGH2 parameter. This option is useful to determine the mean of a log-normally distributed quantity while maintaining ratios (e.g., if estimating a common factor applied to all three permeability values in a model domain, the anisotropy ratio remains constant). Estimating a factor is chosen here over estimating the parameter value directly (command >>>> VALUE) or its logarithm (command >>>> LOGARITHM (p)). Example: > PARAMETER >> ABSOLUTE permeability >>> MATERIAL: SAND1 SAND2 SAND3 SAND4 SAND5 >>>> estimate LOG(F) >>>> INDEX : 1 2 3 >>>> initial GUESS: 0.0 (default) >>>> RANGE : -3.0 3.0 <<<< <<< << See Also: >>>> LOGARITHM (p), >>>> FACTOR, >>>> VALUE @@@ Syntax: >>> MARQUARDT: nue Parent Command: >> CONVERGE Subcommand: - Description: This command sets the Marquardt parameter nue (default: 10.0). During the optimization process, the Levenberg parameter lambda (see command >>> LEVENBERG) will be divided by the Marquardt parameter nue after each successful iteration, and it will be multiplied by nue if the new parameter set leads to an increased value of the objective function, i.e., if an unsuccessful step was proposed. A big value for lambda means that a small step along the gradient direction is performed. A lambda value of zero is equivalent to a Gauss-Newton step. The former is robust but inefficient, the latter has a quadratic convergence rate but may lead to unsuccessful steps. The Marquardt parameter therefore determines how fast the step size and step direction changes from steepest descent to Gauss-Newton and vice versa. Example: > COMPUTATION >> CONVERGE >>> maximum number of ITERATIONS: 10 >>> set initial LEVENBERG parameter to: 0.1 to make a safe first step >>> MARQUARDT parameter : 2.0 (slow change to Gauss-Newton steps) <<< << See Also: >>> LEVENBERG @@@ Syntax: >> MASS FRACTION (comp_name/COMPONENT: icomp) (phase_name/PHASE: iphase) Parent Command: > OBSERVATION Subcommand: >>> ELEMENT Description: This command selects as an observation type the mass fraction of component icomp in phase iphase. This observation type refers to one or more elements. Component number icomp or component name comp_name, and phase number iphase or phase name phase_name depend on the EOS module being used. They are listed in the iTOUGH2 header, and can be specified either on the command line or using the two subcommands >>>> COMPONENT and >>>>ÊPHASE, respectively. Example: > OBSERVATION >> MASS FRACTION of BRINE in LIQUID >>> ELEMENT: A1__1 or > OBSERVATION >> MASS FRACTION of COMPONENT No.: 2 in PHASE No.: 2 >>> ELEMENT: A1__1 or > OBSERVATION >> MASS FRACTION >>> ELEMENT: A1__1 >>>> COMPONENT: 2 >>>> PHASE : 2 See Also: >> CONCENTRATION @@@ Syntax: >>> MATERIAL: mat_name (mat_name_i ...) (+ iplus) or >>> ROCKS : mat_name (mat_name_i ...) (+ iplus) Parent Command: all second-level commands in block > PARAMETER referring to a material name Subcommand: all fourth-level commands in block > PARAMETER Description: This command identifies material names (TOUGH2 variable MAT). Most parameters refer to a particular material, i.e., they are specified in TOUGH2 in block ROCKS. Rock types are designated by a five-character code name. Blanks in the material name must be replaced by underscores (e.g., if MAT in TOUGH2 reads 'CLAY ', mat_name must read 'CLAY_'). If multiple material names are provided, the estimate of the corresponding parameter will be jointly assigned to all listed materials. If distinct parameters are sought for each rock type, separate >>> MATERIAL blocks must be defined. Default properties (i.e., for parameters referring to TOUGH2 blocks PARAM.4 and RPCAP) can be selected either by >>> DEFAULT or >>> MATERIAL: DEFAU. If the last two characters of the last mat_name are integers, a sequence of iplus material names can be generated. The following two command lines are thus identical: >>> MATERIAL: BOREH ROC10 ROC_1 +4 >>> MATERIAL: BOREH ROC_1 ROC_2 ROC_3 ROC_4 ROC_5 ROC10 Example: > PARAMETER >> ABSOLUTE permeability >>> MATERIAL: BOUND BOREH SAN_1 +2 >>>> LOGARITHM <<<< <<< >> INITIAL PRESSURE >>> MATERIAL: BOREH >>>> ANNOTATION: Pi borehole <<<< >>> MATERIAL: BOUND DEFAU >>>> ANNOTATION: Pi elsewhere <<<< <<< See Also: >>> DEFAULT, >>> MODEL @@@ Syntax: >>>> MEAN (VOLUME) Parent Command: all third-level commands in block > OBSERVATION Subcommand: - Description: (synonym for command >>>> AVERAGE) Example: (see command >>>> AVERAGE) See Also: >>>> AVERAGE @@@ Syntax: >> MINC Parent Command: > PARAMETER Subcommand: >>> MODEL Description: This command selects as a parameter the fracture spacing which is a parameter of the MINC preprocessor (TOUGH2 variable PARMINC(I)). The fracture set is identified through command >>>> INDEX. This parameter refers to the entire model. Estimating fracture spacing is only possible if the mesh can be generated internally without further editing by the user. Single elements and connections can be modified, however, by means of TOUGH2 commands ELEM2 and CONN2, respectively. For example, if a mesh is generated using MESHMAKER and MINC, the volumes of individual boundary elements can be adjusted in the ELEM2 block, i.e., avoiding the need for external editing. Example: > PARAMETER >> MINC parameter >>> MODEL >>>> ANNOTATION: Fracture spacing >>>> INDEX : 1 2 3 (one value for all three fracture sets) >>>> GUESS : 50.0 [m] >>>> DEVIATION : 10.0 [m] <<<< <<< << See Also: - @@@ Syntax: >>> MODEL or >>> NONE Parent Command: all second-level commands in block > PARAMETER or > OBSERVATION addressing parameters or observations that refer to the entire model domain or a non-specific item. Subcommand: all fourth-level commands in block > PARAMETER or > OBSERVATION, respectively. Description: Most parameters refer to a rock type or code name of a sink or source. Some parameters, however, are general or associated with the entire model domain. Similarly, while most observations refer to an element, connection, or sink/source, there are observation types that are not associated with a well-defined point in space. The commands >>> MODEL or >>> NONE are dummy commands, i.e. place holders on the third command level for parameter and observation types not further specified by one of the other third-level commands. Example: > PARAMETER >> SELEC parameter >>> NONE >>>> ANNOTATION: Gel Density (EOS11) >>>> INDEX : 2 >>>> VALUE <<<< <<< << > OBSERVATION >> TOTAL MASS of PHASE: 2 >>> refers to entire MODEL >>>> ANNOTATION : Mass of liquid >>>> DATA on FILE : liquid.dat >>>> DEVIATION : 0.01 [kg] <<< << See Also: >>> ELEMENT, >>> CONNECTION, >>> DEFAULT, >>> MATERIAL, >>> SET (p), >>> SOURCE @@@ Syntax: >> MOMENT (FIRST/SECOND) (X/Y/Z) (comp_name/COMPONENT: icomp) (phase_name/PHASE: iphase) Parent Command: > OBSERVATION Subcommand: >>> MODEL Description: This command selects as an observation type the first or second spatial moment in X, Y, or Z direction of component icomp or phase iphase. This observation type refers to all elements with 10,000 > SPHT > 0. The X, Y, and Z coordinates of the grid blocks must be given in TOUGH2 block ELEME, columns 51-60, 61-70, 71-80, respectively. Component number icomp or component name comp_name, and phase number iphase or phase name phase_name depend on the EOS module being used. They are listed in the iTOUGH2 header, and can be specified either on the command line or using the two subcommands >>>> COMPONENT and >>>> PHASE, respectively. If only a phase but no component is specified, the spatial moment of the indicated phase including all components is calculated. If only a component but no phase is given, the spatial moment of that component in all phases is calculated. If both a component and a phase are given, the spatial moment of the component in the specified phase is calculated. The spatial moments are calculated as follows: (nel) i j k kappa M =Sum Sum Sum (X * Y * Z * V * phi * S * rho * X ) ijk (beta) (kappa) (n) beta beta n where the first sum is taken over the selected phase(s) beta, the second sum is taken over the selected component(s) kappa, and the third summation accumulates the masses of component kappa in phase beta from all elements that are included in the global mass balance calculation (i.e., elements with a rock grain specific heat lower than 104 J/kg C). The mass in element n is the product of the element volume V, the porosity phi, the saturation S, the phase density rho, and the mass fraction X. The first moment represents the center of mass coordinates which are given by: = M /M 100 000 = M /M 010 000 = M /M 001 000 The second moment represents the variances in the three directions given by: 2 2 sigma = M /M - X 200 000 2 2 sigma = M /M - Y 020 000 2 2 sigma = M /M - Z 002 000 This option may be especially useful for characterizing the location and spreading of a contaminant or saturation plume. Note that boundary effects may have a strong impact on spatial moment calculation. Example: > OBSERVATION >> FIRST MOMENT (Z-coordinate) of TRACER COMPONENT in LIQUID PHASE >>> entire MODEL >>>> ANNOTATION: plume Z coord. >>>> NO DATA <<<< <<< >> SECOND MOMENT (X-coordinate) of TRACER COMPONENT in LIQUID PHASE >>> entire MODEL (except boundary elements with SPHT .gt. 10000) >>>> ANNOTATION: transversal spreading >>>> NO DATA <<<< <<< << See Also: - @@@ Syntax: >>> MONTE CARLO (SEED: iseed) (GENERATE) (CLASS: nclass) Parent Command: >> ERROR Subcommand: - Description: This command performs Monte Carlo simulations to determine the uncertainty of model predictions as a result of parameter uncertainty. The general procedure is as follows: (1) a probability distribution is defined for each uncertain parameter; (2) parameter values are randomly sampled from their respective distributions; (3) sampled parameter values are randomly combined to obtain a parameter vector; (4) a TOUGH2 simulation is performed and the results at the specified observation points are stored; (5) steps (3) through (4) are repeated; (6) the ensemble of the modeling results can be statistically analyzed. The type of distribution can be specified for each parameter in the respective parameter definition block (see command >>>> UNIFORM or >>>> NORMAL). The mean is given by the initial guess (see command >>>> GUESS), and the standard deviation by command >>>> DEVIATION (p). The generated parameter value is rejected if outside the specified range (see command >>>> RANGE). The number of Monte Carlo simulations, nMC, must be provided in block >> CONVERGE using command >>> SIMULATION, i.e., by specifying the maximum number of TOUGH2 simulations. The number of Monte Carlo simulations nMC can be considered sufficient if: (1) the selected probability density function of the input parameters is reasonably well approximated by the histogram of the randomly generated parameter values. Keyword GENERATE can be used in combination with various seed numbers (keyword SEED) and values for nMC (command >>> SIMULATION) to generate histograms of the input parameters without actually performing Monte Carlo simulations. Once a satisfactory distribution of the input parameters is achieved, the Monte Carlo simulations can be invoked by simply deleting keyword GENERATE. (2) the histogram of the model predictions allows for a statistical analysis. That means that a sufficient number of realizations (= simulation results) should fall within each interval used to calculate probabilities. For example: The probability that TCE concentrations cTCE fall within the interval [a,b] is approximated by: number of realizations in interval [a,b] n[a,b] P(a < cTCE < b) = ---------------------------------------- = ------ total number of Monte Carlo simulations nMC Therefore, the minimum number of Monte Carlo simulations, nMC(min), should be large enough so that P remains constant, i.e. independent of nMC. This condition is fulfilled for relatively small values of nMC in the case of intervals around the mean, where n[a,b] is usually large due to the high probability density. However, if we are interested in the tail of the distribution, for example to calculate the (low) risk that TCE concentrations exceed a certain standard, then the number of Monte Carlo simulations required is much higher. (3) The minimum number of Monte Carlo simulations must be increased if the number of uncertain parameter increases because more parameter combinations are possible. (4) From experience, the number of Monte Carlo simulations can be as low as 50 and as high as 2000 or greater. Histograms of the input parameters and output variables as printed to the iTOUGH2 output file. By default, the interval between the smallest and highest value is subdivided into sqrt(nMC) classes. The number of classes can be changed using keyword CLASS. The standard plot file contains all output sets from nMC simulations, where each set contains the model result as a function of time. A second plotfile is generated with "_mc" in the file name. In this second plot file, each curve represents the ensemble of the model output at one point in time. Denoting the number of output sets, for which prediction uncertainty is to be studied, by nSET, and the number of times by nTIMES, then the standard plot contains nSET*nMC curves, each curve consisting of nTIMES points. The second plotfile contains nSET*nTIMES curves, each consisting of nMC points. Example: > PARAMETER >> ABSOLUTE permeability >>> MATERIAL : ROCK_ >>>> generate NORMAL distribution >>>> of LOGARITHM >>>> with mean (GUESS) : -16.0 >>>> standard DEVIATION : 1.0 >>>> in the RANGE : -18.5 -13.5 <<<< <<< >> POROSITY >>> MATERIAL : ROCK_ >>>> VALUE >>>> UNIFORM distribution >>>> RANGE : 0.02 0.10 <<<< <<< << > OBSERVATION >> TIMES: 20 EQUALLY spaced in MINUTES 3.0 60.0 >> PRESSURE >>> ELEMENT: PRE_0 >>>> NO DATA >>>> WEIGHT: 1.0 <<<< <<< << > COMPUTATION >> STOP >>> number of Monte Carlo SIMULATIONS: 250 <<< >> ERROR propagation analysis >>> MONTE CARLO (SEED number is: 777) <<< << See Also: >>> FOSM, >>> SIMULATION, >>>> NORMAL, >>>> RANGE, >>>> UNIFORM @@@ Syntax: >>> NEW OUTPUT Parent Command: >> OUTPUT Subcommand: - Description: This command creates a new TOUGH2 output file with unique file name for each TOUGH2 run. By default, the TOUGH2 output file is overwritten each time a new simulation starts. Example: > COMPUTATION >> OUTPUT >>> write to NEW OUTPUT after each TOUGH2 run. <<< << See Also: - @@@ Syntax: >>> NONE Parent Command: all second-level commands in block > PARAMETER or > OBSERVATION addressing parameters or observations that refer to the entire model domain or a non-specific item. Subcommand: all fourth-level commands in block > PARAMETER or > OBSERVATION, respectively. Description: (synonym for command >>> MODEL) Example: (see command >>> MODEL) See Also: >>> MODEL @@@ Syntax: >>>> NORMAL Parent Command: all third-level commands in block > PARAMETER Subcommand: - Description: (synonym for command >>>> GAUSS) Example: (see command >>>> GAUSS) See Also: >>>> GAUSS @@@ Syntax: >>> OBJECTIVE Parent Command: >> OUTPUT Subcommand: - Description: This command prints the value of the objective function after each TOUGH2 simulation. By default, the value of the objective function is printed to the output file only after completion of an iTOUGH2 iteration. Example: > COMPUTATION >> OUTPUT >>> always print OBJECTIVE function <<< << See Also: >>> JACOBIAN @@@ Syntax: >>> OBJECTIVE (UNSORTED) (: ninval1 (ninval2 (inval3)) / FILE: filename) Parent Command: >> OPTION Subcommand: - Description: (synonym for command >>> GRID SEARCH) Example: (see command >>> GRID SEARCH) See Also: >>> GRID SEARCH @@@ Syntax: > OBSERVATION Parent Command: - Subcommands: >> CONCENTRATION >> CONTENT >> COVARIANCE >> CUMULATIVE >> DRAWDOWN >> ENTHALPY >> FLOW >> GENERATION >> LIST >> MASS FRACTION >> MOMENT >> PRESSURE >> PRODUCTION >> RESTART TIME >> SATURATION >> SECONDARY >> TEMPERATURE >> TIME (o) >> TOTAL MASS >> USER (o) >> VOLUME Description: This is the first-level command for specifying the observations available for use in parameter estimation. It can also be used to specify the points in space and time at which output is requested for sensitivity analysis, uncertainty propagation analysis, or plotting. The observations are a subset of all TOUGH2 output variables. Only those variables should be specified for which data are available. Besides the observations listed above, the user can specify additional data types by means of command >> USER. The second-level command >> TIME is used to select calibration points in time. The ob- servation type is specified by the second-level command, the points in space are identified by the third-level command, and further specifications as well as the data themselves are given through fourth-level commands. The generic structure of a observation block is as follows: > OBSERVATION >> specify calibration points in TIME >> specify observation type >>> specify location >>>> provide details >>>> provide data <<<< <<< << Example: (see examples on second command level) See Also: - @@@ Syntax: >> OPTION Parent Command: > COMPUTATION Subcommand: >>> ANDREW >>> ANNEAL >>> CAUCHY >>> DIRECT >>> FORWARD >>> GAUSS-NEWTON >>> GRID SEARCH >>> L1-ESTIMATOR >>> LEAST-SQUARE >>> LEVENBERG-MARQUARDT >>> LIST >>> OBJECTIVE >>> QUADRATIC-LINEAR >>> SELECT >>> SENSITIVITY >>> SIMPLEX >>> STEADY-STATE Description: This is the parent command of a number of subcommands for selecting iTOUGH2 program options. By default, iTOUGH2 performs automatic model calibration using the weighted least-squares objective function and the Levenberg-Marquardt minimization algorithm. Example: (see examples on third command level) See Also: - @@@ Syntax: >> OUTPUT Parent Command: > COMPUTATION Subcommand: >>> BENCHMARK >>> CHARACTERISTIC >>> COVARIANCE >>> FORMAT >>> INDEX >>> LIST >>> JACOBIAN >>> NEW OUTPUT >>> OBJECTIVE >>> PERFORMANCE >>> PLOTFILE >>> PLOTTING >>> SENSITIVITY >>> time_unit >>> UPDATE >>> RESIDUAL >>> VERSION Description: This command specifies the format and amount of printout generated. The iTOUGH2 output file contains the results usually needed for subsequent interpretation. Additional information can be requested which may be useful for debugging. Example: > COMPUTATION >> OUTPUT >>> Generate plot files in : TECPLOT FORMAT >>> plot CHARACTERISTIC curves >>> print OBJECTIVE function after each TOUGH2 run >>> print RESIDUALS after each iTOUGH2 iteration >>> print the iTOUGH2 command INDEX >>> print VERSION control statements >>> print with UPDATE information. <<< << See Also: - @@@ Syntax: >> PARALLEL PLATE Parent Command: > PARAMETER Subcommand: >>> MATERIAL Description: This command selects as a parameter the aperture of a parallel plate fracture model. The single fracture must be modeled as a 1D- or 2D model of thickness 1 meter, i.e., aperture must be identical to porosity. Furthermore, the capillary pressure model must contain a parameter CP(2,NMAT) which represents the gas entry pressure (e.g., Brooks-Corey (ICP=10), van Genuchten (ICP=11)). The parallel plate model relates porosity phi, permeability k [m2], and gas entry pressure pe [Pa] to aperture a [m] as follows: phi = a k = a**3/12 pe = 0.14366/a Note that using this option overwrites the porosity, absolute permeability and parameter CP(2,NMAT) given in the TOUGH2 input file. Note that the parallel plate model is not consistently applied. Using a relative permeability and capillary pressure function presumes some surface roughness or aperture distribution within the fracture plane. Example: > PARAMETER >> aperture in PARALLEL PLATE fracture model >>> ROCK type : FRACT >>>> LOGARITHM >>>> PRIOR information : -4.0 (100 micron) >>>> standard DEVIATION: 1.0 >>>> RANGE : -5.0 -3.0 <<<< <<< << See Also: - @@@ Syntax: > PARAMETER Parent Command: - Subcommands: >> ABSOLUTE PERMEABILITY >> BOTTOMHOLE PRESSURE >> CAPACITY >> CAPILLARY PRESSURE FUNCTION >> COMPRESSIBILITY >> CONDUCTIVITY >> DRIFT >> ENTHALPY >> FORCHHEIMER >> GUESS >> IFS >> INITIAL >> KLINKENBERG >> LAG >> LIST >> MINC >> PARALLEL PLATE >> POROSITY >> PRODUCTIVITY INDEX >> PUMPING RATIO >> RATE >> RELATIVE PERMEABILITY FUNCTION >> SCALE >> SELEC >> SHIFT >> SKIN >> TIME (p) >> USER (p) Description: This is the first-level command used to specify the parameters to be estimated. The parameters to be estimated are a subset of all TOUGH2 input parameters defined in the TOUGH2 input file. Only those parameters should be specified that are unknown or uncertain; they will be subjected to the estimation process or uncertainty propagation analysis. Select only those parameters that are sensitive enough yo influence the state variables for which observations are available (see also >>> SELECT). Besides the parameters listed above, the user can specify additional parameters by means of command >> USER. The parameter type is specified by the second-level command, the domain it refers to is identified by the third-level command, and further specifications must be provided through a number of fourth-level commands. The generic structure of a parameter block is as follows: > PARAMETER >> specify parameter type >>> specify parameter domain >>>> provide details <<<< <<< << Example: (see examples for second-level commands) See Also: > OBSERVATION, > COMPUTATION @@@ Syntax: >>>> PARAMETER: index (index_i...) Parent Command: all third-level commands in block > PARAMETER and > OBSERVATION Subcommand: - Description: (synonym for command >>>> INDEX) Example: (see command >>>> INDEX) See Also: >>>> INDEX @@@ Syntax: >>> PERFORMANCE Parent Command: >> OUTPUT Subcommand: - Description: This command performs a very rough benchmark analysis of computer performance and prints the relative CPU time requirement as compared to a reference workstation. Example: > COMPUTATION >> OUTPUT >>> perform PERFORMANCE comparison <<< << See Also: - @@@ Syntax: >>> PERTURB: (-)alpha (%) Parent Command: >> JACOBIAN Subcommand: - Description: This command specifies the perturbation factor alpha for numerical computation of the Jacobian matrix. The columns of the Jacobian matrix are calculated by perturbing the corresponding parameter p by a small amount dp, and taking either a forward or centered finite difference quotient. The perturbation is usually a fraction of the parameter value itself, independent of parameter value: dp = alpha * p The default value for alpha is 1 %, which can be changed globally for all parameters using the third-level command >>> PERTURB, or individually for each parameter using the fourth- level command >>>> PERTURB. A negative value can be provided to specify a constant perturbation: dp = |-alpha| This option is sometimes required for parameters having either very small or very large values (such as initial pressure, generation times, or residual gas saturation). Example: > COMPUTATION >> JACOBIAN >>> PERTURBation factor alpha : 0.005 of parameter value <<< << See Also: >>> FORWARD, >>> CENTERED, >>>> PERTURB @@@ Syntax: >>>> PERTURB: (-)alpha (%) Parent Command: all third-level commands in block > PARAMETER Subcommand: - Description: This command specifies the perturbation factor alpha for numerical computation of the Jacobian matrix. The columns of the Jacobian matrix are calculated by perturbing the corresponding parameter p by a small amount dp, and taking either a forward or centered finite difference quotient. The perturbation is usually a fraction of the parameter value itself: dp = alpha * p The default value for alpha is 1 %, which can be changed globally for all parameters using the third-level command >>> PERTURB, or individually for each parameter using the fourth- level command >>>> PERTURB. A negative value can be provided to specify a constant perturbation, independent of parameter value: dp = |-alpha| This option is sometimes required for parameters having either very small or very large values (such as initial pressure, generation times, or residual gas saturation). Example: > PARAMETER >> TIME at which production rate changes >>> SOURCE: WEL_3 >>>> INDEX of array F1 : 5 >>>> initial GUESS : 1.7E8 seconds >>>> PERTURB by constantly : -3.6E3 seconds <<<< <<< << > COMPUTATION >> JACOBIAN >>> all other parameters are PERTURBed by : 2 % of their values <<< << See Also: >>> PERTURB @@@ Syntax: >>>> PHASE phase_name/: iphase Parent Command: >>> ELEMENT >>> SOURCE (o) Subcommand: - Description: This command identifies a phase either by its name (phase_name) or the phase number (iphase). A list of allowable phase names for the given EOS module can be obtained from the header of the iTOUGH2 output file. Example: > OBSERVATION >> CONCENTRATION >>> ELEMENT: ZZZ99 >>>> ANNOTATION: TCE concentration >>>> COMPONENT No.: 3 >>>> dissolved in LIQUID PHASE >>>> DATA on FILE: tce.dat >>>> standard DEVIATION: 1.0E-6 <<<< <<< << See Also: >>>> COMPONENT @@@ Syntax: >>>> PICK: npick Parent Command: all third-level commands in block > OBSERVATION Subcommand: - Description: This command identifies the number of data points being skipped when reading from a long data file. Only every npick data point is read. The default is npick=1, i.e., every data point is accepted. Example: > OBSERVATION >> TEMPERATURE >>> ELEMENTS: ELM_10 + 4 >>>> SKIP: 3 lines before reading data >>>> PICK only every : 10 data point >>>> DATA on file: temp.log >>>> standard DEVIATION: 0.5 degrees C <<<< <<< << See Also: >>>> COLUMN, >>>> DATA, >>>> FORMAT, >>>> SET (o), >>>> SKIP @@@ Syntax: >>> PLOTFILE: format (LIST) Parent Command: >> OUTPUT Subcommand: - Description: (synonym for command >>> FORMAT (o)) Example: (see command >>> FORMAT (o)) See Also: >>> FORMAT (o) @@@ Syntax: >>> PLOTTING: niter Parent Command: >> OUTPUT Subcommand: - Description: By default, the plot file contains the observed data (interpolated at the calibration points), as well as the system response calculated with the initial and final parameter set. Additional intermediate curves can be requested for visualizing the optimization process. Curves are generated for every multiple of niter iTOUGH2 iterations. Example: > COMPUTATION >> OUTPUT >>> PLOTTING: 1 (plots the calculated system response after each iTOUGH2 iteration) <<< << See Also: - @@@ Syntax: >>>> POLYNOM: idegree (time_unit) Parent Command: all third-level commands in block > OBSERVATION Subcommand: - Description: Represents observed data by a polynomial of degree idegree: i z(t)=Sum(A * t ) i=0,...,idegree i where t denotes time in time_units (default is seconds), and A are the idegree+1 coefficients i which are read in free format on the lines following the command line. Example: > OBSERVATION >> LIQUID FLOW >>> CONNECTION: A1__1 A1__2 >>>> TIME SHIFT: 5 MINUTES >>>> conversion FACTOR: 1.6667E-02 [kg/min] - [kg/sec] >>>> POLYNOM of degree: 1 (linear function), time in MINUTES 2.34 -0.03 A0 A1 = coefficients of linear regression through data given in [min] and [kg/min] >>>> standard DEVIATION: 0.01 kg/min <<<< <<< << See Also: >>>> DATA, >>>> USER @@@ Syntax: >> POROSITY Parent Command: > PARAMETER Subcommand: >>> MATERIAL Description: This command selects as a parameter porosity (TOUGH2 variable POR(NMAT)). This parameter refers to a rock type. Note that the porosity specified in TOUGH2 block ROCKS (variable POR(NMAT)) may be overwritten by non-zero values given in block INCON (variable PORX). However, porosity values are not overwritten if the element belongs to a rock type for which porosity is a parameter to be estimated, unless a negative value for PORX is provided. Example: > PARAMETER >> POROSITY >>> ROCK type : CLAY1 >>>> VALUE >>>> PRIOR information : 0.28 >>>> standard DEVIATION: 0.05 >>>> RANGE : 0.10 0.50 >>>> PERTURB : -0.01 <<<< <<< << See Also: - @@@ Syntax: >>> POSTERIORI Parent Command: >> ERROR Subcommand: - Description: The estimated error variance s02 represents the variance of the mean weighted residual and is thus a measure of goodness-of-fit: T -1 r C r 2 zz s = -------- 0 m - n The a posteriori error variance so2 or a priori error variance sigma02 is used in the subsequent error analysis. For example, the covariance matrix of the estimated parameters, C , pp is directly proportional to the scalar s02 or sigma02, respectively. Note that if the residuals are consistent with the distributional assumption about the measurement errors (i.e., matrix C ), zz then the estimated error variance assumes a value close to one. The user must decide whether the error analysis should be based on the a posteriori or a priori error variance. The decision can also be delegated to the Fisher Model Test (see command >>> FISHER). iTOUGH2 uses the a posteriori error variance s02 by default. Example: > COMPUTATION >> ERROR analysis >>> based on A POSTERIORI error variance <<< See Also: >>> FISHER, >>> PRIORI @@@ Syntax: >> PRESSURE (CAPILLARY) (phase_name/PHASE: iphase) Parent Command: > OBSERVATION Subcommand: >>> ELEMENT Description: This command selects as an observation type the phase pressure or capillary pressure. This observation type refers to one or more elements. The phase name phase_name or phase number iphase, which depend on the EOS module being used, are listed in the header of the iTOUGH2 output file. They can be specified either on the command line or using subcommand >>>> PHASE. If no phase is specified, iTOUGH2 takes the pressure of the first phase which is usually the reference pressure. The pressure of a phase is calculated as the sum of the reference pressure and the corresponding capillary pressure. In a two-phase system, there is only one capillary pressure. The capillary pressure can be selected using keyword CAPILLARY. In a three-phase system (e.g., gas, NAPL, aqueous phase), there are two capillary pressures, i.e., the capillary pressure between the NAPL and the gas phase, and between the aqueous and the gas phase, which is the reference phase. The name of the wetting phase must be provided to identify the particular capillary pressure in the three-phase system. Example: > OBSERVATION >> PRESSURE >>> ELEMENT: AA__1 + 56 >>>> ANNOTATION : Mean gas pressure >>>> take AVERAGE of pressures in all 57 elements >>>> DATA on FILE : pres.dat >>>> VARIANCE : 1E6 [Pa^2] <<<< <<< >> NAPL CAPILLARY PRESSURE >>> ELEMENT: BB__1 >>>> take LOGARITHM of >>>> ABSOLUTE Pco >>>> DATA on FILE : Pco.dat >>>> DEVIATION : 1.0 log-cycle <<<< <<< See Also: >> DRAWDOWN @@@ Syntax: >>>> PRIOR: prior_info Parent Command: all third-level commands in block > PARAMETER Subcommand: - Description: This command provides the prior information of the parameter to be estimated. If command >>>> PRIOR is omitted, the value from the TOUGH2 input file is taken. Prior information is only effective if a standard deviation is provided (see command >>>> DEVIATION (p)), in which case the difference between the parameter estimate and its prior value is penalized in the objective function. The starting point for the optimization is given through commands >> GUESS and >>>> GUESS. If command >>>> LOGARITHM is present, the prior information is the logarithm of the parameter. Similarly, if command >>>> FACTOR is present, the prior information should be a multiplication factor (default is 1.0). Example: > PARAMETER >> ABSOLUTE permeability >>> ROCK type : SAND1 >>>> LOGARITHM >>>> PRIOR information : -12.0 >>>> standard DEVIATION: 1.0 order of magnitude <<<< >>> ROCK types: CLAY1 CLAY2 CLAY3 BOUND >>>> FACTOR >>>> initial GUESS : 1.0 >>>> is not WEIGHTed : 0.0 (default) <<<< <<< >> GUESS, i.e., starting point for optimization 1 -13.0 << See Also: >> GUESS, >>>> GUESS, >>>> DEVIATION, >>>> VARIATION @@@ Syntax: >>> PRIORI Parent Command: >> ERROR Subcommand: - Description: The estimated error variance s02 represents the variance of the mean weighted residual and is thus a measure of goodness-of-fit: T -1 r C r 2 zz s = -------- 0 m - n The a posteriori error variance so2 or a priori error variance sigma02 is used in the subsequent error analysis. For example, the covariance matrix of the estimated parameters, C , pp is directly proportional to the scalar s02 or sigma02, respectively. Note that if the residuals are consistent with the distributional assumption about the measurement errors (i.e., matrix C ), zz then the estimated error variance S02 assumes a value close to one. The user must decide whether the error analysis should be based on the a posteriori or a priori error variance. The decision can also be delegated to the Fisher Model Test (see command >>> FISHER). iTOUGH2 uses the a posteriori error variance s02 by default. However, for design calculations or synthetic inversions, the error analysis should be based on the a priori variance sigma02 which is 1 by definition. Example: > COMPUTATION >> ERROR >>> based on A PRIORI error variance <<< See Also: >>> FISHER, >>> POSTERIORI @@@ Syntax: >> PRODUCTION (phase_name/PHASE: iphase) Parent Command: > OBSERVATION Subcommand: >>> SINK Description: (synonym for command >> GENERATION) Example: (see command >> GENERATION) See Also: >> GENERATION @@@ Syntax: >> PRODUCTIVITY INDEX Parent Command: > PARAMETER Subcommand: >>> SOURCE Description: This command selects the productivity index for wells on deliverability (TOUGH2 variable GX) as a parameter to be estimated. This parameter refers to a sink/source code name. The generation type must be DELV. Example: > PARAMETER >> PRODUCTIVITY INDEX >>> SINK: WEL_1 <<<< <<< << See Also: - @@@ Syntax: >> PUMPING RATIO Parent Command: > PARAMETER Subcommand: >>> SOURCE Description: This command selects as a parameter the pumping ratios of wells belonging to the same well group. This option can be used to determine the distribution of generation rates among a group of wells, e.g., to determine the optimum pumping strategy for a cleanup operation. For example, the total extraction rate from a system of wells is often limited by the treatment capacity. However, extraction rates of individual wells can be adjusted, optimizing the efficiency of the cleanup operation. A well group consists of all sinks/sources with the same code name (TOUGH2 variable SL). The sum of the constant generation rates (TOUGH2 variable GX) of all wells within the same well group remains constant, but individual rates are adjusted. It is imperative to estimate as many pumping ratios as the number n of wells within the well group of interest. After optimization, the actual generation rate for well i is calculated from the prescribed total pumping rate q and the estimated pumping ratio a : tot i a i q = q ------- j=1,...,n i tot Sum(a ) j Example: > PARAMETER >> PUMPING RATIO >>> SOURCE: EXT_1 >>>> GUESS : 0.25 <<<< >>> SOURCE: EXT_2 >>>> GUESS : 0.5 <<<< >>> SOURCE: EXT_3 >>>> GUESS : 0.25 <<<< <<< << See Also: - @@@ Syntax: >>> QUADRATIC-LINEAR: c Parent Command: >> OPTION Subcommand: - Description: This command selects a quadratic-linear objective function. Given this estimator, the objective function to be minimized is a combination of least-squares for small residuals and the first norm for residuals larger than c-times the prior standard deviation: S = Sum(g(y )) i=1,...,m i where | 2 | y |y | < c | i i g(y ) = | i | | c(2|y | - c) |y | > c | i i with y = r /sigma i i i This objective function does not correspond to a standard probability density function. It has the general characteristic that the weight given individual residuals first increases quadratically with deviation, then only linearly to reduce the impact of outliers. For c --> infinity, the estimator is identical to least-squares; for c --> 0, it approaches the L1-estimator. Note that this objective function is minimized using the standard Levenberg-Marquardt algorithm which is designed for a quadratic objective function. Since the function is quadratic for y < c, the Levenberg-Marquardt algorithm is usually quite efficient. Example: > COMPUTATION >> OPTION >>> use a QUADRATIC-LINEAR robust estimator with a constant c : 1.0 <<< << See Also: >>> ANDREW, >>> CAUCHY, >>> L1-ESTIMATOR, >>> LEAST-SQUARES @@@ Syntax: >>>> RANGE: lower upper or >>>> BOUND: lower upper Parent Command: all third-level commands in block > PARAMETER Subcommand: - Description: This command sets the admissible parameter range. It provides lower and upper bounds of the parameter. During the optimization process, iTOUGH2 may suggest parameter values that are physically not valid (e.g. negative porosity) or not reasonable (e.g. very high permeability). Limiting the admissible range for the values a parameter can assume prevents the simulation from stopping due to an unphysical or unreasonable parameter value. However, it is strongly suggested not to specify a narrow parameter range about the initial guess. The range should reflect physical bounds, and the expected variation of the parameter. If prior knowledge suggests that a certain parameter varies only slightly about the initial guess, this information should enter the inversion as a standard deviation associated with the initial guess, i.e., prior information (see command >>>> DEVIATION (p)). A parameter tends to greatly vary, potentially hitting its lower or upper bound, if (i) a systematic error is present, (ii) the initial guess is far away from the best estimate, (iii) the parameter is not sensitive, or (iv) the parameter is highly correlated to more sensitive parameters. The final parameter set should not contain parameters at their lower or upper bounds. If some of the estimated parameters are at the bounds, it is suggested to carefully examine the four potential reasons mentioned above. A new inversion should be performed after corrective actions have been taken. Example: > PARAMETER >> POROSITY >>> MATERIAL: SANDY >>>> PRIOR information : 0.34 >>>> standard DEVIATION: 0.05 >>>> admissible RANGE : 0.01 0.99 <<<< <<< << See Also: >>>> DEVIATION (p), >>>> STEP @@@ Syntax: >> RATE Parent Command: > PARAMETER Subcommand: >>> SOURCE Description: This command selects as a parameter the constant generation rate (TOUGH2 variable GX) or time-dependent generation rate (TOUGH2 variable F2(L) for LTAB > 1). This parameter refers to a sink/source code name. Estimating a time-dependent generation rate requires providing index L through command >>>> INDEX. Example: > PARAMETER >> RATE >>> SOURCE: WEL_1 + 5 >>>> ANNOTATION: const. rate >>>> LOGARITHM <<<< >>> SOURCE: INJ_1 >>>> ANNOTATION: variable rate >>>> VALUE >>>> INDEX : 7 <<<< <<< << See Also: >> TIME (p) @@@ Syntax: >>> REDUCTION: max_red Parent Command: >> CONVERGE Subcommand: - Description: By default, a TOUGH2 simulation stops if 20 consecutive time step reductions have occurred without convergence. This command changes the maximum number of allowable time step reductions to max_red. Time step reductions occur if: (1) the initial time step is too large (see TOUGH2 variable DELTEN or DLT(1), and command >>> ADJUST), (2) TOUGH2 parameter NOITE is too small, (3) a failure in the EOS module occurs , (4) boundary conditions are changed drastically during the course of the simulation. Variable max_red should only be increased to address problem (4), i.e., when drastic changes in generation rates (TOUGH2 block GENER) are imposed, or if Dirichlet boundary conditions are changed using command >> RESTART TIME or through subroutine USERBC. Example: > COMPUTATION >> CONVERGE >>> accept : 30 CONSECUTIVE time step reductions <<< << See Also: >> RESTART TIME, >>> ADJUST, >>> CONSECUTIVE @@@ Syntax: >> RELATIVE Parent Command: > PARAMETER Subcommand: >>> DEFAULT >>> MATERIAL Description: This command selects a parameter of the relative permeability function (TOUGH2 variable RP(IPAR,NMAT)) of a certain rock type, or a parameter of the default relative permeability function (TOUGH2 variable RPD(IPAR)). Command >>>> INDEX must be used to select the parameter index IPAR. The physical meaning of the parameter depends on the type of relative permeability function selected in the TOUGH2 input file, variable IRP or IRPD. The admissible range should be specified explicitly to comply with parameter restrictions (see Pruess [1987], Appendix A). Example: > PARAMETER >> parameter of RELATIVE permeability function >>> DEFAULT >>>> ANNOTATION : Resid. Gas Sat. >>>> PARAMETER no. : 2 >>>> VALUE >>>> RANGE : 0.01 0.99 <<<< >>> MATERIAL: ZONE1 +3 >>>> ANNOTATION : IRP=7, RP(1)=m >>>> PARAMETER no. : 1 >>>> FACTOR <<<< <<< << See Also: >> CAPILLARY @@@ Syntax: >>>> RELATIVE: rel_err (%) Parent Command: all third-level commands in block > OBSERVATION Subcommand: - Description: This command takes a fraction of the observed value as the standard deviation of the measurement error (for more details see command >>>> DEVIATION (o)). This option cannot be applied to data sets that contain zero measurements. Example: > OBSERVATION >> LIQUID FLOW RATE >>> CONNECTION INJ_1 DOM_2 >>>> DATA on FILE: flow.dat >>>> RELATIVE measurement error of : 5 % is assumed <<<< <<< << See Also: >>>> DEVIATION (o) @@@ Syntax: >>> RESIDUAL Parent Command: >> OUTPUT Subcommand: - Description: This command prints the observed and calculated system response as well as the residuals after each iTOUGH2 iteration. By default, the residuals are printed only once at the end of the optimization. Example: > COMPUTATION >> OUTPUT >>> print RESIDUALs after each TOUGH2 simulation. <<< << See Also: >>> JACOBIAN @@@ Syntax: >> RESTART TIME: ntime (time_unit) (NEW) Parent Command: > OBSERVATION Subcommand: - Description: This command selects points in time at which the boundary conditions are changed by a step function, and reassigns primary variables and/or grid block volumes for selected elements. Such times are termed "restart times" because in standard TOUGH2 one would have to stop the simulation, and restart it after having changed the initial conditions of certain elements. This option is useful for modeling well tests, where the condition in the borehole is changed at certain points in time. For the simultaneous calibration of well tests consisting of many test events, it is imperative to model the entire sequence in a single simulation run, i.e. individual events must be connected. Recall, that complicated, time-varying boundary conditions can also be programmed into subroutine USERBC. The specification of a restart time is identical to specifying calibration points (see command >> TIME (o)). Instead of calibration times, a restart time is indicated. Following the line containing the restart time, a list of element names elem (or element numbers) can be given, followed by an integer ipv indicating which primary variable is to be changed. If ipv is zero, the volume of the corresponding element is changed. Finally, the new primary variable or grid block volume, respectively, is given. The general format is as follows: >> RESTART TIME: 1 (time_unit) restart_time elem ipv pv elem ipv pv .... ... .. A comprehensive example is given below. This option can also be used to periodically generate a SAVE file. This may be desirable for very long TOUGH2 simulations. In case of a computer failure, the run can be restarted at the time of the last restart time. If keyword NEW is present, a new SAVE file with unique file name is created for each restart time. Example: This example demonstrates the use of restart times to connect four individual test events into a single simulation. The test sequence starts with a shut-in recovery period, i.e., in the TOUGH2 input file the actual interval volume is assigned to the element representing the borehole. At time tCP, a constant pressure pumping test is initiated, i.e. the element volume is increased to a very large number, and the prescribed interval pressure is specified as initial conditions. A shut-in pressure recovery period starts at time tREC, modeled by reassigning the actual interval volume. Finally, a pulse test is simulated, assuming that all the gas that potentially accumulates in the borehole interval has been released at time tPULSE, prior to applying a short pressure pulse. The pressure response in the injection well is schematically shown in the figure below, followed by the appropriate iTOUGH2 block with restart times and boundary condition specifications. > OBSERVATION >> RESTART TIME: 1 [HOURS] 2.56 (tCP) BOR_1 0 1.0E+50 (large volume for const. pressure b.c.) BOR_1 1 1.3E+05 (set constant interval pressure) >> RESTART TIME: 1 [HOURS] 3.51 (tREC) BOR_1 0 0.73 (actual volume for shut-in recovery) >> RESTART TIME: 1 [HOURS] 5.44 (tPULSE) BOR_1 2 0.00 (prescribe single-phase liquid cond.) BOR_1 1 4.85E+05 (pressure pulse) | | | element ipv pv/vol TOUGH2 stops at each restart time, writes a SAVE file, reads it as an INCON file, changes initial conditions, i.e. updates the primary variables or grid block volumes of the indicated elements, and continues the simulation. See Also: >> TIME (o) @@@ Syntax: >>> ROCKS: mat_name (mat_name_i ...) (+ iplus) Parent Command: all second-level commands in block > PARAMETER referring to a material name Subcommand: (synonym for command >>> MATERIAL) Description: (see command >>> MATERIAL) Example: - See Also: >>> MATERIAL @@@ Syntax: >> SATURATION (phase_name/PHASE: iphase) Parent Command: > OBSERVATION Subcommand: >>> ELEMENT Description: This command selects phase saturation as an observation type. This observation type refers to an element. The phase name phase_name or phase number iphase, which depend on the EOS module being used, are listed in the iTOUGH2 header. They can be specified either on the command line or using the subcommand >>>> PHASE. Example: > OBSERVATION >> GAS SATURATION >>> calculated for ELEMENT: AA__5 >>>> ANNOTATION: Sg during gas injection >>>> DATA [HOURS] 0.1 0.01 0.3 0.13 0.5 0.34 0.8 0.59 1.2 0.72 1.5 0.81 2.0 0.86 2.5 0.89 5.0 0.91 >>>> DEVIATION: 0.05 <<<< <<< >> SATURATION >>> ELEMENT: BB__5 >>>> NAPL PHASE saturation >>>> NO DATA available (i.e. just for plotting) >>>> WEIGHT: 1.0E-20 (don't weigh, just plot) <<<< <<< << See Also: - @@@ Syntax: >> SCALE Parent Command: > PARAMETER Subcommand: >>> NONE Description: This command selects as a parameter a grid scaling factor. Nodal distances, interface areas, and gridblock volumes will be scaled accordingly. There are three grid scaling factors, referring to the three directions specifed by TOUGH2 variable ISOT. The direction is selected through command >>>> INDEX. If all three directions are selected, the mesh is scaled isotropically (see TOUGH2 variable SCALE). Selecting a grid scaling factor as a parameter can be used to design and optimize the horizontal and/or vertical spacing between injection points. Example: > PARAMETER >> grid SCALEing factor >>> NONE >>>> ANNOTATION: horizontal well spacing >>>> INDEX : 1 2 >>>> GUESS : 1.0 <<<< <<< << See Also: - @@@ Syntax: >>>> SCHEDULE: beta Parent Command: >>> ANNEAL Subcommand: - Description: This command defines the annealing schedule for Simulated Annealing minimization. The annealing schedule is a function describing the temperature reduction (and thus the probability of accepting an uphill step, see command >>> ANNEAL). The temperature is updated after a certain number of successful steps have been performed (see command >>>> STEP (a)). There are two functions available. If beta is in the range 0 < beta < 1 (typically 0.9), the following annealing schedule is used: k tau = beta * tau k 0 where k is the iteration index, and tau is the initial temperature specified by command >>>> TEMPERATURE. 0 If beta is greater than one, the following annealing schedule is invoked: beta tau = tau (1 - k/K) k 0 where K is the maximum number of iterations (see command >>>> ITERATION (a)). Example: > COMPUTATION >> OPTION >>> Simulated ANNEALing >>>> total number of ITERATIONS: 200 >>>> initial TEMPERATURE: -0.05 >>>> update after: 100 STEPS >>>> annealing SCHEDULE: 0.95 <<<< <<< << See Also: >>>> ITERATION (a), >>>> STEP, >>>> TEMPERATURE @@@ Syntax: >> SECONDARY (phase_name/PHASE: iphase) (: ipar) Parent Command: > OBSERVATION Subcommand: >>> ELEMENT Description: This command selects thermophysical properties, which are so-called "secondary parameters" in TOUGH2, as an observation type. This observation type refers to an element. The secondary parameter refers to elements of TOUGH2 vector PAR (see Pruess [1991], Figure 2). The index ipar must be provided in the command line after a colon or through the fourth-level command >>>> INDEX. The fluid phase must also be identified. The phase name phase_name or phase number iphase, which depend on the EOS module being used, are listed in the iTOUGH2 header. They can be specified either on the command line or using the fourth-level command >>>> PHASE. The following table lists the thermophysical property addressed by ipar. Some of the properties can be selected using an alternative second-level command. ------------------------------------------------------------- ipar Secondary Parameter Alternative Command ------------------------------------------------------------- 1 phase saturation SATURATION 2 relative permeability - 3 viscosity - 4 density - 5 specific enthalpy - 6 capillary pressure PRESSURE NB+i mass fraction of component i MASS FRACTION ------------------------------------------------------------- Example: > OBSERVATION >> SECONDARY parameter No: 3 >>> ELEMENT: AA__5 >>>> ANNOTATION: gas viscosity >>>> GAS PHASE >>>> NO DATA <<<< <<< See Also: >> MASS FRACTION, >> PRESSURE, >> SATURATION, >>>> PHASE, >>>> INDEX @@@ Syntax: >> SELEC Parent Command: > PARAMETER Subcommand: >>> MODEL Description: This command selects as a parameter one of the SELEC parameters (TOUGH2 variable FE(I)). The physical meaning of the parameter depends on the module being used. The index I must be provided through command >>>> INDEX. Example: > PARAMETER >> SELEC parameter >>> MODEL >>>> ANNOTATION: Gel Density (EOS11) >>>> INDEX : 2 >>>> VALUE <<<< <<< << See Also: - @@@ Syntax: >>> SELECT Parent Command: >> OPTION Subcommand: >>>> CORRELATION >>>> ITERATION >>>> LIST >>>> SENSITIVITY Description: This command invokes the automatic parameter selection option of iTOUGH2. The parameters defined in block > PARAMETER are screened according to two selection criteria (see commands >>>> SENSITIVITY and >>>> CORRELATION). Only the most sensitive and/or most independent parameters are subjected to the optimization process. The selection procedure is repeated every few iterations. Automatic parameter selection allows one to submit a larger set of parameters to the estimation process. If a parameter is not sensitive enough to be estimated from the available data, it is automatically removed from the set of parameters being updated. This makes the inversion faster because fewer parameters have to be perturbed for calculating the Jacobian matrix (the full Jacobian is only calculated every few iteration when the selection criteria are reevaluated). The inversion is also more robust. Parameters that are not sensitive or highly correlated tend to be changed drastically during an iTOUGH2 iteration which may cause unnecessary numerical difficulties. If they are (temporarily) removed from the parameter set, they remain at their initial current value. An additional advantage of using this option is the fact that sensitivities, estimation uncertainties, and parameter correlations are calculated for all the specified parameters, regardless of whether they are updated during the optimization. Due to the non-linearity of the inverse problem at hand, sensitivity coefficients and parameter correlations constantly change during the optimization. Therefore, the selection criteria must be reevaluated from time to time (see command >>>> ITERATION (s)), i.e., parameters may be deactivated and reactivated during the course of an inversion. Example: > COMPUTATION >> OPTION >>> automatic parameter SELECTion >>>> SENSITIVITY criterion: -0.1 >>>> repeat selection every : 3 rd ITERATION <<<< <<< See Also: - @@@ Syntax: >>> SENSITIVITY (There are two third-level commands >>> SENSITIVITY. Check paraent command.) Parent Command 1: >> OPTION Syntax: >>> SENSITIVITY or >>> DESIGN Subcommand: - Description: This command makes iTOUGH2 evaluate the sensitivity matrix without performing any optimization. By default, the scaled Jacobian matrix, i.e., the sensitivity coefficients scaled by the standard deviation of the observation and expected parameter variation, respectively, is printed to the iTOUGH2 output file: sigma dz sigma p i p _ j j J = J ------- = --- ------- ij ij sigma dp sigma z j z i i In addition, the unscaled sensitivity coefficients can be printed by invoking subcommand >>> SENSITIVITY in block >> OUTPUT. This information can be used to identify the parameters that most strongly affect the system behavior at actual or potential observation points. Similarly, the relative information content of actual or potential observations, i.e., the contribution of each data point to the solution of the inverse problem can be evaluated. Based on this command, iTOUGH2 also calculates the covariance matrix of the estimated parameters, i.e., the estimation uncertainty under the assumption that the variances of the residuals are accurately depicted by the prior covariance matrix Czz. This information along with the global sensitivity measures (sums of absolute sensitivity coefficients) can be used to optimize the design of an experiment. It is recommended to use a relatively large perturbation factor (see command >>> PERTURB), possibly in combination with centered finite difference quotients (see command >>> CENTERED) for the purpose of sensitivity analysis. Example: > COMPUTATION >> OPTION >>> perform a SENSITIVITY analysis for test DESIGN <<< << See Also: >>> CENTERED, >>> PERTURB, >>>> SENSITIVITY (o) @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ Parent Command 2: >> OUTPUT Syntax: >>> SENSITIVITY Subcommand: - Description: This command prints the sensitivity matrix to the iTOUGH2 output file. The elements of the sensitivity matrix are the partial derivatives of the system response at the observation points with respect to the parameters: dz i J = --- ij dp j By default, iTOUGH2 prints the scaled Jacobian matrix, the elements of which are the sensitivity coefficients scaled by the ratio of the standard deviation of the observation and expected parameter variation: sigma dz sigma p i p _ j j J = J ------- = --- ------- ij ij sigma dp sigma z j z i i Example: > COMPUTATION >> OUTPUT >>> print SENSITIVITY matrix in addition to the scaled Jacobian <<< << See Also: - @@@ Syntax: >>>> SENSITIVITY: (-)rsens Parent Command: >>> SELECT Subcommand: - Description This command defines one of the criteria used for automatic parameter selection. It examines the potential of a parameter to reduce the objective function based on the sensitivity coefficient: dD = |delta S| where (delta S) is the change of the objective function if the parameter is perturbed by a certain, small value (see command >>> PERTURB). The sensitivities are normalized to the maximum sensitivity: omega = dD / dDmax Those parameters with a omega-value larger than |rsens|, i.e., the most sensitive parameters, are selected. Parameters which are unlikely to significantly reduce the objective function are (temporarily) excluded from the optimization process. If a negative value is given for rsens, the selection criterion is relaxed with each iteration k, and reaches zero for the last iteration max_iter, i.e., all parameters specified in block > PARAMETER are selected for the final step. rsens = |rsens| (1 - k/max_iter) k Example: > COMPUTATION >> OPTION >>> SELECT parameter automatically every >>>> : 3 ITERATIONS >>>> based on the SENSITIVITY criterion with rsens : -0.10 <<<< <<< << See Also: >>>> ITERATION (s), >>>> CORRELATION @@@ Syntax: >>> SET: iset Parent Command: >> DRIFT >> FACTOR >> LAG >> SHIFT Subcommand: all fourth-level commands in block > PARAMETER Description: The parent command of this command identifies a parameter that refers to a data set, i.e., it manipulates the observed data. The data set is identified by its ordering number iset as specified in block > OBSERVATION. Alternatively, iset can be read using subcommand >>>> INDEX; the latter command must be used if multiple sets are selected. Example: > PARAMETER Estimate coefficients of regression dz=A+B*time to correct flowmeter data. The flowmeter data are provided as data set No. 2, 3, and 4 in the OBSERVATION block. All three data sets exhibit a constant offset to be estimated. Data set No. 3 also shows a drift. >> SHIFT >>> NONE (multiple sets will be selected) >>>> INDEX : 2 3 4 >>>> ANNOTATION: constant A (set 2, 3 and 4) >>>> GUESS : 4.0E-6 [kg/sec] <<<< <<< >> DRIFT >>> data SET No. : 3 >>>> ANNOTATION: coefficient B (set 3 only) >>>> GUESS : 1.0E-9 [kg/sec/sec] <<<< <<< << See Also: - @@@ Syntax: >>>> SET: iset Parent Command: all third-level commands in block > OBSERVATION Subcommand: - Description: Multiple data sets can be stored on a single file, separated by a single line containing characters. This command is used to select the iset'th data set on a data file. By default, data are read from the first set following the header lines (see command >>>> HEADER). Example: > OBSERVATION >> PRESSURE >>> ELEMENT: AAA99 >>>> ANNOTATION: Pres. well BBB >>>> conversion FACTOR: 1.0E5 >>>> skip: 3 HEADER lines, then >>>> select: 2 nd SET on >>>> COLUMNS: 2 3 >>>> DATA FILE: pres.dat [HOURS] >>>> RELATIVE error: 0.05 <<<< <<< The content of file pres.dat is: 1 This is file pres.dat Line Time Pressure 3 Data set 1: Pressure in borehole AAA 4 0.0 1.000 5 1.0 1.134 6 2.0 1.495 7 Data set 2: Pressure in borehole BBB 8 0.0 1.051 9 1.0 1.433 10 2.0 1.874 11 3.0 2.431 .. ... ..... See Also: >>>> HEADER @@@ Syntax: >> SHIFT Parent Command: > PARAMETER Subcommand: >>> NONE >>> SET Description: This command selects as a parameter a constant used to shift the calculated TOUGH2 output. The constant is added to the output that refers to a specific data set: z = z + shift TOUGH2 where shift is the constant added to the calculated TOUGH2 output z . The result z is TOUGH2 compared to the measurement z* of the corresponding data set. This option allows removal of a constant from the data. For example, if matching relative pressure data that fluctuate around an unknown mean, or if a flowmeter exhibits an unknown offset that needs to be estimated, the shift parameter being estimated is the mean or offset, respectively. A non-zero value must be provided as an initial guess through the iTOUGH2 input file using command >>>> GUESS. The data set is identified by number using command >>> SET (p) or command >>>> INDEX (p). If the constant is known, i.e. does not need to be estimated, use command >>>> SHIFT, a subcommand of > OBSERVATION, to shift the data. Example: > PARAMETER >> SHIFT >>> SET No. : 1 >>>> ANNOTATION: atmos. pres. >>>> GUESS: -1.0E5 [Pa] subtract atmospheric pressure <<<< >>> NONE >>>> ANNOTATION: offset >>>> INDEX : 2 3 4 (one constant for data sets 2, 3, and 4) >>>> GUESS : 4.0E-6 [kg/sec] <<<< <<< << See Also: >> DRIFT, >> FACTOR, >> LAG, >>> SET (p), >>>> SHIFT @@@ Syntax: >>>> SHIFT: shift (TIME (time_unit)) Parent Command: all third-level commands in block > OBSERVATION Subcommand: - Description: This command shifts data values or observation times by a known, constant value shift. The effect of this command is a direct data manipulation which must be distinguished from estimating an unknown constant that shifts the model output (see command >> SHIFT). If keyword TIME is present on the command line, the constant shift is added to all observation times of the corresponding data set. This is useful to adjust the reference time of the data record if it is different from the starting time of the simulation (TOUGH2 variable TSTART). The time unit can be selected using one of the time_unit keywords. If keyword TIME is not present, shift is added to all observed values. The units of shift must match those of the observed data (see command >>>> FACTOR). Example: > OBSERVATION >> PRESSURE >>> ELEMENT: GUG_0 >>>> ANNOTATION: rel. pres. >>>> conversion FACTOR: 1000.0 [kPa] - [Pa] >>>> SHIFT: -100.0 [kPa] subtract atmospheric pressure from data >>>> SHIFT TIMES as well by: -1.25 DAYS >>>> relative pressure DATA in [HOURS] and [kPa] follow: 30.0 101.314 30.5 101.789 31.0 102.113 .... ....... >>>> standard DEVIATION: 0.5 [kPa] <<<< <<< << See Also: >> SHIFT, >>>> FACTOR @@@ Syntax: >>> SIMPLEX Parent Command: >> OPTION Subcommand: - Description: This command selects the downhill simplex method to minimize the objective function. The downhill simplex method does not calculate derivatives and can therefore be used for discontinuous objective functions. The initial simplex is defined by the initial parameter set p0 and n additional points given by : p = p + sigma * e i=2,...,(n+1) i 0 i i where sigma is the parameter variation given by commands >>>> VARIATION or >>>> DEVIATION (p), and the e's are n unit vectors along the parameter axis. At the end of minimization by means of the simplex algorithm, the Jacobian matrix is evaluated to allow for a standard error analysis. The simplex algorithm is most useful in connection with the L1-estimator and discontinuous cost functions. Example: > COMPUTATION >> OPTION >>> use SIMPLEX algorithm to minimize objective function <<< << See Also: >>> ANNEAL, >>> GAUSS-NEWTON, >>> GRID SEARCH, >>> LEVENBERG-MARQUARDT @@@ Syntax: >>> SIMULATION: mtough2 Parent Command: >> CONVERGE Subcommand: - Description: This command limits the number of TOUGH2 simulations performed during an inversion. A rough estimate of the total number of TOUGH2 simulations during an inversion can be made given the number of iterations requested (see command >>> ITERATION) and the type of finite difference quotients calculated (see commands >>> FORWARD and >>> CENTERED). However, there is an unknown number of unsuccessful steps that cannot be accounted for. The maximum number of TOUGH2 simulations may also be limited in order to stop and examine a specific simulation that leads to convergence problems (see command >>> INCOMPLETE). If performing Monte Carlo simulations (see command >>> MONTE CARLO), mtough2 is the number of parameter sets generated and thus the number of realizations of the calculated system output. Example: > COMPUTATION >> STOP after >>> a total of : 500 TOUGH2 SIMULATIONS <<< >> ERROR analysis >>> MONTE CARLO <<< << See Also: >>> ITERATION, >>> MONTE CARLO, >>> INCOMPLETE @@@ Syntax: >>> SINK: sink_name (sink_name_i ...) (+ iplus) Parent Command: all second-level commands in block > PARAMETER or > OBSERVATION referring to sink names Subcommand: all fourth-level commands in block > PARAMETER or > OBSERVATION Description: (synonym for command >>> SOURCE) Example: (see command >>> SOURCE) See Also: >>> SOURCE @@@ Syntax: >> SKIN Parent Command: > PARAMETER Subcommand: >>> MATERIAL Description: This command selects as a parameter the skin zone radius around a well. In general, the radial thickness of the skin zone is predefined by the discretization of the flow region. In order to estimate the skin zone radius, the TOUGH2 mesh must be generated using the MESHMAKER utility. Furthermore, two zones must be generated using logarithmically increasing radial distances (option LOGAR). The skin radius is defined by the parameter RLOG after the first appearance of keyword LOGAR. In addition, an I5 integer must be provided after NRAD, NEQU, and NLOG, indicating the material type number for the corresponding grid blocks (see example below). Estimation of a skin zone radius may be unstable if changing the discretization significantly affects the modeling results. Example: The following MESHMAKER block is from a TOUGH2 input file. A radial mesh is generated with a borehole of radius 0.1 m (material type 1), a skin zone of material type 2 and initial radius of 0.3 m, partitioned into 20 grid blocks, and an outer zone of material type 3 which extends to a radial distance of 10.0 m. The thickness of the layer is 1.0 m. MESHMAKER RZ2D RADII 2 1 0.000E+00 0.100E+00 LOGAR 20 2 0.300E+00 0.100E-01 LOGAR 80 3 1.000E+01 LAYER 1 0.100E+01 The corresponding parameter block in the iTOUGH2 input file reads: > PARAMETER >> SKIN zone radius >>> MATERIAL: SKINZ (= material name 2 in block ROCKS) >>>> ANNOTATION: Skin radius >>>> VALUE >>>> initial guess: 0.3 >>>> RANGE : 0.12 1.00 <<<< <<< << See Also: - @@@ Syntax: >>>> SKIP: nskip Parent Command: all third-level commands in block > OBSERVATION Subcommand: - Description: (synonym for command >>>> HEADER) Example: (see command >>>> HEADER) See Also: >>>> HEADER @@@ Syntax: >>> SOURCE: source_name (source_name_i ...) (+ iplus) or >>> SINK: sink_name (sink_name_i ...) (+ iplus) Parent Command: all second-level commands in block > PARAMETER or > OBSERVATION referring to source names. Subcommand: all fourth-level commands in block > PARAMETER or > OBSERVATION, respectively Description: This command reads one or more sink/source code names (TOUGH2 variable SOURCE) or element names associated with a sink or source (TOUGH2 variable ELEG) as specified in the TOUGH2 block GENER. Both parameter and observations may refer to sources. Sources and source elements are designated by a three-character/two-integer (FORTRAN format: AAAII) code name. Blanks in the names as printed in the TOUGH2 output file must be replaced by underscores (e.g., a source or element name specified in the TOUGH2 input file as 'BÊ007' is printed as 'BÊ0Ê7' in the TOUGH2 output file. Therefore, it must be addressed in the iTOUGH2 input file as 'B_0_7'). Multiple names can be specified. A sequence of iplus elements can be generated by increasing the number of the last element. The following two command lines are identical: >>> SOURCE: WEL_1 WEL15 +3 >>> SOURCE: WEL_1 WEL15 WEL16 WEL17 WEL18 Example: > PARAMETER >> determine ENTHALPY of injected fluid... >>> SOURCE: WEL_1 >>>> LOGARITHM <<<< <<< << ... based on... > OBSERVATION >> ... the total VAPOR PRODUCTION in the extraction wells >>> SINK : EXT_1 + 3 >>>> DATA on FILE : steam.dat >>>> RELATIVE error: 10 % <<<< <<< See Also: - @@@ Syntax: >>> STEADY-STATE (SAVE) (: max_time_step) Parent Command: >> OPTION Subcommand: - Description: This command allows TOUGH2 to reach steady state prior to or after a transient simulation. This option can be used to calibrate against steady-state data (only or in combination with transient data), or to reach an equilibrium as initial conditions for a subsequent transient simulation. Note that a transient TOUGH2 simulation must be performed to reach steady state which is usually indicated by one of the following convergence failures: - too many time steps converged on a single Newton-Raphson iteration (see command >>> CONSECUTIVE); - convergence failure followed by two time steps converging on a single Newton- Raphson iteration; - too many time step reductions (see command >>> REDUCTION); - maximum number of time steps reached (TOUGH2 variable MCYC); - maximum simulation time reached (TOUGH2 variable TIMAX); - maximum time step size reached (use a colon on the command line followed by max_time_step to select a maximum time step size. The max_time_step must be smaller than TOUGH2 variable DELTMX.). iTOUGH2 usually stops if a TOUGH2 run terminates due to one of the above mentioned convergence failures (see command >>> INCOMPLETE). If command >>> STEADY-STATE is present, however, it accepts convergence failures and proceeds with the inversion. Inversions involving steady-state runs can be greatly accelerated by using keyword SAVE on the command line. After the first steady-state run has been completed, iTOUGH2 takes the steady-state conditions stored on file SAVE as the initial condition (file INCON) for the next TOUGH2 run, sets the initial time step to the (usually large) last time step of the previous simulation, and updates the parameters. Since the parameter set is changed only slightly between subsequent TOUGH2 runs, the new steady state is usually reached within a few additional time steps. This option should not be used if also calibrating against transient data preceding the steady-state data point. Assuming that calibration against steady-state data is to be performed, a steady-state calibration time tINF should be specified at a very late point in time (i.e., beyond the transient phase of the simulation), and the same time should be assigned to the observed steady-state data point in block >>>> DATA. (In addition to the steady-state point, one might also specify calibration points during the transient phase). The TOUGH2 simulation proceeds until a convergence failure occurs at an unknown point in time tCF. The primary variables at that point are written to file SAVE and reused as initial conditions for the subsequent TOUGH2 run (only if keyword SAVE is present). Then, the calculated system state at time tCF is compared to the steady-state data point at time tINF (make sure that tINF is always greater than tCF, e.g., set tINF=1.0E20). The second application of the steady-state option is the following. If a steady-state regime is to precede a transient regime within a single simulation (e.g., to assure initial conditions are at equilibrium, a state that depends on the parameters to be estimated), a negative starting time -tINF (TOUGH2 variable TSTART) must be specified. Ensure that |-tINF| is larger than the duration required to reach steady state, e.g., -tINF = -1.0E20. The TOUGH2 simulation proceeds until a convergence failure occurs at an unknown point in time tCF creating the steady-state regime. The primary variables at that point are written to file SAVE to be used as initial conditions for the subsequent TOUGH2 run (only if keyword SAVE is present). The simulation time is then set to zero, and the transient regime of the simulation is initiated. This requires that boundary conditions are changed at time zero, e.g., by starting injection or withdrawal, or by changing Dirichlet-type boundary conditions (see command >> RESTART TIME). (Note that if transient data are combined with steady-state data, the standard deviation of the steady-state data point may have to be decreased substantially to outweigh the large number of transient points.) Example: > OBSERVATION >> steady-state point in TIME: 1 (= t_inf) 1.0E20 >> PRESSURE >>> ELEMENT: FDF76 >>>> DATA 1.0E20 1.354E5 >>>> DEVIATION: 0.05E5 <<<< <<< << > COMPUTATION >> OPTION >>> allow STEADY-STATE, use SAVE file for restart <<< >> CONVERGEnce criteria >>> Presume steady-state if : 5 CONSECUTIVE time steps converge on ITER=1 >>> number of ITERATIONS: 5 <<< << < See Also: >> RESTART TIME, >>> CONSECUTIVE, >>> INCOMPLETE, >>> REDUCTION @@@ Syntax: >>> STEP: max_step (UNSCALED) Parent Command: >> CONVERGENCE Subcommand: - Description: This command defines the maximum allowable size of the scaled (x=p, default) or unscaled (x=1, keyword UNSCALED) update vector delta(p) per iTOUGH2 iteration. The step length of the scaled parameter update vector is defined as follows: 2 1/2 |delta(p)| = [Sum(dp /x ) ] i i This is a global step size limitation as opposed to the one specified for each individual parameter (see command >>>> STEP). Limiting the global step size may make the inversion more stable. Parameter max_step should be chosen large enough, so that the size of the proposed step size |delta(p')| is reduced to |delta(pmax)| only during the first few iterations. Example: > COMPUTATION >> CONVERGENCE >>> number of ITERATIONS : 10 (may need more iterations!) >>> limit scaled STEP size to: 1.0 [dimensionless] <<< << See Also: >>>> STEP @@@ Syntax: >>>> STEP (There are two fourth-level commands >>>> STEP. Check parent command.) Parent Command 1: all third-level commands in block > PARAMETER Syntax: >>>> STEP: max_step Subcommand: - Description: This command defines the maximum allowable step size, limiting the change in the corresponding parameter per iTOUGH2 iteration. Large steps are usually proposed for a parameter if (i) the initial guess is far away from the best estimate, (ii) the parameter has a low sensitivity, or (iii) the parameter is highly correlated to more sensitive parameters. If the system state is a strongly non-linear function of the parameter, even a moderate step size may make the inversion unstable. Parameter max_step should be chosen large enough, so that the proposed step size |deltpa(p')| is reduced to |delta(pmax)| only during the first few iterations. The figure below illustrates that limiting the step size also changes the direction of the step taken in the parameter space. A global step size limitation can also be specified (see command >>> STEP), maintaining the direction of vector delta(p). Example: > PARAMETER >> POROSITY >>> MATERIAL: SANDY >>>> standard DEVIATION: 0.10 >>>> max. STEP size : 0.05 <<<< <<< << See Also: >>> STEP, >>>> DEVIATION, >>>> RANGE @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ Parent Command 2: >>> ANNEAL Syntax: >>>> STEP: max_step Subcommand: - Description: This command defines an iteration for Simulated Annealing minimization based on the number of successful steps or total number of steps as defined by max_step. After each iteration is completed, the temperature is reduced according to the annealing schedule (see command >>>> SCHEDULE). An iteration is completed and the annealing temperature reduced if: (1) the total number of successful and unsuccessful steps reaches max_step, or (2) (0.2 * max_step) successful steps have been performed Example: > COMPUTATION >> OPTION >>> Simulated ANNEALing >>>> maximum number of ITERATIONS: 100 >>>> maximum number of STEPS per ITERATION: 50 >>>> annealing SCHEDULE: 0.9 >>>> initial TEMPERATURE: -0.02 <<<< <<< << See Also: >>>> SCHEDULE @@@ Syntax: >> STOP Parent Command: > COMPUTATION Subcommand: (see command >> CONVERGE) Description: (synonym for command >> CONVERGE) Example: (see command >> CONVERGE) See Also: >> CONVERGE @@@ Syntax: >>>> SUM Parent Command: all third-level commands in block > OBSERVATION Subcommand: - Description: If multiple elements or connections are provided to indicate the location of a measurement point, this command takes the sum of all calculated values as the model output to be compared to the data. The user must ensure that the summation of the quantity is meaningful. Example: > OBSERVATION >> LIQUID FLOW rate >>> CONNECTION: A1__1 A2__1 + 7 >>>> ANNOTATION: Liquid flow across boundary >>>> Take SUM of flow rates across 9 connections >>>> NO DATA <<<< <<< << See Also: >>>> AVERAGE @@@ Syntax: >>> TAU: (-)niter Parent Command: >> ERROR Subcommand: - Description: If multiple observation types (e.g., pressure, flow rate, prior information, etc.) are used to estimate model parameters, the relative weights assigned to each type is given by the ratio lambda = tau /tau ij i j where tau are scalars such that C = tau * V . Here, C is the covariance matrix of i i i i all observations of type i (a submatrix of covariance matrix C ), and V is a positive zz i symmetric matrix. By default, tau is fixed at 1. This command allows lambda to be updated in an iterative process, where tau is recalculated every multiple of niter iterations and is given by: i T -1 r C r i i i tau = --------- i m i If a negative number is provided for niter, prior information is excluded from the process. Recall that tau refers to all data of a certain observation type (i.e., not to individual data sets). i The process assigns weights such that the relative contribution of each observation type to the objective function tends to 1/omega, where omega is the number of observation types used in the inversion. It should also be realized that the Fisher model test becomes meaningless if lambda is updated during the inversion because the test will always be fulfilled by definition. While this option provides flexibility in reassigning relative weights to data of different types, it is instead suggested to carefully select the standard deviations of the observations and prior parameter estimates (see command >>>> DEVIATION (p/o)) based on potential measurement and modeling errors. Example: > COMPUTATION >> ERROR >>> update TAU every : -3 rd iteration <<< See Also: >>>> DEVIATION @@@ Syntax: >> TEMPERATURE Parent Command: > OBSERVATION Subcommand: >>> ELEMENT Description: This command selects temperature as an observation type. This observation type refers to an element. Example: > OBSERVATION >> TEMPERATURE >>> ELEMENT : TCP_1 deg(C)=(deg(F)-32)*0.55 >>>> SHIFT : -32.00 >>>> FACTOR : 0.55 >>>> temperature DATA in deg(F) on file: temp.dat >>>> DEVIATION: 0.2 degree Fahrenheit <<<< <<< << See Also: - @@@ Syntax: >>>> TEMPERATURE: (-)temp0 Parent Command: >>> ANNEAL Subcommand: - Description: This command defines the initial temperature tau0 for Simulated Annealing minimization. The initial temperature is reduced after each iteration k according to the annealing schedule (see command >>>> SCHEDULE). The temperature tau defines the probability P with which an uphill step delta(S) should be accepted: P = exp(-delta(S)/tau) The probability decreases with decreasing temperature. The initial temperature temp0 should be a reasonable fraction of the objective function S. If a positive value is given, then tau0 = temp0. If a negative value is provided, the initial temperature is internally calculated as a fraction of the initial objective function: tau0=|temp0| * S0 Example: > COMPUTATION >> OPTION >>> Simulated ANNEALing >>>> maximum number of ITERATIONS: 100 >>>> maximum number of STEPS per ITERATION: 50 >>>> annealing SCHEDULE: 0.95 >>>> initial TEMPERATURE: -0.01 times the initial obj. func. <<<< <<< << See Also: >>>> STEP (a), >>>> SCHEDULE @@@ Syntax: >> TIME (There are two second-level commands >> TIME. Check parent command.) Parent Command 1: > PARAMETER Syntax: >> TIME Subcommand: >>> SOURCE Description: This command selects as a parameter the time of a time-dependent generation rate (TOUGH2 variable F1(L) for LTAB>1). This parameter refers to a sink/source code name. Index L must be provided through command >>>> INDEX. Time stepping during simulation should be small compared to the expected variation of the parameter. Furthermore, it is suggested to prescribe the parameter perturbation for calculation of the Jacobian, i.e., use command >>>> PERTURB and specify a reasonably large time perturbation provided as a negative number. Example: > PARAMETER >> generation TIME >>> SOURCE: INJ_1 + 5 >>>> ANNOTATION: End of spill >>>> INDEX : 2 >>>> VALUE >>>> RANGE : 1E8 2E8 [sec] >>>> PERTURB : -1E5 [sec] >>>> max. STEP : 86400 [sec] <<<< <<< << See Also: >> ENTHALPY, >> RATE @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ Parent Command 2: > OBSERVATION Syntax: >> TIME: ntime (EQUAL/LOGARITHMIC) (time_unit) Subcommand: - Description: This command selects points in time during a TOUGH2 run at which the calculated system response is used for subsequent iTOUGH2 analysis. In the case of inverse modeling, these are the calibration times at which calculated and observed system responses are compared. Time stepping in the TOUGH2 simulation is forced to exactly match all specified calibration times, i.e., defining calibration times has the same effect on the simulation as specifying printout times in the TOUGH2 block TIMES (printout can be suppressed, however, by specifying a negative integer for TOUGH2 parameter KDATA). Thus, time stepping considerations must be taken into account when selecting the spacing of calibration points (see also command >>> CONSECUTIVE). Only one set of calibration times can be specified which is then applied to all data sets (see, however, command >>>> WINDOW). Calibration times do not have to match the times at which measurements are available since the value of the observed data at the calibration point will be linearly interpolated between adjacent data points. Calibration times can be specified in three ways: (i) explicitly listed, (ii) automatically generated with equal spacing, and (iii) automatically generated with logarithmic spacing. The corresponding input formats are given by example below. Admissible keywords for selecting the time units time_unit are SECOND, MINUTE, HOUR, DAY, WEEK and YEAR. >> (i) provide a list of : 10 TIMES in [MINUTES] on the following lines 1.0 2.0 5.0 10.0 15.0 20.0 30.0 45.0 60.0 120.0 180.0 360.0 In the example above, the first ntime=10 numbers will be read in free format and interpreted as calibration times in minutes. >> (ii) generate :10 points TIMES, EQUALLY spaced between tA and tB 60.0 600.0 tA tB 10 equally spaced points in time will be generated between 60.0 and 600.0 seconds. Time limits tA and tB are read in free format. >> (iii) generate :10 , LOGARITHMICALLY spaced points TIMES in [HOURS] 0.01 12.0 10 logarithmically spaced points in time will be generated between 36 seconds and 12 hours. The three formats can be used repeatedly, concurrently, and with overlapping time periods (see example below). All specified times will be sorted internally. Example: The following block generates a total of 11 calibration times. > OBSERVATION >> : 6 LOGARITHMICALLY spaced TIMES in SECONDS between 30.0 720.0 (tA and tB) >> TIME: 5 EQUALLY spaced [MINUTES] 10.0 30.0 (tC and tD) See Also: >> RESTART TIME, >>> CONSECUTIVE, >>>> WINDOW @@@ Syntax: >>> time_unit or as a keyword to any command requesting time units Parent Command: >> OUTPUT Subcommand: - Description: This command or keyword specifies the time units of all times in the iTOUGH2 output and plot files. Admissible time units are SECOND (default), MINUTE, HOUR, DAY, WEEK, MONTH, and YEAR. The time output unit may be different from the time units specified in the input or data files. Example: > OBSERVATION >> : 7 EQUALLY spaced TIMES in [DAYS] 1.0 7.0 >> PRESSURE >>> ELEMENT: ZZZ90 >>>> DATA in [MINUTES] on FILE: pres.dat >>>> time WINDOW: 48.0 123.0 [HOURS] <<<< <<< << > COMPUTATION >> print OUTPUT times >>> in WEEKS <<< << See Also: - @@@ Syntax: >> TOLERANCE Parent Command: > COMPUTATION Subcommand: (see command >> CONVERGE) Description: (synonym for command >> CONVERGE) Example: (see command >> CONVERGE) See Also: >> CONVERGE @@@ Syntax: >> TOTAL MASS (phase_name/PHASE: iphase/ comp_name/COMPONENT: icomp) (CHANGE) Parent Command: > OBSERVATION Subcommand: >>> MATERIAL >>> MODEL Description: This command selects as an observation type the total mass of phase iphase or component icomp. This observation type refers to the entire model domain or to the subdomain defined by a list of rock types. Component number icomp or component name comp_name, and phase number iphase or phase name phase_name depend on the EOS module being used. They are listed in the header of the iTOUGH2 output file, and can be specified either on the command line or using the two subcommands >>>> COMPONENT and >>>> PHASE, respectively. If keyword CHANGE is present, the change of the total mass since data initialization is computed. Example: > OBSERVATION >> CHANGE of TOTAL MASS in place since beginning of simulation >>> entire MODEL >>>> ANNOTATION : Total brine mass injected >>>> BRINE is the COMPONENT of interest >>>> FACTOR : 1.0E-03 [g] - [kg] >>>> DATA on FILE : brine.dat >>>> DEVIATION : 10.0 [g] <<<< <<< >> TOTAL MASS of PHASE: 2 (= net weight of laboratory column) >>> MATERIAL domains : FRACT MATRI >>>> ANNOTATION : Mass of liquid (water and brine) >>>> DATA on FILE : liquid.dat >>>> DEVIATION : 0.01 [kg] <<< << See Also: >> VOLUME @@@ Syntax: >>>> UNIFORM Parent Command: all third-level commands in block > PARAMETER Subcommand: - Description: This command generates uniformly distributed input parameters for Monte Carlo simulations. Parameter values are sampled between the lower and upper bound specified by command >>>> RANGE. Example: > PARAMETER >> RELATIVE permeability function >>> DEFAULT >>>> PARAMETER RPD(: 1) >>>> ANNOTATION : Slr is uncertain >>>> sample from UNIFORM distribution between... >>>> RANGE : 0.01 0.50 <<<< <<< << > COMPUTATION >> perform ERROR propagation analysis by means of... >>> MONTE CARLO simulations <<< >> STOP after... >>> : 400 TOUGH2 runs <<< << See Also: >>> MONTE CARLO, >>>> GAUSS @@@ Syntax: >>> UPDATE Parent Command: >> OUTPUT Subcommand: - Description: This command writes version update information to the iTOUGH2 output file. Example: > COMPUTATION >> OUTPUT >>> write UPDATE information to iTOUGH2 output file <<< << See Also: >>> INDEX, >>> VERSION, HELP, LIST @@@ Syntax: >>> UPHILL: max_uphill Parent Command: >> CONVERGE Subcommand: - Description: By default, an inversion is stopped if more than 10 consecutive unsuccessful parameter steps have been proposed. The default can be overwritten by max_uphill. Each unsuccessful step results in an increase of the Levenberg parameter (see command >>> LEVENBERG), leading to a smaller step size deflected towards the gradient. Example: > COMPUTATION >> STOP either if >>> : 10 ITERATIONS have been completed or >>> : 3 TOUGH2 runs were INCOMPLETE or >>> : 5 unsuccessful UPHILL steps have been proposed <<< << See Also: >>> ITERATION, >>> LEVENBERG @@@ Syntax: >> USER (There are two second-level commands >> USER. Check parent command.) Parent Command 1: > PARAMETER Syntax: >> USER (: anno) Subcommand: >>> ELEMENT >>> MATERIAL >>> MODEL >>> SET >>> SOURCE Description: This command selects a user-specified parameter. This option enables a user to estimate any conceivable parameter which can be any TOUGH2 variable or function thereof. The user must program the function in subroutine USERPAR, file it2user.f. Identification of and details about the parameter can be given in the iTOUGH2 input file and will be transferred to subroutine USERPAR. A parameter annotation anno should be provided following a colon on the command line. This annotation (or a substring thereof) will be available in subroutine USERPAR (variable ANNO) and can be used to identify the parameter type. The significant part of the string should therefore not be changed by command >>>> ANNOTATION. Furthermore, multiple material names as well as grid block or sink/source code names defined by the corresponding third-level command will be transferred to the subroutine in array NAMEA. Integers read after command >>>> INDEX are provided through array IDA. A flag (variable IVLF) indicates whether the estimate is a value, logarithm, or multiplication factor of the corresponding parameter. The user must ensure that all TOUGH2 variables used by the function are transferred to subroutine USERPAR via COMMON blocks. If a variable is not predefined in one of the standard COMMON blocks, a new COMMON block must be created which and added to the include file usercom.inc. Subroutine USERPAR has two major blocks. In the first block (IUIG=1), the value specified in the TOUGH2 input file is transferred to iTOUGH2 as an initial guess. Programming this first part is optional because initial guesses can also be provided through the iTOUGH2 input file by means of command >> GUESS, >>>> PRIOR, or >>>> GUESS. Programming the second part (IUIG=2) is mandatory. In this part, the parameter is updated, i.e., the generic parameter value calculated by iTOUGH2, which is stored in variable XX, must be assigned to the appropriate TOUGH2 variable. The following is the header of subroutine USERPAR in file it2user.f, describing the transfer variables. File it2user.f must be recompiled before the user-specified parameter becomes active. ************************************************************************ SUBROUTINE USERPAR(IUIG,XX,IVLF,IDA,NAMEA,ANNO) ************************************************************************ * User specified parameters * * IUIG = 1 : Provide initial guess (input) * * = 2 : Update parameter * * XX = iTOUGH2 variable = parameter to be estimated * * (output if IUIG=1, input if IUIG=2) * * IVLF = 1: value (input) * * = 2: logarithm * * = 3: factor * * IDA = parameter IDs (if needed) (input) * * the number of elements in IDA is stored in IDA(MAXR-1) * * NAMEA = material or element names (if needed) (input) * * the number of elements in NAMEA is stored in IDA(MAXR) * * ANNO = parameter annotation as specified in iTOUGH2 input file * ************************************************************************ Example: In this simple example, the tortuosity factor (TOUGH2 variable TORT(NMAT)) is treated as a user-specified parameter. Variable TORT is provided through COMMON block SOLI11 in include file rock.inc. The parameter block in the iTOUGH2 input file and subroutine USERPAR are given below. > PARAMETER >> USER-specified parameter: TORTUOSITY >>> MATERIAL: SAND1 <<<< <<< << ************************************************************************ SUBROUTINE USERPAR(IUIG,XX,IVLF,IDA,NAMEA,ANNO) ************************************************************************ C C$$$$$$$$$ COMMON BLOCKS FOR ROCK PROPERTIES $$$$$$$$$$$$$$$$$$$$$$$$$$$ INCLUDE 'rock.inc' C CHARACTER ANNO*(*),NAMEA*5 DIMENSION IDA(*),NAMEA(*) C CALL GETNMAT(NAMEA(1),NMAT) IF (IUIG.EQ.1) XX=TORT(NMAT) IF (IUIG.EQ.2) TORT(NMAT)=XX END ************************************************************************ The following is a more general version of subroutine USERPAR for the determination of tortuosity. It allows specifying multiple rock types on command line >>>> MATERIAL, and offers the possibility to estimate tortuosity either as a value, a logarithm, or a multiplication factor. Note that identifying the parameter by its annotation is only necessary if other user-specified parameters are also addressed in the same subroutine. ************************************************************************ SUBROUTINE USERPAR(IUIG,XX,IVLF,IDA,NAMEA,ANNO) ************************************************************************ C C$$$$$$$$$ PARAMETERS FOR SPECIFYING THE MAXIMUM PROBLEM SIZE $$$$$$$$$$ INCLUDE 'maxsize.inc' C C$$$$$$$$$ COMMON BLOCKS FOR ROCK PROPERTIES $$$$$$$$$$$$$$$$$$$$$$$$$$$ INCLUDE 'rock.inc' C CHARACTER ANNO*(*),NAMEA*5 DIMENSION IDA(*),NAMEA(*),X0(MAXROC) C C --- Return TOUGH2 value as initial guess IF (IUIG.EQ.1) THEN IF (ANNO(1:10).EQ.'TORTUOSITY') THEN DO 1000 I=1,IDA(MAXR) CALL GETNMAT(NAMEA(I),NMAT) IF (IVLF.EQ.1) THEN XX=TORT(NMAT) ELSE IF (IVLF.EQ.2) THEN XX=LOG10(TORT(NMAT)) ELSE XX=1.0D0 X0(NMAT)=TORT(NMAT) ENDIF 1000 CONTINUE ENDIF C C --- Update parameter ELSE IF (IUIG.EQ.2) THEN C --- Identify parameter by its annotation IF (ANNO(1:10).EQ.'TORTUOSITY') THEN DO 1001 I=1,IDA(MAXR) C --- Obtain material identifier NMAT CALL GETNMAT(NAMEA(I),NMAT) IF (IVLF.EQ.1) THEN C --- Estimate is tortuosity value TORT(NMAT)=XX ELSE IF (IVLF.EQ.2) THEN C --- Estimate is logarithm of tortuosity TORT(NMAT)=10.0D0**XX ELSE C --- Estimate is multiplication factor for initial tortuosity TORT(NMAT)=X0(NMAT)*XX ENDIF 1001 CONTINUE ENDIF ENDIF END ************************************************************************ Additional examples can be found in file it2user.f . See Also: - @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ Parent Command 2: > OBSERVATION Syntax: >> USER (: anno) Subcommand: >>> CONNECTION >>> ELEMENT >>> MODEL >>> SOURCE Description: This command selects a user-specified observation type. This option enables a user to introduce a new observation type, i.e., any type of data can be used for parameter estimation by defining the corresponding model output which is a user-specified function of TOUGH2 variables. The user must program the function in subroutine USEROBS, file it2user.f. Identification of and details about the observation can be given in the iTOUGH2 input file and will be transferred to subroutine USEROBS. The annotation anno (or a substring thereof) will be available in subroutine USEROBS (variable ANNO); it can be used to identify the observation type and data set. The significant part of the string should therefore not be changed by subcommand >>>> ANNOTATION. Multiple grid block names or sink/source code names defined by the appropriate third-level command will be transferred to the subroutine in array GRIDA. The corresponding element numbers are stored in array NECA, with INEC pointing to the currently processed array index. Integer variables read after command >>>> INDEX are provided through array IOBSA. On output, subroutine USEROBS returns the user-specified model result TRESULT. The user must ensure that all TOUGH2 variables used by the function are transferred to subroutine USERPAR via COMMON blocks. If a variable is not predefined in one of the standard COMMON blocks, a new COMMON block must be created and added to the include file usercom.inc. The following is the header of subroutine USEROBS, describing the transfer variables. File it2user.f must be recompiled before the user-specified observation becomes active. ************************************************************************ SUBROUTINE USEROBS(IUSER,IOBSA,GRIDA,NECA,INEC,ANNO,TRESULT) ************************************************************************ * Provides TOUGH2 result for user-specified observation type * * IUSER : Number of dataset (input) * * IOBSA : Array containing user specified IDs (input) * * GRIDA : Array containing grid block names (input) * * NECA : Array containing index of grid block or connection (input) * * INEC : Current pointer to GRIDA and NECA, respectively (input) * * ANNO : Annotation (input) * * TRESULT: User-defined TOUGH2 result (output) * ************************************************************************ Example: In this example the pressure difference measured between two points in a laboratory column is defined as a user-specified observation. Two differential pressures are measured, referring to the liquid and NAPL phase, respectively. The iTOUGH2 input block and sub- routine USEROBS are given below. Variable IOBSA(MAXR-2) holds the phase number. > OBSERVATION >> USER-specified observation type: Pres. Diff. >>> difference between ELEMENTs: A1112 A1152 >>>> ANNOTATION : Pres. Diff. aqueous phase >>>> PHASE : 2 >>>> DATA FILE : dp_aqu.dat >>>> DEVIATION : 1000.0 <<<< >>> difference between ELEMENTs: A1112 A1152 >>>> ANNOTATION : Pres. Diff. NAPL phase >>>> NAPL PHASE >>>> DATA FILE : dp_napl.dat >>>> DEVIATION : 1000.0 <<<< <<< ************************************************************************ SUBROUTINE USEROBS(IUSER,IOBSA,GRIDA,NECA,INEC,ANNO,TRESULT) ************************************************************************ C$$$$$$$$$ PARAMETERS FOR SPECIFYING THE MAXIMUM PROBLEM SIZE $$$$$$$$$$ INCLUDE 'maxsize.inc' C$$$$$$$$$ COMMON BLOCKS FOR PRIMARY VARIABLES $$$$$$$$$$$$$$$$$$$$$$$$$ INCLUDE 'primary.inc' C$$$$$$$$$ COMMON BLOCK FOR SECONDARY VARIABLES $$$$$$$$$$$$$$$$$$$$$$$$ INCLUDE 'second.inc' C --- Identify observation: IF (ANNO(1:11).EQ.'Pres. Diff.') THEN C --- Reference and capillary pressure of first element: NEC=NECA(1) NLOC=(NEC-1)*NK1 NLOC2=(NEC-1)*NSEC*NEQ1+(IOBSA(MAXR-2)-1)*NBK PREF1=X(NLOC+1) PCAP1=PAR(NLOC2+6) P1=PREF1+PCAP1 C --- Reference and capillary pressure of second element: NEC=NECA(2) NLOC=(NEC-1)*NK1 NLOC2=(NEC-1)*NSEC*NEQ1+(IOBSA(MAXR-2)-1)*NBK PREF2=X(NLOC+1) PCAP2=PAR(NLOC2+6) P2=PREF2+PCAP2 C --- Take the difference TRESULT=P2-P1 ENDIF END C --- End of USEROBS See Also: - @@@ Syntax: >>>> USER Parent Command: all third-level commands in block > OBSERVATION Subcommand: - Description: Observed data can be represented as a user-specified function of time. The function must be coded into subroutine USERDATA, file it2user.f. The following is the header of subroutine USERDATA, describing the transfer variables. File it2user.f must be recompiled before the user-specified data definition becomes active. ************************************************************************ SUBROUTINE USERDATA(IDF,TIME,ANNO,F) ************************************************************************ * User specified function to represent observed data * * IDF : data set identifier (input) * * TIME: time at which data are to be provided (input) * * ANNO: annotation (input) * * F : value of observed data at time TIME (output) * ************************************************************************ Example In this example an analytical solution is provided as data to be matched (see sample problem 8). Liquid saturation in response to a liquid pulse is calculated as a function of time and location in subroutine USERDATA (see following page). Note that the Z-coordinate is passed to USERDATA through the annotation. > OBSERVATIONS >> LIQUID SATURATION >>> GRID BLOCK : BP1_1 >>>> ANNOTATION : ANALYT. Z=0.100 >>>> DEVIATION : 0.002 >>>> analytical solution given by USER-specified function <<<< >>> GRID BLOCK : BZ1_1 >>>> ANNOTATION : ANALYT. Z=0.200 >>>> DEVIATION : 0.002 >>>> analytical solution given by USER-specified function <<<< <<< << ************************************************************************ SUBROUTINE USERDATA(IDF,TIME,ANNO,F) ************************************************************************ * User specified function to represent observed data * * IDF : data set identifier (input) * * TIME: time at which data are to be provided (input) * * ANNO: annotation (input) * * F : value of observed data at time TIME (output) * ************************************************************************ C C$$$$$$$$$ PARAMETERS FOR SPECIFYING THE MAXIMUM PROBLEM SIZE $$$$$$$$$$ INCLUDE 'maxsize.inc' C C$$$$$$$$$ COMMON BLOCKS FOR SIMULATION PARAMETERS $$$$$$$$$$$$$$$$$$$$$ INCLUDE 'param.inc' C C$$$$$$$$$ COMMON BLOCKS FOR ROCK PROPERTIES $$$$$$$$$$$$$$$$$$$$$$$$$$$ INCLUDE 'rock.inc' C C$$$$$$$$$ COMMON BLOCK FOR SECONDARY VARIABLES $$$$$$$$$$$$$$$$$$$$$$$$ INCLUDE 'second.inc' C C$$$$$$$$$ COMMON BLOCKS FOR TOTAL MASS AND VOLUMES $$$$$$$$$$$$$$$$$$$$ INCLUDE 'rmasvol.inc' C C$$$$$$$$$ COMMON BLOCKS FOR ELEMENTS $$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$ INCLUDE 'elements.inc' CHARACTER ANNO*(*) SAVE A F=0.0D0 C --- Analytical solution 1D-pulse IF (ICALL.EQ.1) A=CP(1,1) IF (ANNO(1:10).EQ.'ANALYT. Z=') THEN READ(ANNO(11:15),'(F5.3)',IOSTAT=IOS) Z V=PER(3,1)*PAR(4)*GF/POR(1)/PAR(3) DIFF=A*PER(3,1)/POR(1)/PAR(3) XM=XPVOLU0(2)/POR(1) F=XM/(DSQRT(4.0D0*3.1416D0*DIFF*TIME))* & DEXP(-(Z-V*TIME)**2/(4.0D0*DIFF*TIME)) ENDIF END C --- END of USERDATA See Also: >>>> DATA, >>>> POLYNOM @@@ Syntax: >>>> VALUE Parent Command: all third-level commands in block > PARAMETER Subcommand: - Description: This command selects the estimation of the parameter value as opposed to its logarithm (see command >>>> LOGARITHM (p)) or a multiplication factor (commands >>>> FACTOR (p) and >>>> LOG(F)). Example: > PARAMETER >> parameter of RELATIVE permeability function >>> MATERIAL: SAND1 >>>> estimate VALUE of ... >>>> ANNOTATION : Resid. Liq. Sat. >>>> PARAMETER no. : 1 <<<< <<< << See Also: >>>> FACTOR (p), >>>> LOGARITHM (p), >>>> LOG(F) @@@ Syntax: >>>> VARIANCE: sigma^2 Parent Command: all third-level commands in block > PARAMETER and > OBSERVATION Subcommand: - Description: (see >>>> DEVIATION (p/o)) Example: (see >>>> DEVIATION (p/o)) See Also: >>>> DEVIATION (p/o) @@@ Syntax: >>>> VARIATION: sigma Parent Command: all third-level commands in block > PARAMETER Subcommand: - Description: This command specifies the expected variation sigma of a parameter p. Sigma is used to scale the columns of the Jacobian matrix, yielding dimensionless and comparable sensitivity coefficients. While the solution of the inverse problem is not affected by the choice of the scaling factor, all the qualitative sensitivity measures are directly proportional to sigma: dz sigma sigma i p p j j scaled sensitivity coefficient: S = --- ------- = J ------- ij dp sigma ij sigma j z z i i If no standard deviation (see >>>> DEVIATION (p)) or parameter variation is specified, the scaling factor is taken to be 10 % of the respective parameter value. For sensitivity analyses, sigma can be taken as the perturbation one would apply to study the effect of the parameter on the modeling result. Example: > PARAMETER >> POROSITY >>> MATERIAL: FAULT >>>> expected VARIATION : 0.10 <<<< <<< >> ABSOLUTE permeability >>> MATERIAL: FAULT >>>> expected VARIATION : 1.00 (one order of magnitude) <<<< <<< << > COMPUTATION >> OPTION >>> SENSITIVITY analysis <<< << See Also: >>>> DEVIATION (p) @@@ Syntax: >>> VERSION Parent Command: >> OUTPUT Subcommand: - Description: This command prints version control statements at the end of the iTOUGH2 output file. The same information is always written to the *.msg file. If making code modifications it is strongly suggested to update the version control statement at the beginning of each subroutine or function. Example: > COMPUTATION >> OUTPUT >>> VERSION control statements <<< On output: -------------------------------------------------------------------------------------------------------------- iTOUGH2 Current version V3.0 (JULY 12, 1996) -------------------------------------------------------------------------------------------------------------- iTOUGH2 1.0 1 SEPTEMBER 1992 First version is an adaptation of ITOUGH V1.0 iTOUGH2 1.1 1 JANUARY 1993 INOBSDAT,INPAIRED: Flexible time specification 1 JANUARY 1993 INERROR,MTCARLO: number of classes can be specified 1 FEBRUARY 1993 INUSER,USERPAR: user specified parameter 1 FEBRUARY 1993 INUSROBS,USEROBS: user specified observations 15 FEBRUARY 1993 PLOTFI,PLOTCHAR: Reformat plotfiles, plot characteristic curves 15 FEBRUARY 1993 PLOTCHAR: Plots characteristic curves iTOUGH2 1.2 1 APRIL 1993 Add version for IBM RS/6000 26 MAY 1993 INANNEAL,ANNEAL: Simulated Annealing minimization iTOUGH2 2.0 12 AUGUST 1993 File t2cg1.f: Conjugate gradient solvers added iTOUGH2 2.1 23 SEPTEMBER 1993 Rearrange parameter vector 29 SEPTEMBER 1993 Rearrange observation vector 15 FEBRUARY 1994 Add new observation types iTOUGH2 2.2 1 FEBRUARY 1994 Steady-state data points allowed This version is documented in LBL-34581, iTOUGH2 User's Guide, Version 2.2 iTOUGH2 2.3 10 MAY 1994 Correlation chart, performance comparison, stopping and restarting 16 JUNE 1994 New parameter types added iTOUGH2 2.4 15 DECEMBER 1994 Sensitivity analysis iTOUGH2 2.5 10 JANUARY 1995 Automatic parameter selection 13 JANUARY 1996 Aligned common blocks in include files iTOUGH2 3.0 12 JULY 1996 YMP Software Qualification -------------------------------------------------------------------------------------------------------------- WHATCOM 1.0 10 AUGUST 1993 #35: Q: WHAT COMPUTER IS USED? A: IBM CALLSIG 2.5 20 MAY 1996 #112: SIGNAL HANDLER CPUSEC 1.0 10 AUGUST 1993 #--: RETURNS CPU-TIME (VERSION IBM) OPENFILE 2.5 4 JUNE 1996 #31: OPENS MOST OF THE FILES LENOS 1.0 1 MARCH 1992 #28: RETURNS LENGTH OF LINE PREC 1.0 1 AUGUST 1992 #86: CALCULATE MACHINE DEPENDENT CONSTANTS ITHEADER 1.0 1 AUGUST 1992 #29: PRINTS iTOUGH2 HEADER DAYTIM 1.0 10 AUGUST 1993 #32: RETURNS DATE AND TIME (VERSION IBM) THEADER 1.1 27 MAY 1993 #30: PRINTS TOUGH2 HEADER INPUT 2.5 15 MARCH 1996 READ ALL DATA PROVIDED THROUGH FILE *INPUT*, + SECONDARY MESH + USERX MESHM 1.0 24 MAY 1990 EXECUTIVE ROUTINE FOR INTERNAL MESH GENERATION ...... ... .. ........ .... ..................................................................... See Also: >>> UPDATE @@@ Syntax: >> VOLUME (phase_name/PHASE: iphase) (CHANGE) Parent Command: > OBSERVATION Subcommand: >>> MATERIAL >>> MODEL Description: This command selects as an observation type the total volume of phase iphase. This observation type refers to the entire model domain or to the subdomain defined by a list of rock types. The phase name phase_name or phase number iphase, which depend on the EOS module being used, are listed in the iTOUGH2 header. They can be specified either on the command line or using the subcommand >>>> PHASE. If keyword CHANGE is present, the change of the total volume since data initialization is computed. This option can be used, for example, to calculate the cumulative volumetric liquid flow which is equivalent to the change of the total gas volume in place. Example: > OBSERVATION >> CHANGE in total GAS VOLUME >>> entire MODEL >>>> ANNOTATION: Cum. vol. water flux >>>> FACTOR : 1.0E-06 [ml] - [m^3] >>>> DATA [DAYS] 0.00 0.00 0.10 245.16 0.25 354.84 0.50 419.35 0.75 451.61 1.00 470.97 1.60 503.23 1.95 516.13 2.10 522.58 2.50 539.35 3.00 552.26 >>>> DEVIATION : 5.0 [ml] <<<< <<< << See Also: - @@@ Syntax: >>> WARNING Parent Command: >> CONVERGE Subcommand: - Description: iTOUGH2 checks the consistency of the TOUGH2 and iTOUGH2 input, printing error and warning messages to the iTOUGH2 output file. The program stops if an error or warning is encountered. Command >>> WARNING makes iTOUGH2 continue despite the occurrence of a warning message. It is strongly suggested to resolve all warning messages before continuing. Warning messages should only be ignored if the reason for message is completely understood and deemed harmless. Example: > COMPUTATION >> STOP >>> don't stop because of WARNINGS <<< << See Also: >>> INPUT @@@ Syntax: >>>> WEIGHT: 1/sigma Parent Command: all third-level commands in block > PARAMETER and > OBSERVATION Subcommand: - Description: (see >>>> DEVIATION (p/o)) Example: (see >>>> DEVIATION (p/o)) See Also: >>>> DEVIATION (p/o) @@@ Syntax: >>>> WINDOW: time_A time_B (time_unit) Parent Command: all third-level commands in block > OBSERVATION Subcommand: - Description: The times at which the observed and calculated system response are compared are referred to as calibration times. They are specified using command >> TIME. The calibration times are defined globally, i.e., there is only one set of calibration times and it is applied to all data sets. Calibration times and observation times may be different; observed data are linearly interpolated between adjacent data points to obtain a value at the calibration time. In the standard case, the first data point is observed at or before the first calibration time, and the last data point is observed at or after the last calibration time. This configuration ensures that a value for calibration is available or can be interpolated at every calibration point. If, for some reason, only a subset of the available data can be used for calibration, the user must specify the time window between which data should be processed: time_A and time_B are the lower and upper bounds of the window. Only one time window may be specified per data set. If more than one time window is required, new data sets containing the same data must be generated and different time windows specified for each data set. The time units of time_A and time_B can be specified using one of the time_unit keywords. If a data set does not contain data that extend over the entire range of calibration times, iTOUGH2 automatically adjusts the time window to coincide with the first and last data point. A warning message is printed, however, which can be avoided by explicitly specify the time window. If the specified time window is larger than the available data set, the value of the first and last data point is horizontally extrapolated to time_A and time_B, respectively. If time is shifted, the time window must be given with reference to the time system of the data, if command >>>> SHIFT TIME: tshift appears before command >>>> WINDOW. Conversely, the window must be given in the shifted time system, if the shift command appears after command >>>> WINDOW. Example: > OBSERVATION >> :7 EQUALLY spaced TIMES in [MINUTES] 5.0 35.0 >> PRESSURE >>> ELEMENT: ZZZ99 >>>> DATA [HOURS] on FILE: pres.dat >>>> time WINDOW: 299.0 901.0 [SECONDS] -> 3 calibration points >>>> DEVIATION : 1.E3 <<<< <<< See Also: >> TIME, >>>> SHIFT @@@