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;
    fn cost(&self, x: &Vec<f64>) -> f64 {
        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();
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: 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 AGENTS.md’s provisional choices).

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

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>, V: Clone + VectorLen + VectorIndex,

type Param = V

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

type Gradient = V

The gradient type. Typically the same as Param.

fn gradient(&self, param: &V) -> V

Evaluate the gradient at param.

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

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

type Param = V

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

type Output = <V as DenseMatrixFromFn>::Matrix

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

fn hessian(&self, param: &V) -> Self::Output

Evaluate the Hessian at param.

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

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

type Param = V

The parameter type the Jacobian is defined over (matches Residual::Param).

type Output = <V as DenseMatrixFromFn>::Matrix

The Jacobian matrix type, shape m × n.

fn jacobian(&self, param: &V) -> Self::Output

Evaluate the Jacobian at param.

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.

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

Evaluate the residual at param.

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