mod gradient

module gradient

Gradient trait and adapters (Analytic / FiniteDiff) plus DifferentiableObjective. “Native” gradients when the caller can supply them (Ceres-style); explicit central differences otherwise. Gradient<T>` and DifferentiableObjective<T>`: first-derivative support for the typed ``Obj algebra.

This is the “native gradient” path, modeled on how Ceres accepts analytic derivatives: when a caller (HMC, projected-gradient polish, GLE with optimal drift, NEB/saddle search in sibling crates, …) can supply a true derivative it is used directly; otherwise an explicit FiniteDiffGradient adapter falls back to central differences (costing 2·dim extra objective evaluations per gradient).

The separation (value-only Objective vs. Gradient provider) mirrors Stan’s log-density / gradient split and Ceres’ residual + optional Jacobian in a single Evaluate. A type can implement both (via DifferentiableObjective) and supply an efficient fused value_and_gradient to avoid redundant work.

Surrogates (ChebyshevSurrogate, AdditiveSurrogate, ReducedObjective) implement the traits analytically where possible. Built-in test objectives ship with closed-form gradients. Python callables can provide a matching grad_fn at construction time of PyObjective.

Traits

trait DifferentiableObjective<T: Float>

An Objective that can also supply its gradient (natively or via adapter).

Blanket impl for any O: Objective<T> + Gradient<T>. Concrete types (surrogates, PyObjective with grad, builtins) can override value_and_gradient for a fused implementation that re-uses intermediate work (exactly as a Ceres CostFunction computes residuals and Jacobians in one shot).

Functions

fn value_and_gradient(&self, x: ArrayView1<T>) -> (T, Array1<T>)

Returns (f(x), ∇f(x)). Default calls the two methods separately; analytic implementations should override for efficiency.

Implemented for

impl<T: Float, O> DifferentiableObjective<T> for O
where
    O: Objective<T> + Gradient<T>

trait Gradient<T: Float>

First-derivative interface. Types that know an analytic gradient implement this directly (or via DifferentiableObjective).

When only a black-box Objective is available, wrap it with FiniteDiffGradient. When a closure or Python grad callable is known, use AnalyticGradient (or construct a PyObjective with grad_fn).

Functions

fn dim(&self) -> usize

Number of input dimensions (must match the paired Objective::dim).

fn grad(&self, x: ArrayView1<T>) -> Array1<T>

Gradient of the underlying scalar field at x.

Implemented for

impl<const D: usize> Gradient<f64> for Ackley<D>

impl<const D: usize> Gradient<f64> for Rastrigin<D>

impl<const D: usize> Gradient<f64> for Rosenbrock<D>

impl Gradient<f64> for StybTang2D

impl Gradient<f64> for PyObjective

impl Gradient<f64> for ChebyshevSurrogate

impl<O: Objective<f64> + Gradient<f64>> Gradient<f64> for ReducedObjective<O>

Structs and Unions

struct AnalyticGradient<F>
where
    F: Fn(ArrayView1<f64>) -> Array1<f64> + Send + Sync

Closure-based analytic gradient (the common case for user Rust code that has a hand-derived or AD-produced x |-> ∇f(x)).

grad_fn: F

User-supplied analytic gradient callback.

dim: usize

Number of input dimensions accepted by grad_fn.

Implementations

impl<F> AnalyticGradient<F>
where
    F: Fn(ArrayView1<f64>) -> Array1<f64> + Send + Sync

Functions

fn new(dim: usize, grad_fn: F) -> Self

Constructs an analytic-gradient adapter from a dimension and callback.

Traits implemented

impl<F> Gradient<f64> for AnalyticGradient<F>
where
    F: Fn(ArrayView1<f64>) -> Array1<f64> + Send + Sync

struct FiniteDiffGradient<O: Objective<f64>>

Central-difference adapter around any Objective<f64>. Use only when no native gradient is available.

obj: O

Objective evaluated by the central-difference stencil.

h: f64

Symmetric perturbation step.

Implementations

impl<O: Objective<f64>> FiniteDiffGradient<O>

Functions

fn new(obj: O) -> Self

Constructs a central-difference adapter with a conservative default step.

fn with_step(obj: O, h: f64) -> Self

Constructs a central-difference adapter with a caller-selected step.

Traits implemented

impl<O: Objective<f64> + Send + Sync> Gradient<f64> for FiniteDiffGradient<O>