Expand description
§Chapter 5.6 — Scalars and comparisons
§Purpose
The containers and the factorization are written once, for any scalar
type T that behaves like a real number with rounding: f64 today,
double-double and quad-double from xingo-extprec (trilha L2). This
chapter fixes that interface, Real, and the only functions of the
crate that compare scalar values (Chapter 5, §5.C).
§Notation
T is the scalar type, ε_T its machine epsilon (Real::EPSILON).
For finite a, b and a tolerance ε ≥ 0 let s(a, b) = max(1, |a|, |b|) (the scale of xingo_core::Tolerances, Chapter 1.3). Then
lt(a, b)—a < bexactly, writtenb − a > 0·s(a, b)for finite values anda < botherwise: the definition ofTolerances::lt(a, b, 0.0), kept as an expression, so that thef64instance performs the very operations of the first edition;le(a, b, ε)—¬ lt_ε(b, a);approx_eq(a, b, ε)—|a − b| ≤ ε·s(a, b), exact when a value is infinite;is_zero(x, ε)—|x| ≤ ε(a drop test);is_exact_zero(x)—x = 0(a structural test: is the entry stored?).
§Requirements on T
(R1) The field operations are the correctly rounded ones of T (no
fused or reassociated arithmetic is assumed anywhere).
(R2) PartialOrd is a total order on the values that occur: NaN never
enters a factorization (debug builds assert it in the comparisons).
(R3) Sum adds in iteration order starting from the type’s additive
identity for sums — for f64, the standard library’s
Iterator::sum, which the first edition used; requiring it keeps
the order of every dot product of the solves unchanged.
(R4) from_f64(to_f64(x)) is x for f64; for the extended types
to_f64 is the nearest f64 and from_f64 exact.
§Why a trait of this size
A threshold LU needs the field operations, abs, max and a total
order (pivot search and tests), is_finite (input validation), and the
conversion of f64 thresholds into T. sqrt, recip and mul_add
are in the contract for the KKT solver (L1.5) and are unused by the LU;
they are part of the trait so that implementors see the whole
interface once. faer’s RealField is the model, without its SIMD
surface (D-0080, Q1).
§References
Knuth, TAOCP vol. 2, §4.2.2; Higham, Accuracy and Stability of
Numerical Algorithms (2002), ch. 1–2; faer’s RealField (read, not
copied); Chapter 1.3 of the solver (Tolerances).
Traits§
- Real
- The scalar type of every container and factorization of the crate.