MeanField/experiments/PRESSURE_OBSTRUCTION_METHODOLOGY_2026-09-17.md

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.