Internal Abstract Types

NonlinearSolveBase

Shared implementation layer for NonlinearSolve.jl solver packages.

NonlinearSolveBase defines the common cache, tracing, automatic differentiation, termination, and developer-extension interfaces used by the nonlinear solver subpackages. Most users should access these capabilities through NonlinearProblem, NonlinearLeastSquaresProblem, solve, and init from the public SciML interface. Solver-package authors may extend the documented developer APIs on this page.

Example

using NonlinearSolve

prob = NonlinearProblem((u, p) -> u^2 - p, 1.0, 2.0)
sol = solve(prob, NewtonRaphson())

NonlinearSolveBase.InternalAPI

Developer extension namespace for nonlinear solver implementations.

Methods in this module are public only for NonlinearSolve.jl subpackages and downstream solver packages that implement the NonlinearSolveBase interfaces. They are not intended as the user-facing cache API; user code should prefer solve, init, step!, and SciMLBase problem and solution objects.

Interface Functions

• InternalAPI.init(args...; kwargs...): construct an algorithm-specific cache.
• InternalAPI.solve!(cache, args...; kwargs...): update an internal cache and return the algorithm-specific result.
• InternalAPI.step!(cache, args...; kwargs...): advance an iterative nonlinear solver cache by one step.
• InternalAPI.reinit!(cache, args...; kwargs...): reset a cache and any nested caches for a new solve.
• InternalAPI.reinit_self!(cache, args...; kwargs...): reset only the fields owned by cache; callers use this from generated nested-cache reset implementations.

get_concrete_problem(prob; kwargs...)

Return the concrete nonlinear problem used by solver initialization after applying state and parameter overrides, numeric promotion, symbolic updates, and the problem function's specialization policy. Solver packages can use this developer API before constructing a cache or composing nonlinear subproblems.

Internal solve function that can be hooked by ChainRulesCore for AD.

AbstractNonlinearSolveAlgorithm <: AbstractNonlinearAlgorithm

Abstract Type for all NonlinearSolveBase Algorithms.

Interface Functions

• concrete_jac(alg): whether or not the algorithm uses a concrete Jacobian. Defaults to nothing.

AbstractNonlinearSolveCache <: AbstractNonlinearSolveBaseAPI

Abstract supertype for caches returned by init(prob, alg; kwargs...) for nonlinear algorithms with a stepping implementation.

This is a developer-facing interface for packages that implement nonlinear solver algorithms. It is not a replacement for the user-facing solve and init APIs. An algorithm that does not provide a stepping implementation should use NonlinearSolveNoInitCache instead of constructing a partial stepping cache.

Fields

The default CommonSolve.step!, CommonSolve.solve!, and SymbolicIndexingInterface methods read the following fields from a stepping cache:

• prob::AbstractNonlinearProblem: the problem being solved.
• alg::AbstractNonlinearSolveAlgorithm: the algorithm associated with the cache.
• p: the current parameter values.
• u: the current iterate, used by the default get_u method.
• fu: the residual at the current iterate, used by the default get_fu method.
• nsteps::Integer: the number of completed solver steps.
• maxiters::Integer: the maximum number of solver steps.
• force_stop::Bool: whether a caller or the solver has requested termination.
• retcode::SciMLBase.ReturnCode.T: the current solver status.
• stats::SciMLBase.NLStats: counters for function, Jacobian, factorization, and step work.
• termination_cache: the cache used by the termination-condition implementation.
• trace: the optional nonlinear solver trace.
• timer: the timer used by the default step! wrapper.
• verbose: the verbosity specification used by solver messages.

maxtime and total_time are also required when the cache reports a time limit through has_time_limit. A cache may store any of these values elsewhere, but then it must override every accessor or driver method that otherwise reads the default field.

Interface

• get_u: return the current iterate.
• get_fu: return the current residual vector.
• get_nsteps: return the number of completed steps.
• CommonSolve.step!: advance the cache by one step.
• CommonSolve.solve!(cache): run a stepping cache to termination and return a SciMLBase.NonlinearSolution.
• SciMLBase.reinit!(cache, u0; kwargs...): reset the cache for a new initial state and solve options.
• get_abstol and get_reltol: return the active tolerances.
• SciMLBase.set_u!, set_fu!, SciMLBase.isinplace, and the SymbolicIndexingInterface accessors: update or inspect the cache state.
• supports_deferred_residual and refresh_residual!: coordinate an optional deferred residual evaluation.

Extension Rules

• Implement NonlinearSolveBase.InternalAPI.step!(cache::YourCache; kwargs...); the public CommonSolve.step! wrapper handles termination, timing, and the top-level step counters.
• Override get_u and get_fu when the iterate or residual is stored in a nested cache or another representation. These accessors must describe the same state that step! and reinit! operate on.
• Implement NonlinearSolveBase.InternalAPI.reinit! and preserve the cache's documented invariants when SciMLBase.reinit! is called.
• Return true from supports_deferred_residual only when deferring the residual cannot change termination or trace semantics, and implement refresh_residual! for that cache.
• Generic drivers should use the documented accessors rather than reaching into algorithm-specific fields. Solver packages may add internal fields without making them part of this interface.

Examples

import NonlinearSolve
import NonlinearSolveBase

prob = NonlinearSolve.NonlinearProblem((u, p) -> u^2 - p, 1.0, 2.0)
cache = NonlinearSolve.init(prob, NonlinearSolve.NewtonRaphson())
NonlinearSolve.step!(cache)
u = NonlinearSolveBase.get_u(cache)

NonlinearSolveNoInitCache <: AbstractNonlinearSolveCache

Cache returned by init(prob, alg; kwargs...) when alg has no algorithm-specific SciMLBase.__init method. Every SimpleNonlinearSolve algorithm uses this form, for example. It stores the problem and solve options so generic code can call init on any nonlinear algorithm.

Unlike a stepping cache, it holds no iteration state and implements only part of the AbstractNonlinearSolveCache interface. solve!(cache) runs the complete solve and returns a SciMLBase.NonlinearSolution; that solution is the only record of the iterations, and no iteration state is written back into the cache. get_u(cache) reads the problem's initial state, while SciMLBase.reinit!, get_abstol, get_reltol, and the SymbolicIndexingInterface accessors operate on the stored problem as usual.

CommonSolve.step!, get_fu, get_nsteps, and cache.stats are not available for this cache. Generic code that drives caches one step at a time must detect this type and call solve!(cache) instead.

Fields

• prob::AbstractNonlinearProblem: the problem passed to init.
• alg::AbstractNonlinearSolveAlgorithm: the algorithm passed to init.
• args::Tuple: positional arguments forwarded to the eventual solve.
• kwargs::Any: keyword options forwarded to the eventual solve, including tolerances.
• initializealg: the initialization algorithm used before the solve.
• retcode::SciMLBase.ReturnCode.T: the initialization status, if initialization ran.
• verbose: the verbosity specification forwarded to the solve.

Extension Rules

This cache is the fallback produced by the package's generic initialization method; solver packages should not add step! methods to it to imitate a stepping cache. Use isa NonlinearSolveNoInitCache only to select the complete solve! path, and use the generic accessors for all other supported operations.

Examples

import NonlinearSolve
import NonlinearSolveBase

prob = NonlinearSolve.NonlinearProblem((u, p) -> u^2 - p, 1.0, 2.0)
cache = NonlinearSolve.init(prob, NonlinearSolve.SimpleNewtonRaphson())
cache isa NonlinearSolveBase.NonlinearSolveNoInitCache
sol = NonlinearSolve.solve!(cache)

get_precondition(prob, kwargs)

The left preconditioner G(fu, u, p) in effect for this solve, or nothing.

get_postcondition(prob, kwargs)

The iterate corrector H(u_proposed, u_prev, p, cache) in effect for this solve, or nothing. It may be wrapped in a PostconditionSpecifier.

get_postcondition(cache)

The iterate corrector in effect for an initialized solver cache, read from the keywords the cache was built with.

needs_conditioning(prob, kwargs)

Whether transform_conditioned_problem must run before solving. A problem whose residual has already been composed with its preconditioner is skipped, which keeps the transform idempotent across the nested solve/init/__solve entry points.

transform_conditioned_problem(prob, alg, kwargs)

Compose the precondition option into the problem's residual and apply the postcondition option once to the initial guess as H(u0, u0, p, nothing), so solves start from a corrected iterate. Reports a postcondition combined with an algorithm that does not apply it (see supports_postcondition) through the unsupported_postcondition verbosity toggle, which raises by default.

The initial guess is skipped only for a PostconditionSpace.Transformed corrector on a bounded problem: prob.u0 is still in the original coordinates here, since this pass runs before the bounds transform.

apply_postcondition!!(u, u_prev, cache)

Apply the solve's postcondition corrector to the just-committed iterate u, given the previous accepted iterate u_prev. Returns the corrected iterate (u itself for in-place problems). Solver families must call this at every iterate-commit point before evaluating the residual or testing convergence there, so residuals and Jacobians stay consistent with the corrected iterates.

Correctors always take the solver cache as their fourth argument; a corrector that does not need it simply ignores the parameter. Only the documented cache accessors (get_u, get_fu, get_nsteps, get_abstol, get_reltol) should be used on it. The argument is nothing for the initial-guess correction, which runs before any cache exists.

On a bounded problem the solver iterates on the unconstrained variable produced by the lb/ub transform, so u here is in transformed coordinates. Unless the corrector was declared PostconditionSpace.Transformed (see PostconditionSpecifier), it is applied in the original bounded variable: the iterates are mapped back, corrected, and mapped forward again.

supports_postcondition(alg)

Trait declaring whether a solver algorithm applies the postcondition corrector at its iterate-commit points. Algorithms without support must not silently ignore the option, so transform_conditioned_problem throws for them.

AbstractDescentDirection

Abstract Type for all Descent Directions used in NonlinearSolveBase. Given the Jacobian J and the residual fu, these algorithms compute the descent direction δu.

For non-square Jacobian problems, if we need to solve a linear solve problem, we use a least squares solver by default, unless the provided linsolve can't handle non-square matrices, in which case we use the normal form equations $JᵀJ δu = Jᵀ fu$. Note that this factorization is often the faster choice, but it is not as numerically stable as the least squares solver.

InternalAPI.init specification

InternalAPI.init(
    prob::AbstractNonlinearProblem, alg::AbstractDescentDirection, J, fu, u;
    pre_inverted::Val = Val(false), linsolve_kwargs = (;),
    abstol = nothing, reltol = nothing, alias_J::Bool = true,
    shared::Val = Val(1), kwargs...
)::AbstractDescentCache

• pre_inverted: whether or not the Jacobian has been pre_inverted.
• linsolve_kwargs: keyword arguments to pass to the linear solver.
• abstol: absolute tolerance for the linear solver.
• reltol: relative tolerance for the linear solver.
• alias_J: whether or not to alias the Jacobian.
• shared: Store multiple descent directions in the cache. Allows efficient and correct reuse of factorizations if needed.

Some of the algorithms also allow additional keyword arguments. See the documentation for the specific algorithm for more information.

Interface Functions

• supports_trust_region(alg): whether or not the algorithm supports trust region methods. Defaults to false.
• supports_line_search(alg): whether or not the algorithm supports line search methods. Defaults to false.

See also NewtonDescent, Dogleg, SteepestDescent, DampedNewtonDescent.

AbstractDescentCache

Abstract Type for all Descent Caches.

InternalAPI.solve! specification

InternalAPI.solve!(
    cache::AbstractDescentCache, J, fu, u, idx::Val;
    skip_solve::Bool = false, new_jacobian::Bool = true, kwargs...
)::DescentResult

• J: Jacobian or Inverse Jacobian (if pre_inverted = Val(true)).
• fu: residual.
• u: current state.
• idx: index of the descent problem to solve and return. Defaults to Val(1).
• skip_solve: Skip the direction computation and return the previous direction. Defaults to false. This is useful for Trust Region Methods where the previous direction was rejected and we want to try with a modified trust region.
• new_jacobian: Whether the Jacobian has been updated. Defaults to true.
• kwargs: keyword arguments to pass to the linear solver if there is one.

Returned values

• descent_result: Result in a DescentResult.

Interface Functions

• get_du(cache): get the descent direction.
• get_du(cache, ::Val{N}): get the Nth descent direction.
• set_du!(cache, δu): set the descent direction.
• set_du!(cache, δu, ::Val{N}): set the Nth descent direction.
• last_step_accepted(cache): whether or not the last step was accepted. Checks if the cache has a last_step_accepted field and returns it if it does, else returns true.
• preinverted_jacobian(cache): whether or not the Jacobian has been preinverted.
• normal_form(cache): whether or not the linear solver uses normal form.

supports_line_search(alg)::Bool

Return whether the descent direction alg can be used with line-search globalization.

Descent algorithms should overload this trait when their InternalAPI.solve! implementation accepts the line-search call pattern used by GeneralizedFirstOrderAlgorithm and QuasiNewtonAlgorithm.

Arguments

• alg: An AbstractDescentDirection.

Examples

using NonlinearSolveBase

NonlinearSolveBase.supports_line_search(NewtonDescent())

supports_trust_region(alg)::Bool

Return whether the descent direction alg can be used inside a trust-region method.

Descent algorithms should overload this trait when their InternalAPI.solve! method accepts a trust_region keyword and reports whether the proposed step was accepted.

Arguments

• alg: An AbstractDescentDirection.

Examples

using NonlinearSolveBase

NonlinearSolveBase.supports_trust_region(Dogleg())

set_du!(cache, δu)
set_du!(cache, δu, ::Val{N})

Store the current descent direction in cache.

This developer hook is used by descent, quasi-Newton, and spectral-method caches to expose their latest step through SciMLBase.get_du.

Arguments

• cache: An AbstractDescentCache or compatible solver cache.
• δu: The descent direction to store.
• ::Val{N}: Optional index for caches storing multiple shared directions.

last_step_accepted(cache::AbstractDescentCache) -> Bool

Return whether the most recent descent step was accepted.

The default reads cache.last_step_accepted when that field exists and returns true otherwise. Trust-region and damping cache implementations should overload this hook when acceptance is stored outside that field.

Arguments

• cache::AbstractDescentCache: A descent or trust-region cache. If the cache does not have a last_step_accepted field, the default method assumes that the step was accepted.

Returns

true when the most recent step was accepted and false when it was rejected.

Examples

mutable struct MyDescentCache <: NonlinearSolveBase.AbstractDescentCache
    δu::Vector{Float64}
    last_step_accepted::Bool
end

cache = MyDescentCache([1.0], false)
NonlinearSolveBase.last_step_accepted(cache) # false

preinverted_jacobian(cache::AbstractDescentCache) -> Bool

Return whether the cache stores an inverse Jacobian rather than the Jacobian itself.

The default reads the cache's preinverted_jacobian field and treats missing as false. Descent cache implementations should provide that field or overload this hook.

Arguments

• cache::AbstractDescentCache: A descent cache whose preinverted_jacobian field is a Bool or Val{Bool}, or a cache with a specialized method.

Returns

true when the cache stores an inverse Jacobian and false when it stores the Jacobian.

Examples

struct InvertedCache <: NonlinearSolveBase.AbstractDescentCache
    preinverted_jacobian::Val{true}
end

NonlinearSolveBase.preinverted_jacobian(InvertedCache(Val(true))) # true

normal_form(cache::AbstractDescentCache) -> Bool

Return whether the cache's linear solve uses normal-form equations.

The default reads the cache's normal_form field and treats missing as false. Descent cache implementations should provide that field or overload this hook.

Arguments

• cache::AbstractDescentCache: A descent cache whose normal_form field is a Bool or Val{Bool}, or a cache with a specialized method.

Returns

true when the cache uses normal-form equations $JᵀJ δu = Jᵀfu$ and false otherwise.

Examples

struct NormalFormCache <: NonlinearSolveBase.AbstractDescentCache
    normal_form::Val{true}
end

NonlinearSolveBase.normal_form(NormalFormCache(Val(true))) # true

DescentResult(;
    δu = missing, u = missing, success::Bool = true, linsolve_success::Bool = true,
    extras = (;)
)

Construct a DescentResult object.

Keyword Arguments

• δu: The descent direction.
• u: The new iterate. This is provided only for multi-step methods currently.
• success: Certain Descent Algorithms can reject a descent direction for example GeodesicAcceleration.
• linsolve_success: Whether the line search was successful.
• extras: A named tuple containing intermediates computed during the solve. For example, GeodesicAcceleration returns NamedTuple{(:v, :a)} containing the "velocity" and "acceleration" terms.

AbstractApproximateJacobianStructure

Abstract Type for all Approximate Jacobian Structures used in NonlinearSolve.jl.

Interface Functions

• stores_full_jacobian(alg): whether or not the algorithm stores the full Jacobian. Defaults to false.
• get_full_jacobian(cache, alg, J): get the full Jacobian. Defaults to throwing an error if stores_full_jacobian(alg) is false.

AbstractJacobianInitialization

Abstract Type for all Jacobian Initialization Algorithms used in NonlinearSolveBase.

Interface Functions

• jacobian_initialized_preinverted(alg): whether or not the Jacobian is initialized preinverted. Defaults to false.

InternalAPI.init specification

InternalAPI.init(
    prob::AbstractNonlinearProblem, alg::AbstractJacobianInitialization, solver,
    f, fu, u, p;
    linsolve = missing, internalnorm::IN = L2_NORM, kwargs...
)::AbstractJacobianCache

All subtypes need to define (cache::AbstractJacobianCache)(alg::NewSubType, fu, u) which reinitializes the Jacobian in cache.J.

AbstractApproximateJacobianUpdateRule

Abstract Type for all Approximate Jacobian Update Rules used in NonlinearSolveBase.

Interface Functions

• store_inverse_jacobian(alg): Return alg.store_inverse_jacobian

InternalAPI.init specification

InternalAPI.init(
    prob::AbstractNonlinearProblem, alg::AbstractApproximateJacobianUpdateRule, J, fu, u,
    du, args...; internalnorm = L2_NORM, kwargs...
)::AbstractApproximateJacobianUpdateRuleCache

AbstractApproximateJacobianUpdateRuleCache

Abstract Type for all Approximate Jacobian Update Rule Caches used in NonlinearSolveBase.

Interface Functions

• store_inverse_jacobian(cache): Return store_inverse_jacobian(cache.rule)
• reset_update_rule_state!(cache, fu): Reseed any residual the cache carries between iterations with fu.

InternalAPI.solve! specification

InternalAPI.solve!(
    cache::AbstractApproximateJacobianUpdateRuleCache, J, fu, u, du; kwargs...
) --> J / J⁻¹

reset_update_rule_state!(cache::AbstractApproximateJacobianUpdateRuleCache, fu)

Reseed the update rule cache with fu, the residual at the iterate the enclosing solver cache is being (re)initialized at, exactly as InternalAPI.init seeds it.

Secant-type update rules difference the current residual against the previous iterate's, which they store across iterations. That stored residual is not reachable from InternalAPI.reinit_self!, which runs on the nested caches before the enclosing cache has evaluated the residual at the new iterate, so the enclosing cache calls this afterwards instead. The default is a no-op, which is correct for update rules whose cache holds only scratch buffers.

AbstractResetCondition

Condition for resetting the Jacobian in Quasi-Newton's methods.

InternalAPI.init specification

InternalAPI.init(
    alg::AbstractResetCondition, J, fu, u, du, args...; kwargs...
)::AbstractResetConditionCache

stores_full_jacobian(alg::AbstractApproximateJacobianStructure) -> Bool

Return whether an approximate-Jacobian structure retains the full Jacobian.

The default is false. A structure that retains a full Jacobian must overload this trait and provide the corresponding get_full_jacobian behavior.

Arguments

• alg::AbstractApproximateJacobianStructure: The approximate-Jacobian structure.

Returns

true when the structure retains a full Jacobian and false otherwise.

Examples

struct LowRankStructure <: NonlinearSolveBase.AbstractApproximateJacobianStructure end

NonlinearSolveBase.stores_full_jacobian(LowRankStructure()) # false

get_full_jacobian(cache, alg::AbstractApproximateJacobianStructure, J)

Return the full Jacobian represented by an approximate-Jacobian cache.

The default returns J when stores_full_jacobian is true and throws otherwise. Implementations that store the full Jacobian in a separate buffer should overload this hook.

Arguments

• cache: The approximate-Jacobian cache, when the implementation stores the full matrix separately.
• alg::AbstractApproximateJacobianStructure: The structure describing the cache.
• J: The current Jacobian representation.

Returns

The full Jacobian represented by the cache. The default returns J only when stores_full_jacobian is true.

Examples

struct FullStructure <: NonlinearSolveBase.AbstractApproximateJacobianStructure end
NonlinearSolveBase.stores_full_jacobian(::FullStructure) = true

J = [1.0 0.0; 0.0 1.0]
NonlinearSolveBase.get_full_jacobian(nothing, FullStructure(), J) == J

jacobian_initialized_preinverted(alg::AbstractJacobianInitialization) -> Bool

Return whether a Jacobian initialization algorithm produces an inverse Jacobian.

The default is false; an initialization algorithm that constructs an inverse directly must overload this trait so the enclosing solver interprets the cache correctly.

Arguments

• alg::AbstractJacobianInitialization: The Jacobian initialization algorithm.

Returns

true when the initialization algorithm returns an inverse Jacobian and false when it returns an ordinary Jacobian.

Examples

struct DirectInverse <: NonlinearSolveBase.AbstractJacobianInitialization end
NonlinearSolveBase.jacobian_initialized_preinverted(DirectInverse()) # false by default

store_inverse_jacobian(rule) -> Bool

Return whether an approximate-Jacobian update rule stores an inverse Jacobian.

The default for a concrete rule reads its store_inverse_jacobian field. Update-rule cache implementations delegate to the rule, so the same contract applies to both forms.

Arguments

• rule::AbstractApproximateJacobianUpdateRule: The update rule whose stored Jacobian representation is being queried.

Returns

true when the rule stores an inverse Jacobian and false when it stores an ordinary Jacobian.

Examples

struct DirectUpdate <: NonlinearSolveBase.AbstractApproximateJacobianUpdateRule
    store_inverse_jacobian::Bool
end

NonlinearSolveBase.store_inverse_jacobian(DirectUpdate(true)) # true

AbstractDampingFunction

Abstract Type for Damping Functions in DampedNewton.

InternalAPI.init specification

InternalAPI.init(
    prob::AbstractNonlinearProblem, f::AbstractDampingFunction, initial_damping,
    J, fu, u, args...;
    internalnorm = L2_NORM, kwargs...
)::AbstractDampingFunctionCache

Returns a NonlinearSolveBase.AbstractDampingFunctionCache.

AbstractDampingFunctionCache

Abstract Type for the Caches created by AbstractDampingFunctions

Interface Functions

• requires_normal_form_jacobian(alg): whether or not the Jacobian is needed in normal form. No default.
• requires_normal_form_rhs(alg): whether or not the residual is needed in normal form. No default.
• returns_norm_form_damping(alg): whether or not the damping function returns the damping factor in normal form. Defaults to requires_normal_form_jacobian(alg) || requires_normal_form_rhs(alg).
• (cache::AbstractDampingFunctionCache)(::Nothing): returns the damping factor. The type of the damping factor returned from solve! is guaranteed to be the same as this.

InternalAPI.solve! specification

InternalAPI.solve!(
    cache::AbstractDampingFunctionCache, J, fu, u, δu, descent_stats
)

Returns the damping factor.

requires_normal_form_jacobian(alg) -> Bool

Return whether a damping function requires the Jacobian in normal form, $JᵀJ$.

Every concrete AbstractDampingFunction must define this trait. It is queried before the damping cache is initialized, so it must not depend on cache state. A damping cache that is passed to this trait by InternalAPI.solve! must implement the same contract.

Arguments

• alg: A damping function, or its cache when the solver queries the cache during a solve.

Returns

true when the Jacobian must be supplied as $JᵀJ$ and false when the ordinary Jacobian is sufficient.

requires_normal_form_rhs(alg) -> Bool

Return whether a damping function requires the residual in normal form, $Jᵀfu$.

Every concrete AbstractDampingFunction must define this trait. It is queried before the damping cache is initialized, so it must not depend on cache state. A damping cache that is passed to this trait by InternalAPI.solve! must implement the same contract.

Arguments

• alg: A damping function, or its cache when the solver queries the cache during a solve.

Returns

true when the residual must be supplied as $Jᵀfu$ and false when the ordinary residual is sufficient.

returns_norm_form_damping(alg) -> Bool

Return whether the damping function returns a normal-form damping factor.

The default is requires_normal_form_jacobian(alg) || requires_normal_form_rhs(alg). A concrete damping function may overload this when its returned factor uses a different representation.

Arguments

• alg: A damping function or damping cache implementing the normal-form traits.

Returns

true when the returned damping factor is in normal form and false otherwise.

Examples

struct MyDamping <: NonlinearSolveBase.AbstractDampingFunction end
NonlinearSolveBase.requires_normal_form_jacobian(::MyDamping) = true
NonlinearSolveBase.requires_normal_form_rhs(::MyDamping) = false

NonlinearSolveBase.returns_norm_form_damping(MyDamping()) # true

AbstractTrustRegionMethod

Abstract Type for all Trust Region Methods used in NonlinearSolveBase.

InternalAPI.init specification

InternalAPI.init(
    prob::AbstractNonlinearProblem, alg::AbstractTrustRegionMethod, f, fu, u, p, args...;
    internalnorm = L2_NORM, kwargs...
)::AbstractTrustRegionMethodCache

AbstractTrustRegionMethodCache

Abstract Type for all Trust Region Method Caches used in NonlinearSolveBase.

Interface Functions

• last_step_accepted(cache): whether or not the last step was accepted. Defaults to cache.last_step_accepted. Should if overloaded if the field is not present.

InternalAPI.solve! specification

InternalAPI.solve!(
    cache::AbstractTrustRegionMethodCache, J, fu, u, δu, descent_stats; kwargs...
)

Returns last_step_accepted, updated u_cache and fu_cache. If the last step was accepted then these values should be copied into the toplevel cache.

get_u(cache::AbstractNonlinearSolveCache) -> u

Return the current iterate held by a nonlinear solver cache.

The default returns cache.u. Caches that keep the iterate elsewhere should overload this hook, such as a polyalgorithm forwarding to its active subsolver or a ForwardDiff cache forwarding to its wrapped primal cache.

Arguments

• cache::AbstractNonlinearSolveCache: the cache whose current iterate is requested.

Returns

The current iterate in the representation used by the cache's solver.

Extension Rules

An overload must return the iterate that the cache will update on its next step. Generic drivers should call this accessor rather than reading cache.u directly.

Examples

u = NonlinearSolveBase.get_u(cache)

get_fu(cache::AbstractNonlinearSolveCache) -> fu

Return the residual stored in a nonlinear solver cache: the most recent value of the problem's residual function the solver evaluated (the full residual vector, not its norm, for a NonlinearLeastSquaresProblem).

The default returns cache.fu, with the same overloading convention as get_u. Between steps this is the residual at get_u, but a solver mid-step commits the new iterate before re-evaluating there. A postcondition corrector runs at exactly such a point and therefore sees the residual at the previous accepted iterate.

Arguments

• cache::AbstractNonlinearSolveCache: the cache whose residual is requested.

Returns

The full residual vector, not its norm, including for a NonlinearLeastSquaresProblem.

Extension Rules

An overload must use the same residual convention as the default and remain synchronized with get_u at cache step boundaries. Generic drivers should call this accessor instead of reading an algorithm-specific residual field.

Examples

fu = NonlinearSolveBase.get_fu(cache)

get_nsteps(cache::AbstractNonlinearSolveCache) -> Int

Return the number of solver iterations the cache has taken so far. This is the count checked against maxiters, and it counts steps of the solver loop rather than function or Jacobian evaluations, which are tracked separately in cache.stats.

Arguments

• cache::AbstractNonlinearSolveCache: the cache whose step count is requested.

Returns

The number of completed solver steps as an integer.

Extension Rules

An overload must use the same count that controls the cache's iteration limit. Function and Jacobian evaluations belong in cache.stats and must not be reported as solver steps.

Examples

nsteps = NonlinearSolveBase.get_nsteps(cache)

get_termination_cache(cache::AbstractNonlinearSolveCache)

Return the termination-condition cache through which a solver cache reports its status.

The default returns cache.termination_cache. Caches that keep it elsewhere should overload this hook, such as a polyalgorithm forwarding to its active subsolver.

Examples

tc = NonlinearSolveBase.get_termination_cache(cache)

get_trace(cache::AbstractNonlinearSolveCache)

Return the trace object a solver cache records its iteration history into.

The default returns cache.trace. Caches that keep it elsewhere should overload this hook, such as a polyalgorithm forwarding to its active subsolver.

Examples

trace = NonlinearSolveBase.get_trace(cache)

solve_cache!(cache::AbstractNonlinearSolveCache; step_observer = nothing) -> ReturnCode

Drive an initialized stepping cache to termination without constructing a SciMLBase.NonlinearSolution.

This allocation-sensitive interface is intended for nested solvers that already own a cache from init. It is available only when the cache implements the nonlinear solver iterator interface. Unlike solve!(cache), it does not transform a bounded problem's internal unconstrained state back to bounded coordinates.

Arguments

• cache::AbstractNonlinearSolveCache: an initialized cache with an InternalAPI.step! implementation.

Keywords

• step_observer = nothing: an optional callable invoked after each nonlinear step as step_observer(u, fu, iteration). The u and fu arguments alias the cache and must not be mutated.

Returns

The final SciMLBase.ReturnCode. The final state remains available through SymbolicIndexingInterface.state_values(cache).

Throws

ArgumentError if cache does not support the stepping interface.

Extension Rules

Implement NonlinearSolveBase.InternalAPI.step! on a cache before calling this function. Use solve!(cache) for NonlinearSolveNoInitCache, which intentionally has no stepping state.

Examples

import NonlinearSolve
import NonlinearSolveBase

prob = NonlinearSolve.NonlinearProblem((u, p) -> u^2 - p, 1.0, 2.0)
cache = NonlinearSolve.init(prob, NonlinearSolve.NewtonRaphson())
retcode = NonlinearSolveBase.solve_cache!(cache)

NonlinearSolveTrace(show_trace, store_trace, history, trace_level, prob)

State used by the nonlinear solver tracing utilities.

This is a developer API used by solver packages that integrate with the built-in tracing implementation. User-facing solver options should use TraceMinimal, TraceWithJacobianConditionNumber, or TraceAll instead.

Arguments

• show_trace::Val{Bool}: Whether trace information is printed during the solve.
• store_trace::Val{Bool}: Whether trace entries are retained in history.
• history: Storage for retained trace entries, or nothing when storage is disabled.
• trace_level::NonlinearSolveTracing: The information and frequency to record.
• prob::AbstractNonlinearProblem: The nonlinear problem associated with the trace.

Fields

• show_trace: The compile-time flag controlling terminal output.
• store_trace: The compile-time flag controlling history allocation and storage.
• history: A vector of NonlinearSolveTraceEntry values, or nothing.
• trace_level: The trace mode and print/store frequencies.
• prob: The associated nonlinear problem.

Returns

A NonlinearSolveTrace value that can be passed to the tracing hooks.

Examples

using NonlinearSolveBase

trace = NonlinearSolveTrace(Val(false), Val(false), nothing, TraceMinimal(), nothing)
NonlinearSolveBase.trace_is_active(trace) # false

supports_deferred_residual(cache) -> Bool

Whether cache honours step!(cache; evaluate_residual = false), that is, whether it can end a step without evaluating the residual at the iterate the step landed on and leave refresh_residual! to supply it on demand.

false for a cache that always evaluates, which is also the safe answer: a cache is free to ignore evaluate_residual = false, and a driver that gets false here simply reads a residual that is already current. A cache may only answer true where deferral is unobservable — in particular where its termination condition depends on nothing but the residual, since a deferred step reports no displacement and reaches the termination check once per refresh_residual! rather than once per step.

Arguments

• cache::AbstractNonlinearSolveCache: the cache whose deferred-residual capability is queried.

Returns

true only when the cache supports the deferred-residual protocol; otherwise false.

Extension Rules

The default is false. An overload returning true must also implement refresh_residual! and preserve the termination and trace semantics described above.

refresh_residual!(cache)

Settle a residual evaluation deferred by step!(cache; evaluate_residual = false): evaluate the problem's residual at get_u, store it, and run the convergence check the step would have run there, leaving cache in the state a plain step! would have left it in. Does nothing when no evaluation is outstanding, so a driver may call it whenever it wants to read get_fu without tracking which of its steps deferred — including on a cache that never defers, which the default here covers. A cache that answers supports_deferred_residual with true must override it.

The next step! settles an outstanding deferral itself, so a driver that only ever steps again never needs to call this.

Arguments

• cache::AbstractNonlinearSolveCache: the cache whose deferred residual should be settled.

Returns

nothing. The cache is updated in place.

Extension Rules

The default is a no-op for caches that never defer. A cache that returns true from supports_deferred_residual must evaluate and store the residual at get_u, perform the corresponding convergence update, and make repeated calls safe when no evaluation is outstanding.

residual_only_termination_mode(mode) -> Bool

Return whether mode decides termination from the residual alone, without reading the iterate or displacement from the previous iterate and without retaining per-step history.

This developer trait is used by supports_deferred_residual to determine whether a solver may honor evaluate_residual = false. A deferred step reports no displacement and reaches the termination check only when the driver requests the residual, so a mode that reads displacement or retains step history would observe a step that did not occur.

This is a developer API for packages implementing a AbstractNonlinearTerminationMode, not a user-facing solver option. A custom mode may return true only when its convergence decision depends on the current residual and tolerances, not on the iterate, displacement, or per-step history.

Arguments

• mode::AbstractNonlinearTerminationMode: The termination mode to inspect.

Returns

true for residual-only modes and false for modes that inspect displacement or retain per-step state. The default implementation returns false; solver packages should add a method for a new termination mode only when it satisfies the residual-only contract.

Examples

using NonlinearSolveBase

NonlinearSolveBase.residual_only_termination_mode(AbsTerminationMode()) # true
NonlinearSolveBase.residual_only_termination_mode(RelTerminationMode()) # false

trace_is_active(trace) -> Bool

Return whether update_trace! would record or print anything for trace.

This developer trait lets a solver skip work whose only consumer is tracing. It is part of the deferred-residual interface: a solver must not defer a residual when an active trace would need to record the resulting iterate.

This is a developer API for packages that provide a trace implementation. For a custom trace type, add a method that returns true whenever its trace-update operation would record or print the current step. Returning false for an active trace can make deferred residuals observable to users.

Arguments

• trace: A NonlinearSolveTrace, nothing, or missing.

Returns

true when trace records or prints trace data, otherwise false.

Examples

using NonlinearSolveBase

NonlinearSolveBase.trace_is_active(nothing) # false

initialization_alg(initprob, autodiff)

Select a nonlinear algorithm for the auxiliary problem in OverrideInitData. Solver packages may extend this hook for supported problem types and should preserve initprob's constraints while forwarding the requested differentiation backend.

Return nothing to leave the algorithm unspecified. When initialization is running on an existing nonlinear solver cache, this falls back to that cache's algorithm.

get_abstol(cache::AbstractNonlinearSolveCache) -> Real

Return the absolute tolerance currently stored in a nonlinear solver cache or problem.

The default reads the cache's termination_cache.

Arguments

• cache::AbstractNonlinearSolveCache: the cache whose absolute tolerance is requested.

Returns

The active absolute tolerance used by the cache's termination condition.

Extension Rules

Override this method when the cache stores its termination state somewhere other than termination_cache. The returned value must agree with the tolerance used by step!.

Examples

abstol = NonlinearSolveBase.get_abstol(cache)

get_reltol(cache::AbstractNonlinearSolveCache) -> Real

Return the relative tolerance currently stored in a nonlinear solver cache or problem.

The default reads the cache's termination_cache.

Arguments

• cache::AbstractNonlinearSolveCache: the cache whose relative tolerance is requested.

Returns

The active relative tolerance used by the cache's termination condition.

Extension Rules

Override this method when the cache stores its termination state somewhere other than termination_cache. The returned value must agree with the tolerance used by step!.

Examples

reltol = NonlinearSolveBase.get_reltol(cache)

AbstractNonlinearTerminationMode

Abstract supertype for nonlinear solver termination modes.

Concrete subtypes define how an update Δu, current iterate u, and tolerances are combined to decide whether a nonlinear solve has converged.

See also RelTerminationMode, AbsTerminationMode, NormTerminationMode, RelNormTerminationMode, and AbsNormTerminationMode.

AbstractSafeNonlinearTerminationMode <: AbstractNonlinearTerminationMode

Abstract supertype for termination modes that include stagnation or divergence safeguards.

Safe termination modes preserve the usual tolerance check while also stopping solves that stop improving according to the mode-specific objective history.

See also RelNormSafeTerminationMode, AbsNormSafeTerminationMode, RelNormSafeBestTerminationMode, and AbsNormSafeBestTerminationMode.