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//! ## Résolution de systèmes
43//!
44//! `solve(b)` résout `A·x = b` et renvoie directement `x` :
45//!
46//! ```rust
47//! use embedded_matrix::Matrix2x2;
48//!
49//! let a = Matrix2x2::new([[2.0, 1.0], [1.0, 3.0]]);
50//! let x = a.solve([3.0, 5.0]).unwrap(); // x = [0.8, 1.4]
51//! assert!((x[0] - 0.8).abs() < 1e-6);
52//! ```
53//!
54//! ## Feature optionnelle : `trig`
55//!
56//! ```toml
57//! embedded-matrix = { version = "0.3", features = ["trig"] }
58//! ```
59//!
60//! Active la dépendance à `embedded-trig-f32` et ajoute les constructeurs de
61//! rotation : `Matrix2x2::rotation(angle)`, `Matrix3x3::rotation_x / _y / _z(angle)`
62//! (angles en radians, règle de la main droite). Sans la feature, la crate
63//! n'a **aucune dépendance**.
64//!
65//! ## Pistes futures (non implémentées)
66//!
67//! Ces idées ne font pas partie de l'API actuelle ; elles sont notées ici
68//! pour la suite :
69//!
70//! - **Taille quelconque** : `Matrix<const R: usize, const C: usize>` sur la
71//!   pile (alias `Matrix2x2 = Matrix<2, 2>`), produit de matrices non carrées.
72//! - **Décomposition LU** avec pivot partiel pour `det`, `inv` et `solve`
73//!   en taille n.
74//! - **Cholesky** pour les matrices symétriques définies positives
75//!   (matrices de covariance).
76//! - **Type `Vector<N>`** : produit scalaire, produit vectoriel 3D, norme.
77//! - **`#[must_use]`** sur les opérations arithmétiques.
78//! - **Benchmarks en cycles** (compteur DWT) et CI de compilation embarquée.
79//!
80//! ## Détection des matrices singulières
81//!
82//! `inv` compare `|det|` à une borne **relative** à la taille des termes du
83//! déterminant (et non à une constante absolue) : une matrice `1e-4 · I`
84//! reste inversible, alors qu'une matrice de grands coefficients dont le
85//! déterminant n'est que du bruit d'arrondi est correctement rejetée.
86
87#![no_std]
88#![forbid(unsafe_code)]
89#![deny(missing_docs)]
90
91mod error;
92mod matrix2x2;
93mod matrix3x3;
94
95pub use error::MatrixError;
96pub use matrix2x2::Matrix2x2;
97pub use matrix3x3::Matrix3x3;
98
99/// Seuil relatif : `|det| <= SINGULAR_REL * borne` ⇒ matrice singulière.
100/// `borne` est la somme des valeurs absolues des termes du déterminant.
101const SINGULAR_REL: f32 = 8.0 * f32::EPSILON;
102
103/// Valide un déterminant avant inversion.
104///
105/// `bound` : somme des valeurs absolues des termes qui composent `det`
106/// (échelle de l'erreur d'arrondi attendue sur `det`).
107#[inline]
108pub(crate) fn check_det(det: f32, bound: f32) -> Result<(), MatrixError> {
109    if !det.is_finite() || !bound.is_finite() {
110        return Err(MatrixError::NonFiniteValue);
111    }
112    if det.abs() <= SINGULAR_REL * bound {
113        Err(MatrixError::SingularMatrix)
114    } else {
115        Ok(())
116    }
117}