7.31. Nonlinear Solve Settings

This section is referenced in the following other sections

7.31.1. Accept Solution After Maximum Nonlinear Iterations

Syntax: Accept Solution After Maximum Nonlinear Iterations {=} {false | no | off | on | true | yes}
Summary: Specifies whether solution is considered to be converged after MAXIMUM NONLINEAR ITERATIONS even if none of the convergence criteria are satisfied.

Parameter	Value	Default
{=}	{= \| are \| is}	–
Bool	{false \| no \| off \| on \| true \| yes}	FALSE

7.31.2. Filter Nonlinear Solution

Syntax: Filter Nonlinear Solution For AssociatedDoF FilterType {=} Values…
Summary: Restrict the value of a solution variable used in the nonlinear solver iterations of a solution step.
Description: The nonlinear solution can be restricted to a range with upper and lower limits using the FILTER_TYPE = RANGE while supplying two bounding values. To set an upper or lower bound use FILTER_TYPE = MAXIMUM or FILTER_TYPE = MINIMUM while supplying a single bounding value.

Parameter	Value	Default
AssociatedDoF	string	–
FilterType	string	–
{=}	{= \| are \| is}	–
Values	string…	–

7.31.3. Maximum Accepted Nonlinear Correction

Syntax: Maximum Accepted Nonlinear Correction {=} mnlc
Summary: Maximum allowed nonlinear correction tolerance during residual acceptance.

Parameter	Value	Default
{=}	{= \| are \| is}	–
mnlc	real	1e16

7.31.4. Maximum Accepted Nonlinear Residual

Syntax: Maximum Accepted Nonlinear Residual {=} mnlr
Summary: Maximum allowed nonlinear residual tolerance during nonlinear correction acceptance.

Parameter	Value	Default
{=}	{= \| are \| is}	–
mnlr	real	1e16

7.31.5. Maximum Line Search Steps

Syntax: Maximum Line Search Steps {=} MaxSteps
Summary: Maximum number of line search steps per nonlinear iteration.
Description: Only applicable when the LINE_SEARCH nonlinear solution strategy is used.

Parameter	Value	Default
{=}	{= \| are \| is}	–
MaxSteps	integer	10

7.31.6. Maximum Nonlinear Iterations

Syntax: Maximum Nonlinear Iterations {=} Np
Summary: Number of allowable nonlinear iterations in one linear solution step.
Description: The solution step will terminate when the number of nonlinear iterations are exceeded. Default value = 20.

Parameter	Value	Default
{=}	{= \| are \| is}	–
Np	integer	20

7.31.7. Minimum Nonlinear Solves

Syntax

Minimum Nonlinear Solves {=} Np

Summary

Minimum number of actual nonlinear solves that are required.

Description

Each nonlinear iteration involves first assembling the nonlinear residual and Jacobian matrix and second solving the linear system for a nonlinear correction that is applied to the estimate of the nonlinear solution.

The nonlinear solver will continue iterating until this minimum number of solves are performed. The default value is one (1) but setting this to zero can be useful in some situations.

This command is identical to “minimum nonlinear iterations = X”.

Parameter	Value	Default
{=}	{= \| are \| is}	–
Np	integer	1

7.31.8. Nonlinear Correction Ratio Tolerance

Syntax: Nonlinear Correction Ratio Tolerance {=} Pt
Summary: Convergence tolerance for the nonlinear correction. It is satisfied if the nonlinear correction is less than this specified multiple of the initial nonlinear correction.

Parameter	Value	Default
{=}	{= \| are \| is}	–
Pt	real	–

7.31.9. Nonlinear Correction Scaling

Syntax

Nonlinear Correction Scaling {=} {dof_amax | none}

Summary

Specifies how to scale the nonlinear correction norm.

Description

NONE (default) - The unscaled nonlinear corrections will be used.

DOF_AMAX (recommended) - The corrections for each equation will be scaled by max(1., abs(max(solution_N)))

Parameter	Value	Default
{=}	{= \| are \| is}	–
Strategy	{dof_amax \| none}	NONE

7.31.10. Nonlinear Correction Tolerance

Syntax: Nonlinear Correction Tolerance {=} Pt
Summary: Convergence tolerance of nonlinear correction norm for the iteration. Satisfaction of this criterion is sufficient for the iteration to be considered finished.

Parameter	Value	Default
{=}	{= \| are \| is}	–
Pt	real	1.0e-6

7.31.11. Nonlinear Relaxation Factor

Syntax

Nonlinear Relaxation Factor {=} Prf

Summary

Weighting factor for fraction of a new nonlinear solution that will be applied to the linear solution update. Weighting factor must lie in the range 0.0 to 1.0.

Functions of iteration count (i) are also supported. The function string must be enclosed in quotes if it has spaces or commas.

Parameter	Value	Default
{=}	{= \| are \| is}	–
Prf	“string”	1.0

7.31.12. Nonlinear Residual Minimum Convergence Rate

Syntax: Nonlinear Residual Minimum Convergence Rate {=} MinRate [ Number Of Steps {=} MinSteps ]
Summary: Set a minimum convergence rate based on the nonlinear residual At each nonlinear iteration the condition $resid_N / resid_{N-MinSteps} \lt MinRate^{MinSteps}$ . If that condition is not met then the time step fails and is retried with a shorter dt. The usage of this test is modified if the command “USE SECONDARY LINEAR SOLVER” is specified. See the description of that command for details.

Parameter	Value	Default
{=}	{= \| are \| is}	–
MinRate	real	–

7.31.13. Nonlinear Residual Ratio Tolerance

Syntax: Nonlinear Residual Ratio Tolerance {=} Pt
Summary: Convergence tolerance for the ratio of the nonlinear residual to the initial nonlinear residual for the solution iteration. Convergence is satisfied if the ratio is less than this specified multiple of the initial nonlinear residual.

Parameter	Value	Default
{=}	{= \| are \| is}	–
Pt	real	0.0

7.31.14. Nonlinear Residual Scaling

Syntax

Nonlinear Residual Scaling {=} {custom | dof_amax | none}

Summary

Specifies how to scale the nonlinear residuals.

Description

NONE - The unscaled nonlinear residuals will be used.

DOF_AMAX (recommended) - The residuals for each equation will be scaled by max(1., abs(max(solution_N)))

CUSTOM - Provide scales for individual DoFs (default 1)

This option will only affect problems using Tpetra-based linear solvers.

Parameter	Value	Default
{=}	{= \| are \| is}	–
Strategy	{custom \| dof_amax \| none}	NONE

7.31.15. Nonlinear Residual Tolerance

Syntax: Nonlinear Residual Tolerance {=} Pt
Summary: Convergence tolerance of nonlinear residual for the iteration. Satisfaction of this criterion is sufficient for the iteration to be considered finished.

Parameter	Value	Default
{=}	{= \| are \| is}	–
Pt	real	1.0e-6

7.31.16. Nonlinear Solution Strategy

Syntax: Nonlinear Solution Strategy {=} {line_search | newton | newton_finite_difference | newton_lagged} [ FormulationType ]
Summary: Specifies the nonlinear solution strategy.
Description: There is no default value so this line command is required.

Parameter	Value	Default
{=}	{= \| are \| is}	–
Strategy	{line_search \| newton \| newton_finite_difference \| newton_lagged}	–

7.31.17. Use Dof Averaged Nonlinear Residual

Syntax: Use Dof Averaged Nonlinear Residual
Summary: Select whether to use a nonlinear residual normalized by the number of degrees of freedom instead of the raw global residual reported by the linear system.
Description: Specifies that the reported nonlinear residual is scaled (divided by) the number of DOF in the problem. In selecting appropriate values for the NONLINEAR RESIDUAL TOLERANCE users are cautioned that the average nonlinear residual reported values may be several orders of magnitude smaller than when using the global nonlinear residual. This option is provided to allow comparison with residual values from other applications.

7.31.18. Use Linear Solver

Syntax: Use Linear Solver Solver [ SolverName ]
Summary: Specifies which solver to use with this region, optionally providing a name for the solver (default: the_linear_solver)

Parameter	Value	Default
Solver	string	–

7.31.19. Use Secondary Linear Solver

Syntax

Use Secondary Linear Solver Solver… [ For NumSteps… Steps ]

Summary

Specifies which auxiliary solver(s) to use with this region. Every nonlinear solve will begin employing either the primary solver specified by the command “USE LINEAR SOLVER”, of one of the auxiliary solver(s) specified by this command. A new auxiliary solver will take over for the current solver in two cases. First, if the current linear solver fails due to a critical numerical issue (e.g. solver breakdown), the time step is failed and the next linear solver is used. Second, if the current linear solver fails due to a loss of accuracy (-3) or does not converge in the maximum iteration count, the nonlinear residual is observed. If the nonlinear residual fails to decrease, the time step is failed and the next linear solver is used. Note that, in both cases, the time step is re-tried at the same time step size. This process is repeated until all auxiliary solvers have been tried. If none of the auxiliary solvers work, the time step will fail with the usual new time step size selection. This command allows for successively more robust solvers to be used if the linear solver struggles to converge at some point in a simulation. This only functions if both the primary and auxiliary solver(s)s are Tpetra-based. This should be considered a feature for expert users.

By default, each auxiliary solver is active for 10 time steps once it has been activated. You can change that by adding the optional “FOR X1, X2, …, XN STEPS” command suffix, where the step count order corresponds to the solver order specified in this command. After the number of time steps, the previous auxiliary or primary linear solver is restored.

Parameter	Value	Default
Solver	string…	–