fp-stability: refresh --help description for case.py usage + sig-bits/cancellation reframe

The --help prose was stale: it claimed 'PASS/FAIL against per-case thresholds' (now scale-free sig-bits), didn't mention the case.py positional / its serial-CPU constraints / the feasibility guard, and listed an outdated case set. Rewrote the description to cover: running on a built-in suite or a user case .py (with constraints + guard), the >= 24-bit scale-free pass criterion, and the analysis passes (dd confirmation/ranking, cancellation origins by digits lost). Also updated the module-docstring Usage. The positional INPUT and a case.py example were already shown in --help; this fixes the surrounding prose.

Author: sbryngelson

toolchain/mfc/cli/commands.py

@@ -898,23 +898,25 @@
     name="fp-stability",
     help="Run floating-point stability tests using Verrou.",
     description=(
-        "Runs each registered test case N times under Verrou's random IEEE-754 "
-        "rounding mode and compares against a nearest-rounding reference run. "
-        "Reports the max L∞ deviation and PASS/FAIL against per-case thresholds.\n\n"
+        "Runs Verrou random-rounding stability analysis on a built-in suite of small "
+        "1-D cases, or — given a case .py (positional INPUT) — on your own case. Each "
+        "case is run N times under Verrou's random IEEE-754 rounding and compared "
+        "against a nearest-rounding reference. PASS/FAIL is scale-free: a case must "
+        "retain at least ~24 significant bits (single precision) under random rounding "
+        "(no per-case thresholds).\n\n"
+        "With a case .py, that case is run as a SINGLE serial CPU process under Verrou "
+        "(~30x slower, and run many times), so it must be a small, short proxy — large "
+        "grids or long runs are rejected with guidance; serial .dat I/O is forced. "
+        "Example: ./mfc.sh fp-stability my_case.py\n\n"
         "Requires a Verrou-enabled Valgrind at $VERROU_HOME/bin/valgrind "
         "(defaults to $HOME/.local/verrou). The simulation and pre_process "
         "binaries must be serial (no-MPI, no-GPU) debug builds.\n\n"
-        "Test cases:\n"
-        "  sod_standard      1-D standard Sod, p_L/p_R=10 (well-conditioned baseline)\n"
-        "  sod_strong        1-D Sod, p_L/p_R=100,000 — HLLC xi-factor cancellation\n"
-        "  water_stiffened   1-D water shock (pi_inf=4046) — pressure-recovery cancellation\n"
-        "  air_water_interface  1-D air/water contact (two-fluid) — mixed-cell cancellation\n\n"
-        "Additional features (skip with --no-* flags):\n"
+        "Analysis passes (skip with --no-* flags):\n"
         "  float proxy    One run with --rounding-mode=float (single-precision sensitivity)\n"
         "  vprec sweep    Runs at mantissa bits [52, 23, 16, 10] (precision floor curve)\n"
-        "  dd_sym         verrou_dd_sym bisection to responsible functions (on failure)\n"
-        "  dd_line        verrou_dd_line bisection to responsible source lines (on failure)\n"
-        "  cancellation   --check-cancellation detection of catastrophic cancellation sites\n"
+        "  dd_sym/dd_line verrou_dd bisection to responsible functions/lines, then a\n"
+        "                 --source positive control confirms + ranks them by sensitivity\n"
+        "  cancellation   --check-cancellation origins, ranked by significant digits lost\n"
         "  mca-sigbits    Monte Carlo Arithmetic (mcaquad) significant-bits lower bound\n"
         "  float-max      --check-max-float detection of double→float overflow sites\n"
     ),

toolchain/mfc/fp_stability.py

@@ -59,9 +59,14 @@
   - A serial pre_process binary (to generate initial conditions)
 
 Usage:
-  ./mfc.sh fp-stability
+  ./mfc.sh fp-stability                       # built-in 1-D suite
+  ./mfc.sh fp-stability my_case.py            # your own case (small/short, serial, CPU)
   ./mfc.sh fp-stability --no-vprec --no-dd-line
   ./mfc.sh fp-stability --sim-binary PATH --pre-binary PATH
+
+A user case .py is run as a single serial CPU process under Verrou, so it must be
+a small, short proxy (a feasibility guard rejects large grids / long runs); output
+is forced to serial .dat I/O and the files to diff are auto-detected.
 """
 
 import math