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
72
73
74
75
//! Singular value decomposition and the Moore-Penrose pseudoinverse.
//!
//! # Theorem (existence of the SVD)
//! Every `A ∈ ℝᵐˣⁿ` factors as `A = U Σ Vᵀ` with `U ∈ ℝᵐˣᵏ`, `V ∈ ℝⁿˣᵏ`
//! (`k = min(m,n)`) having orthonormal columns and `Σ = diag(σ₁ ≥ … ≥ σₖ ≥ 0)`.
//! *Proof sketch:* `AᵀA` is symmetric positive-semidefinite, so by the spectral
//! theorem it has an orthonormal eigenbasis `{vᵢ}` with eigenvalues `λᵢ ≥ 0`;
//! set `σᵢ = √λᵢ` and, for `σᵢ > 0`, `uᵢ = A vᵢ / σᵢ`. Then `{uᵢ}` are
//! orthonormal (`uᵢᵀuⱼ = vᵢᵀAᵀA vⱼ / (σᵢσⱼ) = λⱼ δᵢⱼ /(σᵢσⱼ) = δᵢⱼ`) and
//! `A vᵢ = σᵢ uᵢ`, i.e. `A V = U Σ`. ∎
//!
//! One implementation backs the whole surface (SSOT): `bidiagonal_qr`,
//! Golub–Reinsch implicit-shift bidiagonal QR. It never forms `AᵀA`, so
//! conditioning stays `κ(A)` rather than `κ(A)²`, and it is **rank-revealing**:
//! zero singular values emerge from the iteration itself, while `U` and `V`
//! stay orthogonal whatever the rank of `A` — both are accumulated products of
//! Householder reflectors and Givens rotations, and a product of orthogonal
//! factors is orthogonal irrespective of the singular values it diagonalizes.
//! Rank is therefore read off `Σ` rather than signalled by an error (ADR 0005).
//!
//! - [`svd_decompose`] — thin SVD `A = U Σ Vᵀ`, all shapes, any rank.
//! - [`singular_values`] — values only, no `U`/`V` accumulation.
//! - [`pinv`] — Moore-Penrose `A⁺` under a relative rank cutoff.
use crateRealScalar;
use ;
/// Bidiagonal-QR SVD: thin SVD and singular values (accuracy-preserving).
/// Moore-Penrose pseudoinverse.
pub use ;
pub use pinv;
/// Thin singular value decomposition `A = U Σ Vᵀ`.
///
/// `singular_values` are sorted descending (length `k = min(m, n)`) and are
/// non-negative; `left_singular_vectors` is `U` (`m × k`, columns) and
/// `right_singular_vectors` is `V` (`n × k`, columns). Rank-deficient input
/// yields zero singular values, and `U` and `V` keep orthonormal columns in
/// that case too — the null-space directions are materialized rather than left
/// zero, so `UᵀU = VᵀV = I` holds at every rank.
/// Reject empty or non-finite input.
pub