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}