Skip to main content

chainrules_core/
lib.rs

1//! Backend-agnostic contracts for custom automatic-differentiation rules.
2//!
3//! This crate is intentionally not an AD engine. It defines a small common
4//! protocol that numerical packages and AD backends can implement without
5//! depending on one another.
6
7#![forbid(unsafe_code)]
8
9/// Associates a primal value with the type used for its tangent or cotangent.
10pub trait Differentiable {
11    /// The tangent-space representation for this primal type.
12    type Tangent;
13}
14
15/// Marks a value that has no tangent space, such as a discrete configuration.
16#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
17pub struct NoTangent;
18
19/// Represents a structurally known zero without allocating a full tangent.
20#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
21pub struct ZeroTangent;
22
23impl Differentiable for f32 {
24    type Tangent = f32;
25}
26
27impl Differentiable for f64 {
28    type Tangent = f64;
29}
30
31impl Differentiable for () {
32    type Tangent = NoTangent;
33}
34
35impl<A, B> Differentiable for (A, B)
36where
37    A: Differentiable,
38    B: Differentiable,
39{
40    type Tangent = (A::Tangent, B::Tangent);
41}
42
43impl<T, const N: usize> Differentiable for [T; N]
44where
45    T: Differentiable,
46{
47    type Tangent = [T::Tangent; N];
48}
49
50/// A forward-mode rule computing a primal output and a Jacobian-vector product.
51pub trait JvpRule<Args>
52where
53    Args: Differentiable,
54{
55    /// The primal output type.
56    type Output: Differentiable;
57
58    /// Evaluates the primal operation and propagates an input tangent forward.
59    fn jvp(
60        &self,
61        args: &Args,
62        tangent: &Args::Tangent,
63    ) -> (Self::Output, <Self::Output as Differentiable>::Tangent);
64}
65
66/// A reverse-mode pullback from an output cotangent to input cotangents.
67pub trait Pullback<OutputTangent, InputTangent> {
68    /// Applies the pullback once.
69    fn apply(self, cotangent: OutputTangent) -> InputTangent;
70}
71
72impl<F, OutputTangent, InputTangent> Pullback<OutputTangent, InputTangent> for F
73where
74    F: FnOnce(OutputTangent) -> InputTangent,
75{
76    fn apply(self, cotangent: OutputTangent) -> InputTangent {
77        self(cotangent)
78    }
79}
80
81/// A reverse-mode rule computing a primal output and a reusable pullback object.
82///
83/// The generic associated type lets a pullback borrow inputs or caches from the
84/// forward evaluation instead of forcing large scientific arrays to be cloned.
85pub trait VjpRule<Args>
86where
87    Args: Differentiable,
88{
89    /// The primal output type.
90    type Output: Differentiable;
91
92    /// Pullback produced for one primal evaluation.
93    type Pullback<'a>: Pullback<<Self::Output as Differentiable>::Tangent, Args::Tangent>
94    where
95        Self: 'a,
96        Args: 'a;
97
98    /// Evaluates the primal operation and constructs its pullback.
99    fn vjp<'a>(&'a self, args: &'a Args) -> (Self::Output, Self::Pullback<'a>);
100}
101
102/// Small validation helpers for custom rules.
103pub mod testing {
104    /// Estimates a scalar directional derivative with a central difference.
105    #[must_use]
106    pub fn central_difference<F>(f: F, x: f64, direction: f64, step: f64) -> f64
107    where
108        F: Fn(f64) -> f64,
109    {
110        assert!(step > 0.0, "finite-difference step must be positive");
111        (f(x + step * direction) - f(x - step * direction)) / (2.0 * step)
112    }
113
114    /// Asserts approximate equality using combined absolute and relative tolerances.
115    pub fn assert_close(actual: f64, expected: f64, relative: f64, absolute: f64) {
116        let tolerance = absolute + relative * actual.abs().max(expected.abs());
117        assert!(
118            (actual - expected).abs() <= tolerance,
119            "values differ: actual={actual}, expected={expected}, tolerance={tolerance}"
120        );
121    }
122
123    /// Checks the defining adjoint identity `<Jv, w> = <v, J^T w>` for scalars.
124    pub fn assert_scalar_adjoint_identity(
125        jvp: f64,
126        output_cotangent: f64,
127        input_tangent: f64,
128        input_cotangent: f64,
129        tolerance: f64,
130    ) {
131        assert_close(
132            jvp * output_cotangent,
133            input_tangent * input_cotangent,
134            tolerance,
135            tolerance,
136        );
137    }
138}
139#[cfg(test)]
140mod tests {
141    use super::{JvpRule, Pullback, VjpRule};
142    use crate::testing::{assert_close, assert_scalar_adjoint_identity, central_difference};
143
144    struct Square;
145
146    struct SquarePullback {
147        x: f64,
148    }
149
150    impl Pullback<f64, f64> for SquarePullback {
151        fn apply(self, cotangent: f64) -> f64 {
152            2.0 * self.x * cotangent
153        }
154    }
155
156    impl JvpRule<f64> for Square {
157        type Output = f64;
158
159        fn jvp(&self, x: &f64, tangent: &f64) -> (f64, f64) {
160            (x * x, 2.0 * x * tangent)
161        }
162    }
163
164    impl VjpRule<f64> for Square {
165        type Output = f64;
166        type Pullback<'a> = SquarePullback;
167
168        fn vjp<'a>(&'a self, x: &'a f64) -> (f64, Self::Pullback<'a>) {
169            (x * x, SquarePullback { x: *x })
170        }
171    }
172
173    #[test]
174    fn jvp_matches_finite_difference() {
175        let x = 3.0;
176        let direction = -0.25;
177        let (_, jvp) = Square.jvp(&x, &direction);
178        let numerical = central_difference(|value| value * value, x, direction, 1.0e-5);
179
180        assert_close(jvp, numerical, 1.0e-9, 1.0e-9);
181    }
182
183    #[test]
184    fn vjp_satisfies_adjoint_identity() {
185        let x = 3.0;
186        let input_tangent = -0.25;
187        let output_cotangent = 1.75;
188        let (_, jvp) = Square.jvp(&x, &input_tangent);
189        let (_, pullback) = Square.vjp(&x);
190        let input_cotangent = pullback.apply(output_cotangent);
191
192        assert_scalar_adjoint_identity(
193            jvp,
194            output_cotangent,
195            input_tangent,
196            input_cotangent,
197            1.0e-12,
198        );
199    }
200}