Skip to main content

embedded_maths/embedded-maths-functions/
ln.rs

1//! Logarithme népérien approché pour `f32`, sans dépendance externe.
2//!
3//! Méthode : x = m · 2^e avec m ∈ [√2/2, √2), donc
4//!   ln(x) = e·ln(2) + ln(m)
5//!   ln(m) = 2·atanh(s) = 2·(s + s³/3 + s⁵/5 + s⁷/7 + s⁹/9 + …),  s = (m-1)/(m+1)
6//! Avec |s| ≤ 0,1716, cinq termes suffisent à la précision d'un `f32`.
7
8use core::f32::consts::{LN_2, SQRT_2};
9
10/// Approximation du logarithme népérien de `x`.
11///
12/// - `x < 0` ou NaN → NaN
13/// - `x == 0`       → -∞
14/// - `x == +∞`      → +∞
15/// - gère les dénormalisés
16pub fn ln(x: f32) -> f32 {
17    if x.is_nan() || x < 0.0 {
18        return f32::NAN;
19    }
20    if x == 0.0 {
21        return f32::NEG_INFINITY;
22    }
23    if x == f32::INFINITY {
24        return x;
25    }
26
27    let mut bits = x.to_bits();
28    let mut exp: i32 = 0;
29
30    // Nombre dénormalisé : on le remet à l'échelle (× 2^24).
31    if bits < 0x0080_0000 {
32        bits = (x * 16_777_216.0).to_bits();
33        exp = -24;
34    }
35
36    exp += ((bits >> 23) & 0xFF) as i32 - 127;
37
38    // Mantisse normalisée dans [1, 2)
39    let mut m = f32::from_bits((bits & 0x007F_FFFF) | 0x3F80_0000);
40
41    // Recentrage dans [√2/2, √2) pour minimiser |s|
42    if m > SQRT_2 {
43        m *= 0.5;
44        exp += 1;
45    }
46
47    let s = (m - 1.0) / (m + 1.0);
48    let s2 = s * s;
49
50    // 2·s·(1 + s²/3 + s⁴/5 + s⁶/7 + s⁸/9), évalué par Horner
51    let series = 1.0 + s2 * (1.0 / 3.0 + s2 * (1.0 / 5.0 + s2 * (1.0 / 7.0 + s2 * (1.0 / 9.0))));
52    let ln_m = 2.0 * s * series;
53
54    exp as f32 * LN_2 + ln_m
55}
56
57#[cfg(test)]
58mod tests {
59    use super::ln;
60    use core::f32::consts::LN_10;
61
62    const MAX_REL_ERROR: f32 = 1e-5;
63
64    #[test]
65    fn one_is_exactly_zero() {
66        assert_eq!(ln(1.0), 0.0);
67    }
68
69    #[test]
70    fn powers_of_ten() {
71        // ln(10^k) = k · ln(10)
72        for k in -37..=38 {
73            if k == 0 {
74                continue;
75            }
76            let x = 10f32.powi(k);
77            let expected = k as f32 * LN_10;
78            let got = ln(x);
79            let rel = ((got - expected) / expected).abs();
80            assert!(
81                rel <= MAX_REL_ERROR,
82                "k={k}: {got} vs {expected} (rel {rel})"
83            );
84        }
85    }
86
87    #[test]
88    fn subnormal() {
89        let got = ln(1e-40);
90        let expected = -40.0 * LN_10;
91        assert!(((got - expected) / expected).abs() <= MAX_REL_ERROR);
92    }
93
94    #[test]
95    fn special_values() {
96        assert!(ln(-1.0).is_nan());
97        assert!(ln(f32::NAN).is_nan());
98        assert_eq!(ln(0.0), f32::NEG_INFINITY);
99        assert_eq!(ln(f32::INFINITY), f32::INFINITY);
100    }
101}