Crate num_dual

Expand description

Generalized, recursive, scalar and vector (hyper) dual numbers for the automatic and exact calculation of (partial) derivatives.

§Example

This example defines a generic scalar and a generic vector function that can be called using any (hyper-) dual number and automatically calculates derivatives.

use num_dual::*;
use nalgebra::SVector;

fn foo<D: DualNum<f64>>(x: D) -> D {
    x.powi(3)
}

fn bar<D: DualNum<f64>, const N: usize>(x: SVector<D, N>) -> D {
    x.dot(&x).sqrt()
}

fn main() {
    // Calculate a simple derivative
    let (f, df) = first_derivative(foo, 5.0);
    assert_eq!(f, 125.0);
    assert_eq!(df, 75.0);

    // Manually construct the dual number
    let x = Dual64::new(5.0, 1.0);
    println!("{}", foo(x));                     // 125 + [75]ε

    // Calculate a gradient
    let (f, g) = gradient(bar, SVector::from([4.0, 3.0]));
    assert_eq!(f, 5.0);
    assert_eq!(g[0], 0.8);

    // Calculate a Hessian
    let (f, g, h) = hessian(bar, SVector::from([4.0, 3.0]));
    println!("{h}");                            // [[0.072, -0.096], [-0.096, 0.128]]

    // for x=cos(t) calculate the third derivative of foo w.r.t. t
    let (f0, f1, f2, f3) = third_derivative(|t| foo(t.cos()), 1.0);
    println!("{f3}");                           // 1.5836632930100278
}

Macros§

Structs§

Derivative: Wrapper struct for a derivative vector or matrix.
Dual: A scalar dual number for the calculations of first derivatives.
Dual2: A scalar second order dual number for the calculation of second derivatives.
Dual3: A scalar third order dual number for the calculation of third derivatives.
Dual2Vec: A vector second order dual number for the calculation of Hessians.
DualVec: A vector dual number for the calculations of gradients or Jacobians.
HyperDual: A scalar hyper-dual number for the calculation of second partial derivatives.
HyperDualVec: A vector hyper-dual number for the calculation of partial Hessians.
HyperHyperDual: A scalar hyper-hyper-dual number for the calculation of third partial derivatives.
ImplicitDerivative: Helper struct that stores parameters in dual and real form and provides functions for evaluating real residuals (for external solvers) and implicit derivatives for arbitrary dual numbers.

Traits§

BesselDual: Implementation of bessel functions for double precision (hyper) dual numbers.
DualNum: A generalized (hyper) dual number.
DualNumFloat: The underlying data type of individual derivatives. Usually f32 or f64.
DualStruct: A struct that contains dual numbers. Needed for arbitrary arguments in ImplicitFunction.
ImplicitFunction: An implicit function g(x, args) = 0 for which derivatives of x can be calculated with the ImplicitDerivative struct.

Functions§

first_derivative: Calculate the first derivative of a scalar function.
gradient: Calculate the gradient of a scalar function
hessian: Calculate the Hessian of a scalar function.
implicit_derivative: Calculate the derivative of the unary implicit function g(x, args) = 0
implicit_derivative_binary: Calculate the derivative of the binary implicit function g(x, y, args) = 0
implicit_derivative_vec: Calculate the derivative of the multivariate implicit function g(x, args) = 0
jacobian: Calculate the Jacobian of a vector function.
partial_hessian: Calculate second partial derivatives with respect to vectors.
second_derivative: Calculate the second derivative of a univariate function.
second_partial_derivative: Calculate second partial derivatives with respect to scalars.
third_derivative: Calculate the third derivative of a univariate function.
third_partial_derivative: Calculate third partial derivatives with respect to scalars.
third_partial_derivative_vec: Calculate the third partial derivative of a scalar function with arbitrary many variables.
try_first_derivative: Variant of first_derivative for fallible functions.
try_gradient: Variant of gradient for fallible functions.
try_hessian: Variant of hessian for fallible functions.
try_jacobian: Variant of jacobian for fallible functions.
try_partial_hessian: Variant of partial_hessian for fallible functions.
try_second_derivative: Variant of second_derivative for fallible functions.
try_second_partial_derivative: Variant of second_partial_derivative for fallible functions.
try_third_derivative: Variant of third_derivative for fallible functions.
try_third_partial_derivative: Variant of third_partial_derivative for fallible functions.
try_third_partial_derivative_vec: Variant of third_partial_derivative_vec for fallible functions.