Add physical-plane FEM model slice diagnostics and plots

experiments/MODEL_SLICES.md

@@ -0,0 +1,117 @@
+# 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.