Skip to main content

embedded_matrix/
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-matrix
9//!
10//! Matrices 2×2 et 3×3 en `f32` pour systèmes embarqués `no_std`.
11//!
12//! Sans dépendance, sans `unsafe`, sans allocation.
13//!
14//! ```rust
15//! use embedded_matrix::{Matrix2x2, Matrix3x3, MatrixError};
16//!
17//! // Produit matriciel avec l'opérateur *
18//! let a = Matrix3x3::new([
19//!     [1.0, 2.0, 3.0],
20//!     [4.0, 5.0, 6.0],
21//!     [7.0, 8.0, 9.0],
22//! ]);
23//! let b = Matrix3x3::identity();
24//! assert_eq!(a * b, a);
25//!
26//! // Addition, soustraction, scalaire
27//! assert_eq!((a + b) - b, a);
28//! let _double = a * 2.0;
29//!
30//! // Matrice × vecteur
31//! let v = Matrix2x2::identity() * [1.0, 2.0];
32//! assert_eq!(v, [1.0, 2.0]);
33//!
34//! // Inversion (Err si singulière ou non finie)
35//! match Matrix2x2::new([[2.0, 0.0], [0.0, 4.0]]).inv() {
36//!     Ok(inv) => assert_eq!(inv, Matrix2x2::new([[0.5, 0.0], [0.0, 0.25]])),
37//!     Err(MatrixError::SingularMatrix) => { /* gérer */ }
38//!     Err(e) => panic!("{e}"),
39//! }
40//! ```
41//!
42//! ## Détection des matrices singulières
43//!
44//! `inv` compare `|det|` à une borne **relative** à la taille des termes du
45//! déterminant (et non à une constante absolue) : une matrice `1e-4 · I`
46//! reste inversible, alors qu'une matrice de grands coefficients dont le
47//! déterminant n'est que du bruit d'arrondi est correctement rejetée.
48
49#![no_std]
50#![forbid(unsafe_code)]
51#![deny(missing_docs)]
52
53mod error;
54mod matrix2x2;
55mod matrix3x3;
56
57pub use error::MatrixError;
58pub use matrix2x2::Matrix2x2;
59pub use matrix3x3::Matrix3x3;
60
61/// Seuil relatif : `|det| <= SINGULAR_REL * borne` ⇒ matrice singulière.
62/// `borne` est la somme des valeurs absolues des termes du déterminant.
63const SINGULAR_REL: f32 = 8.0 * f32::EPSILON;
64
65/// Valide un déterminant avant inversion.
66///
67/// `bound` : somme des valeurs absolues des termes qui composent `det`
68/// (échelle de l'erreur d'arrondi attendue sur `det`).
69#[inline]
70pub(crate) fn check_det(det: f32, bound: f32) -> Result<(), MatrixError> {
71    if !det.is_finite() || !bound.is_finite() {
72        return Err(MatrixError::NonFiniteValue);
73    }
74    if det.abs() <= SINGULAR_REL * bound {
75        Err(MatrixError::SingularMatrix)
76    } else {
77        Ok(())
78    }
79}