Skip to main content

solow_linalg/
lib.rs

1//! # solow-linalg
2//!
3//! Pure-Rust dense linear algebra for the Solow statistical stack. No system
4//! LAPACK/BLAS is required: the decompositions are implemented here and validated
5//! against an authoritative reference.
6//!
7//! - [`cholesky`] — `A = L Lᵀ`
8//! - [`lu_factor`] — `P A = L U` (powers [`solve`], [`inv`], [`det`])
9//! - [`qr`] — economy Householder QR
10//! - [`svd`] — economy one-sided Jacobi SVD
11//! - [`eigh`] — symmetric eigendecomposition (cyclic Jacobi)
12//! - [`pinv`] / [`lstsq`] / [`matrix_rank`] — SVD-based
13
14mod decomp;
15mod solve;
16
17pub use decomp::{cholesky, eigh, lu_factor, qr, svd, Lu};
18pub use solve::{
19    cholesky_solve, det, inv, lstsq, lstsq_qr, matrix_rank, pinv, pinv_rcond, solve, solve_matrix,
20};
21
22#[cfg(test)]
23mod tests {
24    use super::*;
25    use approx::assert_abs_diff_eq;
26    use ndarray::{array, Array2};
27
28    fn frob(a: &Array2<f64>) -> f64 {
29        a.iter().map(|&x| x * x).sum::<f64>().sqrt()
30    }
31
32    fn norm1(a: &ndarray::Array1<f64>) -> f64 {
33        a.iter().map(|&x| x * x).sum::<f64>().sqrt()
34    }
35
36    #[test]
37    fn cholesky_reconstructs() {
38        let a = array![[4.0, 2.0, 2.0], [2.0, 5.0, 1.0], [2.0, 1.0, 6.0]];
39        let l = cholesky(&a).unwrap();
40        let recon = l.dot(&l.t());
41        assert_abs_diff_eq!(frob(&(&recon - &a)), 0.0, epsilon = 1e-12);
42    }
43
44    #[test]
45    fn lu_solve_and_inv() {
46        let a = array![[2.0, 1.0, 1.0], [4.0, -6.0, 0.0], [-2.0, 7.0, 2.0]];
47        let b = array![5.0, -2.0, 9.0];
48        let x = solve(&a, &b).unwrap();
49        let recon = a.dot(&x);
50        assert_abs_diff_eq!(norm1(&(&recon - &b)), 0.0, epsilon = 1e-10);
51
52        let ainv = inv(&a).unwrap();
53        let id = a.dot(&ainv);
54        let eye = Array2::<f64>::eye(3);
55        assert_abs_diff_eq!(frob(&(&id - &eye)), 0.0, epsilon = 1e-10);
56    }
57
58    #[test]
59    fn det_matches_known() {
60        let a = array![[1.0, 2.0], [3.0, 4.0]];
61        assert_abs_diff_eq!(det(&a).unwrap(), -2.0, epsilon = 1e-12);
62        let singular = array![[1.0, 2.0], [2.0, 4.0]];
63        assert_abs_diff_eq!(det(&singular).unwrap(), 0.0, epsilon = 1e-12);
64    }
65
66    #[test]
67    fn qr_reconstructs_and_orthonormal() {
68        let a = array![
69            [12.0, -51.0, 4.0],
70            [6.0, 167.0, -68.0],
71            [-4.0, 24.0, -41.0],
72            [-1.0, 1.0, 0.0],
73            [2.0, 0.0, 3.0]
74        ];
75        let (q, r) = qr(&a).unwrap();
76        let recon = q.dot(&r);
77        assert_abs_diff_eq!(frob(&(&recon - &a)), 0.0, epsilon = 1e-9);
78        // Qᵀ Q = I_n
79        let qtq = q.t().dot(&q);
80        let eye = Array2::<f64>::eye(3);
81        assert_abs_diff_eq!(frob(&(&qtq - &eye)), 0.0, epsilon = 1e-9);
82        // R upper triangular.
83        for i in 0..3 {
84            for j in 0..i {
85                assert_abs_diff_eq!(r[[i, j]], 0.0, epsilon = 1e-9);
86            }
87        }
88    }
89
90    #[test]
91    fn svd_reconstructs_tall_and_wide() {
92        let tall = array![[1.0, 2.0], [3.0, 4.0], [5.0, 6.0], [7.0, 8.0]];
93        let (u, s, vt) = svd(&tall).unwrap();
94        let sd = Array2::from_diag(&s);
95        let recon = u.dot(&sd).dot(&vt);
96        assert_abs_diff_eq!(frob(&(&recon - &tall)), 0.0, epsilon = 1e-9);
97        // Descending singular values.
98        assert!(s[0] >= s[1]);
99
100        let wide = tall.t().to_owned();
101        let (u2, s2, vt2) = svd(&wide).unwrap();
102        let sd2 = Array2::from_diag(&s2);
103        let recon2 = u2.dot(&sd2).dot(&vt2);
104        assert_abs_diff_eq!(frob(&(&recon2 - &wide)), 0.0, epsilon = 1e-9);
105    }
106
107    #[test]
108    fn lstsq_qr_matches_pinv_and_detects_rank_deficiency() {
109        // Tall full-rank design: QR least squares == pinv least squares.
110        let a = array![
111            [1.0, 0.2, -0.5],
112            [1.0, 1.1, 0.3],
113            [1.0, 2.0, 1.7],
114            [1.0, 3.2, -0.8],
115            [1.0, 4.1, 2.2],
116            [1.0, 5.0, 0.1]
117        ];
118        let b = array![1.0, 2.2, 3.1, 3.8, 5.3, 6.0];
119        let (x_qr, ncp_qr) = lstsq_qr(&a, &b).unwrap().expect("full rank → Some");
120        let x_pinv = lstsq(&a, &b).unwrap();
121        for i in 0..3 {
122            assert_abs_diff_eq!(x_qr[i], x_pinv[i], epsilon = 1e-10);
123        }
124        // ncp == (AᵀA)⁻¹.
125        let ata = a.t().dot(&a);
126        let ata_inv = inv(&ata).unwrap();
127        assert_abs_diff_eq!(frob(&(&ncp_qr - &ata_inv)), 0.0, epsilon = 1e-9);
128
129        // Rank-deficient design (col 3 = 2·col 2) → None (caller falls back to SVD).
130        let rd = array![
131            [1.0, 1.0, 2.0],
132            [1.0, 2.0, 4.0],
133            [1.0, 3.0, 6.0],
134            [1.0, 4.0, 8.0]
135        ];
136        let b2 = array![1.0, 2.0, 3.0, 4.0];
137        assert!(lstsq_qr(&rd, &b2).unwrap().is_none());
138    }
139
140    #[test]
141    fn cholesky_solve_matches_general_solve() {
142        let a = array![[4.0, 2.0, 2.0], [2.0, 5.0, 1.0], [2.0, 1.0, 6.0]];
143        let b = array![1.0, -2.0, 3.0];
144        let x = cholesky_solve(&a, &b).unwrap();
145        assert_abs_diff_eq!(norm1(&(&a.dot(&x) - &b)), 0.0, epsilon = 1e-10);
146    }
147
148    #[test]
149    fn pinv_left_inverse() {
150        let a = array![[1.0, 0.0], [0.0, 1.0], [1.0, 1.0]];
151        let (p, _s) = pinv(&a).unwrap();
152        // For full column rank, pinv(A) A = I.
153        let prod = p.dot(&a);
154        let eye = Array2::<f64>::eye(2);
155        assert_abs_diff_eq!(frob(&(&prod - &eye)), 0.0, epsilon = 1e-9);
156    }
157
158    #[test]
159    fn eigh_reconstructs_symmetric() {
160        let a = array![[2.0, 1.0, 0.0], [1.0, 2.0, 1.0], [0.0, 1.0, 2.0]];
161        let (w, v) = eigh(&a).unwrap();
162        // Ascending eigenvalues; known spectrum 2 - sqrt2, 2, 2 + sqrt2.
163        assert!(w[0] <= w[1] && w[1] <= w[2]);
164        assert_abs_diff_eq!(w[0], 2.0 - 2.0_f64.sqrt(), epsilon = 1e-9);
165        assert_abs_diff_eq!(w[2], 2.0 + 2.0_f64.sqrt(), epsilon = 1e-9);
166        // Reconstruction V diag(w) Vᵀ = A.
167        let recon = v.dot(&Array2::from_diag(&w)).dot(&v.t());
168        assert_abs_diff_eq!(frob(&(&recon - &a)), 0.0, epsilon = 1e-9);
169        // Orthonormal eigenvectors.
170        let vtv = v.t().dot(&v);
171        let eye = Array2::<f64>::eye(3);
172        assert_abs_diff_eq!(frob(&(&vtv - &eye)), 0.0, epsilon = 1e-9);
173    }
174}