Struct FiniteDiff 

pub struct FiniteDiff<P> { /* private fields */ }

Wraps a problem to synthesize its derivatives by finite differences.

Construct with FiniteDiff::new (central gradient/Hessian, forward Jacobian — see the module docs) and adjust with the builder methods. The wrapper delegates CostFunction / Residual / BoxConstraints to the inner problem and implements Gradient / Jacobian / Hessian via finite differences.

Backends

Gradient is backend-generic (any V: Clone + VectorLen + VectorIndex). Jacobian and Hessian additionally require V: DenseMatrixFromFn, so they are available only for the matrix backends (nalgebra DVector → DMatrix, faer Col → Mat) — Vec<f64> and ndarray produce a compile-time error, mirroring the analytic Jacobian / Hessian coverage (tenet 5).

Examples

Run a gradient solver against a problem that only implements CostFunction: wrapping it in FiniteDiff synthesizes the Gradient by central differences.

use basin::{BasicState, CostFunction, Executor, FiniteDiff, GradientDescent, GradientTolerance};

struct Sphere;
impl CostFunction for Sphere {
    type Param = Vec<f64>;
    type Output = f64;
    type Error = std::convert::Infallible;
    fn cost(&self, x: &Vec<f64>) -> Result<f64, std::convert::Infallible> {
        Ok(x.iter().map(|xi| xi * xi).sum())
    }
}

let result = Executor::new(
    FiniteDiff::new(Sphere),
    GradientDescent::new(0.1),
    BasicState::new(vec![1.0, 1.0]),
)
.max_iter(1_000)
.terminate_on(GradientTolerance(1e-8))
.run()
.unwrap();
assert!(result.cost() < 1e-10);

Implementations

impl<P> FiniteDiff<P>

pub fn new(problem: P) -> Self

Wrap problem with default settings: central-difference gradient and Hessian, forward-difference (MINPACK fdjac2) Jacobian, function_precision = f64::EPSILON, adaptive step sizes.

pub fn gradient_method(self, method: Method) -> Self

Set the stencil used for the gradient (default Method::Central).

pub fn jacobian_method(self, method: Method) -> Self

Set the stencil used for the Jacobian (default Method::Forward, the MINPACK fdjac2 parity choice).

pub fn hessian_method(self, method: Method) -> Self

Set the stencil used for the Hessian (default Method::Central).

pub fn function_precision(self, epsfcn: f64) -> Self

Set the assumed relative accuracy of the wrapped function (MINPACK’s epsfcn). Larger values widen the step, which helps when the function is noisy. Floored at f64::EPSILON. Default f64::EPSILON.

pub fn with_step(self, h: f64) -> Self

Override the adaptive step rule with a fixed absolute step h used for every coordinate. Escape hatch — most callers should leave the adaptive |xⱼ|-scaled rule in place.

pub fn get_ref(&self) -> &P

Borrow the wrapped problem.

pub fn into_inner(self) -> P

Unwrap and return the inner problem.

Trait Implementations

impl<P: BoxConstraints> BoxConstraints for FiniteDiff<P>

fn lower(&self) -> &Self::Param

Element-wise lower bound on Param. Same shape as Param.

fn upper(&self) -> &Self::Param

Element-wise upper bound on Param. Same shape as Param.

impl<P: Clone> Clone for FiniteDiff<P>

fn clone(&self) -> FiniteDiff<P>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<P: Copy> Copy for FiniteDiff<P>

impl<P: CostFunction> CostFunction for FiniteDiff<P>

type Param = <P as CostFunction>::Param

The parameter type the objective is defined over.

type Output = <P as CostFunction>::Output

Scalar cost type. In practice f64 (see CONTRIBUTING.md’s provisional choices).

type Error = <P as CostFunction>::Error

User-chosen hard-abort error. Pick std::convert::Infallible when the cost cannot fail — its niche optimization keeps Result<f64, Infallible> the same layout as bare f64 on the happy path.

fn cost(&self, param: &Self::Param) -> Result<Self::Output, Self::Error>

Evaluate the objective at param.

impl<P: Debug> Debug for FiniteDiff<P>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<P, V> Gradient for FiniteDiff<P>

where P: CostFunction<Param = V, Output = f64> + MaybeSync, V: Clone + VectorLen + VectorIndex + MaybeSync, <P as CostFunction>::Error: MaybeSend,

type Gradient = V

The gradient type. Typically the same as CostFunction::Param.

fn gradient(&self, param: &V) -> Result<V, P::Error>

Evaluate the gradient at param.

fn cost_and_gradient( &self, param: &Self::Param, ) -> Result<(Self::Output, Self::Gradient), Self::Error>

Evaluate cost and gradient at param in one call. The default body delegates to CostFunction::cost and Gradient::gradient; override when shared intermediate work can be amortized across the two.

impl<P, V> Hessian for FiniteDiff<P>

where P: CostFunction<Param = V, Output = f64> + MaybeSync, V: Clone + VectorLen + VectorIndex + DenseMatrixFromFn + MaybeSync, <P as CostFunction>::Error: MaybeSend,

type Hessian = <V as DenseMatrixFromFn>::Matrix

The Hessian matrix type, shape n × n and symmetric.

fn hessian(&self, param: &V) -> Result<Self::Hessian, P::Error>

Evaluate the Hessian at param.

fn cost_and_gradient_and_hessian( &self, param: &Self::Param, ) -> Result<(<Self as CostFunction>::Output, <Self as Gradient>::Gradient, Self::Hessian), <Self as CostFunction>::Error>

Evaluate cost, gradient, and Hessian at param in one call. The default body delegates to Gradient::cost_and_gradient followed by Hessian::hessian; override when all three share intermediate work.

impl<P, V> Jacobian for FiniteDiff<P>

where P: Residual<Param = V, Output = V> + MaybeSync, V: Clone + VectorLen + VectorIndex + DenseMatrixFromFn + MaybeSync + MaybeSend, <P as Residual>::Error: MaybeSend,

type Jacobian = <V as DenseMatrixFromFn>::Matrix

The Jacobian matrix type, shape m × n.

fn jacobian(&self, param: &V) -> Result<Self::Jacobian, P::Error>

Evaluate the Jacobian at param.

fn residual_and_jacobian( &self, param: &Self::Param, ) -> Result<(<Self as Residual>::Output, Self::Jacobian), <Self as Residual>::Error>

Evaluate residual and Jacobian at param in one call. The default body delegates to Residual::residual and Jacobian::jacobian; override when shared intermediate work can be amortized across the two — common in NLLS where r(x) reuses forward-mode AD state that J(x) continues from.

impl<P: Residual> Residual for FiniteDiff<P>

type Param = <P as Residual>::Param

The parameter type the residual is defined over (matches CostFunction::Param).

type Output = <P as Residual>::Output

The residual vector type. Length is the number of residuals m, independent of param.len() = n.

type Error = <P as Residual>::Error

User-chosen hard-abort error. Independent of CostFunction::Error — the trait families are orthogonal (NLLS solvers bind on Residual + Jacobian; first-order solvers bind on CostFunction + Gradient).

fn residual(&self, param: &Self::Param) -> Result<Self::Output, Self::Error>

Evaluate the residual at param.