MeanField/experiments/plateau_diagnostic_README.md

Plateau diagnostics

This opt-in experiment runs the current production context, operator, normalization, preconditioner and Newton implementation. It adds observations and uncommitted frozen trials. It does not select a replacement numerical algorithm.

Build from the repository root:

cmake --build cmake-build-release-homebrew --target plateau_diagnostic -j 2

Run a calibrated spherical family with G=M=R_reference=1:

./cmake-build-release-homebrew/plateau_diagnostic \
  --index 1.5 --angular-momentum 0 --no-central --max-newton 8 \
  --output /absolute/path/to/new-results

The output directory must not already exist. The mesh defaults to the repository's sandbox.smesh; --mesh selects another mesh. The driver is restricted to one MPI rank. An MPI runtime must be available even for a single-rank run.

For each index, the driver obtains K and central density from the Lane–Emden solution so the spherical reference mass and radius are one. Index one uses its 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 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. 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. 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.

To inspect a previously saved physical root vector without repeating Newton:

./cmake-build-release-homebrew/plateau_diagnostic \
  --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

Use the same mesh, compiled field orders, index, K/central-density calibration, and model flags. The snapshot is prepared as an uncommitted trial inside the existing 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.

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 actions. global_correction_norm in the block table is the whole-vector norm.

Physical measurements

The observer integrates over stellar material only, at independent quadrature orders 14 and 18. It reconstructs physical positions and Piola-transformed gravity flux. For zero surface pressure it measures

• W = 1/2 integral rho Phi, W_force = -integral rho x dot gradPhi;
• rotational energy T and both P(h) and P(rho) pressure integrals;
• energy and force virials abs(2T + W + 3 integral P) / abs(W_energy);
• mass, angular momentum, center of mass, Bernoulli and EOS mismatch, hydrostatic gradient mismatch, sampled density/enthalpy signs, and geometry quality.

Pressure is evaluated with the actual polytropic index, including noninteger n. Signed finite DG density is retained in mass/gravity/rotation integrals. Any negative density sample makes the complete P(rho) pressure and virial undefined (NaN); P(h) remains available for positive enthalpy. The observer reports the negative-density mass and volume fractions instead of silently clipping them. NaN in P(rho) alone is not a quantitative measure of the global physical error. Quadrature samples are not a global positivity certificate.

normalized_unbordered_residual removes the central phase's artificial source 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.

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.

Check a completed endpoint with python3 experiments/check_plateau_physics.py /absolute/path/to/result-folder. This gates strict recorded solver convergence and all eight finite virial errors at 1e-5, while reporting local field errors separately. See check_plateau_physics_README.md for the exit codes and interpretation limits.