API — Objective Functions

AbstractObjectiveFunction

Supertype for all Retro objective functions.

Concrete subtypes: ADObjectiveFunction, GradientObjectiveFunction, AnalyticObjectiveFunction.

ADObjectiveFunction{F,ADT,PG,PH} <: AbstractObjectiveFunction

Objective function with automatic differentiation via DifferentiationInterface. Precomputes gradient and Hessian preparation objects at construction time so that repeated evaluations are allocation-free.

Works with any AD backend that DifferentiationInterface supports (ForwardDiff, Enzyme, Zygote, …) as long as the objective is compatible.

Fields

• func::F: Scalar objective $f : \mathbb{R}^n \to \mathbb{R}$
• adtype::ADT: AD backend (e.g. AutoForwardDiff())
• prep_g::PG: Prepared gradient operator (from prepare_gradient)
• prep_h::PH: Prepared Hessian operator (from prepare_hessian)

GradientObjectiveFunction{F,G,ADT,PH} <: AbstractObjectiveFunction

Objective with a user-supplied gradient and AD-computed Hessian.

Fields

• func::F: Scalar objective $f : \mathbb{R}^n \to \mathbb{R}$
• grad!::G: In-place gradient grad!(g, x)
• adtype::ADT: AD backend used only for Hessian computation
• prep_h::PH: Prepared Hessian operator

AnalyticObjectiveFunction{F,G,H} <: AbstractObjectiveFunction

Fully user-supplied objective, gradient, and Hessian. No AD dependency.

Fields

• func::F: Scalar objective $f : \mathbb{R}^n \to \mathbb{R}$
• grad!::G: In-place gradient grad!(g, x)
• hess!::H: In-place Hessian hess!(H, x)

objfunc!(cache, obj, x) -> f(x)

Evaluate the objective function at x, incrementing the call counter in cache.

gradient!(g, cache, obj, x)

Compute the gradient of obj at x and store it in g (in-place).

hessian!(H, cache, obj, x)

Compute the Hessian of obj at x and store it in the matrix H (in-place).

value_and_gradient!(g, cache, obj, x) -> f(x)

Compute objective value and gradient simultaneously. Returns the scalar objective value; the gradient is written to g.

value_gradient_and_hessian!(g, H, cache, obj, x) -> f(x)

Compute objective value, gradient, and Hessian simultaneously. Returns the scalar objective value; g and H are written in-place.