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