Skip to main content

ctrl_freeq/autodiff/
dual.rs

1//! First-order dual numbers: a value and one directional derivative.
2
3use std::ops::{Add, AddAssign, Div, DivAssign, Mul, MulAssign, Neg, Rem, RemAssign, Sub, SubAssign};
4
5use num_traits::{Num, One, Zero};
6
7use super::scalar::{Scalar, sinc_derivative_f64, sinc_f64};
8
9/// `re + eps·ε` with `ε² = 0`.  Arithmetic on duals carries the derivative of every intermediate along a single
10/// direction, which is what the Hessian-vector product needs.
11#[derive(Clone, Copy, Debug, Default, PartialEq)]
12pub struct Dual {
13    /// The value.
14    pub re: f64,
15    /// The derivative along the seeded direction.
16    pub eps: f64,
17}
18
19impl Dual {
20    /// A dual with the given value and derivative.
21    pub const fn new(re: f64, eps: f64) -> Self {
22        Dual { re, eps }
23    }
24
25    /// A constant: derivative zero.
26    pub const fn constant(re: f64) -> Self {
27        Dual { re, eps: 0.0 }
28    }
29
30    /// Apply a scalar function with value `f` and derivative `df` at `self.re`.
31    #[inline]
32    fn chain(self, f: f64, df: f64) -> Self {
33        Dual {
34            re: f,
35            eps: df * self.eps,
36        }
37    }
38}
39
40impl PartialOrd for Dual {
41    /// Duals order by value alone, so pivoting and `max` choose the same branch as the `f64` computation.
42    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
43        self.re.partial_cmp(&other.re)
44    }
45}
46
47impl Add for Dual {
48    type Output = Dual;
49    #[inline]
50    fn add(self, o: Dual) -> Dual {
51        Dual::new(self.re + o.re, self.eps + o.eps)
52    }
53}
54
55impl Sub for Dual {
56    type Output = Dual;
57    #[inline]
58    fn sub(self, o: Dual) -> Dual {
59        Dual::new(self.re - o.re, self.eps - o.eps)
60    }
61}
62
63impl Mul for Dual {
64    type Output = Dual;
65    #[inline]
66    fn mul(self, o: Dual) -> Dual {
67        Dual::new(self.re * o.re, self.re * o.eps + self.eps * o.re)
68    }
69}
70
71impl Div for Dual {
72    type Output = Dual;
73    #[inline]
74    fn div(self, o: Dual) -> Dual {
75        let q = self.re / o.re;
76        Dual::new(q, (self.eps - q * o.eps) / o.re)
77    }
78}
79
80impl Rem for Dual {
81    type Output = Dual;
82    /// `a - trunc(a / b)·b`, differentiated with the truncation held constant.
83    fn rem(self, o: Dual) -> Dual {
84        let k = (self.re / o.re).trunc();
85        Dual::new(self.re % o.re, self.eps - k * o.eps)
86    }
87}
88
89impl Neg for Dual {
90    type Output = Dual;
91    #[inline]
92    fn neg(self) -> Dual {
93        Dual::new(-self.re, -self.eps)
94    }
95}
96
97impl AddAssign for Dual {
98    #[inline]
99    fn add_assign(&mut self, o: Dual) {
100        *self = *self + o;
101    }
102}
103
104impl SubAssign for Dual {
105    #[inline]
106    fn sub_assign(&mut self, o: Dual) {
107        *self = *self - o;
108    }
109}
110
111impl MulAssign for Dual {
112    #[inline]
113    fn mul_assign(&mut self, o: Dual) {
114        *self = *self * o;
115    }
116}
117
118impl DivAssign for Dual {
119    #[inline]
120    fn div_assign(&mut self, o: Dual) {
121        *self = *self / o;
122    }
123}
124
125impl RemAssign for Dual {
126    fn rem_assign(&mut self, o: Dual) {
127        *self = *self % o;
128    }
129}
130
131impl Zero for Dual {
132    fn zero() -> Self {
133        Dual::constant(0.0)
134    }
135    fn is_zero(&self) -> bool {
136        self.re == 0.0 && self.eps == 0.0
137    }
138}
139
140impl One for Dual {
141    fn one() -> Self {
142        Dual::constant(1.0)
143    }
144}
145
146impl Num for Dual {
147    type FromStrRadixErr = <f64 as Num>::FromStrRadixErr;
148    fn from_str_radix(s: &str, radix: u32) -> Result<Self, Self::FromStrRadixErr> {
149        f64::from_str_radix(s, radix).map(Dual::constant)
150    }
151}
152
153impl Scalar for Dual {
154    #[inline]
155    fn from_f64(v: f64) -> Self {
156        Dual::constant(v)
157    }
158    #[inline]
159    fn re(self) -> f64 {
160        self.re
161    }
162    fn sqrt(self) -> Self {
163        let s = self.re.sqrt();
164        let d = if s == 0.0 { 0.0 } else { 0.5 / s };
165        self.chain(s, d)
166    }
167    fn sin(self) -> Self {
168        self.chain(self.re.sin(), self.re.cos())
169    }
170    fn cos(self) -> Self {
171        self.chain(self.re.cos(), -self.re.sin())
172    }
173    fn exp(self) -> Self {
174        let e = self.re.exp();
175        self.chain(e, e)
176    }
177    fn ln(self) -> Self {
178        self.chain(self.re.ln(), 1.0 / self.re)
179    }
180    fn atan2(self, x: Self) -> Self {
181        let r2 = x.re * x.re + self.re * self.re;
182        let eps = if r2 == 0.0 {
183            0.0
184        } else {
185            (x.re * self.eps - self.re * x.eps) / r2
186        };
187        Dual::new(self.re.atan2(x.re), eps)
188    }
189    fn abs(self) -> Self {
190        let sign = if self.re > 0.0 {
191            1.0
192        } else if self.re < 0.0 {
193            -1.0
194        } else {
195            0.0
196        };
197        self.chain(self.re.abs(), sign)
198    }
199    fn powi(self, n: i32) -> Self {
200        let d = if n == 0 { 0.0 } else { n as f64 * self.re.powi(n - 1) };
201        self.chain(self.re.powi(n), d)
202    }
203    fn sinc(self) -> Self {
204        self.chain(sinc_f64(self.re), sinc_derivative_f64(self.re))
205    }
206}
207
208#[cfg(test)]
209mod tests {
210    use super::*;
211    use crate::autodiff::C;
212
213    /// The dual derivative of `f` at `x` against a central difference of the `f64` version.
214    fn check(name: &str, f: impl Fn(Dual) -> Dual, g: impl Fn(f64) -> f64, x: f64) {
215        let h = 1e-6;
216        let fd = (g(x + h) - g(x - h)) / (2.0 * h);
217        let ad = f(Dual::new(x, 1.0));
218        assert!(
219            (ad.re - g(x)).abs() <= 1e-15 * g(x).abs().max(1.0),
220            "{name} value at {x}"
221        );
222        let scale = fd.abs().max(1.0);
223        assert!(
224            (ad.eps - fd).abs() <= 1e-7 * scale,
225            "{name}'({x}): dual {} vs fd {fd}",
226            ad.eps
227        );
228    }
229
230    #[test]
231    fn elementary_functions_match_finite_differences() {
232        for &x in &[0.3, -1.7, 2.5] {
233            check("sin", |v| v.sin(), f64::sin, x);
234            check("cos", |v| v.cos(), f64::cos, x);
235            check("exp", |v| v.exp(), f64::exp, x);
236            check("abs", |v| v.abs(), f64::abs, x);
237            check("powi3", |v| v.powi(3), |v| v.powi(3), x);
238            check("sinc", |v| v.sinc(), sinc_f64, x);
239            check("atan2", |v| v.atan2(Dual::constant(0.7)), |v| v.atan2(0.7), x);
240            check("atan2x", |v| Dual::constant(0.7).atan2(v), |v| 0.7f64.atan2(v), x);
241            check(
242                "div",
243                |v| Dual::constant(1.3) / (v * v + Dual::constant(1.0)),
244                |v| 1.3 / (v * v + 1.0),
245                x,
246            );
247        }
248        for &x in &[0.3, 2.5] {
249            check("sqrt", |v| v.sqrt(), f64::sqrt, x);
250            check("ln", |v| v.ln(), f64::ln, x);
251        }
252    }
253
254    #[test]
255    fn sinc_is_smooth_through_zero() {
256        for &x in &[0.0, 1e-5, -1e-5, 9e-5, 1.1e-4] {
257            let h = 1e-7;
258            let fd = (sinc_f64(x + h) - sinc_f64(x - h)) / (2.0 * h);
259            let ad = Dual::new(x, 1.0).sinc();
260            assert!((ad.eps - fd).abs() < 1e-7, "sinc'({x})");
261            assert!((ad.re - 1.0).abs() < 1e-8);
262        }
263    }
264
265    #[test]
266    fn sqrt_has_zero_derivative_at_zero() {
267        assert_eq!(Dual::new(0.0, 1.0).sqrt(), Dual::new(0.0, 0.0));
268    }
269
270    /// Complex arithmetic over duals is the product rule applied to real and imaginary parts.
271    #[test]
272    fn complex_duals_follow_the_product_rule() {
273        let t = 0.4;
274        let z = |s: f64| C::new(1.0 + s, -0.5 * s);
275        let w = C::new(0.3, 2.0);
276        let f64_at = |s: f64| (z(s) * w * z(s)).norm_sqr();
277        let dz = C::new(Dual::new(1.0 + t, 1.0), Dual::new(-0.5 * t, -0.5));
278        let dw = C::new(Dual::constant(0.3), Dual::constant(2.0));
279        let prod = dz * dw * dz;
280        let dual = prod.re * prod.re + prod.im * prod.im;
281        let h = 1e-6;
282        let fd = (f64_at(t + h) - f64_at(t - h)) / (2.0 * h);
283        assert!((dual.eps - fd).abs() < 1e-6 * fd.abs().max(1.0));
284    }
285}