Nonlinear Solutions

abstract type AbstractNonlinearSolution{T, N} <: SciMLBase.AbstractNoTimeSolution{T, N}

struct NonlinearSolution{T, N, uType, R, P, A, O, uType2, S, Tr} <: SciMLBase.AbstractNonlinearSolution{T, N}

Representation of the solution to a nonlinear equation defined by a NonlinearProblem, or the steady state solution to a differential equation defined by a SteadyStateProblem.

Fields

• u: the representation of the nonlinear equation's solution.
• resid: the residual of the solution.
• prob: the original NonlinearProblem/SteadyStateProblem that was solved.
• alg: the algorithm type used by the solver.
• original: if the solver is wrapped from an alternative solver ecosystem, such as NLsolve.jl, then this is the original return from said solver library.
• retcode: the return code from the solver. Used to determine whether the solver solved successfully or whether it exited due to an error. For more details, see the return code documentation.
• left: if the solver is bracketing method, this is the final left bracket value.
• right: if the solver is bracketing method, this is the final right bracket value.
• stats: statistics of the solver, such as the number of function evaluations required.

mutable struct NLStats

Statistics from the nonlinear equation solver about the solution process.

Fields

• nf: Number of function evaluations.
• njacs: Number of Jacobians created during the solve.
• nfactors: Number of factorzations of the jacobian required for the solve.
• nsolve: Number of linear solves W required for the solve.
• nsteps: Total number of iterations for the nonlinear solver.

ImmutableNLStats(nf, njacs, nfactors, nsolve, nsteps)

Statistics from the nonlinear equation solver about the solution process.

Fields

• nf: Number of function evaluations.
• njacs: Number of Jacobians created during the solve.
• nfactors: Number of factorzations of the jacobian required for the solve.
• nsolve: Number of linear solves W required for the solve.
• nsteps: Total number of iterations for the nonlinear solver.

ReturnCode.Success

The success state of the solver. If this return code is given, then the solving process was successful, but no extra information about that success is given.

Common Reasons for Seeing this Return Code

• This is the most common return code and most solvers will give this return code if the solving process went as expected without any errors or detected numerical issues.

Properties

• successful_retcode = true

ReturnCode.ConvergenceFailure

A failure exit state of the solver. If this return code is given, then the solving process was unsuccessful because internal nonlinear solver iterations failed to converge.

Common Reasons for Seeing this Return Code

• The most common reason for seeing this return code is because an inappropriate nonlinear solver was chosen. If fixed point iteration is used on a stiff problem, it will be faster by avoiding the Jacobian but it will make a stiff ODE solver not stable for stiff problems!
• For nonlinear solvers, this can occur if certain threshold was exceeded. For example, in approximate jacobian solvers like Broyden, Klement, etc. if the number of jacobian resets exceeds the threshold, then this return code is given.

Properties

• successful_retcode = false

ReturnCode.Unstable

A failure exit state of the solver. If this return code is given, then the solving process was unsuccessful and exited early because the unstable_check function, as given by the unstable_check common keyword argument (or its default), give a true at the current state.

Common Reasons for Seeing this Return Code

• The most common reason for seeing this return code is because u contains a NaN or Inf value. The default unstable_check only checks for these values.

Properties

• successful_retcode = false

ReturnCode.MaxIters

A failure exit state of the solver. If this return code is given, then the solving process was unsuccessful and exited early because the solver's iterations hit the maxiters either set by default or by the user in the solve/init command.

Note about Nonlinear Optimization

In nonlinear optimization, many solvers (such as OptimizationOptimisers.Adam) do not have an exit criteria other than iters == maxiters. In this case, the solvers will iterate until maxiters and exit with a Success return code, as that is a successful run of the solver and not considered to be an error state. Solves with early termination criteria, such as Optim.BFGS exiting when the gradient is sufficiently close to zero, will give ReturnCode.MaxIters on exits which require the maximum iteration.

Common Reasons for Seeing this Return Code

• This commonly occurs in ODE solving if a non-stiff method (e.g. Tsit5) is used in an algorithm choice for a stiff ODE. It is recommended that in such cases, one tries a stiff ODE solver.
• This commonly occurs in optimization and nonlinear solvers if the tolerance on solve to too low and cannot be achieved due to floating point error or the condition number of the solver matrix. Double check that the chosen tolerance is numerically possible.

Properties

• successful_retcode = false

ReturnCode.Failure

A failure exit state of the solver. If this return code is given, then the solving process was unsuccessful but no extra information is given.

Common Reasons for Seeing this Return Code

• The most common reason for seeing this return code is because the solver is a wrapped solver (i.e. a Fortran code) which does not provide any extra information about its exit state. If this is from a Julia-based solver, please open an issue.

Properties

• successful_retcode = false

ReturnCode.InternalLineSearchFailed

Internal Line Search used by the algorithm has failed.

Properties

• successful_retcode = false

ReturnCode.Stalled

The solution has stalled. This is only returned by algorithms for which stalling is a failure mode. Certain solvers like Nonlinear Least Squares solvers are considered successful if the solution has stalled, in those cases ReturnCode.Success is returned.

Properties

• successful_retcode = false

ReturnCode.ShrinkThresholdExceeded

The trust region radius was shrunk more times than the provided threshold.

Properties

• successful_retcode = false