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
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
/*
* SPDX-License-Identifier: MIT
* Copyright (c) 2023 - 2026. The DeepCausality Authors and Contributors. All Rights Reserved.
*/
//! Norms.
//!
//! # Two shapes, one body each
//!
//! The matrix norms are generic over any [`MatrixView`](crate::MatrixView), so they apply to the
//! sparse and the packed representations too. The vector norms are generic over a **slice**, and
//! [`DenseVector`](crate::DenseVector)'s methods of the same names delegate to them.
//!
//! The slice form exists because the callers being consolidated do not hold a `DenseVector`.
//! `deep_causality_multivector`'s coefficients are a `Vec<T>` and `CausalMultiField`'s are a
//! tensor's buffer; routing either through a `DenseVector` would allocate and copy the whole
//! coefficient vector on every norm. A slice is what both already have, and the method delegating
//! to the function is what keeps this one body rather than two.
//!
//! # Defined once
//!
//! The workspace answers the Euclidean-norm question four times today: `CausalTensor::norm_l2` and
//! `norm_sq`, `frobenius_norm` in `deep_causality_quantum`, `MultiVectorL2Norm::norm_l2` and
//! `CausalMultiField::squared_magnitude` in `deep_causality_multivector`. Each is correct where it
//! sits; together they are four places to fix a bug.
//!
//! # The bound is [`Normed`], not [`NormedScalar`](deep_causality_algebra::NormedScalar)
//!
//! `Normed` is what these functions actually use: a modulus, a squared modulus, and an associated
//! `Real` that is ordered and carries `sqrt`. `NormedScalar` adds `Field`, `FromPrimitive` and
//! `Copy` on top, none of which any body here calls for — and asking for them costs callers real
//! generality, because `Complex<T>: FromPrimitive` holds only when `T: FromPrimitive` does, while
//! `Complex<T>: Normed` holds for every `T: RealField`. Taking the weaker bound is what lets
//! `deep_causality_quantum` reach the scaled norm without widening its own public signatures.
use crateLinearError;
use crateMatrixView;
use ;
use Zero;
/// The 1-norm of a vector, `Σ |aᵢ|`.
/// The squared 2-norm of a vector, `Σ |aᵢ|²`.
///
/// Separate from [`vector_norm_l2`] because the square root is the expensive part and comparisons
/// rarely need it. `deep_causality_multivector`'s `CausalMultiField::squared_magnitude` is exactly
/// this quantity and now is exactly this call.
/// The 2-norm of a vector, `sqrt(Σ |aᵢ|²)`, computed in the scaled form.
///
/// This is the one definition of the Euclidean norm in the workspace.
///
/// # Why not `vector_norm_sq(v).sqrt()`
///
/// That form overflows where the answer does not. A vector holding a component near `T::MAX`
/// squares to an infinity and returns `inf` for a norm that is representable; one whose components
/// sit near `T::MIN_POSITIVE` squares to zero and returns zero for a norm that is not. The squared
/// norm is a genuinely larger quantity than the norm, and routing the norm through it gives away
/// half the exponent range.
///
/// The scaled form factors the largest modulus out — `max · sqrt(Σ (|aᵢ|/max)²)`, where every ratio
/// lies in `[0, 1]` and cannot overflow. It is the reasoning
/// [`Normed::modulus`](deep_causality_algebra::Normed::modulus) already applies to a complex's two
/// components, at the length of a vector.
///
/// # Cost
///
/// One pass, accumulating a running scale and sum of squares rather than taking a maximum and then
/// a second pass, so the slice is read once. It asks each entry for `modulus` where the naive form
/// asked for `modulus_squared`, which for a real is `abs` against a multiply and for a complex is a
/// square root against a multiply-add, and it divides once per entry. A caller that wants the
/// squared norm, or is only comparing magnitudes, should call [`vector_norm_sq`] and pay neither.
///
/// # Non-finite entries
///
/// Unchanged from the naive form: a `NaN` modulus anywhere gives `NaN`, and an infinite one with no
/// `NaN` present gives `+∞`.
/// The running state of the scaled Euclidean norm: the largest modulus seen, and the sum of squared
/// ratios against it.
///
/// # The recurrence
///
/// Holding `scale = max |aᵢ|` over the entries so far and `ssq = Σ (|aᵢ|/scale)²`, a new entry `a`
/// either fits under the current scale, contributing `(a/scale)²`, or replaces it, which rescales
/// the accumulated sum by `(scale_old/a)²`. Both ratios lie in `[0, 1]`, so neither the square nor
/// the sum can overflow while the answer is representable. The first non-zero entry takes the
/// replacing branch against `scale = 0`, whose ratio is zero, leaving `ssq = 1` — the norm of one
/// entry being that entry.
///
/// This is one pass. Taking the maximum first and forming the ratios second would be two, and would
/// ask each entry for its modulus twice, which for a complex entry is a square root each time.
///
/// # Non-finite entries
///
/// Kept separate from the accumulation rather than allowed into it. An infinity would drive `scale`
/// to infinity and make every later ratio `finite/∞ = 0`, which is harmless — but a *second*
/// infinity gives `∞/∞ = NaN`, turning a norm that is infinite into one that is undefined. A `NaN`
/// entry never compares greater than `scale`, so without the check it would fall into the
/// contributing branch and be added as a `NaN` ratio, which happens to give the right answer for the
/// wrong reason. Both are decided here, and the answer matches what summing the squares gave: `NaN`
/// wins over infinity, and infinity over the finite entries.
/// The ∞-norm of a vector, `max |aᵢ|`.
///
/// Zero for the empty vector, which is the supremum over an empty set in the convention this crate
/// uses, and never `NaN`.
/// The 1-norm: the largest column sum of moduli.
/// The ∞-norm: the largest row sum of moduli.
/// The Frobenius norm: `sqrt(Σ |aᵢⱼ|²)`.
///
/// Equal to the 2-norm of the entries read as one vector, which is a test rather than a remark —
/// and the reason this is scaled the way [`vector_norm_l2`] is. The two are the same quantity over
/// the same numbers, so a fix to one that left the other summing squares would put the crate's own
/// identity test in the position of asserting an equality that fails at the extremes it was fixed
/// for.