Struct FiniteDiff 

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

Wraps a problem to synthesize its derivatives by finite differences.

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

Backends

Gradient and HessianProduct are backend-generic (any V: Clone + VectorLen + VectorIndex; no matrix type is involved). Jacobian and Hessian additionally require V: DenseMatrixFromFn, so they are available for Vec<f64>/DenseMatrix, nalgebra DVector<f64>/DMatrix, ndarray Array1<f64>/Array2, and faer Col<f64>/Mat. crate::ConstraintJacobian uses the parameter backend’s dense matrix, independently of the linear block matrices. Use BoundedFiniteDiff for f32 first derivatives.

Solver stopping tolerances

The synthesized gradient has truncation and rounding error, so it can be nonzero at an exact minimum. Choose the solver’s gradient stopping tolerance to account for that error in the problem’s units. A threshold below the derivative error can cause extra evaluations or a line-search failure even after reaching an accurate solution. Central differences often reduce truncation error, but do not guarantee a particular stopping accuracy. function_precision controls probe step sizes; it is not a bound on gradient error. Objective scaling, curvature, parameter magnitudes, and evaluation noise also affect that error. See Lbfgs for a forward-difference stopping example.

Examples

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

use basin::{
    FirstOrderState, CostFunction, Executor, FiniteDiff, GradientDescent};

struct Sphere;
impl basin::ProblemConstraints for Sphere  {
    type Constraints = basin::NoConstraints;
    fn constraint_set(&self) -> basin::NoConstraints { basin::NoConstraints::EMPTY }
}
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).with_absolute_gradient_tolerance(1e-8),
    FirstOrderState::new(vec![1.0, 1.0]),
)
.max_iter(1_000)
.run()
.unwrap();
assert!(result.cost() < 1e-10);

Implementations

impl<P> FiniteDiff<P>

pub fn with_bounds<V: VectorLen + VectorIndex>( self, lower: V, upper: V, ) -> BoundedFiniteDiff<P>

Transfer first-derivative settings into a BoundedFiniteDiff. The resulting adapter supports gradients and Jacobians only. Hessian settings have no effect on its first derivatives.

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: Clone> Clone for FiniteDiff<P>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

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

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

type Param = V

Parameter type.

type Jacobian = <V as DenseMatrixFromFn>::Matrix

Nonlinear Jacobian storage.

type Error = <P as CostFunction>::Error

Original callback error type.

fn constraint_jacobian( &self, x: &V, ) -> Result<Self::Jacobian, ConstraintSolveError<P::Error>>

Evaluate equality rows first, followed by inequality rows.

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> HessianProduct for FiniteDiff<P>

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

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

Hessian-vector product by differencing this wrapper’s own finite-difference gradients along v (stencil set by hessian_method). Note this stacks two truncation errors (FD of FD): it is the no-analytic-anything fallback. With an analytic Gradient, skip the wrapper and call forward_difference_hessian_product / central_difference_hessian_product directly (2 gradient evaluations per product). Cost here is 2 synthesized gradients: ~4n cost evaluations with the central/central default.

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> NonlinearEqualityValues for FiniteDiff<P>

where P: NonlinearEqualityValues,

type Param = <P as NonlinearEqualityValues>::Param

Parameter type.

type Values = <P as NonlinearEqualityValues>::Values

Readable vector of equality residuals.

type Error = <P as NonlinearEqualityValues>::Error

Original callback error type.

fn nonlinear_equalities( &self, x: &Self::Param, ) -> Result<Self::Values, ConstraintSolveError<Self::Error>>

Evaluate h(x) = 0.

impl<P> NonlinearInequalityValues for FiniteDiff<P>

where P: NonlinearInequalityValues,

type Param = <P as NonlinearInequalityValues>::Param

Parameter type.

type Values = <P as NonlinearInequalityValues>::Values

Readable vector of constraint values, independent of the parameter type.

type Error = <P as NonlinearInequalityValues>::Error

Original callback error type.

fn nonlinear_inequalities( &self, x: &Self::Param, ) -> Result<Self::Values, ConstraintSolveError<Self::Error>>

Evaluate the inequalities in the public c(x) <= 0 convention.

impl<P> ProblemConstraints for FiniteDiff<P>

where P: ProblemConstraints,

type Constraints = <P as ProblemConstraints>::Constraints

The complete constraint set. Its type determines solver compatibility.

fn constraint_set( &self, ) -> <Self::Constraints as ConstraintDescription>::Borrowed<'_>

Borrow the complete set without evaluating the problem.

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.