zone fluid command

Syntax

zone fluid keyword

Primary keywords:

active    cmodel    conserve-generated    fastflow    fastflow-relaxation    density    implicit    list    modulus-scale    modulus-automatic    permeability-saturation    constant    s-shape    table    property    property-distribution    saturation-tolerance    steady-state    timestep    time-total    track    unsaturated    zone-based-pp

Set parameters for a groundwater fluid flow analysis.

These commands are only available after a model configure fluid-flow command. These parameters apply to zones only, other model elements may have different values.

active b

Set the fluid process on or off. The process is on for zones, by default, when the model configure fluid-flow command is given. Specify off to suppress the fluid calculation for zones.

cmodel keyword

Associate a fluid constitutive model with specified zones in the grid. The command also allows querying of properties and states of constitutive models.

assign keyword <range>

Assign a fluid model to all zones in the range. This keyword may only be given if the model is configured for fluid calculations (i.e., the command model configure fluid-flow has been issued). Fluid models are described in Grid Configured for Fluid Flow.

inactive

Assigns the inactive model to the zone. This is effectively impermeable for the purposes of fluid flow modeling.

linear

Assigns the linear permeabiliity model to the zone, based on the given mobility-coefficient, mobility-coefficient-tensor, hydraulic-conductivity, or hyraulic-conductivity-tensor. This is the default.

list

List the available fluid constitutive models and their properties.

conserve-generated b

When fluid-mechanical two-way coupling is active (See the pore-pressure-generation property) pore-pressure is generated by mechanical volumetric strain. This pore-pressure is distributed equally to all grid points connected to the zone. If a given grid point is fixed in pore pressure, some of this pore pressure increase is lost. When conserve-generated is on this pore pressure is instead distributed to the remaining non-fixed grid points. The default value is off.

fastflow b

Turn the fastflow solution scheme on/off. Turning fastflow on also turns implicit off, sets the mechnical loosely-coupled substep value to 50, and the fluid substep value to 10. See Fully Saturated Fast Flow.

fastflow-relaxation f

Set the relaxation parameters used in the fastflow solution scheme.

density f

Sets the global fluid density. This is a synonymn for the zone fluid-density command.

implicit <<active> b > <keyword> ...

Turn implicit mode on/off. By default implicit mode is off. Implicit mode requires a manually specified timestep. If no keyword is specified, the implicit logic uses iterative Preconditions Conjugate Gradient solver. If that solver fails to converge to the solution, the logic switches to a slower direct solution scheme. The following keywords apply:

maximum-iterations

Specify the limit on the number of iterations when using the pcg and jacobi solvers. The default iteration limit is 1000.

maxnonlinear-iterations

Specify the limit on the number of non-linear system iterations allowed when a saturation model is active.

Note that if a timestep fails to converge before this number of nonlinear iterations has been reached, the timestep will be reduced automatically and another attempt will be made.

servo <keyword> ...

Controls the optional timestep servo during fluid calculations. This servo attempts to increase or decrease the timestep depending on accuracy of the solution. It does this by monitoring an error approximation, the number of iterations required to converge the matrix solver, and if a saturation model is present how many nonlinear iterations are required.

If the servo is active when a model solve or model cycle command is given fluid calculations always start explicitly using the critical stable timestep. If the error estimate falls below error-explicit (corrected for the expected timestep increase) then implicit calculations are activated automatically at a timestep judged to be generally just above what is necessary for implicit calculations to be more efficient than explicit. During implicit calculations the error estimate and iterations required for convergence are monitored and the timestep raised or lowered. If the servo lowers the timestep below the level where explicit calculations are deemed more efficient the system will drop back into explicit calculations.

All three (if active) servo conditions must be below the minimum level for the timestep to be raised. The timestep is lowered if any of the three are above the maximum level.

NOTE: The error approximation is done using a half-timestep check every error-interval steps – so three fluid steps will be done instead of one on that interval. This half step check assumes that the only state values in the fluid calculation are pore-pressure and saturation - so that the fluid model can go backwards in time one step. If FISH, Python, or a fluid constitutive model with more state variables is being used then the servo should not be activated.

NOTE: This servo is new and very experimental and may require a great deal of tuning in actual practice. The default parameters are conservative by design.

The following keywords are avilable.

active b

Specifies whether the implicit servo is active or inactive. The servo is not active if a manual timestep has been given using the model fluid timestep fix command. It must be set to model fluid timestep automatic.

error f

Specifies the general error level of the servo system. This is a shorthand for the specification of the the error limits error-explicit and the low and high error-implicit. Both error-explicit and the lower error-implicit are set to \(f\). The maximum error-implicit is set to f * 100 or the existing maximum limit – whichever is higher.

error-explicit f

Specifies the estimated error below which the system will switch to implicit calculations. This estimate is corrected for the increase in timestep required for implicit calculations to be efficient. The default value is 1e-8.

error-implicit fmin fmax

Specifies the minimum and maximum estimated error used by the implicit timstep servo. If the estimated error is below fmin the timestep is increased. If the estimated error is above fmax the timestep is decreased. The default values are 1e-8 and 1e-6.

error-interval i

Specifies how often the error estimate is made. The timestep can only be increased on the error estimate interval (it can decrease due to iteration limits at any step). Two extra fluid steps are taken every iteration interval. The default value is 40.

gain flow fhigh

Specifies the amount the timestep is increased or decreased when a servo bound is reached. The flow multiplier is used to decrease the timestep, and the fhigh multiplier is used to increase it. The default values are 0.8 and 1.25.

iterations ilow ihigh

Specifies the minimum and maximum number of matrix solver iterations allowed before the timestep is increased or decreased. This metric does not apply to the direct solver. The default values are 7 and 20.

latency i

Specifies the minimum number of fluid steps required after the timestep is increased before it is allowed to increase again. The default value is 80.

list

Lists to the console the current implicit servo settings.

nonlinear ilow ihigh

Specifies the minimum and maximum number of nonlinear system iterations allowed before the timestep is increased or decreased. This metric only applies if a saturation model is active. The default values are 30 and 120.

pcg-limit f

Specifies the limit at which the servo automatically switches from the preconditioned-conjgate-gradient solver to the direct solver. This limit is specified in terms of the multiplier on the current critical explicit timestep. The default value is 5e4.

table <prefix sprefix >

Activates four tables that can be used to monitor the servo limit values during cycling. This is the best way to query the system in practice and tune the servo limits for your particular model. The four tables created are named Servo-Multiplier, Servo-Error, Servo-Iterations, and Servo-Nonlineariterations. For each fluid step taken they record the value of the current servo multiplier, estimated error, number of solver iterations required, and number of non-linear iterations required respectively. The names of these tables can be changed using the optional sprefix keyword which will change the string Servo- to the contents sprefix in the created table names.

solver <keyword>

Specifies the matrix solver to use during implicit mode. The default is automatic. See also the tolerance and maximum-iteration keywords. The following options are available:

automatic

Starts using the pcg solver. If that solver fails to converge before the maximum number of iterations is reached then switches to the direct solver for all subsequent timesteps.

direct

Use the direct solver similar to matrix inversion (see Advanced implicit solvers). This highly efficient solver is able to handle small to medium size models (< 50-100K zones) and it is unconditionally stable for any timestep.

jacobi

Uses a Jacobi iterative solver. This option is provided for backwards compatibility but it is not reccomended. The pcg solver should provide a faster solution for a given matrix size and error tolerance.

pcg

Use the preconditioned conjugate gradient iterative solver (see Advanced implicit solvers).

tolerance

Specify an error tolerance (solution accuracy) that will determine when to stop iterations when using the pcg and jacobi sovlers. The default tolerance value is 2.e-5.

list

information

Output current configuration settings and status information for the fluid model.

property keyword <range>

Output the values of the specified fluid property in all zones in the range. See the zone fluid property command for details of each property.

biot-coefficient

biot-modulus

consolidation-coefficient

density

density-saturated

effective-cutoff

fluid-density

fluid-modulus

mobility-coefficient

mobility-coefficient-tensor

hydraulic-conductivity

hydraulic-conductivity-tensor

pore-pressure-generation

porosity

undrained-thermal-coefficient

modulus-scale <keyword ...> <range>

This command scales the fluid modulus (or Biot modulus) of the zones in the range - typically in preparation for a consolidation analysis executed with the model solve-fluid-decoupled command. The scaling is designed for a fluid-only calculation, modifying the modulus to account for material compliance changes to pore-pressure when mechanical calculations are not active. See the discussion in the Stiffness Ratio section of Solving Flow-Only and Coupled-Flow Problems.

The fluid modulus is scaled by the material confined modulus using the relation:

\[K_w' = \frac{n}{\frac{n}{K_w}+\frac{1}{{K + {4 \over 3} G}}}\]

where \(n\) is the porosity, \(K\) is the material bulk modulus, and \(G\) is the material shear modulus. Equivalently, or if the Biot coefficient \(\alpha\) is not 1.0, the Biot modulus becomes

\[M' = \frac{1}{\frac{1}{M} + {\frac{\alpha^2}{K + {4 \over 3} G}}}\]

The following keywords are available:

limit-modulus fmin fmax

Specifies minimum and maximum fluid modulus values that can result from this scaling. Effective fluid moduli will be capped at these limits. Note that if the Biot coefficient is non-zero these limits will be ignored.

limit-modulus-biot fmin fmax

Specifies minimum and maximum Biot modulus values that can result from this scaling. Effective Biot moduli will be capped at these limits.

limit-stiffness-ratio fmax

Specifies a maximum limit to the stiffness ratio of the zone \(R = \frac{\alpha^2 M}{K + {4 \over 3} G}\).

restore

Once the fluid modulus (or Biot modulus) has been scaled using this command, the original values can be restored using this keyword.

modulus-automatic <fratio > <range>

Sets the the biot modulus of zones in the range to fratio times the current mechanical confined stiffness, using the relation:

\[R_k = {{\alpha^2 M} \over {K + {4 \over 3} G}}\]

The goal is the set the fluid modulus high enough to get a reasonable transient response while not so high that the limiting timestep is too small. See the discussion in the Stiffness Ratio section of Solving Flow-Only and Coupled-Flow Problems.

If there is a currently assigned modulus (fluid-modulus or biot-modulus) and it is less than this value it will not be changed.

If fratio is not specified the default value is 20.

Note the fluid moduli will not update if the mechanical confined modulus changes later.

permeability-saturation keyword <range>

Specify how the effective permeability of the zone varies as a function of average saturation of the zone grid-points. This can vary in each zone of the model. The available keywords are:

constant

The permeability is not changed by saturation.

s-shape

The permeability is multiplied by the function \(s^2(3-2s)\)

table sname

The permeability is multiplied by the the user defined table sname, where the \(x\) value of the table is the average zone saturation and the \(y\) value is the value the permeability is multiplied by.

property keyword ... <range>

Assign fluid properties for all zones in the range. Any number of name-value pairs may be assigned. The type of the value given must match the type expected by the property s. Any constitutive model that has a matching property name will be assigned the value.

biot-coefficient f

Set the biot coefficient (grain compressibility), \(\alpha\). The default is 1.0. Note that if the biot-coefficient is set to something other than 1.0 then a biot-modulus must be specified and a fluid-modulus cannot be specified. This value is unitless.

biot-modulus f

Sets the Biot modulus. See Biot Coefficient and Biot Modulus). If the biot-coefficient is 1, this is related to the fluid-modulus by \(M = K_w/n\) where \(M\) is the Biot modulus, \(K_w\) is the fluid modulus, and \(n\) is the porosity. The default value is 0. In SI this value has units \([Pa]\).

consolidation-coefficient f

Specify the consolidation coefficient for a zone, as an alternate means of specifying the fluid modulus and/or bulk modulus. This may also be reffered to as the diffusivity coefficient. The relation between fluid modulus is:

\[c = {{k} \over {{1 \over M} + {\alpha^2 \over {K+ 4 G/3}} }}\]

as discussed in Time Scales. Note that if material moduli change this relation is updated on cycling initialization and during global update. The default value is 0. In SI this value has units \([m^2/s]\).

density-saturated b

Specifies whether saturated density is used to determine total fluid density. When the model is configured for fluid flow, the zone density used is \(\rho + \rho_{f}sn\), where \(\rho\) is the material density, \(\rho_f\) is the fluid density, \(n\) is the porosity, and \(s\) is the average zone saturation. If density-saturated is true then saturation is always considered 1.0 regardless of the actual zone saturation. The default value for this property is true.

effective-cutoff f

For the purposes of calculating effective stress in a zone, average zone pore pressure cannot fall below this value. The default is 0. If negative pore pressures are needed for effective stress calculations in this model this property must be modified in the appropriate zones. In SI this value has units \([Pa]\).

fluid-density f

Specifies the fluid density for this zone. Note this value will be used instead of the global fluid density (set with the zone fluid-density or zone fluid fluid-density command). The default value is 0. In SI this value has units \([Kg/m^3]\).

fluid-modulus f

Specify the fluid modulus in a zone. See Biot Coefficient and Biot Modulus). If the biot-coefficient is 1, this is related to the fluid-modulus by \(M = K_w/n\) where \(M\) is the Biot modulus, \(K_w\) is the fluid modulus, and \(n\) is the porosity. The default value is 0. In SI this value has units \([Pa]\).

mobility-coefficient f

Specifies an isotropic mobility coefficient for the zone. This is defined as the hydraulic conductivity divided by the unit weight of water. Or the intrinsic permeability of the medium (in \(m^2\)) divided by the dynamic viscosity. The mobility coefficient must be non zero for fluid calculations to be performed. Only one of hydraulic-conductivity or mobility-coefficient needs to be assigned. The default value is 0. In SI this value has units \([m^2/Pa.s]\).

mobility-coefficient-tensor t

Specifies an mobility coefficient tensor for the zone. This is defined as the hydraulic conductivity divided by the unit weight of water. Or the intrinsic permeability of the medium (in \(m^2\)) divided by the dynamic viscosity. The mobility coefficient must be non zero for fluid calculations to be performed. Only one of hydraulic-conductivity or mobility-coefficient needs to be assigned. In SI this value has units \([m^2/Pa.s]\).

In 3D, tensor components are specified as xx, yy, zz, xy, xz, yz. In 2D the comonents are xx, yy, xy.

hydraulic-conductivity f

Specifies an isotropic hydraulic conductivity. This is defined as the mobility coefficient times the unit weight of water. The hydraulic conductivity must be non zero for fluid calculations to be performed. Only one of hydraulic-conductivity or mobility-coefficient needs to be assigned. The default value is 0. In SI this value has units \([m/s]\).

hydraulic-conductivity-tensor t

Specifies an hydraulic conductivity tensor. This is defined as the mobility coefficient times the unit weight of water. The hydraulic conductivity must be non zero for fluid calculations to be performed. Only one of hydraulic-conductivity or mobility-coefficient needs to be assigned. In SI this value has units \([m/s]\).

In 3D, tensor components are specified as xx, yy, zz, xy, xz, yz. In 2D the comonents are xx, yy, xy.

pore-pressure-generation b

Specifies whether the zone will generate pore-pressure changes due to volumetric strain in the zone - or two way fluid coupling. By default this value is off.

porosity f

Specifies the porosity of the zone, \(n\). The default value is 0.5. This value is unitless.

undrained-thermal-coefficient f

Set the undrained thermal coefficient, \(\beta\). The default value is 0. In SI this value has units \([1/°C]\)

property-distribution s akeyword ... <range>

Assign a single property name to the fluid flow constitutive models of all zones in the range. See the property keyword above for a list of available properties. The property value may be varied in space by using the following optional keyword values.

add

Add a to the property value. This keyword only applies to float type property values.

deviation-gaussian f

A gaussian distribution is used to assign the value randomly, with a mean value of a and a standard deviation of f. This keyword only applies to float type property values.

deviation-uniform f

A uniform distribution is used to assign the value randomly, with a mean value of a and a standard deviation of f. This keyword only applies to float type property values.

gradient v <origin v >

Apply a gradient to the property value. This keyword only applies to float type property values. Note the origin keyword is optional, however, the default value (0,0,0) is used if the origin keyword is not included in the command — which may not produce the intended result.

multiply

Multiply the property value by a.

vary v

Apply a linear variation to the property value. This keyword only applies to float type property values.

saturation-tolerance f

Specify that the effect of saturation changes to gridpoints is only applied when the accumulated saturation change is greater than this value. This is done for efficiency of calculation. The default value is 1e-3.

steady-state <keyword ...>

Calculates a steady state solution for the current fluid boundary conditions of the model. This is done via a solution to the resulting set of linear equations. If an unsaturated flow model is present then the nonlinear effects are handled via Picard iteration. Note that since there is no transient response it is not necessary to specify a fluid modulus (or Biot modulus) in the model.

All current boundary conditions and sources are included. If time-varying boundary conditions are applied their values are calculated at the current fluid time only.

Because the resulting linear system is not diagonally dominant a direct solver is used rather than an iterative one, which means the solution times are longer for each matrix solve necessary.

The following keywords are available:

effective <b >

By default the solution will update the pore-pressures but not the total stresses in the zones, resulting in a change of effective stress. If the effective keyword is set to true used the effective stress is instead held constant and the total stress will be adjusted in each zone. A value of true is assumed if unspecified after the keyword.

linear-first

This option is designed to accelerate convergence to steady-state when using the cutoff unsaturated flow model. All gridpoints with the cutoff option are temporarily changed to unsaturated flow off. All gridpoints with pore pressures fixed at the cutoff (generally zero) are temporarily changed to a maximum pore-pressure instead. Then a linear steady-state solution is done – iterating to compatibility with any maximums. Once that solution is found, the previous states are restored. Any gridpoints with negative pore-pressures are set to zero saturation. Then the steady-state continues with the cutoff model active.

maximum-iterations i

Specifies the maximum number of Picard iterations allowed before the system assumes it will never converge and causes an error. The default value is 300.

minimum-relax f

Specifies the minimum iterative relaxation factor allowed. The default is 0.5. If unsaturated flow models other than cutoff are present and contain sharp gradients it may be necessary to reduce this value.

cutoff <f >

The assigned pore-pressures are not allowed to fall below this value. So regardless of the result of the linear system any pore-pressures below this value are set to the cutoff instead. If not value is given it is assumed to be 0.0. The default condition is that no negative cutoff is applied.

tolerance f

The tolerance used to determine convergence during Picard iteration. The default value is 1e-4.

relax f

If the results of a Picard iteration has a convergence value greater than the previous, than a relaxation factor is employed. Each time this happens the relaxation factor (which starts at 1.0) is reduced by multiplying by this value until either the maximum number of iterations is reached or the relaxation factor reaches a the minimum. See the minimum-relax keyword. The default value is 0.8.

timestep keyword

Options to control the timestep used in zone fluid calculations. The following keywords are available:

automatic

Removes any fixed timestep that may have been specified earlier.

fixed f

Fixes the timestep at the value f. Note that this will ignore any maximum also specified.

maximum

Set a maximum timestep allowed for fluid calculations. Note that this will apply both to the result of the explicit stable timestep and to the implicit servo if active.

time-total f

Specify the accumulated zone fluid time, defined as the sum of all the timesteps over which zone fluid is active. Once set, fluid time will continue to accumulate with subsequent cycles.

track keyword

Place a particle in the grid at the location specified. The particle flows with the fluid and maintains a record of its path over a finite period of time. The grid must be configured for fluid flow (see model configure fluid-flow), and the zone must have a non-null fluid model in order for a particle to exist in a zone. The particle is not created (and no error message is output) if the location does not map into a zone with these specifications. The particles have no mass and do not influence the flow or mechanical behavior in any way; they are simply carried along by the fluid and record its motion. Several TRACK commands may be given, at different times, if desired. See the data files in One-Dimensional Filling of a Porous Region for an example of particle track usage. Location and keywords are given as follows.

active b

Turn particle tracking on/off. track is off by default.

create keyword

Create one or more particles in zones. The location and number of the particles created are controlled by the following keywords. The <[zonefluidblock]> following can be used to specify attributes on the created particles.

point v ... [zonefluidblock]

Place a particle in the grid at the specified location v. For each vector value given, another particle will be created.

line keyword ... [zonefluidblock]

Add particles to the grid along a line.

begin v

Specify the start position of the line. The default value is (0,0,0).

end v

Specify the end position of the line. The default value is (0,0,0).

segment i

Specify the line be divided equally into i + 1 segments, causing i particles to be introduced into the grid. The default value is 2.

plane keyword ... (3D ONLY) [zonefluidblock]

Add particles to the grid along a plane defined by two lines.

begin v

Specify the shared start point of both lines that will define the plane. The default value is (0,0,0).

end-1 v

Specify the end of the first line. The default value is (0,0,0).

end-2 v

Specify the end of the second line. The default value is (0,0,0).

segment i1 i2

Divide the first line into i1 + 1 equal segments and divide the second line into i2 + 1 equal segments. i1 x i2 particles will be introduced to the grid on an evenly spaced grid along the plane. The default values of i1 and i2 are 2.

delete <range>

Delete particles within the given range.

group s keyword <range>

Assign or remove groups to particles in the range. Use of the group logic is described in Groups.

remove

Remove the group s from particles within the given range. This does not remove the particles themselves.

slot s

Assign groups in the given range to the slot named s. By default groups will be assigned to slot Default.

list <path>

List summary information about tracking particles. If the path keyword is omitted, the current particle position information is output. If the path keyword is included, then particle path information is output.

trace <name s > i

Create a location trace (see the zone fluid track command) of the particle with ID number i.

unsaturated keyword <range>

Specify the unsaturated flow model used in the grid-point. Note that this can vary in each grid-point of the model.

When a new unsaturated flow model is assigned, the saturation will be adjusted (if possible) to be consistent with the existing pore-pressure. If the cutoff unsaturated flow model is assigned and the pore pressure is below the newly assigned tension, then the saturation will become reduced to zero and the pore-pressure will be set to the cutoff value.

The available keywords are:

brooks-corey fae fpsi <fcutoff >

The Brooks-Corey model for saturation-suction. The saturation is not reduced until the pore-pressure falls below -fae. Once it does the saturation follows the relation:

\[s = (\frac{-ae}{p})^\psi\]

The optional fcutoff value specifies a limit below which the saturation cannot fall, which prevents infinitely negative pore-pressure results. The default value is 1e-4.

cutoff <fcutoff <ftension >>

Pore-pressure cannot fall below the ftension value. If it reaches that value the pore-pressure is immediately set to the cutoff value and from then on any further fluid volume removed causes the saturation in the grid-point to fall while the pore-pressure stays fixed at the cutoff. If the grid-point again becomes fully saturated the tension is reactivated. The default value for the fcutoff is 0. The default value for ftension is the same as cutoff.

gardner fa fn fref <fcutoff >

The Gardner model for saturation-suction. This model follows the relation:

\[s = \frac{1}{1+a(\frac{p}{ref})^n}\]

The optional fcutoff value specifies a limit below which the saturation cannot fall, which prevents infinitely negative pore-pressure results. The default value is 1e-4.

off

Unsaturated flow is not supported. Saturation in this grid-point is fixed at 1.0 and the pore-pressure can become infinitely negative.

table sname

Pore-pressure and saturation are related via the contents of table sname. This table contains pore-pressure (positive for this purpose) on the \(x\)-axis and saturation on the \(y\)-axis. The pore-pressure values are considered to vary exponentially for the purposes of interpolation. Note that pore-pressure values greater than zero as assumed to have saturation of 1.0.

van-genuchten fn fm fref

The Van-Genuchten model for saturation-suction. This model follows the relation:

\[s = \frac{1}{(1+(\frac{-p}{ref})^n)^m}\]

zone-based-pp b

Specify that pore-pressures should be retrieved directly from the zone, rather than averaged from the gridpoints. Zone pore pressures must be assigned manually via FISH, using the zone.pp intrinsic.

zone fluid Keyword Block

At the time of particle creation the following additional configuration settings may optionally be supplied. They apply to the keywords: line, plane and point.

group s1 <slot s2 >

Assign the created particles to the group s1 and, if supplied, assign that group to slot s2. By default the slot name will be Default.

tail b

When on (the default setting), particles will automatically store a list of coordinates along their path as they move through the grid. If off particles will only keep track of their current position.

tortuosity f

Specify the tortuosity as f. Tortuosity is the ratio of the straight line path to the actual fluid path through a zone. This factor will be used to multiply track increments calculated from the flow velocity. The value defaults to 1 if not given.