Common Solver Options (Solve Keyword Arguments)

solve(prob::NonlinearProblem, alg::Union{AbstractNonlinearAlgorithm, Nothing}; kwargs...)

Arguments

The only positional argument is alg which is optional. By default, alg = nothing. If alg = nothing, then solve dispatches to the NonlinearSolve.jl automated algorithm selection (if using NonlinearSolve was done, otherwise it will error with a MethodError).

Keyword Arguments

The NonlinearSolve.jl universe has a large set of common arguments available for the solve function. These arguments apply to solve on any problem type and are only limited by limitations of the specific implementations.

Many of the defaults depend on the algorithm or the package the algorithm derives from. Not all of the interface is provided by every algorithm. For more detailed information on the defaults and the available options for specific algorithms / packages, see the manual pages for the solvers of specific problems.

Error Control

• abstol: Absolute tolerance.
• reltol: Relative tolerance.

These tolerances are interpreted by the termination condition.

Nonlinear Preconditioning

• precondition: a left preconditioner G applied to the residual, giving the root-equivalent system G(f(u, p), u, p) = 0. Out-of-place problems return the transformed residual, Gfu = precondition(fu, u, p); in-place problems overwrite the first argument, precondition(fu, u, p) -> nothing. The composition is what the solver evaluates and differentiates, so termination and sol.resid are measured on it. G must be root-preserving: G(r, u, p) = 0 if and only if r = 0.

• postcondition: an iterate corrector H applied to every accepted iterate before the residual is evaluated or convergence tested there, and once to the initial guess. Out-of-place problems return the corrected iterate, u_new = postcondition(u_proposed, u_prev, p, cache); in-place problems overwrite the first argument, postcondition(u_proposed, u_prev, p, cache) -> nothing. The fourth argument is the solver cache — nothing for the initial-guess correction, since that runs before a cache exists — and correctors that do not need solver state simply ignore it. H must satisfy H(u, u, p, cache) = u at solutions so that roots are unchanged.

  Native bounded algorithms apply H in the original coordinates. When an explicitly selected algorithm uses an unconstrained reparameterization for lb/ub, H is still applied in the original bounded variable by default. Wrap it in a PostconditionSpecifier to say otherwise: postcondition = PostconditionSpecifier(H; space = PostconditionSpace.Transformed) applies it to the unconstrained iterate instead.

Both are ordinary solver options: pass them to solve/init, or carry them on the problem and have them forwarded like any other keyword.

Miscellaneous

• maxiters: Maximum number of iterations before stopping. Defaults to 1000.
• verbose: Toggles whether warnings are thrown when the solver exits early. Defaults to true.

Sensitivity Algorithms (sensealg)

sensealg is used for choosing the way the automatic differentiation is performed. For more information, see the documentation for SciMLSensitivity

PostconditionSpecifier(corrector; space = PostconditionSpace.Original)

Wrapper for the postcondition solver option that declares which coordinates the iterate corrector H(u_proposed, u_prev, p, cache) is written in when the problem also carries lb/ub bounds. See PostconditionSpace for the meaning of each value.

Without lb/ub the two spaces are identical and the wrapper is unnecessary.

solve(prob, NewtonRaphson(); postcondition = H)   # PostconditionSpace.Original
solve(
    prob, NewtonRaphson();
    postcondition = PostconditionSpecifier(H; space = PostconditionSpace.Transformed)
)

PostconditionSpace

Enum declaring which coordinates a postcondition corrector is written in when the problem also carries lb/ub bounds. When the algorithm handles bounds by reparameterizing the iterate, the original and unconstrained coordinates differ. With native bound handling, both choices refer to the original coordinates.

• PostconditionSpace.Original (the default, and what a bare corrector gets): H sees the original bounded variable. The iterate is mapped back through the bounds transform, corrected, and mapped forward again at every commit point, so a limiting rule written for a physical quantity — a junction voltage in volts, a saturation in [0, 1] — means what it says. A correction landing exactly on a bound is nudged into the interior before the inverse map, since the bound itself is at infinity in the transformed variable.
• PostconditionSpace.Transformed: H sees the unconstrained variable the solver iterates on. Use this for corrections that are statements about the solver's step (damping a raw update, say), not about the model. The initial guess is then left uncorrected, since it is still in the original coordinates when the corrector would run.

Without lb/ub the two are identical.