94 lines
4.7 KiB
Markdown
94 lines
4.7 KiB
Markdown
# 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:
|
||
|
||
```sh
|
||
cmake --build cmake-build-release-homebrew --target plateau_diagnostic -j 2
|
||
```
|
||
|
||
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 \
|
||
--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:
|
||
|
||
```sh
|
||
./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.
|