# 7.33. Nonlinear Solve Settings

This section is referenced in the following other sections

- Releases & Deprecations: Version 5.24 (2025/03/19)
- Running & Troubleshooting: Reading the Aria log file
- Simulation Setup: Solving the problem
- Simulation Setup: Time Step Selection

## 7.33.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.33.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.33.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.33.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.33.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.33.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.33.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.33.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.33.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.33.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.33.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.33.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 . 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.33.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.33.14. Nonlinear Residual Scaling

Syntax

  Nonlinear Residual Scaling {=} {custom | dof_amax | non_dimensional | 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)

  NON_DIMENSIONAL - This option scales the nonlinear residual by the inverse of `W = D * dX_scale` resulting in a non-dimensional residual, where `D = diag(J)`, is the diagonal of the current Jacobian and `dX_scale` is a matrix whose diagonal is the DOF_AMAX residual scaling vector. Note that scaling the residual implies left scaling of the linear system (i.e., matrix rows are scaled as well). If a zero diagonal entry is encountered, the one norm of the matrix rows is used instead.

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

## 7.33.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.33.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.33.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.33.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.33.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… | –