fp-stability: scale-free pass/fail + Verrou cancellation-origin reporting; auto-installed prebuilt

[sbryngelson]

Summary

Makes ./mfc.sh fp-stability (the Verrou-based floating-point–stability harness) trustworthy, self-installing, and self-explanatory:

• Scale-free pass/fail — retires the per-case hand-tuned absolute thresholds for one significant-bits floor.
• Cancellation-origin reporting — the report localizes where catastrophic cancellation arises, ranked by decimal digits lost, with fypp-expanded lines honestly flagged as instance-ambiguous.
• Self-installing Verrou — first use downloads a pinned, hash-verified prebuilt (with a source build as fallback); no manual ~20-min build.

Toolchain-only — no Fortran/solver and no build-system changes (CMakeLists.txt / build.py untouched relative to master). gfortran is the fp-stability CI compiler.

What it does

Each small 1-D case is run under Verrou and compared to a nearest-rounding reference:

• Scale-free PASS/FAIL. A case passes iff it retains sig_bits = -log2(max_dev / max|ref|) >= 24 (single-precision accuracy). Normalizing by field scale collapses the old six-order-of-magnitude threshold spread into a tight ~30-48-bit band, so one global floor replaces six hand-tuned per-case numbers.
• Cancellation origins (--check-cancellation). Source lines that lose leading significant digits in near-equal subtraction, ranked worst-first by digits lost (a sweep of --cc-threshold-double levels buckets each site by the highest it survives; bits -> digits, since a double carries ~16). Reported in the console (count + worst severity), as inline GitHub annotations (file:line), and in the step-summary table.
• fypp instance-ambiguity flag. fypp #:for/#:def expansion collapses many generated computations onto one .fpp line, so line-level attribution can't identify which instance is responsible. Any cancellation site inside such an expansion is flagged "may represent multiple instances" rather than presented as a single confident culprit. (In the CI suite ~75-80% of sites land inside expansions — which is exactly why per-line pinpointing is not trustworthy here; see the note below.)
• Supporting passes: float-proxy (single-precision sensitivity, one run), VPREC mantissa-bit sweep (at what precision a case breaks), and float-max (double->float overflow sites). Each is skippable with a --no-* flag.

Verrou installation

Verrou is a Valgrind fork (not a pip package). fp-stability installs it automatically on first use via toolchain/bootstrap/verrou.sh, which downloads a pinned, hash-verified prebuilt from the companion repo sbryngelson/verrou-dist (built in manylinux_2_28 for broad glibc reach; relocatable via a generated env.sh setting VALGRIND_LIB), falling back to a ~20-min source build if no prebuilt is available. A failed install aborts (never a silent skip). CI consumes the prebuilt + caches it, so the from-source build now happens once in verrou-dist's own CI rather than on every run.

Code organization

The feature outgrew the 1000-line file guideline, so fp_stability.py was split (pure relocation, no behavior change) into fp_stability_metrics.py (leaf: pure parsing/metrics), fp_stability_runners.py (Verrou orchestration), fp_stability_report.py (GitHub emitters), and fp_stability.py (CLI entry, CASES, _run_case) — each under the guideline, no import cycles. 33 toolchain unit tests; ruff + format clean; ./mfc.sh precheck all 7.

History note (re: the branch name)

The branch is named …-dd-confirm-rank after an earlier design that used Verrou's verrou_dd delta-debug to bisect to, confirm, and sensitivity-rank a single "responsible" source line. That machinery was removed in this PR: fypp expansion makes single-line attribution instance-ambiguous by construction (it was the fragile part — the sensitivity leader was almost always the benign time integrator, not the cancellation origin). A later commit also dropped the MCA (mcaquad) pass as redundant with the random-rounding sig-bits gate. The net result keeps file:line attribution via the cancellation-origin lens (more honest, and the one that matters for ill-conditioning) and drops ~900 lines of bisection/ranking. The add/remove pairs are visible in the commit list; the net diff contains none of the removed tooling.

Caveats

• The sig-bits floor is a flat regression bar: a clean case degrading from ~47 to ~25 bits would still pass. Auto-measured per-case baselines + a regression delta would add that sensitivity — deferred.
• Per-site "digits lost" is a sweep lower bound (no false positives, may under-count). High local cancellation in flux/reconstruction differences is often by-design (the small difference is the physics) and only harms the result if it propagates.
• Job pass/fail is governed solely by the sig-bits floor; the cancellation/vprec/float passes localize and characterize, they don't change exit semantics.
• Coverage is N small 1-D cases — not a guarantee for unexercised multi-D / viscous / MHD / IGR / bubble paths.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 60.63%. Comparing base (2d0d2fd) to head (0099674).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1526   +/-   ##
=======================================
  Coverage   60.63%   60.63%           
=======================================
  Files          73       73           
  Lines       20219    20219           
  Branches     2937     2937           
=======================================
  Hits        12259    12259           
  Misses       5972     5972           
  Partials     1988     1988           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.