chainrules-core 0.2.0

Backend-agnostic JVP and VJP rule protocol for scientific Rust
Documentation
//! Backend-agnostic contracts for custom automatic-differentiation rules.
//!
//! `chainrules-core` is intentionally not an AD engine. It defines a small
//! protocol through which numerical packages publish operation-aware
//! Jacobian-vector product (JVP) and vector-Jacobian product (VJP) rules.
//! Backends may consume those rules without either side depending on the
//! other.
//!
//! Version 0.2 specifies distinct tangent and cotangent associations, typed
//! failure for both primal and reverse computations, and one-shot pullback
//! ownership. See the repository's `PROTOCOL.md` and `MIGRATION.md` for the
//! complete semantic contract and the migration from 0.1.
//!
//! # Example
//!
//! ```
//! use std::convert::Infallible;
//!
//! use chainrules_core::{JvpRule, Pullback, VjpRule};
//!
//! struct Scale(f64);
//! struct ScalePullback(f64);
//!
//! impl JvpRule<f64> for Scale {
//!     type Output = f64;
//!     type Error = Infallible;
//!
//!     fn jvp(&self, x: &f64, dx: &f64) -> Result<(f64, f64), Self::Error> {
//!         Ok((self.0 * x, self.0 * dx))
//!     }
//! }
//!
//! impl Pullback<f64, f64> for ScalePullback {
//!     type Error = Infallible;
//!
//!     fn apply(self, cotangent: f64) -> Result<f64, Self::Error> {
//!         Ok(self.0 * cotangent)
//!     }
//! }
//!
//! impl VjpRule<f64> for Scale {
//!     type Output = f64;
//!     type Error = Infallible;
//!     type Pullback<'a> = ScalePullback;
//!
//!     fn vjp<'a>(
//!         &'a self,
//!         x: &'a f64,
//!     ) -> Result<(f64, Self::Pullback<'a>), Self::Error> {
//!         Ok((self.0 * x, ScalePullback(self.0)))
//!     }
//! }
//!
//! let rule = Scale(3.0);
//! assert_eq!(rule.jvp(&2.0, &0.5).unwrap(), (6.0, 1.5));
//! let (value, pullback) = rule.vjp(&2.0).unwrap();
//! assert_eq!((value, pullback.apply(0.25).unwrap()), (6.0, 0.75));
//! ```

#![forbid(unsafe_code)]

/// Associates a primal value with its forward tangent and reverse cotangent
/// representations.
///
/// The two associated types may be identical for Euclidean values, but the
/// protocol keeps their roles distinct. A scientific type may therefore use a
/// lightweight perturbation in forward mode and a different accumulator in
/// reverse mode.
pub trait Differentiable {
    /// Representation of a forward perturbation of this primal value.
    type Tangent;

    /// Representation of a reverse sensitivity of this primal value.
    type Cotangent;
}

/// Marks a primal value with no differentiable input space.
///
/// Examples include a solver choice, an index, a sparsity pattern, or a
/// discrete sector. `NoTangent` is not a zero derivative: a zero derivative
/// belongs to a tangent space that exists, whereas `NoTangent` means there is
/// no such space.
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub struct NoTangent;

impl Differentiable for f32 {
    type Tangent = f32;
    type Cotangent = f32;
}

impl Differentiable for f64 {
    type Tangent = f64;
    type Cotangent = f64;
}

impl Differentiable for () {
    type Tangent = NoTangent;
    type Cotangent = NoTangent;
}

impl<A, B> Differentiable for (A, B)
where
    A: Differentiable,
    B: Differentiable,
{
    type Tangent = (A::Tangent, B::Tangent);
    type Cotangent = (A::Cotangent, B::Cotangent);
}

impl<T, const N: usize> Differentiable for [T; N]
where
    T: Differentiable,
{
    type Tangent = [T::Tangent; N];
    type Cotangent = [T::Cotangent; N];
}

impl<T> Differentiable for Vec<T>
where
    T: Differentiable,
{
    type Tangent = Vec<T::Tangent>;
    type Cotangent = Vec<T::Cotangent>;
}

#[cfg(feature = "num-complex")]
impl<T> Differentiable for num_complex::Complex<T>
where
    T: Differentiable,
{
    type Tangent = num_complex::Complex<T::Tangent>;
    type Cotangent = num_complex::Complex<T::Cotangent>;
}

/// A forward-mode rule computing a primal output and a Jacobian-vector
/// product.
///
/// Numerical rules are fallible by construction. Pure algebraic rules should
/// use [`std::convert::Infallible`] as `Error`.
pub trait JvpRule<Args>
where
    Args: Differentiable,
{
    /// Primal output type.
    type Output: Differentiable;

    /// Error returned by primal evaluation or tangent propagation.
    type Error;

    /// Evaluates the primal operation and propagates one input tangent.
    #[allow(clippy::type_complexity)]
    fn jvp(
        &self,
        args: &Args,
        tangent: &Args::Tangent,
    ) -> Result<(Self::Output, <Self::Output as Differentiable>::Tangent), Self::Error>;
}

/// A one-shot reverse-mode pullback.
///
/// Consuming `self` permits a pullback to own a factorization, Krylov basis,
/// checkpoint set, or device buffer and release it after one reverse
/// application. A pullback may also borrow immutable primal inputs through the
/// generic associated type on [`VjpRule`].
pub trait Pullback<OutputCotangent, InputCotangent> {
    /// Error returned by the reverse computation.
    type Error;

    /// Applies the pullback once.
    fn apply(self, cotangent: OutputCotangent) -> Result<InputCotangent, Self::Error>;
}

impl<F, OutputCotangent, InputCotangent, Error> Pullback<OutputCotangent, InputCotangent> for F
where
    F: FnOnce(OutputCotangent) -> Result<InputCotangent, Error>,
{
    type Error = Error;

    fn apply(self, cotangent: OutputCotangent) -> Result<InputCotangent, Self::Error> {
        self(cotangent)
    }
}

/// A reverse-mode rule computing a primal output and a one-shot pullback.
///
/// The generic associated type allows the pullback to borrow `self` or
/// `args`. Caches produced during the forward evaluation can instead be owned
/// by the pullback. The same typed error is used at the rule boundary for
/// forward and reverse failures; downstream error enums can record the stage.
pub trait VjpRule<Args>
where
    Args: Differentiable,
{
    /// Primal output type.
    type Output: Differentiable;

    /// Error returned by primal evaluation or pullback application.
    type Error;

    /// Pullback produced for one primal evaluation.
    type Pullback<'a>: Pullback<<Self::Output as Differentiable>::Cotangent, Args::Cotangent, Error = Self::Error>
    where
        Self: 'a,
        Args: 'a;

    /// Evaluates the primal operation and constructs its pullback.
    fn vjp<'a>(&'a self, args: &'a Args)
    -> Result<(Self::Output, Self::Pullback<'a>), Self::Error>;
}

/// Numerical conformance helpers for custom rules.
///
/// The helpers accept closures for perturbation, differencing, and pairings so
/// that the core protocol does not need a matrix, tensor, normed-space, or
/// device-array abstraction.
pub mod testing {
    /// Estimates a scalar directional derivative with a central difference.
    #[must_use]
    pub fn central_difference<F>(f: F, x: f64, direction: f64, step: f64) -> f64
    where
        F: Fn(f64) -> f64,
    {
        assert_valid_step(step);
        (f(x + step * direction) - f(x - step * direction)) / (2.0 * step)
    }

    /// Estimates a directional derivative for an arbitrary output type.
    ///
    /// `evaluate_at_offset(scale)` evaluates the primal at `x + scale * v`.
    /// `difference` receives the positive value, negative value, and
    /// denominator `2h`. Keeping those operations in closures avoids imposing
    /// public vector-space traits on scientific types.
    pub fn directional_central_difference<Output, Error, Evaluate, Difference>(
        mut evaluate_at_offset: Evaluate,
        step: f64,
        difference: Difference,
    ) -> Result<Output, Error>
    where
        Evaluate: FnMut(f64) -> Result<Output, Error>,
        Difference: FnOnce(Output, Output, f64) -> Output,
    {
        assert_valid_step(step);
        let positive = evaluate_at_offset(step)?;
        let negative = evaluate_at_offset(-step)?;
        Ok(difference(positive, negative, 2.0 * step))
    }

    /// Asserts approximate equality using combined absolute and relative
    /// tolerances.
    pub fn assert_close(actual: f64, expected: f64, relative: f64, absolute: f64) {
        assert!(
            relative.is_finite() && relative >= 0.0,
            "relative tolerance must be finite and nonnegative"
        );
        assert!(
            absolute.is_finite() && absolute >= 0.0,
            "absolute tolerance must be finite and nonnegative"
        );
        let tolerance = absolute + relative * actual.abs().max(expected.abs());
        assert!(
            (actual - expected).abs() <= tolerance,
            "values differ: actual={actual}, expected={expected}, tolerance={tolerance}"
        );
    }

    /// Checks the adjoint identity for arbitrary tangent and cotangent types.
    ///
    /// The defining identity is
    /// `<Jv, w>_output = <v, J*w>_input`. The two pairing closures return real
    /// scalars and therefore also support complex spaces using a real pairing.
    #[allow(clippy::too_many_arguments)]
    pub fn assert_adjoint_identity<
        OutputTangent,
        OutputCotangent,
        InputTangent,
        InputCotangent,
        OutputPairing,
        InputPairing,
    >(
        jvp: &OutputTangent,
        output_cotangent: &OutputCotangent,
        input_tangent: &InputTangent,
        input_cotangent: &InputCotangent,
        output_pairing: OutputPairing,
        input_pairing: InputPairing,
        relative: f64,
        absolute: f64,
    ) where
        OutputPairing: FnOnce(&OutputTangent, &OutputCotangent) -> f64,
        InputPairing: FnOnce(&InputTangent, &InputCotangent) -> f64,
    {
        assert_close(
            output_pairing(jvp, output_cotangent),
            input_pairing(input_tangent, input_cotangent),
            relative,
            absolute,
        );
    }

    /// Scalar convenience wrapper for [`assert_adjoint_identity`].
    pub fn assert_scalar_adjoint_identity(
        jvp: f64,
        output_cotangent: f64,
        input_tangent: f64,
        input_cotangent: f64,
        tolerance: f64,
    ) {
        assert_adjoint_identity(
            &jvp,
            &output_cotangent,
            &input_tangent,
            &input_cotangent,
            |left, right| left * right,
            |left, right| left * right,
            tolerance,
            tolerance,
        );
    }

    fn assert_valid_step(step: f64) {
        assert!(
            step.is_finite() && step > 0.0,
            "finite-difference step must be finite and positive"
        );
    }
}