Record reproducible plateau campaigns and selected-direction probes

experiments/plateau_diagnostic_README.md

@@ -14,7 +14,7 @@ Run a calibrated spherical family with `G=M=R_reference=1`:
 
 ```sh
 ./cmake-build-release-homebrew/plateau_diagnostic \
-  --index 1.5 --angular-momentum 0 --max-newton 8 \
+  --index 1.5 --angular-momentum 0 --no-central --max-newton 8 \
   --output /absolute/path/to/new-results
 ```
 
@@ -28,6 +28,9 @@ analytic constants. Other indices use the production radial integrator, so this
 calibration is seed-consistent, not an independent exact reference. Angular momentum
 sets a physical target, not a fraction of critical rotation. `--no-central` omits
 the central phase for controlled comparisons; it changes the model specification.
+The central phase remains enabled by default to reproduce earlier runs. Pass
+`--no-central` for the n=1 and n=1.5 campaign models; retain the optional phase for
+the n=3 homology-control experiment.
 
 Default solver controls are restart 40, 200 linear iterations, linear relative
 tolerance 0.03, Newton relative tolerance 1e-8 and absolute tolerance zero. Override
@@ -35,13 +38,20 @@ with `--restart`, `--max-linear`, `--linear-tol`, `--rtol`, `--atol`, and
 `--max-newton`. Exit 0 means the requested Newton criterion was met, 3 means it was
 not met (or a seed-only inspection was requested), and 2 means setup/diagnostics
 failed. A nonconverged result still saves the retained accepted state and its
-physical measurements.
+physical measurements. `newton.csv` also records `linear_initial_residual`,
+`linear_rhs_norm`, and `linear_initial_over_rhs` to measure the incoming correction
+warm start. The initial residual is `||b - J p_initial||`; the ratio is zero for an
+exactly solved zero RHS and infinity for a nonzero initial residual with zero RHS.
+Missing solve reports produce NaN.
 
 ## Frozen investigations
 
 Append `--probes` to inspect the retained state after a solve. This compares cold
 FGMRES windows 40 and 160 at the same iteration budget and independently recomputes
-both true residuals. It also exports normalization consistency checks, the scalar
+both true residuals. These are direct `mfem::FGMRESSolver` calls with empty Krylov
+history, not calls through the configured production linear backend; they do not
+test a modified backend or its recycling behavior. It also exports normalization
+consistency checks, the scalar
 Schur matrix and its coordinate labels, inverse-diagonal quality, and full-Jacobian
 actions on preconditioner-completed scalar directions.
 
@@ -49,7 +59,8 @@ To inspect a previously saved physical root vector without repeating Newton:
 
 ```sh
 ./cmake-build-release-homebrew/plateau_diagnostic \
-  --index 1.5 --angular-momentum 0 --max-newton 0 \
+  --index 1.5 --angular-momentum 0 --no-central --max-newton 0 \
+  --probe-restart 160 \
   --probe-state /absolute/path/to/previous/accepted_state.txt \
   --output /absolute/path/to/new-frozen-results
 ```
@@ -60,8 +71,12 @@ diagnostic hook; the context's accepted state is unchanged. This is a frozen
 inspection facility, not a Newton continuation/restart facility. The saved vector
 is dimension-checked, but does not contain a mesh/model fingerprint.
 
-Finite-difference and nonlinear-trial probes always use the **window-40 direction**,
-even if window 160 obtains a better correction. They compute the exact sampled
+Set `--probe-restart 40` or `--probe-restart 160` to select the correction used for
+positivity, finite-difference, and nonlinear-trial probes. The default is 40 for
+reproducibility; both cold solves still run, and the choice does not change the
+production Newton `--restart` setting. `metadata.txt` records `probe_restart` and
+`frozen_probe_backend=direct_mfem_fgmres_cold`; the selected correction is saved as
+`probe_normalized_correction.txt`. The probes compute the exact sampled
 enthalpy step bounds for both production closure and pressure-force quadrature.
 Every trial is restored and none is committed. Finite differences are one-sided;
 interpret their epsilon trend and absolute error, particularly for tiny Jacobian
@@ -91,3 +106,26 @@ Quadrature samples are not a global positivity certificate.
 from the hydrostatic equation. A small bordered residual can otherwise hide a
 pointwise modification at the central vertex. Virial success and Newton stopping
 success are deliberately separate measurements.
+
+## Reproducible serial campaigns
+
+`run_plateau_campaign.py` requires a committed source revision and an already
+configured CMake build directory. It rebuilds the diagnostic target, records the
+source commit, build settings, binary and mesh hashes, and copies the executable
+into the result directory before running cases serially. Every exact command,
+exit code, log, state and compact summary is retained. A model exit code 3 is an
+observed nonconvergence; campaign exit 0 means the observations completed, not
+that every model converged. Output directories must be new.
+
+```sh
+python3 experiments/run_plateau_campaign.py \
+  --source . --build cmake-build-release-homebrew --mesh sandbox.smesh \
+  --cases experiments/plateau_control_cases.json \
+  --output /absolute/path/to/new-campaign
+```
+
+Use `--cmake` if CMake is not on PATH. Build products, raw states and full result
+folders should remain outside source commits; retain compact result tables and
+reproduction instructions with each hypothesis branch. The controls omit the
+central phase at n=1 and n=1.5. A separate n=3 control retains it to fix homology;
+the production model API does not insert it implicitly.