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}