Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ADR 0016: Switchable floating-point precision

  • Status: Accepted (2026-11-10)
  • Date: 2026-11-10
  • Deciders: Vincent Mader
  • Related: findings F5, F9; experiments E3, E4; ADR 0003, 0014; grill decision Q21

Context

The thesis reports mass errors around 10⁻¹² and relies on analytic cancellation handling because f64 cannot represent m_i + m_j when m_i ≪ m_j. Comparing f64 against an extended precision answers whether that error is a round-off floor or a method error. As of November 2026 Rust’s native f128 is nightly-only, with stabilization targeted for late 2026 at the earliest. Double-double arithmetic (about 106 bits of mantissa) is available on stable Rust, in pure Rust, and works in wasm.

Decision

  • Numerics are generic over a Real trait defined in coag-core: axes, recipes, kernel assembly, RHS, explicit integrators, and the implicit integrators with a small own dense LU.
  • Supported types: f64 (default), double-double (the stable extended type; the crate is chosen in M1 after checking current releases), and native f128 behind a nightly-only cargo feature until it stabilizes.
  • The production path stays specialized for f64: faer-based linear algebra, alias-table sampling, and probabilities are f64 only.
  • Precision is a config key ([numerics] precision), recorded in the run manifest.
  • E3 and E4 compare f64 against double-double for per-pair mass defects, cancellation handling, and long-term mass error.

Alternatives considered

  • f64 only: simplest, but leaves the round-off question unanswered.
  • Arbitrary precision (MPFR via rug): C dependency, no wasm, much slower than needed.
  • Native f128 only: blocked on nightly.

Consequences

  • Generic code in the core crates (trait bounds, constants via Real::from_f64).
  • Extended-precision runs are limited to small grids (own dense LU is O(N³), double-double arithmetic is several times slower than f64, to be measured in M1).
  • Tests run for both f64 and double-double in CI on small sizes.
  • Found in M1: twofloat documents its exp, ln, and powf as not accurate to full double-double precision, so the Real trait offers only arithmetic, sqrt, and abs. Grids are defined in f64 and promoted exactly, so f64 and extended runs use bit-identical bin masses; physics that needs transcendental functions computes in f64.
  • Found in M1: on nightly 1.101 for aarch64-apple-darwin, f128::sqrt returns 0. Real::sqrt for f128 uses two Newton steps from the f64 root instead (tested to f128 accuracy).