Nonlinear Solver Iterator Interface

There is an iterator form of the nonlinear solver which somewhat mirrors the DiffEq integrator interface:

using NonlinearSolve

f(u, p) = u .* u .- 2.0
u0 = 1.5
probB = NonlinearProblem(f, u0)

nlcache = init(probB, NewtonRaphson())

NonlinearSolve.GeneralizedFirstOrderAlgorithmCache{false, :LineSearch, false, Float64, Float64, Float64, SciMLBase.NullParameters, Float64, Float64, GeneralizedFirstOrderAlgorithm{nothing, :NewtonRaphson, NoLineSearch, Missing, NewtonDescent{Nothing, typeof(NonlinearSolve.DEFAULT_PRECS)}, Nothing, Nothing, Nothing}, NonlinearProblem{Float64, false, SciMLBase.NullParameters, NonlinearFunction{false, SciMLBase.FullSpecialize, typeof(Main.f), LinearAlgebra.UniformScaling{Bool}, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, typeof(SciMLBase.DEFAULT_OBSERVED_NO_TIME), Nothing, SymbolicIndexingInterface.SymbolCache{Nothing, Nothing, Nothing}, Nothing}, Base.Pairs{Symbol, Union{}, Tuple{}, @NamedTuple{}}, SciMLBase.StandardNonlinearProblem}, NonlinearSolve.JacobianCache{false, Float64, NonlinearFunction{false, SciMLBase.FullSpecialize, typeof(Main.f), LinearAlgebra.UniformScaling{Bool}, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, typeof(SciMLBase.DEFAULT_OBSERVED_NO_TIME), Nothing, SymbolicIndexingInterface.SymbolCache{Nothing, Nothing, Nothing}, Nothing}, SciMLBase.JacobianWrapper{false, NonlinearFunction{false, SciMLBase.FullSpecialize, typeof(Main.f), LinearAlgebra.UniformScaling{Bool}, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, typeof(SciMLBase.DEFAULT_OBSERVED_NO_TIME), Nothing, SymbolicIndexingInterface.SymbolCache{Nothing, Nothing, Nothing}, Nothing}, SciMLBase.NullParameters}, Float64, Float64, SciMLBase.NullParameters, Nothing, GeneralizedFirstOrderAlgorithm{nothing, :NewtonRaphson, NoLineSearch, Missing, NewtonDescent{Nothing, typeof(NonlinearSolve.DEFAULT_PRECS)}, Nothing, Nothing, Nothing}, Nothing, Nothing, Nothing}, NonlinearSolve.NewtonDescentCache{false, false, Float64, Nothing, NonlinearSolve.LinearSolverCache{Nothing, Nothing, Float64, Float64, Nothing}, Nothing, Nothing, TimerOutputs.TimerOutput}, NonlinearSolve.NoLineSearchCache{Float64}, Nothing, Nothing, TimerOutputs.TimerOutput, DiffEqBase.NonlinearTerminationModeCache{Float64, Float64, false, AbsSafeBestTerminationMode{Nothing, Int64, Float64, Int64}, Float64, Vector{Float64}, Nothing, SciMLBase.ReturnCode.T, Nothing, Vector{Float64}, Int64}, NonlinearSolve.NonlinearSolveTrace{false, false, TraceMinimal, Nothing}}(0.25, 1.5, 1.5, SciMLBase.NullParameters(), 1.5, 1.5, NewtonRaphson(
   descent = NewtonDescent()
), NonlinearProblem{Float64, false, SciMLBase.NullParameters, NonlinearFunction{false, SciMLBase.FullSpecialize, typeof(Main.f), LinearAlgebra.UniformScaling{Bool}, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, typeof(SciMLBase.DEFAULT_OBSERVED_NO_TIME), Nothing, SymbolicIndexingInterface.SymbolCache{Nothing, Nothing, Nothing}, Nothing}, Base.Pairs{Symbol, Union{}, Tuple{}, @NamedTuple{}}, SciMLBase.StandardNonlinearProblem}(NonlinearFunction{false, SciMLBase.FullSpecialize, typeof(Main.f), LinearAlgebra.UniformScaling{Bool}, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, typeof(SciMLBase.DEFAULT_OBSERVED_NO_TIME), Nothing, SymbolicIndexingInterface.SymbolCache{Nothing, Nothing, Nothing}, Nothing}(Main.f, LinearAlgebra.UniformScaling{Bool}(true), nothing, nothing, nothing, nothing, nothing, nothing, nothing, nothing, nothing, nothing, SciMLBase.DEFAULT_OBSERVED_NO_TIME, nothing, SymbolicIndexingInterface.SymbolCache{Nothing, Nothing, Nothing}(nothing, nothing, nothing), nothing), 1.5, SciMLBase.NullParameters(), SciMLBase.StandardNonlinearProblem(), Base.Pairs{Symbol, Union{}, Tuple{}, @NamedTuple{}}()), NonlinearSolve.JacobianCache{false, Float64, NonlinearFunction{false, SciMLBase.FullSpecialize, typeof(Main.f), LinearAlgebra.UniformScaling{Bool}, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, typeof(SciMLBase.DEFAULT_OBSERVED_NO_TIME), Nothing, SymbolicIndexingInterface.SymbolCache{Nothing, Nothing, Nothing}, Nothing}, SciMLBase.JacobianWrapper{false, NonlinearFunction{false, SciMLBase.FullSpecialize, typeof(Main.f), LinearAlgebra.UniformScaling{Bool}, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, typeof(SciMLBase.DEFAULT_OBSERVED_NO_TIME), Nothing, SymbolicIndexingInterface.SymbolCache{Nothing, Nothing, Nothing}, Nothing}, SciMLBase.NullParameters}, Float64, Float64, SciMLBase.NullParameters, Nothing, GeneralizedFirstOrderAlgorithm{nothing, :NewtonRaphson, NoLineSearch, Missing, NewtonDescent{Nothing, typeof(NonlinearSolve.DEFAULT_PRECS)}, Nothing, Nothing, Nothing}, Nothing, Nothing, Nothing}(1.5, NonlinearFunction{false, SciMLBase.FullSpecialize, typeof(Main.f), LinearAlgebra.UniformScaling{Bool}, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, typeof(SciMLBase.DEFAULT_OBSERVED_NO_TIME), Nothing, SymbolicIndexingInterface.SymbolCache{Nothing, Nothing, Nothing}, Nothing}(Main.f, LinearAlgebra.UniformScaling{Bool}(true), nothing, nothing, nothing, nothing, nothing, nothing, nothing, nothing, nothing, nothing, SciMLBase.DEFAULT_OBSERVED_NO_TIME, nothing, SymbolicIndexingInterface.SymbolCache{Nothing, Nothing, Nothing}(nothing, nothing, nothing), nothing), SciMLBase.JacobianWrapper{false, NonlinearFunction{false, SciMLBase.FullSpecialize, typeof(Main.f), LinearAlgebra.UniformScaling{Bool}, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, typeof(SciMLBase.DEFAULT_OBSERVED_NO_TIME), Nothing, SymbolicIndexingInterface.SymbolCache{Nothing, Nothing, Nothing}, Nothing}, SciMLBase.NullParameters}(NonlinearFunction{false, SciMLBase.FullSpecialize, typeof(Main.f), LinearAlgebra.UniformScaling{Bool}, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, typeof(SciMLBase.DEFAULT_OBSERVED_NO_TIME), Nothing, SymbolicIndexingInterface.SymbolCache{Nothing, Nothing, Nothing}, Nothing}(Main.f, LinearAlgebra.UniformScaling{Bool}(true), nothing, nothing, nothing, nothing, nothing, nothing, nothing, nothing, nothing, nothing, SciMLBase.DEFAULT_OBSERVED_NO_TIME, nothing, SymbolicIndexingInterface.SymbolCache{Nothing, Nothing, Nothing}(nothing, nothing, nothing), nothing), SciMLBase.NullParameters()), 1.5, 1.5, SciMLBase.NullParameters(), nothing, NewtonRaphson(
   descent = NewtonDescent()
), 0, nothing, nothing, nothing), NonlinearSolve.NewtonDescentCache{false, false, Float64, Nothing, NonlinearSolve.LinearSolverCache{Nothing, Nothing, Float64, Float64, Nothing}, Nothing, Nothing, TimerOutputs.TimerOutput}(1.5, nothing, NonlinearSolve.LinearSolverCache{Nothing, Nothing, Float64, Float64, Nothing}(nothing, nothing, 1.5, 0.25, nothing, 0, 0), nothing, nothing,  ───────────────────────────────────────────────────────────────────────────────
                                       Time                    Allocations      
                              ───────────────────────   ────────────────────────
       Tot / % measured:          37.9ms /  10.2%           5.51MiB /   0.1%    

 Section              ncalls     time    %tot     avg     alloc    %tot      avg
 ───────────────────────────────────────────────────────────────────────────────
 cache construction        1   3.86ms  100.0%  3.86ms   6.61KiB  100.0%  6.61KiB
 ───────────────────────────────────────────────────────────────────────────────), NonlinearSolve.NoLineSearchCache{Float64}(1.0), nothing, 0, 0, 1000, nothing, 9223372036854775807,  ───────────────────────────────────────────────────────────────────────────────
                                       Time                    Allocations      
                              ───────────────────────   ────────────────────────
       Tot / % measured:          38.2ms /  10.1%           5.56MiB /   0.1%    

 Section              ncalls     time    %tot     avg     alloc    %tot      avg
 ───────────────────────────────────────────────────────────────────────────────
 cache construction        1   3.86ms  100.0%  3.86ms   6.61KiB  100.0%  6.61KiB
 ───────────────────────────────────────────────────────────────────────────────, 0.0, true, DiffEqBase.NonlinearTerminationModeCache{Float64, Float64, false, AbsSafeBestTerminationMode{Nothing, Int64, Float64, Int64}, Float64, Vector{Float64}, Nothing, SciMLBase.ReturnCode.T, Nothing, Vector{Float64}, Int64}(1.5, SciMLBase.ReturnCode.Default, 3.000213634488528e-13, 3.000213634488528e-13, 0.25, AbsSafeBestTerminationMode{Nothing, Int64, Float64, Int64}(nothing, 100, 3, 1.3, 32), 0.25, [6.90834178200513e-310, 0.0, 6.90837298121985e-310, 0.0, 6.90837298121985e-310, 0.0, 6.90837298121985e-310, 0.0, 6.90834038389105e-310, 0.0  …  6.90834038389105e-310, 0.0, 6.90837298121985e-310, 0.0, 6.90837298121985e-310, 0.0, 6.90837298121985e-310, 0.0, 6.90827423349865e-310, 6.9082742335018e-310], 0, nothing, nothing, [6.9083109013592e-310, 6.9083109702691e-310, 6.90831090136236e-310, 6.90831090136394e-310, 6.9083109013655e-310, 6.9083109013671e-310, 6.9083109013687e-310, 6.90831090137027e-310, 6.90831090137185e-310, 6.90831090137343e-310  …  6.9083109014256e-310, 6.9083109014272e-310, 6.90831090142876e-310, 6.9083109702517e-310, 6.9083109702628e-310, 6.90830107990253e-310, 6.9083010799033e-310, 6.90831097026436e-310, 6.9083010798954e-310, 6.9083010798962e-310], 32, 1.5), Tracing Disabled, SciMLBase.ReturnCode.Default, false)

init takes the same keyword arguments as solve, but it returns a cache object that satisfies typeof(nlcache) <: AbstractNonlinearSolveCache and can be used to iterate the solver.

The iterator interface supports:

CommonSolve.step! — Method

step!(cache::AbstractNonlinearSolveCache;
    recompute_jacobian::Union{Nothing, Bool} = nothing)

Performs one step of the nonlinear solver.

Keyword Arguments

recompute_jacobian: allows controlling whether the jacobian is recomputed at the current step. If nothing, then the algorithm determines whether to recompute the jacobian. If true or false, then the jacobian is recomputed or not recomputed, respectively. For algorithms that don't use jacobian information, this keyword is ignored with a one-time warning.

We can perform 10 steps of the Newton-Raphson solver with the following:

for i in 1:10
    step!(nlcache)
end

We currently don't implement a Base.iterate interface but that will be added in the future.