Skip to content

Controls

Upcoming release 
*Controls, method, mode
<parameter 1>, ..., <parameter n>

The nonlinear convergence controls are evaluated separately for every active physical field. Global convergence controls are no longer supported. Overall convergence is obtained only when all active fields with free equations have converged and any additional contact-iteration requirements are fulfilled.

The convergence evaluation requires residual equilibrium together with a secondary correction or energy criterion. For numerically stagnant fields, residual equilibrium may alternatively be established by a scale-aware absolute residual safeguard. The safeguard is generated internally from machine precision and the current force scale; it is not prescribed through *Controls.

Details of the mathematical formulation and acceptance logic are provided in Section Convergence criteria of the Theory Manual.

Dof-based solution control

*Controls, dof=<degree of freedom name>, mode
epsilon^d, epsilon^e, epsilon^r, epsilon^{Delta d}, epsilon^{Delta e}, r^epsilon

This optional keyword modifies or deactivates the convergence controls for an individual physical field. If no modification is given, the default values listed below are used.

dof=<degree of freedom name>

The following user-configurable fields are available:

  • u: solid displacement in the \(x_1\)-, \(x_2\)- and \(x_3\)-directions;
  • pw: pore-water pressure;
  • pa: pore-air pressure;
  • w: water displacement in the \(x_1\)-, \(x_2\)- and \(x_3\)-directions.

The mixed-element fields J and pmean are activated automatically when required by the selected element formulation and use internal default controls.

mode

Set mode to one of the following values:

  • modify: replace the default tolerances for the selected field. A subsequent parameter line is required;
  • deactivate: suppress the convergence evaluation for the selected field. No subsequent parameter line is read.

A field can participate in convergence evaluation only if its degree of freedom exists in the model. A field whose equations are all constrained is automatically excluded from the equilibrium check and is reported with status 2 in <jobname>.conv.fields.

Parameters for modify

The parameters are prescribed in the following order:

  1. \(\epsilon^{d}\): tolerance for the ratio of the largest Newton correction to the largest accumulated solution increment;
  2. \(\epsilon^{e}\): tolerance for the relative unbalanced energy;
  3. \(\epsilon^{r}\): tolerance for the relative residual norm;
  4. \(\epsilon^{\Delta d}\): absolute threshold used to identify a negligible accumulated increment and negligible latest correction;
  5. \(\epsilon^{\Delta e}\): absolute threshold for negligible unbalanced energy;
  6. \(r^{\epsilon}\): relaxation factor for nonquadratic convergence. The default is 2.

The negligible-response threshold \(\epsilon^{\Delta d}\) does not accept a field by itself. After iteration zero, numerical stagnation is identified only when both the accumulated field increment and the latest Newton correction are not larger than \(\epsilon^{\Delta d}\). A stagnant field is accepted only if either a relaxed relative residual criterion or the internal scale-aware absolute residual criterion is also fulfilled.

Residual equilibrium remains mandatory for all normal acceptance routes. Correction and energy criteria cannot establish convergence together when the residual criterion is not fulfilled.

Relaxation

The relaxation iteration is

\[ n_{rel} = \max\left( 1, \min\left( \left\lfloor\frac{n_{max}}{2}\right\rfloor, 12 \right) \right), \]

where \(n_{max}\) is the maximum number of equilibrium iterations of the current step.

For ordinary nonlinear steps, the correction, residual and energy tolerances are multiplied by \(r^{\epsilon}\) from iteration \(n_{rel}\) onwards. For *Reduction steps, the correction tolerance is multiplied by \(r^{\epsilon}\), the residual tolerance is multiplied by 5, and the energy tolerance is not relaxed.

Independently of this late-iteration relaxation, numerical stagnation activates a residual check with \(5\epsilon^{r}\). This fixed factor is not changed by the user-defined value of \(r^{\epsilon}\).

Absolute residual safeguard

No absolute force tolerance is entered on the *Controls card. If a field has numerically stagnated, numgeo calculates a characteristic per-equation force scale from the current and stored force vectors and evaluates the largest residual component against

\[ \epsilon_{mach}^{2/3}F_{char}. \]

For IEEE double precision and a unit characteristic force scale, the limit is approximately \(3.67\cdot10^{-11}\). A fixed absolute tolerance of \(10^{-8}\) is therefore not used and would be too permissive at unit force scale.

Examples

Modify the displacement controls:

*Controls, u, modify
1e-3, 2e-3, 5e-4, 1e-6, 1e-6, 1.5

Deactivate the pore-air-pressure convergence evaluation:

*Controls, pa, deactivate

Global controls such as

*Controls, global, modify

are obsolete and must not be used.

Default values

dof \(\epsilon^{d}\) \(\epsilon^{e}\) \(\epsilon^{r}\) \(\epsilon^{\Delta d}\) \(\epsilon^{\Delta e}\) \(r^{\epsilon}\)
u \(1\cdot10^{-2}\) \(1\cdot10^{-2}\) \(1\cdot10^{-2}\) \(1\cdot10^{-6}\) \(1\cdot10^{-5}\) 2
w \(1\cdot10^{-2}\) \(1\cdot10^{-2}\) \(1\cdot10^{-2}\) \(1\cdot10^{-5}\) \(1\cdot10^{-5}\) 2
pw \(1\cdot10^{-2}\) \(1\cdot10^{-2}\) \(1\cdot10^{-2}\) \(1\cdot10^{-3}\) \(1\cdot10^{-10}\) 2
pa \(1\cdot10^{-2}\) \(1\cdot10^{-2}\) \(1\cdot10^{-2}\) \(1\cdot10^{-3}\) \(1\cdot10^{-10}\) 2

Failure handling and diagnostics

NaN, infinity and arithmetic overflow in the convergence quantities cause immediate rejection and an enforced cutback. This safeguard also applies when NOCUTBACK is active. The .msg file identifies the affected quantity and, where available, the global degree of freedom and node.

The .msg file reports the active tolerances and the exact acceptance or rejection route for every field. Two machine-readable convergence files are written:

<jobname>.conv
<jobname>.conv.fields

The existing <jobname>.conv file remains compatible with the convergence viewer and contains

step inc attempt iter rhs_ratio inc_ratio rhs_criterion inc_criterion

When the absolute stagnation safeguard is used, equivalent ratios are written so that the viewer remains consistent with the solver decision. The attempt column remains equal to 1 because the legacy report interface does not provide the actual attempt number.

The field-resolved <jobname>.conv.fields file contains

step inc iter field residual_ratio correction_ratio energy_ratio force_criterion correction_criterion energy_criterion max_abs_residual abs_component_limit status

with the status values:

  • 1: accepted;
  • 0: rejected;
  • -1: non-finite value or arithmetic overflow;
  • 2: no free equations.

Maximum solution increment

*Controls, max-<dof>, activate
tilde{Delta}_{dof}, s^{max}

This optional keyword modifies the time-step control after a successful Newton iteration. If activated, all sub-keywords are mandatory.

See Maximum solution increment for further information.

<dof>

The following solution increment can currently be controlled:

  • dpw: change in pore-water pressure.

Parameters

  • \(\widetilde{\Delta}_{dof}\): target solution increment that should not be exceeded within one increment;
  • \(s^{max}\): maximum time-scaling factor.

Example

*Controls, max-dpw, activate
50, 4

*Controls, method, mode
<parameter 1>, ..., <parameter n>

If an incremental solution strategy based on iterative methods is to be effective, realistic criteria should be used for the termination of the iteration. At the end of each iteration, the solution obtained should be checked to see whether it has converged within preset tolerances or whether the iteration is diverging. The convergence tolerance determines the speed and accuracy of a calculation. If the criterion is too coarse, the solution may be quite inaccurate. On the other hand, a criterion which is too tight results in unnecessary computations. Similarly, an ineffective divergence check can terminate the iteration when the solution is not actually diverging or force the iteration to search for an unattainable solution.

Details on the choice and formulation of convergence controls are provided in Section Convergence criteria of the Theory Manual

In numgeo we offer the user a two level approach to evaluate the convergence of the solution:

  • Per default, we evaluate the global (overall) convergence without distinguishing between different fields \(\alpha\) (e.g. solid displacement and pore water pressure). This measure gives an idea of the overall (mean) quality of the solution, however, especially in multi-field solutions, this measure could shadow non-converged fields or lead to non-convergence due to the different fields with significantly different magnitudes.

  • Advanced users may not only adapt the error tolerance of the global convergence control, but can also use controls based on each individual type of degree of freedom (e.g. solid displacements or pore water pressure). These dof-based controls may either be used in addition to the global control or can replace it, see Fig. 1.


Figure 1. Available convergence criteria in numgeo (left) and application to Newton's Method (right)

Global solution control

*Controls, dof=<degree of freedom name>, global
epsilon^r, epsilon^e, epsilon^d

Either set this parameter equal modify if you want to change the convergence criteria or set it to deactivate if you want to suppress the solution control for this specific degree of freedom. This parameter is mandatory.

  • If modify is chosen, a subsequent line <parameter 1>, <parameter 2>, <parameter 3> is required, where:

    • \(\epsilon^{r}\) = convergence criterion for negligible unbalance force

    • \(\epsilon^e\) = convergence criterion for the relative unbalanced energy

    • \(\epsilon^d\) = convergence criterion for the ratio of L2-norm of the solution correction to the L2-norm of the incremental solution value

    Example:
    *Controls, global, modify
    1e-3, 1e-3, 1e-3

  • If deactivate is chosen, no subsequent line is required.

    Example:
    *Controls, global, deactivate

  • Default values

    \(\epsilon^{r}\) \(\epsilon^e\) \(\epsilon^{d}\)
    \(5 \cdot 10^{-3}\) \(5 \cdot 10^{-3}\) \(1 \cdot 10^{-2}\)

Dof-based solution control

*Controls, dof=<degree of freedom name>, mode
epsilon^d, epsilon^e, epsilon^r, epsilon^{Delta d}, epsilon^{Delta e}, r^epsilon

This optional keyword enables the user to modify the default settings for the convergence evaluation of the solution. If activated, the convergence controls are prescribed in the order shown above. For a detailed explanation on the convergence criteria, the reader is referred to the Theory Manual.

  • dof=<degree of freedom name>

    Set this parameter equal to the degree of freedom for which the controls should be changed. This parameter is mandatory. For the following degrees of freedom the solution controls can be modified:

    • u: Solid-displacement in \(x_1\)-, \(x_2\)- and \(x_3\)-direction

    • pw: Pore-water pressure

    • pa: Pore-air pressure

    • w: Water-displacement in \(x_1\)-, \(x_2\)- and \(x_3\)-direction

  • mode

    Either set this parameter equal modify if you want to change the convergence criteria or set it to deactivate if you want to suppress the solution control for this specific degree of freedom.

    • If modify is chosen, a subsequent line is required, where:

      • \(\epsilon^{d}\) = convergence criterion for the ratio of the largest solution correction to the largest corresponding incremental solution value

      • \(\epsilon^e\) = convergence criterion for the relative unbalanced energy

      • \(\epsilon^{r}\) = convergence criterion for negligible unbalance force

      • \(\epsilon^{\Delta d}\) = criterion for negligible response, i.e. the absolute value of the solution increment or correction is smaller than the specified tolerance

      • \(\epsilon^{\Delta e}\) = criterion for negligible response, i.e. the unbalance energy is smaller than the specified tolerance

      • \(r^\epsilon > 1\) = relaxation factor for non-quadratic convergence (default is \(r^\epsilon = 2\))

      Negligible response

      The criterion \(\epsilon^{\Delta d}\) is evaluated after the first iteration of an increment. In the present implementation, a negligible solution increment or negligible correction is treated as a special convergence case for the corresponding degree of freedom. This criterion should therefore be selected with care, because it may suppress the force and energy checks for a field with very small response.

      Example:
      *Controls, u, modify
      1e-3, 2e-3, 5e-4, 1e-6, 1e-6, 1.5

    • If deactivate is chosen, no subsequent line is required.

      Example:
      *Controls, u, deactivate

    • The default values for the controls are:

      dof \(\epsilon^{d}\) \(\epsilon^e\) \(\epsilon^{r}\) \(\epsilon^{\Delta d}\) \(\epsilon^{\Delta e}\) \(r^\epsilon\)
      u \(1 \cdot 10^{-2}\) \(1 \cdot 10^{-2}\) \(1 \cdot 10^{-2}\) \(1 \cdot 10^{-6}\) \(1 \cdot 10^{-5}\) 2
      w \(1 \cdot 10^{-2}\) \(1 \cdot 10^{-2}\) \(1 \cdot 10^{-2}\) \(1 \cdot 10^{-5}\) \(1 \cdot 10^{-5}\) 2
      pw \(1 \cdot 10^{-2}\) \(1 \cdot 10^{-2}\) \(1 \cdot 10^{-2}\) \(1 \cdot 10^{-3}\) \(1 \cdot 10^{-10}\) 2
      pa \(1 \cdot 10^{-2}\) \(1 \cdot 10^{-2}\) \(1 \cdot 10^{-2}\) \(1 \cdot 10^{-3}\) \(1 \cdot 10^{-10}\) 2

    The relaxation factor \(r^\epsilon\) is used for non-quadratic convergence after \(n^{iter}_{nc}=\min(n^{iter}_{max}/2,12)\) iterations, where \(n^{iter}_{max}\) is the maximum number of iterations of the current step. In that case the solution-increment and energy tolerances are relaxed by \(r^\epsilon\).

Maximum solution increment

*Controls, max-<dof>, activate
tilde{Delta}_{dof}, s^{max}

This optional keyword enables the user to modify the default settings for time stepping after a successful Newton iteration. If activated, all sub-keywords are mandatory.

See Maximum solution increment for further information.

  • <dof>

    Set this parameter equal to the degree of freedom for which the controls should be changed. This parameter is mandatory. For the following degrees of freedom the solution controls can be modified:

    • dpw: Change in pore-water pressure

  • \(\tilde{\Delta}_{dof}\) = target solution increment that should not be exceeded in one increment

  • \(s^{max}\) = maximum time scaling factor

Example:
*Controls, max-dpw, activate
50, 4