MeanField/experiments/MODEL_SLICES.md

# Physical slices of the deformed FEM model

This optional experiment displays the independent density, enthalpy and actual
material boundary of a prepared state. It changes no solver equations, fields,
orders, positivity handling or public library API.

## Use

Add `--model-slices` to a normal `plateau_diagnostic` invocation. It writes
`initial_slices` and `final_slices`, each with `xz` and `xy` subdirectories.

Optional settings:

- `--slice-plane both|xz|xy|yz` (default `both`, meaning xz and xy).
- `--slice-offset VALUE` (default zero). This is the physical coordinate normal
  to the plane: y for xz, z for xy, x for yz. `both` applies the same offset to
  both planes.
- `--slice-subdivisions N` (default 6, allowed 2–32). Begin with 4–8 and compare
  two resolutions for a plot whose small features matter. Work grows with the
  number of reference subcells; 32 is an explicit upper bound, not a suggested
  default.

Existing harmonic snapshots can be observed through the checked density replay
path, using the matching binary, mesh and physical specifications:

```sh
plateau_diagnostic --index 3 --angular-momentum 0 \
  --surface-prescription harmonics --surface-degree 4 \
  --mesh /absolute/path/to/saved/input.smesh \
  --density-snapshot /absolute/path/to/saved \
  --model-slices-only --max-newton 0 --slice-subdivisions 6 \
  --output /absolute/path/to/new_observation
```

`--model-slices-only` writes `frozen_slices` and the replay's normal physical
metrics/provenance, skipping the expensive density-region observations. It does
not perform Newton iterations. `--model-slices` can also accompany an existing
frozen density diagnostic. Replay checks still apply; a size match alone does
not establish compatibility of a saved state.

Render one plane with Python, NumPy and Matplotlib:

```sh
python experiments/plot_model_slices.py /absolute/path/to/new_observation/frozen_slices/xz \
  --reference-outline --title 'n=3 rotating trial; unconverged' \
  --output /absolute/path/to/new_figures/n3_trial_xz
```

The helper writes PNG and PDF and refuses to overwrite either. Both axes use
the same physical length scale. The solid curve is the deformed material
boundary; the optional dashed curve is the undeformed boundary intersected
with the same plane. No deformation magnification is applied. A two-sided
color scale centered at zero retains the sign when a field has both signs;
the displayed ticks are the actual values, and each color half may have a
different range. All-positive or all-negative data use a linear color scale.
No density or enthalpy values are clipped, replaced by an EOS evaluation, or
logged. Extrema in panel titles are sampled extrema.

Final-state plots use the surrounding run's convergence flag when available;
replayed or initial states are labeled as not assessed by the image. Give a
descriptive title, including the physical parameters and any known failure,
when plotting a stalled or otherwise unconverged state. A plausible picture
does not establish virial balance or an unbordered equilibrium.

## Geometry and field contract

Only stellar hexahedra are visited. Each is split into a configurable reference
lattice and consistent tetrahedra within that element. Intersections solve
`mapped_position[normal] = offset` on the actual curved map along each crossed
edge, using a safeguarded bracketed root calculation. This is a physical-plane
cut, not a deformed image of a reference-plane selection. The mapped Jacobian
must remain valid at every evaluation. Exterior compactification is not used.

Density and enthalpy are evaluated directly from their existing FEM fields at
the resolved reference coordinates. Output triangles keep their owning element
and separate vertex records. The plotter uses this supplied connectivity and
never triangulates a global point cloud; consequently it does not connect
disconnected material across vacuum or average the two DG traces on an
interface. A plane exactly coincident with an internal element face uses the
trace from its positive-normal side.

The material boundary is found from stellar/nonstellar faces and evaluated from
the stellar side. Its curve is computed separately from the volume coloring.
The undeformed outline is independently intersected with the physical plane;
projecting reference positions of the deformed cut would be a different curve.
An exactly coplanar surface patch is reported as unsupported instead of being
silently drawn as a unique intersection curve.

Curved cuts are displayed using straight triangles and boundary chords. Field
colors are piecewise linear on those triangles, not exact values throughout
their interiors. Root tolerances, maximum physical-plane residuals, sampled
centroid/midpoint chord errors, counts, bounds and time are recorded in each
plane's `metadata.csv`. The chord errors and bounds are sampled diagnostics,
not rigorous global enclosures. Tangencies or multiple crossings contained
between subdivision vertices can be missed; compare subdivisions for image
stability. This visualization does not certify pointwise positivity or exclude
small unsampled features.

## Checks

Every export runs pure geometric controls: unit-cube section area, integration
of a signed affine field, a curved shear for which the reference-plane cut is
wrong, surface segment intersection, and deterministic one-sided treatment of
a coincident internal face. The same controls can run without FEM:

```sh
c++ -std=c++20 -O0 experiments/model_slice_geometry_tests.cpp -o /tmp/model_slice_checks
/tmp/model_slice_checks
python -m unittest discover -s experiments -p test_plot_model_slices.py -v
```

The Python controls cover signed independent fields, supplied connectivity for
disconnected material, equal axes, PNG/PDF rendering, and rejection of a
cross-element triangle, an off-plane field/outline, and shape exaggeration.
They are geometry and plotting controls, not a substitute for a coupled-model
validation run. The exporter checks that its density, enthalpy and displacement
source buffers remain bitwise unchanged.