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
/*
* SPDX-License-Identifier: MIT
* Copyright (c) 2023 - 2026. The DeepCausality Authors and Contributors. All Rights Reserved.
*/
//! The one set of per-precision parameters every numeric suite uses.
//!
//! A suite that ran at `f64` alone would pass with a tolerance that is unreachable at `f32` and
//! ten orders too loose at `Float106`. This table is what lets the same assertions be meaningful
//! at all three.
//!
//! # One table, no local copies
//!
//! Every tolerance in every suite comes from here. A suite does **not** declare its own
//! `TOL_F32`/`TOL_F64`/`TOL_F106`: six suites did, under five different names, with values that
//! disagreed for no stated reason, and a reader had no way to tell which was considered correct.
//!
//! # The rows are computation kinds, not suites
//!
//! The rows differ because the *operations* differ, not because the callers do. A direct reduction
//! keeps more digits than a linear solve, at every precision, and any suite doing either picks the
//! matching row. Choose by asking what the assertion is comparing:
//!
//! | Row | Use it when |
//! |---|---|
//! | [`Prec::native`] | both sides computed in `T`, over a handful of operations |
//! | [`Prec::literal`] | the expectation crossed in as an `f64` decimal literal |
//! | [`Prec::reduction`] | a sum or fold over roughly a thousand terms |
//! | [`Prec::solve`] | the value came out of a linear solve or an iterative fit |
//! | [`Prec::zero`] | the expected value is zero, so relative tolerance says nothing |
//!
//! # Why `native` and `literal` are separate
//!
//! They are floored by different things, and conflating them is the mistake this table exists to
//! prevent.
//!
//! `native` is floored by the working scalar's own accuracy. `literal` is floored by the
//! expectation's *route* into the scalar: a decimal literal crosses through
//! `deep_causality_num::lift`, which takes an `f64`, so at `Float106` the comparison can never be
//! tighter than `f64`'s epsilon — about `2.2e-16` — however accurate the arithmetic is. At `f32`
//! the two rows coincide; at `Float106` they differ by ten orders of magnitude.
//!
//! Using `native` where `literal` belongs makes an assertion unsatisfiable at `Float106`. Using
//! `literal` where `native` belongs makes it toothless there.
//!
//! # Why the epsilon multiples are not uniform
//!
//! `f32` has about seven decimal digits, so there is no room to spend: `native` is roughly eight
//! epsilon. `Float106` has about thirty-two, so the same row sits at millions of epsilon and is
//! still far tighter than `f64` could ever be. The multiple is not the invariant; the number of
//! digits an operation actually delivers is.
//!
//! # `BFloat16` is not simply a smaller `f32`
//!
//! It is a *truncated* one: the same eight exponent bits, so the same reach, with the mantissa cut
//! from 23 bits to 7. That makes `epsilon` `7.8e-3` — under one percent relative, about two
//! decimal digits — while `max_finite` and `min_positive` are `f32`'s.
//!
//! One consequence shapes what a suite can ask of it: integers are exact only to 256, so a
//! cancellation fixture cannot use `f32`'s offset of ten thousand.
//!
//! A second consequence used to be recorded here and was withdrawn, because it was a property of
//! an arrangement rather than of the type. The claim was that a thousand-term reduction is not
//! merely imprecise but meaningless — once the running sum reaches one, an addend of a thousandth
//! falls below `epsilon · sum` and vanishes — and `reduction` was set to 1.0 to say so rather than
//! to a tolerance. That is true of a sum formed left to right and of no other. Summed as a
//! balanced tree, a thousand addends of a thousandth land within `5.5e-4` of their mean and ten
//! thousand within `4.7e-3`, both inside this type's own `epsilon` of `7.8e-3`. The row is a
//! tolerance again.
/// What changes between the three precisions.
///
/// Every field is `f64` because a tolerance is compared after lowering, and because the reach
/// fields describe the type from outside it.
/// `BFloat16`: epsilon `7.8e-3`, about two decimal digits.
///
/// `native` `5e-2` is about six epsilon, the same headroom `f32`'s row takes, which is all two
/// digits allow. `literal` matches it: an `f64` literal is far more accurate than `BFloat16` can
/// hold, so the `BFloat16` side floors the comparison.
/// `solve` `2e-1`: squaring the condition number costs about half of two digits, leaving one.
/// `reduction` `5e-2` matches `native`, because a balanced-tree sum at this width delivers what a
/// handful of operations does: measured, a thousand addends of a thousandth land within `5.5e-4`
/// of their mean, a thousand-term ramp within `9.99e-4`, and ten thousand within `4.7e-3` — all
/// inside `epsilon`. This row read `1.0` while the reductions were formed left to right, which is
/// where a long sum really does lose everything at two digits.
/// `zero` `1e-1`: an ulp at magnitude ten is `7.8e-2`, so anything tighter sits inside the noise.
/// `cancel_offset` `64`: the binding constraint is the SUM, not the values. Integers are exact
/// only to 256, and a three-element fixture sums to about three times the offset, so an offset of
/// 100 gives 303 — past 256, where the spacing is already 2, and the mean is wrong before the
/// variance is reached. At 64 the sum is 195 and every intermediate stays exact. `f32`'s ten
/// thousand is not representable here at all.
/// `huge` `1e20` squares past `MAX = 3.39e38`; `1e19` does not, since `sqrt(MAX) = 1.84e19`.
/// `nudge` `0.25`: the spacing at ten is `7.8e-2`, so a smaller step would not move the value.
/// The reach fields are `f32`'s, because the exponent field is.
pub const BF16: Prec = Prec ;
/// `f32`: epsilon `1.19e-7`, about seven decimal digits.
///
/// `native` `1e-6` is roughly eight epsilon — all the headroom seven digits allow over a
/// handful of operations. `literal` matches it, because an `f64` literal is far more accurate
/// than `f32` can hold, so the `f32` side is what floors the comparison.
/// `solve` `1e-4` is two digits looser: squaring the condition number costs about half of seven.
/// `zero` `1e-5` rather than `1e-6`: a residual between operands of magnitude ten is a few ulps,
/// and an ulp at ten in `f32` is already `1e-6`, so the tighter floor sits inside the noise it is
/// meant to be above. Measured: an exactly-determined two-by-two solve leaves `1.19e-6`.
/// `huge` `1e20` squares to `1e40`, past `f32::MAX = 3.4e38`, which is the point: the value
/// itself is finite and its square is not.
/// `overflow_scale` `5e18`: `55·k² = 1.4e39` exceeds the maximum, while `10·k² = 2.5e38` and the
/// answer `2.5·k² = 6.3e37` do not.
/// `cancel_offset` `1e4`: 10000, 10001 and 10002 are all below `2^24` and so exact in `f32`.
pub const F32: Prec = Prec ;
/// `f64`: epsilon `2.22e-16`, about sixteen decimal digits.
///
/// `native` `1e-12` is roughly `4.5e3` epsilon, leaving four digits of headroom.
/// `literal` `1e-13` is tighter than `native` because the crossing is exact here: an `f64`
/// literal is the value, so only the arithmetic contributes.
/// `solve` `1e-12` matches `native`: at sixteen digits, halving still leaves eight, so the solve
/// is not what floors these comparisons.
/// `huge` `2e154` squares to `4e308`, past `f64::MAX = 1.8e308`. `1e154` would not do: its
/// square `1e308` is still finite, so it would not exercise the overflow path at all.
/// `overflow_scale` `2e153`: `55·k² = 2.2e308` exceeds the maximum, while `10·k² = 4.0e307` does
/// not.
/// `cancel_offset` `1e8`: `Σxᵢ²` is then about `3e16`, where an ulp is 4 and the quantity being
/// recovered is 2.
pub const F64: Prec = Prec ;
/// `Float106`: epsilon `4.93e-32`, about thirty-two decimal digits.
///
/// `native` `1e-25` is roughly `2e6` epsilon, and still ten orders tighter than the `f64` row —
/// the point of the table.
/// `literal` `1e-15` stays at `f64` reach for the reason in the module header: the expectation
/// crossed through an `f64`, so the comparison cannot see past `f64`'s epsilon.
/// `zero` `1e-10` likewise: a quantity that should vanish, built from lifted `f64` fixtures,
/// carries `f64` residue rather than `Float106` residue.
///
/// The exponent range is `f64`'s, because the head of a double-double is an `f64`. So
/// `max_finite`, `min_positive`, `huge` and `overflow_scale` are shared with the `f64` row: the
/// extra precision is in the mantissa, not the reach. `cancel_offset` is capped at `1e15` by the
/// `f64` fixture crossing rather than by the type.
pub const F106: Prec = Prec ;