Nonlinear solver parameters

PETSc SNES

The petscsnes adapter delegates nonlinear globalization to PETSc SNES while retaining OOFEM’s residual and tangent assembly. It is selected in a StaticStructural engineering-model or meta-step record.

PETSc SNES solver options

solvertype (s) smtype (in) [snesmaxiter (in)] [snesmaxfunc (in)] [snesatol (rn)] [snesrtol (rn)] [snesstol (rn)] [snestype (s)] [snesoptionsprefix (s)] [snesmonitor (in)] [soldepextforces] [snesfieldscaling (in)] [snesminscalesquared (rn)] [forcescaledofs (ia)] [forcescale (ra)] [snesbounddofs (ia)] [sneslowerbounds (ra)] [snesupperbounds (ra)] [snesirreversibledofs (ia)] [snestrustregion (in)] [snestrdelta0 (rn)] [snestrdeltamin (rn)] [snestrdeltamax (rn)] [snestrmaxtrials (in)]

solvertype (s)

Set to petscsnes.

smtype (in)

Set to 7, the PETSc sparse matrix storage.

This solver requires an OOFEM build with PETSc. It currently supports only an OOFEM model running in serial; shared-memory assembly may still be used. The adapter fixes the load factor at one and does not provide arc-length or other indirect load control. Each attempted solve invokes SNESSolve once; cutbacks invoke it again for the reduced step. A failed SNES solve is reported as nonconvergence so that the engineering model can apply its usual cutback and restart procedure.

The residual supplied to PETSc is the internal force minus the external force, and its Jacobian is the OOFEM tangent. SNES uses a separate PETSc matrix so that residual row scaling does not modify the physical OOFEM tangent.

Basic options

[snesmaxiter (in)]

Maximum number of nonlinear iterations. The default is 50 and the value must be positive.

[snesmaxfunc (in)]

Maximum number of residual evaluations. The default is 10000 and the value must be positive.

[snesatol (rn)]

Absolute residual tolerance. The default is 1.e-50 and the value must be non-negative.

[snesrtol (rn)]

Relative residual tolerance. The default is 1.e-8 and the value must be non-negative.

[snesstol (rn)]

Relative step tolerance. The default is 1.e-12 and the value must be non-negative.

[snestype (s)]

PETSc SNES type name. The default is newtonls and the string must not be empty. Other PETSc types can also be selected through PETSc run-time options.

[snesmonitor (in)]

If nonzero, print the OOFEM SNES iteration monitor. The default is 1. The output also follows OOFEM’s iteration-log and problem-scale filtering. PETSc’s own monitors can independently be enabled at run time.

[soldepextforces]

Reassemble ExternalRhs at every SNES trial solution and after state restoration. By default the external-force vectors passed to the solver remain fixed. This option disables support for the compact custom equation numbering used by staggered solves.

Residual scaling

[snesfieldscaling (in)]

If nonzero, scale the residual and corresponding Jacobian rows by DOF group. The default is 1. The scale is constructed at the first admissible residual evaluation and remains fixed during that nonlinear solve. Consequently, the SNES residual tolerances apply to the scaled norm.

[snesminscalesquared (rn)]

Positive threshold below which a DOF group is left unscaled. The default is 1.e-6 and the value must be finite and positive.

[forcescaledofs (ia)]

DOF identifiers for which characteristic forces are supplied. Specify together with [forcescale (ra)]; both arrays must have the same length and a DOF identifier may occur only once.

[forcescale (ra)]

Positive, finite characteristic force corresponding to every entry in [forcescaledofs (ia)].

For a DOF group \(d\), the squared characteristic force is formed from the squared external-force norm, the sum of squared element-force contributions, and, when specified, \(n_d f_d^2\), where \(n_d\) is the number of active equations in the group and \(f_d\) is its forcescale value. If this sum is at least snesminscalesquared, the residual and tangent rows in the group are multiplied by the inverse square root of the sum. Otherwise they are left unscaled. forcescale and snesminscalesquared have no effect when snesfieldscaling is zero.

Variable bounds

[snesbounddofs (ia)]

DOF identifiers to be bounded. Specify together with [sneslowerbounds (ra)] and [snesupperbounds (ra)]; all three arrays must have equal lengths and a DOF identifier may occur only once. A bound is applied to every active equation having the corresponding DOF identifier.

[sneslowerbounds (ra)]

Finite lower bound corresponding to every entry in [snesbounddofs (ia)].

[snesupperbounds (ra)]

Finite upper bound corresponding to every entry in [snesbounddofs (ia)]. Each lower bound must not exceed its upper bound.

Bounds require the SNES type vinewtonrsls or vinewtonssls. This requirement is checked after PETSc run-time options have been applied.

[snesirreversibledofs (ia)]

Bounded DOF identifiers whose value may not decrease during a step. The default is an empty list. Every identifier must also occur in snesbounddofs. Its effective lower bound is the larger of the specified lower bound and the accepted value at the beginning of the step. That reference value is retained across cutbacks and staggered sweeps.

PETSc’s VI active-bound tolerance defaults to 1.e-8 and can be changed with -snes_vi_zero_tolerance or its prefixed equivalent.

Bounded trust region

[snestrustregion (in)]

Enable OOFEM’s bounded reduced-space trust-region line search when set to 1. The default is 0. This is distinct from selecting PETSc’s newtontr SNES type. It requires at least one variable bound, and the selected SNES type must resolve to vinewtonrsls after run-time options have been processed.

[snestrdelta0 (rn)]

Initial trust-region radius. The default is 1.

[snestrdeltamin (rn)]

Minimum trust-region radius. The default is 1.e-8 and it must be positive.

[snestrdeltamax (rn)]

Maximum trust-region radius. The default is 1.e8.

[snestrmaxtrials (in)]

Maximum number of trial points in one trust-region step. The default is 20 and the value must be positive.

The three radii must be finite and satisfy

\[0 < \mathtt{snestrdeltamin} \leq \mathtt{snestrdelta0} \leq \mathtt{snestrdeltamax}.\]

The trust-region metric is balanced by DOF group and is frozen from the first full Newton direction of the nonlinear solve.

PETSc run-time options

[snesoptionsprefix (s)]

PETSc options prefix assigned to this SNES object. The default is an empty string. It must not start with -, which PETSc adds automatically; a trailing underscore is customary. For example, snesoptionsprefix "nl_" selects options such as -nl_snes_type, -nl_ksp_type, -nl_pc_type, -nl_snes_linesearch_type, and -nl_snes_vi_zero_tolerance.

PETSc options are processed after the OOFEM input fields and therefore override the input SNES type, tolerances, iteration limits, and PETSc KSP/PC choices. When snestrustregion 1 is used, its shell line search is installed after PETSc options are processed and therefore replaces any run-time line-search type.

The tangent predictor used by StaticStructural has a separate, unprefixed PETSc KSP. Without snesoptionsprefix, global -ksp_* and -pc_* options affect both that predictor and SNES’s inner linear solve. With a prefix, unprefixed KSP/PC options affect the predictor, while prefixed KSP/PC options affect SNES.

Each meta-step record is self-contained. Omitted SNES fields are reset to the defaults above instead of inheriting values from the preceding meta-step.

Example

A minimal StaticStructural analysis record using the default tangent predictor and default newtonls SNES type is

StaticStructural nsteps 1 smtype 7 solvertype "petscsnes" snesrtol 1.e-10 snesatol 1.e-12

PETSc algorithms and preconditioners may then be selected at run time, for example:

oofem -f model.in -snes_type newtonls -ksp_type preonly -pc_type lu