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:

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:

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.

Field values are linearly interpolated within each supplied triangle at the centers of a 512-by-512 scalar grid, then mapped to colors. This avoids Gouraud shading's interpolation of RGBA colors, which can change an unchanged affine field's appearance under triangle refinement. --pixels N changes this display resolution (32–2048). Uncovered pixels remain masked; a pixel covered by more than one approximate triangle takes the first supplied triangle, with no cross-element averaging. No global triangulation or global point-location topology is inferred. Pixels can miss subpixel features and straddle a boundary; the separately drawn physical outline remains the geometric reference.

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.

The tetrahedral subdivisions are conforming inside each parent hexahedron, but their face diagonals are not made globally consistent across differently oriented neighboring elements. Boundary faces are triangulated independently as well. On a curved shared face, these choices can produce slightly different chord approximations: small gaps or overlaps between neighboring element fills, or a mismatch between the colored edge and the independently drawn outline. Deterministic ownership of a coincident planar face does not remove this curved interface approximation. These image artifacts must not be interpreted as physical gaps, jumps in geometry or an additional density feature.

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.

Before interpreting an actual FEM image, export the same saved state and plane at two subdivision counts, for example 6 and 12 (or 4 and 8 for a first bounded check). Compare the outlines, element-interface seams, sampled chord errors and the visible density/enthalpy structure at the same axes and color ranges. The pure geometry and plotting controls below do not test differently oriented neighboring curved hexahedra and do not replace this export refinement check. Globally consistent face triangulation would remove the diagonal mismatch; it is not implemented in this bounded diagnostic.

The comparison helper enforces a common plane/orientation/offset, increasing subdivision counts, shared physical axes and shared per-field color scales:

python experiments/compare_model_slices.py \
  /absolute/path/to/coarse/final_slices/xz \
  /absolute/path/to/fine/final_slices/xz \
  --source-state /absolute/path/to/original/accepted_state.txt \
  --reference-outline --title 'Same rotating trial; unconverged' \
  --output /absolute/path/outside/source/slice_refinement

It writes a side-by-side PNG/PDF and JSON containing triangle-area sums, signed piecewise-linear 2D density/enthalpy integrals, surface bounds, segment-length sums, exported geometric diagnostics and their absolute/relative changes. Area and field integrals include any overlapping triangles; segment-length sums include any duplicate segments. These are measures of the displayed slice, not exact curved-FEM integrals, 3D mass or virial diagnostics. Near-zero signed integrals make relative changes sensitive, so also inspect absolute changes. The two panels use the same scalar raster grid and bounds; its pixel resolution and overlap ownership are recorded. Quantitative integrals are computed from the supplied triangles, independently of the display raster.

--source-state is the caller's declaration of the common saved state and its SHA256 is recorded. The caller must verify that both exports used that state, mesh, field orders and physical specifications. The current export CSVs do not bind themselves to a snapshot, and this helper does not establish provenance from matching plane metadata. Output artifacts must be outside the source checkout and existing files are not overwritten.

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:

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
python -m unittest discover -s experiments -p test_compare_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.

The comparison controls use an affine signed density and independent enthalpy on a unit square at two subdivisions. They check exact area/integrals/perimeter, explicit counting of duplicated triangles, shared axes/color normalizations, and rejection of a mismatched offset or reversed refinement. They do not run a FEM model. An additional affine control verifies that coarse and fine scalar rasters agree, and the disconnected-material control verifies masked vacuum.