Skip to main content

embedded_invsqrt_f32/
lib.rs

1// Copyright (C) 2026 Jorge Andre Castro
2//
3// Ce programme est un logiciel libre : vous pouvez le redistribuer et/ou le modifier
4// selon les termes de la Licence Publique Générale GNU telle que publiée par la
5// Free Software Foundation, soit la version 2 de la licence, soit (à votre convention)
6// n'importe quelle version ultérieure.
7
8//! # embedded-invsqrt-f32
9//!
10//! Inverse de racine carrée rapide `f32` (`1 / sqrt(x)`) pour systèmes embarqués `no_std`.
11//!
12//! Sans dépendance, sans `unsafe`, sans FPU requise (mais optimisé si présente).
13//!
14//! ```rust
15//! use embedded_invsqrt_f32::inv_sqrt;
16//!
17//! assert!((inv_sqrt(4.0).unwrap() - 0.5).abs() < 1e-5);
18//! assert!((inv_sqrt(1.0).unwrap() - 1.0).abs() < 1e-5);
19//! assert!(inv_sqrt(-1.0).is_err());
20//! ```
21
22#![no_std]
23#![forbid(unsafe_code)]
24#![warn(missing_docs)]
25
26/// Erreur retournée pour une entrée négative ou nulle.
27#[derive(Debug, Clone, Copy, PartialEq, Eq)]
28pub struct NegativeOrZeroInput;
29
30/// Inverse de racine carrée `f32` par méthode itérative.
31///
32/// Estimation initiale via la constante magique IEEE 754 (style Fast Inverse Square Root),
33/// puis itérations de Newton-Raphson pour converger vers une précision élevée.
34///
35/// Retourne `Err(NegativeOrZeroInput)` si `x <= 0.0`.
36pub fn inv_sqrt(x: f32) -> Result<f32, NegativeOrZeroInput> {
37    if x.is_nan() {
38        return Ok(f32::NAN);
39    }
40    if x.is_infinite() {
41        return Ok(if x.is_sign_negative() { f32::NAN } else { 0.0 });
42    }
43    if x <= 0.0 {
44        return Err(NegativeOrZeroInput);
45    }
46
47    // Constante magique pour f32 (variante de la Fast Inverse Square Root)
48    let i = 0x5F37_59DF - (x.to_bits() >> 1);
49    let mut y = f32::from_bits(i);
50
51    // Itération de Raffinement de Newton-Raphson : y = y * (1.5 - 0.5 * x * y * y)
52    // 2 itérations suffisent généralement amplement après la constante magique.
53    let xhalf = 0.5 * x;
54    y = y * (1.5 - xhalf * y * y);
55    y = y * (1.5 - xhalf * y * y);
56
57    Ok(y)
58}
59
60#[cfg(test)]
61mod tests {
62    use super::*;
63
64    #[test]
65    fn standard_values() {
66        let expected = 1.0 / (4.0_f32).sqrt();
67        assert!((inv_sqrt(4.0).unwrap() - expected).abs() < 1e-5);
68
69        let expected_two = 1.0 / (2.0_f32).sqrt();
70        assert!((inv_sqrt(2.0).unwrap() - expected_two).abs() < 1e-5);
71    }
72
73    #[test]
74    fn negative_or_zero() {
75        assert_eq!(inv_sqrt(0.0), Err(NegativeOrZeroInput));
76        assert_eq!(inv_sqrt(-1.0), Err(NegativeOrZeroInput));
77    }
78}