Skip to main content

chainrules_core/
lib.rs

1//! Backend-agnostic contracts for custom automatic-differentiation rules.
2//!
3//! `chainrules-core` is intentionally not an AD engine. It defines a small
4//! protocol through which numerical packages publish operation-aware
5//! Jacobian-vector product (JVP) and vector-Jacobian product (VJP) rules.
6//! Backends may consume those rules without either side depending on the
7//! other.
8//!
9//! Version 0.2 specifies distinct tangent and cotangent associations, typed
10//! failure for both primal and reverse computations, and one-shot pullback
11//! ownership. See the repository's `PROTOCOL.md` and `MIGRATION.md` for the
12//! complete semantic contract and the migration from 0.1.
13//!
14//! # Example
15//!
16//! ```
17//! use std::convert::Infallible;
18//!
19//! use chainrules_core::{JvpRule, Pullback, VjpRule};
20//!
21//! struct Scale(f64);
22//! struct ScalePullback(f64);
23//!
24//! impl JvpRule<f64> for Scale {
25//!     type Output = f64;
26//!     type Error = Infallible;
27//!
28//!     fn jvp(&self, x: &f64, dx: &f64) -> Result<(f64, f64), Self::Error> {
29//!         Ok((self.0 * x, self.0 * dx))
30//!     }
31//! }
32//!
33//! impl Pullback<f64, f64> for ScalePullback {
34//!     type Error = Infallible;
35//!
36//!     fn apply(self, cotangent: f64) -> Result<f64, Self::Error> {
37//!         Ok(self.0 * cotangent)
38//!     }
39//! }
40//!
41//! impl VjpRule<f64> for Scale {
42//!     type Output = f64;
43//!     type Error = Infallible;
44//!     type Pullback<'a> = ScalePullback;
45//!
46//!     fn vjp<'a>(
47//!         &'a self,
48//!         x: &'a f64,
49//!     ) -> Result<(f64, Self::Pullback<'a>), Self::Error> {
50//!         Ok((self.0 * x, ScalePullback(self.0)))
51//!     }
52//! }
53//!
54//! let rule = Scale(3.0);
55//! assert_eq!(rule.jvp(&2.0, &0.5).unwrap(), (6.0, 1.5));
56//! let (value, pullback) = rule.vjp(&2.0).unwrap();
57//! assert_eq!((value, pullback.apply(0.25).unwrap()), (6.0, 0.75));
58//! ```
59
60#![forbid(unsafe_code)]
61
62/// Associates a primal value with its forward tangent and reverse cotangent
63/// representations.
64///
65/// The two associated types may be identical for Euclidean values, but the
66/// protocol keeps their roles distinct. A scientific type may therefore use a
67/// lightweight perturbation in forward mode and a different accumulator in
68/// reverse mode.
69pub trait Differentiable {
70    /// Representation of a forward perturbation of this primal value.
71    type Tangent;
72
73    /// Representation of a reverse sensitivity of this primal value.
74    type Cotangent;
75}
76
77/// Marks a primal value with no differentiable input space.
78///
79/// Examples include a solver choice, an index, a sparsity pattern, or a
80/// discrete sector. `NoTangent` is not a zero derivative: a zero derivative
81/// belongs to a tangent space that exists, whereas `NoTangent` means there is
82/// no such space.
83#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
84pub struct NoTangent;
85
86impl Differentiable for f32 {
87    type Tangent = f32;
88    type Cotangent = f32;
89}
90
91impl Differentiable for f64 {
92    type Tangent = f64;
93    type Cotangent = f64;
94}
95
96impl Differentiable for () {
97    type Tangent = NoTangent;
98    type Cotangent = NoTangent;
99}
100
101impl<A, B> Differentiable for (A, B)
102where
103    A: Differentiable,
104    B: Differentiable,
105{
106    type Tangent = (A::Tangent, B::Tangent);
107    type Cotangent = (A::Cotangent, B::Cotangent);
108}
109
110impl<T, const N: usize> Differentiable for [T; N]
111where
112    T: Differentiable,
113{
114    type Tangent = [T::Tangent; N];
115    type Cotangent = [T::Cotangent; N];
116}
117
118impl<T> Differentiable for Vec<T>
119where
120    T: Differentiable,
121{
122    type Tangent = Vec<T::Tangent>;
123    type Cotangent = Vec<T::Cotangent>;
124}
125
126#[cfg(feature = "num-complex")]
127impl<T> Differentiable for num_complex::Complex<T>
128where
129    T: Differentiable,
130{
131    type Tangent = num_complex::Complex<T::Tangent>;
132    type Cotangent = num_complex::Complex<T::Cotangent>;
133}
134
135/// A forward-mode rule computing a primal output and a Jacobian-vector
136/// product.
137///
138/// Numerical rules are fallible by construction. Pure algebraic rules should
139/// use [`std::convert::Infallible`] as `Error`.
140pub trait JvpRule<Args>
141where
142    Args: Differentiable,
143{
144    /// Primal output type.
145    type Output: Differentiable;
146
147    /// Error returned by primal evaluation or tangent propagation.
148    type Error;
149
150    /// Evaluates the primal operation and propagates one input tangent.
151    #[allow(clippy::type_complexity)]
152    fn jvp(
153        &self,
154        args: &Args,
155        tangent: &Args::Tangent,
156    ) -> Result<(Self::Output, <Self::Output as Differentiable>::Tangent), Self::Error>;
157}
158
159/// A one-shot reverse-mode pullback.
160///
161/// Consuming `self` permits a pullback to own a factorization, Krylov basis,
162/// checkpoint set, or device buffer and release it after one reverse
163/// application. A pullback may also borrow immutable primal inputs through the
164/// generic associated type on [`VjpRule`].
165pub trait Pullback<OutputCotangent, InputCotangent> {
166    /// Error returned by the reverse computation.
167    type Error;
168
169    /// Applies the pullback once.
170    fn apply(self, cotangent: OutputCotangent) -> Result<InputCotangent, Self::Error>;
171}
172
173impl<F, OutputCotangent, InputCotangent, Error> Pullback<OutputCotangent, InputCotangent> for F
174where
175    F: FnOnce(OutputCotangent) -> Result<InputCotangent, Error>,
176{
177    type Error = Error;
178
179    fn apply(self, cotangent: OutputCotangent) -> Result<InputCotangent, Self::Error> {
180        self(cotangent)
181    }
182}
183
184/// A reverse-mode rule computing a primal output and a one-shot pullback.
185///
186/// The generic associated type allows the pullback to borrow `self` or
187/// `args`. Caches produced during the forward evaluation can instead be owned
188/// by the pullback. The same typed error is used at the rule boundary for
189/// forward and reverse failures; downstream error enums can record the stage.
190pub trait VjpRule<Args>
191where
192    Args: Differentiable,
193{
194    /// Primal output type.
195    type Output: Differentiable;
196
197    /// Error returned by primal evaluation or pullback application.
198    type Error;
199
200    /// Pullback produced for one primal evaluation.
201    type Pullback<'a>: Pullback<<Self::Output as Differentiable>::Cotangent, Args::Cotangent, Error = Self::Error>
202    where
203        Self: 'a,
204        Args: 'a;
205
206    /// Evaluates the primal operation and constructs its pullback.
207    fn vjp<'a>(&'a self, args: &'a Args)
208    -> Result<(Self::Output, Self::Pullback<'a>), Self::Error>;
209}
210
211/// Numerical conformance helpers for custom rules.
212///
213/// The helpers accept closures for perturbation, differencing, and pairings so
214/// that the core protocol does not need a matrix, tensor, normed-space, or
215/// device-array abstraction.
216pub mod testing {
217    /// Estimates a scalar directional derivative with a central difference.
218    #[must_use]
219    pub fn central_difference<F>(f: F, x: f64, direction: f64, step: f64) -> f64
220    where
221        F: Fn(f64) -> f64,
222    {
223        assert_valid_step(step);
224        (f(x + step * direction) - f(x - step * direction)) / (2.0 * step)
225    }
226
227    /// Estimates a directional derivative for an arbitrary output type.
228    ///
229    /// `evaluate_at_offset(scale)` evaluates the primal at `x + scale * v`.
230    /// `difference` receives the positive value, negative value, and
231    /// denominator `2h`. Keeping those operations in closures avoids imposing
232    /// public vector-space traits on scientific types.
233    pub fn directional_central_difference<Output, Error, Evaluate, Difference>(
234        mut evaluate_at_offset: Evaluate,
235        step: f64,
236        difference: Difference,
237    ) -> Result<Output, Error>
238    where
239        Evaluate: FnMut(f64) -> Result<Output, Error>,
240        Difference: FnOnce(Output, Output, f64) -> Output,
241    {
242        assert_valid_step(step);
243        let positive = evaluate_at_offset(step)?;
244        let negative = evaluate_at_offset(-step)?;
245        Ok(difference(positive, negative, 2.0 * step))
246    }
247
248    /// Asserts approximate equality using combined absolute and relative
249    /// tolerances.
250    pub fn assert_close(actual: f64, expected: f64, relative: f64, absolute: f64) {
251        assert!(
252            relative.is_finite() && relative >= 0.0,
253            "relative tolerance must be finite and nonnegative"
254        );
255        assert!(
256            absolute.is_finite() && absolute >= 0.0,
257            "absolute tolerance must be finite and nonnegative"
258        );
259        let tolerance = absolute + relative * actual.abs().max(expected.abs());
260        assert!(
261            (actual - expected).abs() <= tolerance,
262            "values differ: actual={actual}, expected={expected}, tolerance={tolerance}"
263        );
264    }
265
266    /// Checks the adjoint identity for arbitrary tangent and cotangent types.
267    ///
268    /// The defining identity is
269    /// `<Jv, w>_output = <v, J*w>_input`. The two pairing closures return real
270    /// scalars and therefore also support complex spaces using a real pairing.
271    #[allow(clippy::too_many_arguments)]
272    pub fn assert_adjoint_identity<
273        OutputTangent,
274        OutputCotangent,
275        InputTangent,
276        InputCotangent,
277        OutputPairing,
278        InputPairing,
279    >(
280        jvp: &OutputTangent,
281        output_cotangent: &OutputCotangent,
282        input_tangent: &InputTangent,
283        input_cotangent: &InputCotangent,
284        output_pairing: OutputPairing,
285        input_pairing: InputPairing,
286        relative: f64,
287        absolute: f64,
288    ) where
289        OutputPairing: FnOnce(&OutputTangent, &OutputCotangent) -> f64,
290        InputPairing: FnOnce(&InputTangent, &InputCotangent) -> f64,
291    {
292        assert_close(
293            output_pairing(jvp, output_cotangent),
294            input_pairing(input_tangent, input_cotangent),
295            relative,
296            absolute,
297        );
298    }
299
300    /// Scalar convenience wrapper for [`assert_adjoint_identity`].
301    pub fn assert_scalar_adjoint_identity(
302        jvp: f64,
303        output_cotangent: f64,
304        input_tangent: f64,
305        input_cotangent: f64,
306        tolerance: f64,
307    ) {
308        assert_adjoint_identity(
309            &jvp,
310            &output_cotangent,
311            &input_tangent,
312            &input_cotangent,
313            |left, right| left * right,
314            |left, right| left * right,
315            tolerance,
316            tolerance,
317        );
318    }
319
320    fn assert_valid_step(step: f64) {
321        assert!(
322            step.is_finite() && step > 0.0,
323            "finite-difference step must be finite and positive"
324        );
325    }
326}