Compare physical slice refinement with shared scalar rendering

experiments/MODEL_SLICES.md

@@ -56,6 +56,16 @@ 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,
@@ -115,6 +125,36 @@ 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:
+
+```sh
+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
@@ -126,6 +166,7 @@ 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
@@ -134,3 +175,10 @@ 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.