1#![forbid(unsafe_code)]
8
9pub trait Differentiable {
11 type Tangent;
13}
14
15#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
17pub struct NoTangent;
18
19#[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
50pub trait JvpRule<Args>
52where
53 Args: Differentiable,
54{
55 type Output: Differentiable;
57
58 fn jvp(
60 &self,
61 args: &Args,
62 tangent: &Args::Tangent,
63 ) -> (Self::Output, <Self::Output as Differentiable>::Tangent);
64}
65
66pub trait Pullback<OutputTangent, InputTangent> {
68 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
81pub trait VjpRule<Args>
86where
87 Args: Differentiable,
88{
89 type Output: Differentiable;
91
92 type Pullback<'a>: Pullback<<Self::Output as Differentiable>::Tangent, Args::Tangent>
94 where
95 Self: 'a,
96 Args: 'a;
97
98 fn vjp<'a>(&'a self, args: &'a Args) -> (Self::Output, Self::Pullback<'a>);
100}
101
102pub mod testing {
104 #[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 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 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}