OptimizationFunction

SciMLBase.OptimizationFunctionType

OptimizationFunction{iip,AD,F,G,H,HV,C,CJ,CH,HP,CJP,CHP,S,HCV,CJCV,CHCV} <: AbstractOptimizationFunction{iip}

A representation of an optimization of an objective function f, defined by:

\[min_{u} f(u,p)\]

and all of its related functions, such as the gradient of f, its Hessian, and more. For all cases, u is the state and p are the parameters.

Constructor

OptimizationFunction{iip}(f,adtype::AbstractADType=NoAD(); grad=nothing,hess=nothing,hv=nothing, cons=nothing, consj=nothing,consh=nothing, hessprototype=nothing,consjacprototype=nothing, conshessprototype = nothing, syms = nothing, hesscolorvec = nothing, consjaccolorvec = nothing, conshesscolorvec = nothing)

  • adtype: see the section "Defining Optimization Functions via AD"
  • grad(G,u,p) or G=grad(u,p): the gradient of f with respect to u
  • hess(H,u,p) or H=hess(u,p): the Hessian of f with respect to u
  • hv(Hv,u,v,p) or Hv=hv(u,v,p): the Hessian-vector product $rac{d^2 f}{du^2} v$.
  • cons(res,x,p) or res=cons(x,p): the equality constraints vector, where the constraints are satisfied when res = 0.
  • cons_j(res,x,p) or res=cons_j(x,p): the Jacobian of the equality constraints.
  • cons_h(res,x,p) or res=cons_h(x,p): the Hessian of the equality constratins, provided as and array of Hessians with res[i] being the Hessian with respect to the ith output on cons.
  • paramjac(pJ,u,p): returns the parameter Jacobian $rac{df}{dp}$.
  • hess_prototype: a prototype matrix matching the type that matches the Hessian. For example, if the Hessian is tridiagonal, then an appropriately sized Hessian matrix can be used as the prototype and integrators will specialize on this structure where possible. Non-structured sparsity patterns should use a SparseMatrixCSC with a correct sparsity pattern for the Hessian. The default is nothing, which means a dense Hessian.
  • cons_jac_prototype: a prototype matrix matching the type that matches the constraint Jacobian. The default is nothing, which means a dense constraint Jacobian.
  • cons_hess_prototype: a prototype matrix matching the type that matches the constraint Hessian. This is defined as an array of matrices, where hess[i] is the Hessian w.r.t. the ith output. For example, if the Hessian is sparse, then hess is a Vector{SparseMatrixCSC}. The default is nothing, which means a dense constraint Hessian.
  • syms: the symbol names for the elements of the equation. This should match u0 in size. For example, if u = [0.0,1.0] and syms = [:x, :y], this will apply a canonical naming to the values, allowing sol[:x] in the solution and automatically naming values in plots.
  • hess_colorvec: a color vector according to the SparseDiffTools.jl definition for the sparsity pattern of the hess_prototype. This specializes the Hessian construction when using finite differences and automatic differentiation to be computed in an accelerated manner based on the sparsity pattern. Defaults to nothing, which means a color vector will be internally computed on demand when required. The cost of this operation is highly dependent on the sparsity pattern.
  • cons_jac_colorvec: a color vector according to the SparseDiffTools.jl definition for the sparsity pattern of the cons_jac_prototype.
  • cons_hess_colorvec: an array of color vector according to the SparseDiffTools.jl definition for the sparsity pattern of the cons_hess_prototype.

Defining Optimization Functions Via AD

While using the keyword arguments gives the user control over defining all of the possible functions, the simplest way to handle the generation of an OptimizationFunction is by specifying an AD type. By doing so, this will automatically fill in all of the extra functions. For example,

OptimizationFunction(f,AutoZygote())

will use Zygote.jl to define all of the necessary functions. Note that if any functions are defined directly, the auto-AD definition does not overwrite the user's choice.

Each of the AD-based constructors are documented separately via their own dispatches.

iip: In-Place vs Out-Of-Place

For more details on this argument, see the ODEFunction documentation.

recompile: Controlling Compilation and Specialization

For more details on this argument, see the ODEFunction documentation.

Fields

The fields of the OptimizationFunction type directly match the names of the inputs.

Automatic Differentiation Construction Choice Recommendations

The choices for the auto-AD fill-ins with quick descriptions are:

  • AutoForwardDiff(): The fastest choice for small optimizations
  • AutoReverseDiff(compile=false): A fast choice for large scalar optimizations
  • AutoTracker(): Like ReverseDiff but GPU-compatible
  • AutoZygote(): The fastest choice for non-mutating array-based (BLAS) functions
  • AutoFiniteDiff(): Finite differencing, not optimal but always applicable
  • AutoModelingToolkit(): The fastest choice for large scalar optimizations

Automatic Differentiation Choice API

The following sections describe the Auto-AD choices in detail.

Missing docstring.

Missing docstring for AutoForwardDiff. Check Documenter's build log for details.

Missing docstring.

Missing docstring for AutoFiniteDiff. Check Documenter's build log for details.

Missing docstring.

Missing docstring for AutoReverseDiff. Check Documenter's build log for details.

Missing docstring.

Missing docstring for AutoZygote. Check Documenter's build log for details.

Missing docstring.

Missing docstring for AutoTracker. Check Documenter's build log for details.

Missing docstring.

Missing docstring for AutoModelingToolkit. Check Documenter's build log for details.