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, 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. ConstraintJacobian requires the constraint matrix type to match that backend’s dense matrix. Use BoundedFiniteDiff for f32 first derivatives.

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,
};

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).with_absolute_gradient_tolerance(1e-8),
    BasicState::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: 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) -> 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: NonlinearConstraints<Param = V, Output = f64> + MaybeSync, V: Clone + VectorLen + VectorIndex + DenseMatrixFromFn<Matrix = P::Matrix> + MaybeSync, P::Error: MaybeSend,

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

Evaluate the nonlinear constraint Jacobian at x.

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

type Matrix = <P as LinearConstraints>::Matrix

The constraint-matrix type for the equality/inequality blocks. LINCOA bounds it on MatTransposeVec<Param> (each constraint normal is Aᵀ eⱼ); never a linear solve.

fn inequalities(&self) -> Option<(&P::Matrix, &P::Param)>

Linear inequalities A_ineq x ≤ b_ineq as (A_ineq, b_ineq), or None (the default) when the problem has no inequality constraints.

fn equalities(&self) -> Option<(&P::Matrix, &P::Param)>

Linear equalities A_eq x = b_eq as (A_eq, b_eq), or None (the default) when the problem has no equality constraints.

fn lower(&self) -> Option<&P::Param>

Element-wise lower bound on the iterate (length n), or None (the default) when unbounded below. Non-finite entries leave that coordinate unbounded below.

fn upper(&self) -> Option<&P::Param>

Element-wise upper bound on the iterate (length n), or None (the default) when unbounded above. Non-finite entries leave that coordinate unbounded above.

impl<P: LinearEqualityConstraints> LinearEqualityConstraints for FiniteDiff<P>

type Matrix = <P as LinearEqualityConstraints>::Matrix

The m × n constraint-matrix type. Consumers bound this on MatVec<Param> + MatTransposeVec<Param>.

fn a(&self) -> &P::Matrix

The constraint matrix A (m rows = number of equalities).

fn b(&self) -> &P::Param

The right-hand side b ∈ ℝᵐ.

impl<P: LinearInequalityConstraints> LinearInequalityConstraints for FiniteDiff<P>

type Matrix = <P as LinearInequalityConstraints>::Matrix

The m × n constraint-matrix type. Consumers bound this on MatVec<Param> + MatTransposeVec<Param>.

fn a(&self) -> &P::Matrix

The constraint matrix A (m rows = number of inequalities).

fn b(&self) -> &P::Param

The right-hand side b ∈ ℝᵐ.

impl<P: NonlinearConstraints> NonlinearConstraints for FiniteDiff<P>

type Matrix = <P as NonlinearConstraints>::Matrix

The matrix type for the optional linear constraint blocks.

fn nonlinear_constraints(&self, x: &P::Param) -> Result<P::Param, P::Error>

Evaluate the nonlinear inequalities c(x) ≤ 0. The returned vector has length num_nonlinear_constraints.

fn num_nonlinear_constraints(&self) -> usize

The number of nonlinear inequalities, excluding bounds and linear constraints. Zero is valid.

fn nonlinear_equalities( &self, x: &P::Param, ) -> Result<Option<P::Param>, P::Error>

Evaluate native nonlinear equalities. None means an absent block and requires a zero declared count. A present vector must have length num_nonlinear_equalities. SLSQP handles these natively; FoldedConstraints folds both signs.

fn num_nonlinear_equalities(&self) -> usize

Number of native nonlinear equalities h(x) = 0. Defaults to zero. Keep this count fixed throughout a solve.

fn inequalities(&self) -> Option<(&P::Matrix, &P::Param)>

Linear inequalities A_ineq x ≤ b_ineq as (A_ineq, b_ineq), or None (the default) when absent.

fn equalities(&self) -> Option<(&P::Matrix, &P::Param)>

Linear equalities A_eq x = b_eq as (A_eq, b_eq), or None (the default) when absent. Folding represents each equality by both signs of its residual, without relaxing the equality at the start point.

fn lower(&self) -> Option<&P::Param>

Element-wise lower bounds of length n, or None (the default). Non-finite entries leave that coordinate unbounded below.

fn upper(&self) -> Option<&P::Param>

Element-wise upper bounds of length n, or None (the default). Non-finite entries leave that coordinate unbounded above.

impl<P: NonlinearInequalityConstraints> NonlinearInequalityConstraints for FiniteDiff<P>

fn num_constraints(&self) -> usize

The number of constraints m (length of the constraints vector). Lets a solver size its per-constraint model storage before the first evaluation.

fn constraints(&self, x: &P::Param) -> Result<P::Param, P::Error>

Evaluate the constraint function c(x) ∈ ℝᵐ. The point is feasible iff every returned component is ≤ 0; the constraint violation is [ maxᵢ cᵢ(x) ]₊. The returned vector has length num_constraints and shares the parameter’s vector type.

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.