Back to Input Deck Cards

Back to SUBSURFACE_FLOW

Back to MODE

GENERAL¶

Defines options for the General subsurface flow mode. For more details and governing equations see the Theory Guide.

SIMULATION Options

TIMESTEPPER Options

NEWTON_SOLVER Options

Examples

SIMULATION Options¶

(under SUBSURFACE_FLOW in SIMULATION PROCESS_MODELS block)

Basic Settings

ARITHMETIC_GAS_DIFFUSIVE_DENSITY: Use arithmetic weighting for gas diffusivity.
GAS_COMPONENT_FORMULA_WEIGHT <float>: Specifies the molecular weight of the gas component [g/mol].
HARMONIC_GAS_DIFFUSIVE_DENSITY: Use harmonic weighting for gas diffusivity.
IMMISCIBLE: Disables solubility calculations.
ISOTHERMAL: Disables the energy calculation forcing constant temperature.
LIQUID_COMPONENT_FORMULA_WEIGHT <float>: Specifies the molecular weight of the liquid component [g/mol].
LOGGING_VERBOSITY <integer>: Prints additional convergence logging to the screen when the integer is greater than 0 (for process models that have logging verbosity implemented).
NON_DARCY_FLOW: Calculates non-Darcian flow based on Liu (2014)
NON_DARCY_FLOW_A: Parameter A for non-Darcian flow in equation 11 in Liu (2014)
NON_DARCY_FLOW_B: Parameter B for non-Darcian flow in equation 11 in Liu (2014)
NO_AIR: Disables the gas component mass conservation equation.
NO_STATE_TRANSITION_OUTPUT: Eliminates “State Transition” screen output. E.g. State Transition: 2 Phase -> Gas at Cell 23331
NO_TEMP_DEPENDENT_DIFFUSION: Turns off temperature-dependent diffusion coefficients.
NUMBER_OF_EQUATIONS <int>: Specifies the number of equations solved (3: air/water/energy (default), 4: air/water/solute/energy)
REPLACE_INIT_PARAMS_ON_RESTART: Forces the overwrite of base (0) porosity and permeabilities off which solution dependent parameters may be calculated.
REVERT_PARAMETERS_ON_RESTART: Reverts permeability and porosity back to the values specified in the input file instead of the checkpointed values.
SKIP_RESTART: On a restarted simulation, employs the initial condition for process model instead of the restarted solution.
SOLUBLE_MATRIX: Allows the rock matrix to dissolve with changing solubility conditions. Requires NUMBER_OF_EQUATIONS 4 and SOLUTE SALT.
SOLUTE <string>: Specifies the solute used when NUMBER_OF_EQUATIONS 4. Default SALT.

Expert Settings

CHECK_MAX_DPL_LIQ_STATE_ONLY: When calculating the maximum change in liquid pressure over a time step, consider only liquid state cells. Helpful when capillary pressures are extreme.
COUNT_UPWIND_DIRECTION_FLIP: Turns on and increments a counter whenever the upwind direction changes. This is only useful for non-parallel execution.
DIFFUSE_XMASS: Calculate gradietns of dissolved gas in diffusion equation based on mass fraction instead of mole fraction.
FIX_UPWIND_DIRECTION: Limits the update of the upwind direction (based on pressure gradients) to UPWIND_DIR_UPDATE_FREQUENCY Newton iterations.
GAS_STATE_AIR_MASS_DOF <string>: Sets the primary dependent variable for the air mass conservation equation for cells in a single-phase gas state (2nd dof) [AIR_PRESSURE, WATER_MOL_FRAC]. (default = AIR_PRESSURE, whihc is the most tested)
NEWTONTRDC_HOLD_INNER_ITERATIONS: If your simulation expects many state changes throughout the simulation, NEWTONTRDC_HOLD_INNER_ITERATIONS is recommended.
PHASE_CHANGE_EPSILON <float>: Assign a fixed initial saturation of a new phase that is created upon a state change.
RESTRICT_STATE_CHANGE: Restricts any changes of state to only occur once per Newton iteration.
TWO_PHASE_STATE_ENERGY_DOF <string>: Sets the primary dependent variable for the energy conservation equation for cells in a two-phsae state (3rd dof) [TEMPERATURE, AIR_PRESSURE]. (default = TEMPERATURE, which is most tested)
UNFIX_UPWIND_DIRECTION: Turns off fixing of upwind direction.
UPWIND_DIR_UPDATE_FREQUENCY: Frequency at which the upwind direction is updated if FIX_UPWIND_DIRECTION is included.
WINDOW_EPSILON <float>: Specifies the tolerance or window that must be exceeded before state change will occur.

TIMESTEPPER Options¶

Basic Settings

CFL_GOVERNOR: Specifies a maximum CFL (Courant–Friedrichs–Lewy) number that governs time step size. Subsequent time steps are calculated as a function of the maximum flow velocity and grid discretization such that the CFL is not exceeded.
CONCENTRATION_CHANGE_GOVERNOR: Specifies a maximum absolute change in concentration [mole fraction] that governs time step size. Subsequent time steps are calculated such that the governing concentration change is not exceeded.
PRESSURE_CHANGE_GOVERNOR: Specifies a maximum absolute change in pressure [Pa] that governs time step size. Subsequent time steps are calculated such that the governing pressure change is not exceeded.
SATURATION_CHANGE_GOVERNOR: Specifies a maximum absolute change in saturation [-] that governs time step size. Subsequent time steps are calculated such that the governing saturation change is not exceeded.
TEMPERATURE_CHANGE_GOVERNOR: Specifies a maximum absolute change in temperature [C] that governs time step size. Subsequent time steps are calculated such that the governing temperature change is not exceeded.

NEWTON_SOLVER Options¶

Basic Settings

ANALYTICAL_JACOBIAN

Calculate derivatives in Jacobian analytically.

ATOL <float>

Declare convergence when the 2-norm of residual is less than ATOL \(\left(\|f(x_n)\|<\text{ATOL}\right)\). (default: \(10^{-50}\)).

CONVERGENCE_INFO

Opens a block for toggling ON/OFF convergence information in screen output (default: YES to all). See example below.

2R, FNORM, 2NORMR - 2-norm of residual
2X, XNORM, 2NORMX - 2-norm of solution
2U, UNORM, 2NORMU - 2-norm of update
IR, INORMR - inifinity norm of residual
IU, INORMU - inifinity norm of update

DTOL <float>

Declare divergence (cut the time step) when the 2-norm of the residual is greater than DTOL times the 2-norm of the initial residual \(\left(\frac{\|f(x_n)\|}{\|f(x_0)\|}>\text{DTOL}\right)\). (default: \(10^{4}\)).

MAXIMUM_NUMBER_OF_ITERATIONS <int>

Maximum number of Newton iterations before reporting failed convergence.

NO_PRINT_CONVERGENCE

Toggle off printing of convergence information.

NTRDC_OPTIONS or NTR_OPTIONS

Opens a block for trust-region options and parameters (SNES_TYPE NTRDC or SNES_TYPE NTR required)

TR_TOL - trust-region tolerance (default: \(1.0^{-12}\))
ETA1 - trust-region parameter \(0.0 \le \eta_1 \le \eta_2\), \(\density \ge \eta_1\) breaks out of the inner iteration (default: \(\eta_1=0.001\))
ETA2 - trust-region parameter \(0.0 \le \eta_1 \le \eta_2\), \(\density \ge \eta_2\) shrinks the trust-region (default: \(\eta_2=0.25\))
ETA3 - trust-region parameter \(\eta_3 > \eta_2\), \(\density \ge \eta_3\) expands the trust-region (default: \(\eta_3=0.75\))
T1 - trust-region parameter, shrinking factor of trust-region (default: 0.25)
T2 - trust-region parameter, initial size of trust-region, \(\Delta_0*\|x\|_2\) (default: 0.1)
DELTA_M - trust-region parameter, max size of trust-region, \(\Delta_M*\|x\|_2\) (default: 0.5)
DELTA_0 - trust-region parameter, initial size of trust-region, \(\Delta_0*\|x\|_2\) (default: 0.1)
AUTO_SCALE - TRUE enables solution update scaling meaning all types of unknowns are equally treated when evaluating solution update (recommended for WIPP-FLOW, TH); FALSE disables solution update scaling meaning that solution update evaluation will focus more on pressure than other unknowns (recommended for GENERAL, HYDRATE).
AUTO_SCALE_MAX - used with AUTO_SCALE, caps the maximum auto-scaling factor

NUMERICAL_JACOBIAN

Calculate derivatives in Jacobian numerically.

PRINT_LINEAR_ITERATIONS

Prints the number of linear iterations for each Newton iteration to the screen.

RTOL <float>

Declare convergence when the 2-norm of the residual is less than RTOL times the 2-norm of the initial residual \(\left(\frac{\|f(x_n)\|}{\|f(x_0)\|}<\text{RTOL}\right)\). (default: \(10^{-8}\)).

SNES_TYPE <string>

The default is LINE_SEARCH (Basic, see PETSc documenetation) from PETSc which is Newton-Raphson nonlinear solver. NTRDC is the Newton Trust-Region Dogleg-Cauchy nonlinear solver, and NTR is the Newton Trust-Region nonlinear solver. The difference between NTRDC and NTR is that NTRDC adds steepest-descent solution update to the Newton solution iff it optimizes better than Newton solution alone within the trust-region. NTR only applies Newton solution update and it is truncated by the trust-region. NTRDC MAY perform better with LESS phase state change simulations for GENERAL MODE.

STOL <float>

Declare convergence when the 2-norm of the update divided by the 2-norm of the solution is less than STOL \(\left(\frac{\|x_n-x_{n-1}\|}{\|x_{n-1}\|}<\text{STOL}\right)\). (default: \(10^{-8}\)).

VERBOSE_LOGGING

Prints additional convergence information to screen.

Expert Settings

ABS_UPDATE_INF_TOL <float>: Specify a single infinity norm convergence tolerance on the absolute value of all solution updates.
AIR_PRES_ABS_UPDATE_INF_TOL <float>: Specify a maximum absolute change in air partial pressure in the gas phase.
AIR_PRES_REL_UPDATE_INF_TOL <float>: Specify a maximum relative change in air pressure.
DAMPING_FACTOR <float>: The scalar value by which the solution is damped between each Newton-Raphson iteration. Acceptable values on (0,1].
ENERGY_RESIDUAL_ABS_INF_TOL: Specify the infinity norm convergence tolerance on the absolute residual of energy. (default = 1e-5)
ENERGY_RESIDUAL_SCALED_INF_TOL <float>: Specify the infinity norm convergence tolerance on the scaled residual of energy.
GAS_PRES_ABS_UPDATE_INF_TOL <float>: Specify a maximum absolute change in gas phase pressure.
GAS_PRES_REL_UPDATE_INF_TOL <float>: Specify a maximum relative change in gas phase pressure.
GAS_RESIDUAL_ABS_INF_TOL: Specify the infinity norm convergence tolerance on the absolute residual of gas mass (gas phase). (default = 1e-5)
GAS_RESIDUAL_SCALED_INF_TOL <float>: Specify the infinity norm convergence tolerance on the scaled residual of gas mass (gas phase primary component).
LIQUID_PRES_ABS_UPDATE_INF_TOL <float>: Specify a maximum absolute change in liquid phase pressure.
LIQUID_PRES_REL_UPDATE_INF_TOL <float>: Specify a maximum relative change in liquid phase pressure.
LIQUID_RESIDUAL_ABS_INF_TOL: Specify the infinity norm convergence tolerance on the absolute residual of water mass (liquid phase). (default = 1e-5)
LIQUID_RESIDUAL_SCALED_INF_TOL <float>: Specify the infinity norm convergence tolerance on the scaled residual of water mass (liquid phase).
MATRIX_TYPE <string>: Format of main solver matrix. PETSc Mat (i.e. AIJ, BAIJ, or HYPRESTRUCT).
MAXF <int>: Maximum number of function evaluations before reporting failed convergence.
MAXIMUM_PRESSURE_CHANGE <float>: The change in pressure is truncated to within this limit.
MAX_ITERATION_BEFORE_DAMPING <integer>: Specifies the threshold number of Newton iterations before damping is imposed.
MAX_NORM <float>: Declare divergence (cut the time step) when the infinity norm of the residual is greater than MAX_NORM \(\left( \| f(x_n) \|_{inf} > \text{MAX_NORM} \right)\). (default: \(10^{20}\)).
MINIMUM_NUMBER_OF_ITERATIONS <int>: Newton solver convergence requires at least MINIMUM_NUMBER_OF_ITERATIONS.
NO_FORCE_ITERATION: Toggle off the forcing of at least 1 linear iteration. The default is to force at least 1 linear iteration. In a quasi-stationary state, the initial residual may be sufficiently small for convergence, but often it is better to force at least one iteration.
NO_INFINITY_NORM: Toggle off calculation of infinity norm on residual and update vectors. The default is to calculate the infinity norm.
PRECONDITIONER_MATRIX_TYPE <string >: Format of preconditioning matrix. PETSc Mat (i.e. AIJ, BAIJ, or HYPRESTRUCT). Default is same as solver.
PRES_ABS_UPDATE_INF_TOL <float>: Specify a single maximum absolute change in liquid phase, gas phase, and air partial pressure. (default = 1)
PRES_REL_UPDATE_INF_TOL <float>: Specify a single maximum relative change in liquid phase, gas phase, and air partial pressure. (default = 1e-3)
PRINT_DETAILED_CONVERGENCE: Toggle on printing of detailed convergence information.
REL_UPDATE_INF_TOL <float>: Specify a single infinity norm convergence tolerance on the relative solution update.
RESIDUAL_ABS_INF_TOL: Specify a single infinity norm convergence tolerance on all absolute residuals. (default = 1e-5)
RESIDUAL_INF_TOL: Specify a single infinity norm convergence tolerance on all absolute and scaled residuals. (default = 1e-5, abs; 1e-6, scaled)
RESIDUAL_SCALED_INF_TOL <float>: Specify a single infinity norm convergence tolerance on all scaled residuals. (default = 1e-6)
SAT_ABS_UPDATE_INF_TOL <float>: Specify a maximum absolute change in phase saturation. (default = 1e-5)
SAT_REL_UPDATE_INF_TOL <float>: Specify a maximum relative change in phase saturation. (default = 1e-3)
TEMP_ABS_UPDATE_INF_TOL <float>: Specify a maximum absolute change in temperature. (default = 1e-5)
TEMP_REL_UPDATE_INF_TOL <float>: Specify a maximum relative change in temperature. (default = 1e-3)
UPDATE_INF_TOL <float>: Specify a single infinity norm convergence tolerance on the absolute and relative updates of all solution updates.
XMOL_ABS_UPDATE_INF_TOL <float>: Specity a maximum absolute change in mass fraction of dissolved gas in the aqueous phase. (default = 1e-9)
XMOL_REL_UPDATE_INF_TOL <float>: Specify a maximum relative change in mass fraction of dissolved gas in the aqueous phase over a given timestep. (default = 1e-3)

Examples¶

SIMULATION
  SIMULATION_TYPE SUBSURFACE
  PROCESS_MODELS
    SUBSURFACE_FLOW flow
      MODE GENERAL
      OPTIONS
        #  WINDOW_EPSILON 1.d-4
        ISOTHERMAL
        TWO_PHASE_STATE_ENERGY_DOF TEMPERATURE
        ARITHMETIC_GAS_DIFFUSIVE_DENSITY
        NEWTONTRDC_HOLD_INNER_ITERATIONS
      /
    /
  /
END
...
SUBSURFACE
  NUMERICAL_METHODS FLOW
    TIMESTEPPER
      TS_ACCELERATION 8
      MAX_TS_CUTS 10
    /
    NEWTON_SOLVER
      ATOL 1.d-8
      RTOL 1.d-8
      STOL 1.d-30
      NO_INFINITY_NORM
      MAXIMUM_NUMBER_OF_ITERATIONS 15
      RESIDUAL_SCALED_INF_TOL 1.d-5
    /
    LINEAR_SOLVER
      SOLVER DIRECT
    /
  /
  ...

GENERAL¶

SIMULATION Options¶

TIMESTEPPER Options¶

NEWTON_SOLVER Options¶

Examples¶

Table of Contents

Local Table of Contents

Previous topic

Next topic