83 lines
5.1 KiB
Markdown
83 lines
5.1 KiB
Markdown
# Frozen pressure-obstruction diagnostic
|
|
|
|
`plateau_pressure_obstruction_diagnostics.hpp` exports the experiment-only helper
|
|
`experiment::plateau_diagnostics::ProbePressureObstruction(state, fem, n, normalizedBase, normalizedDirection, output)`.
|
|
Include it after `import mean_field` and call it inside the existing context
|
|
diagnostics guard. The output directory must exist and its four
|
|
`pressure_obstruction_*.csv` files must not already exist. The helper is limited
|
|
to one MPI rank and the current registered polytropic field orders. No public
|
|
configuration, model equation, solver acceptance rule, or accepted state changes.
|
|
|
|
The caller supplies an owned or borrowed frozen normalized state and correction;
|
|
the helper copies both before mutating workspaces. It restores the frozen state
|
|
before each candidate, and restores that state, inverse freshness, and the
|
|
caller's correction on return. It never calls `CommitPreparedTrial` or changes
|
|
accepted coefficients. The outer `WithState` guard remains responsible for
|
|
restoring the context's actual accepted state when a loaded frozen state differs
|
|
from it. Fatal restoration errors are propagated instead of silently claiming a
|
|
clean context.
|
|
|
|
## Bound and location
|
|
|
|
The existing `MeasureEnthalpyStep` scans the exact production pressure-force and
|
|
barotropic-closure quadrature rules. For scalar pullbacks, sampled enthalpy along
|
|
a fixed direction obeys `h_q(alpha) = h_q(0) + alpha * dh_q`. Each family reports
|
|
its smallest `-h/dh` for negative `dh`, and their minimum is the union bound.
|
|
Zero means that a sampled zero-enthalpy point is decreasing; infinity means no
|
|
sampled upper bound. Neither means that all other preparation checks pass.
|
|
|
|
`pressure_obstruction_summary.csv` retains the complete existing scan, including
|
|
point counts, negative samples, both limiting points and both bounds.
|
|
`pressure_obstruction_limits.csv` adds the limiting element's Cartesian reference
|
|
and frozen physical positions. Element-local integration coordinates are recorded
|
|
separately. The exact topological flag `element_touches_stellar_surface` locates
|
|
the element relative to the tagged stellar/vacuum interface. It is not a physical
|
|
distance or a certificate that the failure occurs at the boundary. Radii are
|
|
measured about the coordinate origin and are not normalized by a critical radius.
|
|
|
|
The scanner uses a pointwise polynomial contraction; optimized production may
|
|
use tensor contractions. These sample the same polynomial but need not agree
|
|
bitwise. Trials avoid alpha equal to the bound. Full-direction factors are
|
|
0.5, 0.9, 0.99, 1.01, 1.1, and 2 times the union bound, plus distinct fixed
|
|
steps 1, 1/2, 1/4, 1/8, and 1/16. Fixed steps coincident with the boundary are
|
|
omitted. The helper also tests enthalpy-only and shape-only components at the
|
|
same factors 0.9, 0.99, 1.01, and 1.1, retaining their original amplitudes.
|
|
This is at most 19 candidate preparations plus frozen-state restorations. For a
|
|
zero or infinite bound, a smaller fixed grid replaces the relative-bound grid.
|
|
|
|
## Exact rejection and interpretation
|
|
|
|
`pressure_obstruction_trials.csv` records the full root preparation reason and
|
|
stage enums, an explicit reason name, the EOS error enum, and whether that EOS
|
|
code is applicable. Nonthermodynamic failures can carry a default EOS code;
|
|
do not interpret it without the applicability flag. Missing determinant data
|
|
remain NaN. Successful preparation records normalized and physical residual
|
|
norms, with normalized residual blocks in `pressure_obstruction_blocks.csv`.
|
|
The physical whole-vector norm combines units and is for reproduction, not a
|
|
physical acceptance metric. The helper does not run the line-search merit test.
|
|
|
|
For this production pressure operator, `thermodynamic_domain` at the pressure
|
|
stage identifies a finite sampled negative enthalpy; `inverted_geometry`
|
|
identifies the mapping's nonpositive-determinant/weight branch. Other mapping
|
|
statuses and nonfinite input/results have separate reasons. Thus the exact
|
|
failure payload resolves the ambiguity of the earlier observer's generic
|
|
`inadmissible_state` plus `pressure force` label. The recorded reason identifies
|
|
the selected preparation failure, not necessarily every defect in the candidate.
|
|
|
|
Both predicted and independently re-evaluated enthalpy at the two frozen limiting
|
|
points are saved for every candidate. This is not a rescan for the most negative
|
|
trial point: the most negative point need not be the earliest-crossing point.
|
|
If full and enthalpy-only trials cross the same pressure thermodynamic boundary
|
|
while shape-only remains admissible, that isolates the enthalpy obstruction from
|
|
shape geometry along this correction. It does not establish the spatial cause
|
|
of the Newton direction or suggest permitting negative enthalpy.
|
|
|
|
If the caller reconstructs the correction from a recorded trial as
|
|
`(candidate - base) / alpha`, cancellation at tiny alpha can perturb the direction
|
|
and bound. Preserve that provenance and replay the original candidate directly
|
|
as an independent control. This helper diagnoses only its supplied direction.
|
|
|
|
Implementation review only: no compilation or numerical runs have been performed
|
|
for this helper at the time of this note. Root integration and validation remain
|
|
pending.
|