Skip to main content

Module real

Module real 

Source
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 < b exactly, written b − a > 0·s(a, b) for finite values and a < b otherwise: the definition of Tolerances::lt(a, b, 0.0), kept as an expression, so that the f64 instance 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.