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 --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.

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.

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 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 --max-newton 0 \
  --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.

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 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.