Nonlinear Problems

The Four Types of Nonlinear Problems

NonlinearSolve.jl tackles four related types of nonlinear systems:

Interval rootfinding problems. I.e., find the $t \in [t_0, t_f]$ such that $f(t) = 0$.
Systems of nonlinear equations, i.e., find the $u$ such that $f(u) = 0$.
Steady state problems, i.e., find the $u$ such that $u' = f(u,t)$ has reached steady state, i.e., $0 = f(u, ∞)$.
The nonlinear least squares problem, which is an under/over-constrained nonlinear system which might not be satisfiable, i.e. there may be no u such that f(u) = 0, and thus we find the u which minimizes ||f(u)|| in the least squares sense.

The first is for solving scalar rootfinding problems, i.e., finding a single number, and requires that a bracketing interval is known. For a bracketing interval, one must have that the sign of f(t_0) is opposite the sign of f(t_f), thus guaranteeing a root in the interval.

Note

Interval rootfinding problems allow for f to return an array, in which case the interval rootfinding problem is interpreted as finding the first t such that any of the components of the array hit zero.

The second type of nonlinear system can be multidimensional, and thus no ordering nor boundaries are assumed to be known. For a system of nonlinear equations, f can return an array, and the solver seeks the value of u for which all outputs of f are simultaneously zero.

The last type if equivalent to a nonlinear system, but with the extra interpretation of having a potentially preferred unique root. That is, when there are multiple u such that f(u) = 0, the NonlinearProblem does not have a preferred solution, while for the SteadyStateProblem the preferred solution is the u(∞) that would arise from solving the ODE u' = f(u,t).

Warning

Most solvers for SteadyStateProblem do not guarantee the preferred solution and instead will solve for some u in the set of solutions. The documentation of the nonlinear solvers will note if they return the preferred solution.

Problem Construction Details

SciMLBase.IntervalNonlinearProblem — Type

Defines an interval nonlinear system problem. Documentation Page: https://docs.sciml.ai/NonlinearSolve/stable/basics/nonlinear_problem/

Mathematical Specification of an Interval Nonlinear Problem

To define a Nonlinear Problem, you simply need to give the function $f$ which defines the nonlinear system:

\[f(t,p) = u = 0\]

along with an interval tspan, $t \in [t_0,t_f]$, within which the root should be found. f should be specified as f(t,p) (or in-place as f(u,t,p)), and tspan should be a Tuple{T,T} where T <: Number.

Note

The output value u is not required to be a scalar. When u is an AbstractArray, the problem is a simultaneous interval nonlinear problem where the solvers are made to give the first t for which any of the u hit zero. Currently, none of the solvers support this mode.

Problem Type

Constructors

IntervalNonlinearProblem(f::NonlinearFunction, tspan, p = NullParameters(); kwargs...)
IntervalNonlinearProblem{isinplace}(f, tspan, p = NullParameters(); kwargs...)

isinplace optionally sets whether the function is in-place or not. This is determined automatically, but not inferred.

Parameters are optional, and if not given, then a NullParameters() singleton will be used, which will throw nice errors if you try to index non-existent parameters. Any extra keyword arguments are passed on to the solvers. For example, if you set a callback in the problem, then that callback will be added in every solve call.

Fields

f: The function in the problem.
tspan: The interval in which the root is to be found.
p: The parameters for the problem. Defaults to NullParameters.
kwargs: The keyword arguments passed on to the solvers.

SciMLBase.NonlinearProblem — Type

Defines a nonlinear system problem. Documentation Page: https://docs.sciml.ai/NonlinearSolve/stable/basics/nonlinear_problem/

Mathematical Specification of a Nonlinear Problem

To define a Nonlinear Problem, you simply need to give the function $f$ which defines the nonlinear system:

\[f(u,p) = 0\]

and an initial guess $u₀$ of where f(u, p) = 0. f should be specified as f(u, p) (or in-place as f(du, u, p)), and u₀ should be an AbstractArray (or number) whose geometry matches the desired geometry of u. Note that we are not limited to numbers or vectors for u₀; one is allowed to provide u₀ as arbitrary matrices / higher-dimension tensors as well.

Problem Type

Constructors

NonlinearProblem(f::NonlinearFunction, u0, p = NullParameters(); kwargs...)
NonlinearProblem{isinplace}(f, u0, p = NullParameters(); kwargs...)

isinplace optionally sets whether the function is in-place or not. This is determined automatically, but not inferred.

For specifying Jacobians and mass matrices, see the NonlinearFunctions page.

Fields

f: The function in the problem.
u0: The initial guess for the root.
p: The parameters for the problem. Defaults to NullParameters.
kwargs: The keyword arguments passed on to the solvers.

SciMLBase.SteadyStateProblem — Type

Defines a steady state ODE problem. Documentation Page: https://docs.sciml.ai/DiffEqDocs/stable/types/steadystatetypes/

Mathematical Specification of a Steady State Problem

To define a Steady State Problem, you simply need to give the function $f$ which defines the ODE:

\[\frac{du}{dt} = f(u, p, t)\]

and an initial guess $u_0$ of where f(u, p, t) = 0. f should be specified as f(u, p, t) (or in-place as f(du, u, p, t)), and u₀ should be an AbstractArray (or number) whose geometry matches the desired geometry of u. Note that we are not limited to numbers or vectors for u₀; one is allowed to provide u₀ as arbitrary matrices / higher dimension tensors as well.

Note that for the steady-state to be defined, we must have that f is autonomous, that is f is independent of t. But the form which matches the standard ODE solver should still be used. The steady state solvers interpret the f by fixing $t = \infty$.

Problem Type

Constructors

SteadyStateProblem(f::ODEFunction, u0, p = NullParameters(); kwargs...)
SteadyStateProblem{isinplace, specialize}(f, u0, p = NullParameters(); kwargs...)

isinplace optionally sets whether the function is inplace or not. This is determined automatically, but not inferred. specialize optionally controls the specialization level. See the specialization levels section of the SciMLBase documentation for more details. The default is AutoSpecialize.

Parameters are optional, and if not given, a NullParameters() singleton will be used, which will throw nice errors if you try to index non-existent parameters. Any extra keyword arguments are passed on to the solvers. For example, if you set a callback in the problem, then that callback will be added in every solve call.

Additionally, the constructor from ODEProblems is provided:

SteadyStateProblem(prob::ODEProblem)

For specifying Jacobians and mass matrices, see the DiffEqFunctions page.

Fields

f: The function in the ODE.
u0: The initial guess for the steady state.
p: The parameters for the problem. Defaults to NullParameters
kwargs: The keyword arguments passed onto the solves.

Special Solution Fields

The SteadyStateSolution type is different from the other DiffEq solutions because it does not have temporal information.

SciMLBase.NonlinearLeastSquaresProblem — Type

Defines a nonlinear least squares problem.

Mathematical Specification of a Nonlinear Least Squares Problem

To define a Nonlinear Problem, you simply need to give the function $f$ which defines the nonlinear system:

\[\underset{x}{\min} \| f(x, p) \|\]

and an initial guess $u_0$ for the minimization problem. $f$ should be specified as $f(u, p)$ (or in-place as $f(du, u, p)$), and $u_0$ should be an AbstractArray (or number) whose geometry matches the desired geometry of $u$. Note that we are not limited to numbers or vectors for $u_0$; one is allowed to provide $u_0$ as arbitrary matrices / higher-dimension tensors as well.

Problem Type

Constructors

NonlinearLeastSquaresProblem(f::NonlinearFunction, u0, p = NullParameters(); kwargs...)
NonlinearLeastSquaresProblem{isinplace}(f, u0, p = NullParameters(); kwargs...)

isinplace optionally sets whether the function is in-place or not. This is determined automatically, but not inferred.

Parameters are optional, and if not given, then a NullParameters() singleton will be used, which will throw nice errors if you try to index non-existent parameters.

For specifying Jacobians and mass matrices, see the NonlinearFunctions page.

Fields

f: The function in the problem.
u0: The initial guess for the solution.
p: The parameters for the problem. Defaults to NullParameters.
kwargs: The keyword arguments passed on to the solvers.