1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
//! Numerical matrix rank via the singular-value spectrum.
use crateRealScalar;
use ;
/// Numerical rank: the count of singular values above a relative threshold.
///
/// ```
/// use leto::Array2;
/// use leto_ops::{matrix_rank, matrix_rank_with_tolerance};
///
/// let full = Array2::from_shape_vec([2, 2], vec![1.0_f64, 0.0, 0.0, 3.0]).unwrap();
/// assert_eq!(matrix_rank(&full.view()).unwrap(), 2);
///
/// let nearly_zero = Array2::from_shape_vec([2, 2], vec![1.0_f64, 0.0, 0.0, 1.0e-12]).unwrap();
/// assert_eq!(matrix_rank_with_tolerance(&nearly_zero.view(), 1.0e-9).unwrap(), 1);
/// ```
///
/// # Theorem (rank equals the number of nonzero singular values)
/// For `A = U Σ Vᵀ` with `U, V` having orthonormal columns,
/// `rank(A) = #{ i : σᵢ ≠ 0 }`.
/// *Proof:* orthonormal-column factors are injective linear maps, so they
/// preserve rank; hence `rank(A) = rank(Σ)`. A (rectangular) diagonal matrix's
/// rank is exactly the number of nonzero diagonal entries. ∎
///
/// Exact rank is discontinuous under round-off, so the numerical rank counts
/// `σᵢ > τ · σ_max` for a *relative* tolerance `τ`: any singular value below the
/// noise floor of the largest is treated as structurally zero. This is the same
/// SVD-truncation criterion leto's `rank` uses.
///
/// Single source of truth: the spectrum is computed by
/// [`singular_values`](crate::singular_values) (which already returns zeros for
/// rank-deficient inputs); this function adds only the threshold count — there
/// is no second SVD path.
///
/// # Errors
/// Propagates [`LetoError`](leto::LetoError) for empty or non-finite input
/// (from the singular-value kernel).
/// Numerical rank with a conservative default relative tolerance (`1e-9`).
///
/// See [`matrix_rank_with_tolerance`] for the criterion and proof.
///
/// # Errors
/// Propagates [`LetoError`](leto::LetoError) for empty or non-finite input.
/// Conservative relative singular-value floor used by [`matrix_rank`].