tenferro_linalg/results.rs
1//! Structured results of linear-algebra decompositions (the #2552 grammar).
2
3/// Thin or full singular value decomposition `A = U diag(S) Vh`.
4///
5/// Field order equals the former tuple order `(U, S, Vh)`.
6///
7/// - `u`: left singular vectors
8/// - `s`: singular values
9/// - `vh`: conjugate transpose of the right singular vectors
10///
11/// # Examples
12///
13/// ```
14/// use tenferro_linalg::Svd;
15///
16/// let r = Svd { u: 1, s: 2.0, vh: 3 };
17/// let Svd { u, s, vh } = r;
18/// assert_eq!((u, s, vh), (1, 2.0, 3));
19/// ```
20#[derive(Clone, Debug)]
21pub struct Svd<V, R = V> {
22 /// See the type-level documentation.
23 pub u: V,
24 /// See the type-level documentation.
25 pub s: R,
26 /// See the type-level documentation.
27 pub vh: V,
28}
29
30/// QR decomposition `A = Q R`.
31///
32/// Field order equals the former tuple order `(Q, R)`.
33///
34/// - `q`: orthonormal factor
35/// - `r`: upper-triangular factor
36///
37/// # Examples
38///
39/// ```
40/// use tenferro_linalg::Qr;
41///
42/// let r = Qr { q: 1, r: 2 };
43/// let Qr { q, r } = r;
44/// assert_eq!((q, r), (1, 2));
45/// ```
46#[derive(Clone, Debug)]
47pub struct Qr<V> {
48 /// See the type-level documentation.
49 pub q: V,
50 /// See the type-level documentation.
51 pub r: V,
52}
53
54/// Partial-pivot LU decomposition `P A = L U`.
55///
56/// Field order equals the former tuple order `(P, L, U, parity)`.
57///
58/// - `p`: the permutation MATRIX tensor (not a pivot index vector)
59/// - `l`: unit lower-triangular factor
60/// - `u`: upper-triangular factor
61/// - `parity`: permutation parity
62///
63/// # Examples
64///
65/// ```
66/// use tenferro_linalg::Lu;
67///
68/// let r = Lu { p: 1, l: 2, u: 3, parity: 4.0 };
69/// let Lu { p, l, u, parity } = r;
70/// assert_eq!((p, l, u, parity), (1, 2, 3, 4.0));
71/// ```
72#[derive(Clone, Debug)]
73pub struct Lu<V, R = V> {
74 /// See the type-level documentation.
75 pub p: V,
76 /// See the type-level documentation.
77 pub l: V,
78 /// See the type-level documentation.
79 pub u: V,
80 /// See the type-level documentation.
81 pub parity: R,
82}
83
84/// Full-pivot LU decomposition `P A Q = L U`.
85///
86/// Field order equals the former tuple order `(P, L, U, Q, parity)`.
87///
88/// - `p`: row permutation MATRIX tensor (not a pivot index vector)
89/// - `l`: unit lower-triangular factor
90/// - `u`: upper-triangular factor
91/// - `q`: column permutation matrix tensor
92/// - `parity`: permutation parity
93///
94/// # Examples
95///
96/// ```
97/// use tenferro_linalg::FullPivLu;
98///
99/// let r = FullPivLu { p: 1, l: 2, u: 3, q: 4, parity: 5.0 };
100/// let FullPivLu { p, l, u, q, parity } = r;
101/// assert_eq!((p, l, u, q, parity), (1, 2, 3, 4, 5.0));
102/// ```
103#[derive(Clone, Debug)]
104pub struct FullPivLu<V, R = V> {
105 /// See the type-level documentation.
106 pub p: V,
107 /// See the type-level documentation.
108 pub l: V,
109 /// See the type-level documentation.
110 pub u: V,
111 /// See the type-level documentation.
112 pub q: V,
113 /// See the type-level documentation.
114 pub parity: R,
115}
116
117/// General eigendecomposition.
118///
119/// Field order equals the former tuple order `(values, vectors)`.
120///
121/// - `values`: eigenvalues
122/// - `vectors`: eigenvectors
123///
124/// # Examples
125///
126/// ```
127/// use tenferro_linalg::Eig;
128///
129/// let r = Eig { values: 1, vectors: 2 };
130/// let Eig { values, vectors } = r;
131/// assert_eq!((values, vectors), (1, 2));
132/// ```
133#[derive(Clone, Debug)]
134pub struct Eig<C> {
135 /// See the type-level documentation.
136 pub values: C,
137 /// See the type-level documentation.
138 pub vectors: C,
139}
140
141/// Hermitian/symmetric eigendecomposition.
142///
143/// Field order equals the former tuple order `(values, vectors)`.
144///
145/// - `values`: real eigenvalues
146/// - `vectors`: eigenvectors
147///
148/// # Examples
149///
150/// ```
151/// use tenferro_linalg::Eigh;
152///
153/// let r = Eigh { values: 1.0, vectors: 2 };
154/// let Eigh { values, vectors } = r;
155/// assert_eq!((values, vectors), (1.0, 2));
156/// ```
157#[derive(Clone, Debug)]
158pub struct Eigh<V, R = V> {
159 /// See the type-level documentation.
160 pub values: R,
161 /// See the type-level documentation.
162 pub vectors: V,
163}
164
165/// Sign and log-absolute-value of the determinant.
166///
167/// Field order equals the former tuple order `(sign, log|det|)`.
168///
169/// - `sign`: sign (or phase) of the determinant
170/// - `log_abs_det`: `log|det|`
171///
172/// # Examples
173///
174/// ```
175/// use tenferro_linalg::Slogdet;
176///
177/// let r = Slogdet { sign: 1, log_abs_det: 2.0 };
178/// let Slogdet { sign, log_abs_det } = r;
179/// assert_eq!((sign, log_abs_det), (1, 2.0));
180/// ```
181#[derive(Clone, Debug)]
182pub struct Slogdet<V, R = V> {
183 /// See the type-level documentation.
184 pub sign: V,
185 /// See the type-level documentation.
186 pub log_abs_det: R,
187}