MeanField/experiments/plateau_shape_curvature_README.md

# Shape and field Taylor decomposition

`plateau_shape_curvature_diagnostics.hpp` is an experiment-only observer, included
after `import mean_field;`. It also includes the existing sampled enthalpy-bound
helper. The root driver supplies an actual frozen normalized base and selected
normalized correction:

```cpp
experiment::plateau_diagnostics::ProbeShapeCurvature(
    state, finiteElements, polytropicIndex, normalizedBase, normalizedDirection,
    outputDirectory);
```

Use a distinct output directory for each state/direction. The inputs are copied
before state workspaces change, so aliases of those workspaces are safe. The
caller must use this context's normalization and matching EOS index; the helper
does not reconstruct a Newton correction from a damped trial. If the driver does
that reconstruction, its alpha and roundoff uncertainty belong in the enclosing
provenance, particularly when the accepted step is tiny.

## Experiment and preparation budget

The actual value manifest must contain exactly one nonempty block whose stable
ID starts with `surface`. Only that block enters p_shape; all remaining value
coordinates, including scalar multipliers and angular velocity, enter p_fields.
No value/residual offsets or field sizes are hard-coded.

The helper prepares the exact supplied base immediately before each of its
three Jacobian actions. It records repeated base residuals and checks
`p=p_shape+p_fields` and `Jp=Jp_shape+Jp_fields`. These measurements are made
before any step-size gate, even when the direction's enthalpy boundary makes
curvature differencing unusable.

At that same prepared base, it measures geometry limits for all three directions
using the production preflight rules, and scans the exact production closure and
pressure enthalpy quadrature for full and fields directions separately. Their
enthalpy bounds should agree because the shape direction changes no enthalpy
coefficient. The shape-only bound is therefore infinite for an admissible base.
The common maximum alpha is the minimum of one, all geometry-safe bounds, and
0.8 times the finite full/fields enthalpy crossings. The geometric estimator uses
its existing safety fraction 0.9.

Six common scales are used: alpha_max times 1, 0.1, 0.01, 0.001, 0.0001, 0.00001.
Each scale prepares full, shape-only, and fields-only trials. Every trial vector
is constructed directly from the copied base; trials never accumulate. The
ordinary budget is 22 preparations (three for J actions, 18 trials, final base
restoration), three Jv, and zero preconditioner applications or linear solves.
An unusable common cap skips all trial preparations, retaining the action/bound
diagnostics. Exceptions attempt one additional base restoration before rethrow.

For each residual block and direction it records the **vector** Taylor remainder

```
R_d(alpha) = F(x + alpha p_d) - F(x) - alpha Jp_d.
```

The mixed term is formed by vector subtraction before taking its norm:

```
R_mixed = R_full - R_shape - R_fields.
```

For each block the mixed file also records the linear prediction
`L=F_base+alpha Jp_full`, its norm, the measured full-trial residual norm, and
long-double-accumulated signed products `<L,R_full>`, `<L,R_shape>`,
`<L,R_fields>`, and `<L,R_mixed>`. These distinguish curvature amplitude from
its effect on the merit. The file checks both scalar identities

```
||F_full_trial||² = ||L||² + 2<L,R_full> + ||R_full||²
<L,R_full> = <L,R_shape> + <L,R_fields> + <L,R_mixed>.
```

The errors of these identities are exported, not forced to zero. Individual
signed projections remain available when their own trial is valid, even if
another direction at that alpha is inadmissible; mixed projections require all
three. Summing signed products across residual blocks gives the full normalized
merit decomposition. A large norm alone does not establish an adverse merit
contribution.

It is not the difference of three norms. Six remainder cosines and the sum of
component norms divided by the full norm show cancellation between terms. All
three trials must be admissible before a mixed result exists; otherwise mixed
values are NaN. Individual valid trials remain available even if another trial
at that alpha fails.

At fixed shape, the two gravity residual blocks should be affine in the remaining
independent fields. The `fields` rows therefore test an arithmetic-level gravity
remainder. The helper records that measurement without forcing it to zero.
Closure, pressure/mechanics, rotation and scalar constraints need not be affine
in these remaining coordinates; the same expectation does not apply to every
residual block.

## Arithmetic limits

The state addition error is measured explicitly as
`(fl(x+alpha p)-x)-alpha p`. A nonzero direction's increment is flagged resolved
only if its expected norm exceeds `64 epsilon (1+||x||)`, its actual increment
is nonzero, and its addition error is below 1% of the expected increment. These
are diagnostic numerical heuristics, not physical tolerances. Tiny components
may be unresolved even when the whole direction is resolved.

Per-block residual roundoff scales use the larger of eight times the observed
pre-action base-restoration drift and
`128 epsilon (1+||F_base,block||+alpha||Jp_block||)`. Mixed scales sum the three
component scales. The `above_roundoff_scale` flag also requires admissibility
and a resolved state increment. This heuristic is not a certified bound on
matrix-free assembly error: terms may cancel before the residual is formed.
Use the alpha trend, the fields-only gravity measurement, and the final
restoration CSV together. If final restoration drift exceeds the pre-action
drift, increase the interpretation floor accordingly; previously written rows
are not retroactively rescaled.

If the common alpha cap is zero/nonfinite, its largest full increment is below
the update threshold, or the Jacobian split exceeds its recorded roundoff
heuristic, `common_step_regime_usable=0` and no curvature is inferred. Below-floor
remainders are unresolved, not evidence of zero physical curvature. Inadmissible
trials and zero-denominator cosines/relative errors stay NaN, never fabricated
zeros. Root norms remain in the supplied normalization; manifest scale metadata
is not used as a replacement normalization.

`alpha_squared_valid` requires a positive finite floating-point alpha². If it
underflows or is nonfinite, scaled curvature is NaN and the resolved-curvature
flag is false. Invalid denominators or overflow in scaled ratios also produce
NaN; a nonpositive/nonfinite alpha itself is skipped and recorded in the summary.
Absolute measured remainders may still be available when squared scaling is not.

## Outputs and lifecycle

- `shape_curvature_summary.csv`: base/direction sizes and norms, split checks,
  arithmetic thresholds, common cap, preparation count, and accepted-vector
  invariance checks.
- `shape_curvature_preparations.csv`: every attempted preparation with exact
  available rejection reason/stage, names, meaningful EOS code, and the reported
  minimum mapping determinant. The production payload does not identify an
  offending element or quadrature point; the helper does not invent one.
- `shape_curvature_restorations.csv`: per-block residual differences on each
  repeated base preparation, including final restoration.
- `shape_curvature_directions.csv` and `shape_curvature_actions.csv`: norms
  split with the actual value/residual manifests and Jacobian reconstruction.
- `shape_curvature_bounds.csv`: geometry and sampled pressure/closure limits,
  including the enthalpy scanner's limiting sample coordinates.
- `shape_curvature_remainders.csv`: absolute R, R/alpha², derivative error
  R/alpha, relative derivative error, arithmetic flags, and actual state-addition
  errors for every block/direction/alpha.
- `shape_curvature_mixed.csv`: the mixed vector's norm/scaling, cosines, linear
  prediction and trial norms, signed merit projections, and identity errors.

No trial is committed and no accepted vector is changed. The helper leaves the
supplied frozen base prepared and restores the entry normalized correction,
physical correction, and volume-displacement-direction workspaces. Preparation
revisions advance, so a caller that subsequently applies an inverse must refresh
it; the enclosing `WithState` hook normally restores its accepted state and
inverse. The helper performs no preconditioner refresh or policy change itself.
Its rejection/event files are flushed incrementally. No physics, normalization,
production API, driver, or build configuration is changed by this helper.