Expand description
Reproducible floating-point primitives.
+, -, *, / and sqrt are correctly rounded by IEEE-754, so every
conforming target computes them to the same bits. The transcendental
functions are not: sin, cos, atan2, pow and tanh come from the
platform’s libm, and Apple’s, glibc’s and musl’s implementations disagree
in the last ulp for many inputs. That is enough. A 1-ulp difference in one
sin inside integrate_configuration is amplified by a contact-rich
rollout until the trajectories are visibly different, which is exactly the
failure mode where you cannot tell chaos from a bug.
So the rollout path does not call the platform’s libm. It calls this
module, which forwards to the libm crate — a pure-Rust port of musl’s
libm that computes the same bits from the same inputs on every target,
because it is the same Rust source compiled with the same IEEE semantics
(Rust never contracts to FMA or reassociates FP without explicit opt-in).
§The portable-fp feature
On by default. Turning it off routes every function here straight to std,
which is faster (the platform libm is usually vectorized and tuned) and
gives up cross-platform bit equality. Do that only if you have measured the
difference and do not need to compare numbers across machines.
§What this does not fix
Nothing here makes a chaotic rollout stop being chaotic. It makes the
same rollout on two machines take the same path through that chaos. See
docs/determinism.md for the full contract.