MeanField/experiments/SYSTEM_ISOLATION_PROFILE_HARNESS.md

# Final optimization batch: pressure, gravity source, preparation, and fixed divergence

Build the targets explicitly; sandbox is excluded from the default build:

```sh
cmake --build cmake-build-release-homebrew \
  --target system_isolation_profile_harness sandbox tests --parallel
```

Run from the repository root with a new output directory:

```sh
./cmake-build-release-homebrew/system_isolation_profile_harness \
  --system final-optimizations --check full --implementation both \
  --samples 5 --iterations 10 --warmup 2 \
  --prepare-samples 3 --prepare-iterations 1 \
  --output final_optimizations_01
```

This group measures:

- `pressure-displacement`: tensor evaluation of displacement gradients and
  tensor gradient transpose, compared with the previous optimized pointwise
  application (`cached_pointwise_reference`). The general prepared action
  and stateless kernel remain correctness references.
- `pressure-preparation`: batched displacement and enthalpy evaluation and
  tensor assembly of the enthalpy derivative matrix, compared with the
  previous blocked matrix assembly and pointwise displacement evaluation.
- `gravity-source-displacement`: tensor density/displacement evaluation and
  potential-test transpose, compared with the previous pointwise application.
- `hydrostatic-preparation`: batched displacement and scalar evaluation and
  tensor assembly of the algebraic matrices, compared with the previous
  pointwise/dense preparation.
- `gravity-schur-preparation`: reuse of the fixed divergence matrix during
  Schur assembly, compared with assembling divergence on every call. This
  timing excludes mass-diagonal preparation and AMG setup, which are unchanged.

Preparation timings change state/revisions before each measured call and
verify that pressure/hydrostatic preparation actually rebuilds. Schur timings
cycle through mass diagonals prepared from three displacement states.
Cold hydrostatic preparation and cold divergence-cache assembly are reported
separately. These medians measure the incremental benefit of this batch;
they do not reuse the slower baselines from earlier batches.

Full harness checks compare prepared and stateless derivatives, residuals,
algebraic actions, enthalpy diagonals, multiple states and directions, zero
source directions, and finite differences. Hydrostatic checks also reject
folded geometry and recover afterward. Schur checks compare cached and
fresh assembly, change and restore the mass diagonal, check exact inverse
scaling, clear the cache, and invalidate it with `Mesh::NodesUpdated()`.
New unit coverage checks the scalar gradient transpose against dense
reference gradients and adjoint products for multiple H1/L2 orders/bases,
preparation-mode switches, rejection/recovery, and production gravity-block
cache reuse/invalidation.

The divergence cache belongs to each prepared gravity block. It retains one
assembled sparse matrix for the block's lifetime. Every refresh still forms
a fresh weighted transpose and Schur matrix using the current mass diagonal.
A discretization revision clears the cache; mesh, node, FE-space sequences,
and quadrature-policy identity are also checked collectively before reuse.
Raw computational-coordinate edits must call `Mesh::NodesUpdated()`.
A standalone cache must be cleared after changing a quadrature policy in
place. Physical displacement changes do not invalidate fixed divergence.

The tensor paths retain the existing mapper validation, quadrature, DOF
transformations, and fallbacks for unsupported elements/rules. Metadata
reports `pressure_tensor_elements`, `source_tensor_variation_elements`, and
`hydro_preparation_tensor_elements`, plus divergence assembly counts. A zero
tensor count indicates fallback, not measured tensor acceleration.

The new individual selectors are `gravity-source-displacement`,
`hydrostatic-preparation`, and `gravity-schur-preparation`.
`pressure-displacement` includes its preparation benchmark. This batch is
selected together with `final-optimizations`.

Return `summary.txt`, `metadata.txt`, `timings.csv`, and `checks.csv`.
After the checks pass, run the rebuilt sandbox with the same preflight
setting as the previous run, and capture its Newton timings and profiles.
Compare the residual, accepted step, trial count, determinant minimum, Krylov
iterations, and true linear residual along with the wall times. The previous
reference was 24.174 s for Newton 0, 8.00964 s trial preparation, 2.14648 s
accepted refresh, and 13.6571 s linear solve (26 J and 24 preconditioner calls).

These source and test changes have not been compiled or executed by the agent.

---

# Application optimization batch: closure, rotation, primal mass, and trial preparation

Build both `system_isolation_profile_harness` and `sandbox` explicitly in
`cmake-build-release-homebrew`; sandbox is excluded from the default build.

Run from the repository root:

```sh
./cmake-build-release-homebrew/system_isolation_profile_harness \
  --system application-optimizations --check full --implementation both \
  --samples 5 --iterations 10 --warmup 2 \
  --prepare-samples 3 --prepare-iterations 1 \
  --output application_optimizations_01
```

The group measures these changes against the implementations immediately before
this batch:

- `barotropic-closure`, `barotropic-enthalpy`, and `barotropic-displacement`:
  tensor interpolation and transpose versus the cached pointwise path. The
  dedicated enthalpy and displacement baselines retain their dedicated entry
  points, so these ratios measure tensor acceleration without counting the
  earlier removal of zero-block work again.
- `rotation-force`: tensor density/displacement interpolation and force
  transpose versus the cached pointwise complete action.
- `hdiv-mass`: the new CPU application versus retained MFEM partial assembly
  (`mfem_pa_reference`), with identical prepared coefficients, quadrature,
  restrictions, orientation handling, and true-DOF transfers. The new integrator
  contracts only its marked domain, uses scratch sized to the actual order,
  and specializes the current RT2/nine-point-per-axis case. Other supported
  CPU orders use the same algorithm with runtime dimensions. Other backends
  retain MFEM's application. Mass-only runs use primal preparation.
- `geometry-inspection`: the production trial-geometry validator with cached
  computational-mesh inverse Jacobians and tensor gradients, versus the original
  `GridFunction::GetVectorGradient` loop. Every volume element, inspection
  point, and determinant check is retained. The first cold inspection is
  reported separately; paired medians measure reuse with changing displacement.
- `gravity-source-preparation`: reuses the mesh weight already computed during
  mapping evaluation, versus recomputing `ElementTransformation::Weight()`.
  Both paths rebuild on every measured call; the harness checks preparation
  counters and compares forward, transpose, and displacement actions.

The scalar tensor plans now include nodal H1 and L2 hexes. Basis reconstruction,
native DOF permutations, and Cartesian quadrature ordering are verified before
a plan is enabled. Unsupported elements/rules retain the dense implementation.
Metadata reports `closure_tensor_elements`, `rotation_tensor_elements`,
`fast_mass_elements`, and `geometry_inspection_tensor_elements` so a fallback
cannot be mistaken for acceleration.

Full checks include general prepared and independent stateless comparisons,
existing finite differences, mass symmetry/linearity/positive energy/zero input,
changing geometries, fold rejection, and non-finite geometry rejection. The
unit-test additions also cover both global vector orderings, curved-mesh cache
invalidation, explicit cache clearing, tetrahedron fallback, and L2 basis
variants. These tests are supplied for the user to compile and run.

The inspector stores nine doubles (72 bytes) per eligible inspection point,
plus shared reference tables and reusable element scratch. It refreshes fixed
geometry when the mesh, nodes, or finite-element-space sequence changes.
Raw coordinate edits must call `Mesh::NodesUpdated()`, as with MFEM's geometry
cache, or clear a standalone inspector with `ClearCache()`. Displacement is
read anew for every inspection. Its mutable scratch is intended for sequential
calls, consistent with the prepared operators.

Use a new output directory and return `summary.txt`, `metadata.txt`,
`timings.csv`, and `checks.csv`. Application timings use `--samples` and
`--iterations`; inspection/source preparation timings use `--prepare-samples`
and `--prepare-iterations`. This group omits unrelated force-preparation
benchmarks. Individual systems remain selectable. After checks pass, rebuild
sandbox too and compare its printed Newton timings and convergence against the
previous run.

---

# Runtime optimization batch: tensor applications, geometry cache, normalization

Build both `system_isolation_profile_harness` and `sandbox` explicitly in
`cmake-build-release-homebrew`; sandbox is excluded from the default build.

Run from the repository root:

```sh
./cmake-build-release-homebrew/system_isolation_profile_harness \
  --system runtime-optimizations --check full --implementation both \
  --samples 5 --iterations 10 --warmup 2 \
  --prepare-samples 3 --prepare-iterations 1 \
  --output runtime_optimizations_01
```

This group checks and measures:

- `normalization-diagonals`: H(div), potential, density, enthalpy, and surface
  reference-mass diagonals, comparing volume partial assembly and direct surface
  diagonal integration to full true-DOF matrix assembly. Both diagonal norms
  are recorded, and the surface diagonal must have positive entries. These use
  the preparation sample/iteration counts.
- `geometry-preparation`: complete H(div) preparation with the fixed-mesh
  geometry cache enabled versus disabled, changing displacement between paired
  samples. Both use the same optimized operator. Mass and displacement actions
  are checked outside the timer. The initial cold-cache preparation is reported
  separately; median timings measure reuse. Cache hit/miss/point counts are saved.
- `hdiv-displacement`: tensor interpolation/transpose versus the **previous
  optimized pointwise** implementation (`cached_pointwise_reference`).
- `gravity-force`: tensor application versus the **previous optimized pointwise**
  application. General prepared paths and finite differences remain independent
  checks. The older gravity preparation comparison is omitted from this group.

The metadata includes `tensor_variation_elements` and
`gravity_tensor_elements`. The current hex mesh should use tensor paths on all
eligible elements. General geometries and quadrature retain the existing paths;
these counts distinguish real acceleration from a correct fallback.

Individual systems remain selectable, including the two new setup systems.
Use a new output directory for every run. Upload `summary.txt`, `metadata.txt`,
`timings.csv`, and `checks.csv`. Preparation timings use `--prepare-samples`
and `--prepare-iterations`; application timings use `--samples` and
`--iterations`.

## Preflight option

```sh
./cmake-build-release-homebrew/sandbox --skip-preflight
```

Library option: `NewtonOptions.backtracking.geometryPreflight = false`.
The default remains `true`; sandbox also accepts `--preflight`. Skipping avoids
both the predictive geometry scan and its lazy rule construction. Trial mapping
validation, finite-value checks, backtracking, and accepted-state restoration
remain active. Skipped scans have zero reported time and an empty optional
geometry estimate; `geometryLimitedIterations` counts only predictive limits.
A skipped scan can trade its time for extra rejected trials on a large step.

## Geometry and normalization contracts

The mapper caches only fixed computational-mesh positions, Jacobians, inverse
Jacobians, and weights. It recomputes displacement and compactification mapping
data on each call. Cache keys use element and actual reference coordinates, so
copied or changed quadrature rules cannot reuse the wrong point; quadrature
weights are applied by each caller. Mesh and node sequence changes invalidate
the entries. After raw coordinate changes, call `Mesh::NodesUpdated()`, as for
MFEM's geometric-factor cache, or `DomainMapper::ClearGeometryCache()`. Clear
the cache before destroying a mesh that the mapper will outlive. Cache entries
consume memory proportional to the distinct element/quadrature points visited,
and the mapper cache, like the element transformations it uses, is not thread-safe.

Normalization retains full matrix assembly for nonconforming, variable-order,
and unsupported element spaces. In particular, it does not substitute the
approximate partial-assembly diagonal for `diag(P^T A P)` on hanging-node meshes.
Supported conforming hex volume spaces use MFEM partial assembly followed by
exact true-DOF diagonal assembly. The surface path integrates only diagonal
entries over marked boundary elements, using the same quadrature and physical
shape functions as full assembly. This includes the internal star/vacuum
interface, which MFEM's exterior boundary partial-assembly restriction omits.
The direct surface path supports conforming scalar H1 spaces without general
DOF transformations; other spaces retain full assembly.

The new tests in existing test sources cover scalar/RT tensor transposes and
adjoint products, integrated RT bases, retained-table lifetime, general fallback,
geometry cache invalidation, changed displacement/compactification, exact
normalization diagonals, nonconforming fallback, and Newton acceptance/fold
rejection with preflight skipped. Compilation and execution are left to the user.

---

# System isolation profile harness

This executable checks and times individual operators without constructing a
stellar model, preconditioner, or Newton solver. Available systems are:

- `hdiv-displacement`: optimized versus retained prepared H(div) derivative.
- `hdiv-mass`: new CPU primal application versus retained MFEM partial assembly.
- `mass-normalization`: cached scalar mass row versus retained quadrature action.
- `angular-momentum`: cached scalar angular-momentum row versus retained quadrature action.
- `hydrostatic-displacement`: tensor evaluation versus the previous cached pointwise derivative; checks also compare the general mapping variation.
- `stellar-derivatives`: mass normalization, angular momentum, and hydrostatic displacement.
- `barotropic-closure`: complete density/enthalpy/displacement closure action.
- `barotropic-enthalpy`: tensor versus cached dense dedicated enthalpy coupling.
- `barotropic-displacement`: tensor versus cached pointwise dedicated displacement coupling.
- `pressure-displacement`: direct pressure displacement contraction versus the old matrix products.
- `pressure-enthalpy`: local-matrix application after blocked versus original matrix preparation.
- `gravity-force`: complete density/displacement/gravity-gradient force derivative.
- `rotation-force`: complete density/displacement force derivative at fixed rotation.
- `linear-derivatives`: the seven closure/force comparisons above, plus pressure/gravity/rotation preparation timings.
- `preparation-optimizations`: pressure displacement and enthalpy, gravity force, rotation force, their preparation comparisons, then hydrostatic displacement.
- `geometry-inspection`: cached fixed geometry and tensor gradients versus the original geometry scan.
- `gravity-source-preparation`: cached mesh weights versus repeated weight evaluation.
- `application-optimizations`: the closure, rotation, primal mass, inspection, and source comparisons described above.
- `all`: all application and preparation comparisons, including geometry inspection and normalization diagonals.
  A failure stops the affected group before its benchmarks.

The default remains `hdiv-displacement`. Scalar systems prepare a shared gravity
context to supply their frozen state, but do not solve for gravity. Hydrostatic
only runs do not construct that shared context.

## Preparation and hydrostatic optimization comparison

The current changes fuse gravity/rotation residual assembly with element-cache
preparation, block pressure enthalpy-matrix assembly, and use tensor contractions
for supported hydrostatic displacement elements. From the repository root,
after the user builds the release targets:

```sh
./cmake-build-release-homebrew/system_isolation_profile_harness \
  --system preparation-optimizations --check full --implementation both \
  --samples 5 --iterations 10 --warmup 2 \
  --prepare-samples 3 --prepare-iterations 1 \
  --output preparation_optimizations_01
```

Return the four output files. The new preparation medians are
`pressure-preparation.*`, `gravity-force-preparation.*`, and
`rotation-force-preparation.*`. Every timed pair gets fresh dependency revisions
with the same frozen physical state. Order alternates between samples.
Preparation counters must increase once per call; an accidental no-op is an error.
Shared gravity-context preparation and residual copying/norms are outside these
timers. These are warm re-preparation timings; they include geometry rebuilding
and do not measure first-construction cost or a complete Newton iteration.
Initial and unchanged-state preparation remain separately reported.

Preparation uses its own sample/iteration counts to avoid accidentally repeating
multi-second work with the application iteration count. Set `--prepare-samples 0`
to skip preparation timings. Both implementations remain available through
`--implementation`; correctness checks can still prepare references in an
optimized-only timing run. Independent reference operators require additional
memory in the harness, not in the production solver.

Checks compare prepared residuals and pressure enthalpy actions against the
original preparation at five states, as well as the existing derivative and
finite-difference checks. Hydrostatic timings use
`cached_pointwise_reference`, isolating this change from the earlier fast-path
optimization. Metadata reports `hydrostatic-displacement.tensor_elements`.
On the standard mesh this should equal the stellar element count.

Focused regression cases:

```sh
./cmake-build-release-homebrew/tests '*Tensor reference*,*Pressure*Force*,*Gravity Displacement Force*,*Rotational Displacement Force*,*Prepared Hydrostatic*'
```

For a nonlinear EOS check, repeat with `--polytropic-index 3` and a new output
directory. No stellar seed or Newton convergence is required.

## First comparison of closure and force derivatives

Explicitly build the harness target: it is excluded from the default build.
From `/Users/tboudreaux/Programming/4DSTAR/MeanField`, use:

```sh
cmake --build cmake-build-release-homebrew \
  --target system_isolation_profile_harness tests sandbox --parallel 2
./cmake-build-release-homebrew/system_isolation_profile_harness \
  --system linear-derivatives --check full --implementation both \
  --samples 5 --iterations 10 --warmup 2 \
  --output linear_derivatives_01
```

Return `summary.txt`, `checks.csv`, `metadata.txt`, and `timings.csv`.
Use a new output directory for every run. Individual system names above let you
isolate a failure or time one operator without constructing the others.
The group defaults to a polytrope with n=1 and K=1. To exercise a nonlinear EOS
without creating a stellar seed, add `--polytropic-index 3`; this option applies
only to the closure/force group and does not change the FEM mesh.

The complete closure comparison measures the contraction change. The two
coupling comparisons include savings from omitting absent columns, exactly as
the preconditioner now does. Their reference still executes the old complete
action with explicit zeros. Pressure measures both displacement and enthalpy derivatives.
Gravity and rotation measure their combined derivatives; their individual
stateless column methods remain available as independent checks.

Full validation covers undeformed and deformed geometry, a density/enthalpy-only
update, a gravity/rotation update, and a rotation-only update to zero angular
velocity. Nonzero rotation uses a tilted axis and an offset center. Each state
compares every requested direction and an exact zero direction. Column checks
compare old/new complete actions; gravity and rotation also compare their
independent stateless columns. Prepared gravity/rotation residuals are also
compared with independently assembled stateless residuals at every validation
state. Centered differences of primal residuals use two step sizes. Grouped runs check the complete closure FD;
individual coupling runs check that coupling's FD. Unchanged dependency
revisions must preserve preparation counts.

The scaled comparison uses the same unit-floor metric as the stellar group.
An additional relative comparison is reported for non-negligible outputs,
with tolerance 2e-10 for references and 2e-6 for finite differences. Full
validation may take several minutes because it prepares many states; its time
is reported separately and excluded from application samples.
`--check reference` checks one state plus zero input and unchanged revisions;
`--check none` skips correctness checks.

Initial, repeated, and unchanged preparation times are separate. The gravity
context is counted once, separately from gravity force preparation.
Application comparisons retain the earlier reference derivatives. The pressure
enthalpy comparison uses independently prepared local matrices, and the separate
preparation benchmarks compare original versus optimized preparation.
Gravity/rotation metadata reports fast-element counts; on the standard
3D mesh these should equal the stellar element count. Their fast paths require
VALUE/GRAD displacement with byNODES global ordering; gravity also requires an
H(div) reference table. Other configurations retain the previous implementation.
Closure and pressure use their direct contractions in 3D and retain their
previous general-dimensional calculations otherwise.

Focused regression cases, including material/surface coupling tests:

```sh
./cmake-build-release-homebrew/tests '*Barotropic Closure*,*Pressure*Force*,*Gravity Displacement Force*,*Rotational Displacement Force*,*Material*Surface*'
```

## First comparison of the scalar rows and hydrostatic derivative

After compiling the updated release executable, run from the repository root:

```sh
./cmake-build-release-homebrew/system_isolation_profile_harness \
  --system stellar-derivatives --check full --implementation both \
  --samples 5 --iterations 20 --warmup 2 \
  --output stellar_derivatives_01
```

Return `summary.txt`, `checks.csv`, `metadata.txt`, and `timings.csv`. To isolate
one system, replace `stellar-derivatives` with `mass-normalization`,
`angular-momentum`, or `hydrostatic-displacement`. The scalar benchmarks apply
the complete row (density/displacement and, for angular momentum, Omega).
The hydrostatic benchmark applies only its displacement derivative.

Full checks compare four states: undeformed, deformed, changed density, and
changed rotation including negative Omega. They use several directions, with
an element-scale perturbation in the second displacement direction. The
rotation axis is tilted and its center is displaced from the origin. Checks
cover separate scalar columns and zero inputs, the mass transpose identity,
lazy row construction, reuse on rotation/target-only updates, and invalidation
on geometry/density updates. Two centered differences perturb density,
displacement and Omega together for the scalar rows; the hydrostatic difference
holds the other fields and rotation fixed. Finite differences use the existing
primal residual preparation, which has not been replaced by the new row code.

For these three systems, errors are
`norm(actual-reference) / max(1, norm(actual), norm(reference))`; the unit floor
also makes zero scalar columns testable. Reference tolerance is 2e-11 and finite
difference tolerance is 2e-6. Lifecycle checks use exact counts. `--check reference`
checks one state and all requested directions; `--check none` performs no
correctness checks. These runs do not establish stellar accuracy or MPI correctness.

Preparation is reported separately for the shared gravity context and each
selected operator, on initial construction and on re-preparation. Scalar rows
are built lazily in production on first Jacobian use. The harness explicitly
times `PrepareJacobianRows()` before warmup, including in reference-only runs,
so that repeated-application medians do not hide that cost in one sample.
`explicit_row_prepare_seconds` records this first-use cost. When both paths are
timed, the summary also reports the break-even application count and the
reference/optimized ratio for 1, 10 and 25 calls including one row assembly.
A break-even value of -1 means no measured per-application saving. These ratios
exclude the common state/context preparation costs, which are reported separately.
Hydrostatic comparison uses the same augmented geometry cache for both paths;
it does not independently measure the previous preparation time.

Metadata reports scalar row eligibility and the hydrostatic fast-element count.
On the standard mesh both scalar flags should be 1 and the hydrostatic count
should equal the stellar element count. The optimized scalar rows retain two
local vectors per operator; hydrostatic adds nine doubles (72 bytes) per eligible
quadrature point. Reference tables are shared across operators with matching
elements and quadrature rules. Old mapping caches remain for reference/fallback.

The user-run `stellar_derivatives_01` comparison passed all checks and measured
885x and 1349x repeated scalar applications, and 1.94x hydrostatic displacement.
These exclude common preparation. The closure/force changes described below
have not been compiled or executed by the coding agent.

## H(div) comparison

From the repository root, run:

```sh
./cmake-build-release-homebrew/system_isolation_profile_harness \
  --system hdiv-displacement \
  --check full \
  --implementation both \
  --samples 5 --iterations 3 --warmup 1 \
  --output hdiv_isolation_01
```

The output directory must not exist. This uses `sandbox.smesh`, the production
quadrature policy and registered element orders, and one MPI rank on the CPU.
It performs no equilibrium solve. Directions and gravity coefficients are
deterministic; the geometry is a small nonuniform polynomial displacement with
shear and cross terms. `--deformation 0` selects the undeformed timing state;
the default is `0.7`, multiplying displacements whose coefficients are of order
0.01–0.04. This argument is not a fractional stellar radius or rotation rate.

Full validation checks two geometries (zero and the selected deformation), all
configured directions against the retained prepared derivative, and the first
direction against the independent stateless kernel. It also checks the selected
geometry against centered differences of the primal mass operator at two step
sizes. Those differences hold the gravity coefficients fixed. A failed check
stops the run before timing and returns status 3. Execution errors return 2;
successful requested checks and timing return 0. With `--check none`, status 0
means execution completed, not that correctness was checked.

Return `summary.txt`, `checks.csv`, `metadata.txt`, and `timings.csv` for analysis.
There is no need to run the full stellar model for this first comparison.

## Timing and interpretation

- `metadata.txt`: mesh path, geometry parameter, build/compiler information,
  problem sizes, domain element counts, quadrature count, and how many elements
  use the new derivative path. For the standard 3D Kelvin case, the last count
  should equal the total element count.
- `summary.txt`: finite-element setup, operator construction, initial and repeat
  preparation, validation time, median application times and their ratio.
- `timings.csv`: every measured sample, application count, seconds per
  application, and the last output norm. Warmup is excluded. A/B execution order
  alternates between samples. Output norms and file writes are outside the
  application timer. Each sample cycles through the same direction sequence.
- `checks.csv`: numerical errors, tolerances, and pass/fail status. The derivative
  comparison tolerance is 2e-11; centered differences use 2e-6 to allow subtraction
  error. A numerical failure is not permission to relax a tolerance.

For `hdiv-displacement`, `prepared_reference` is the previous prepared application
algorithm, retained in the same executable and using the same prepared state,
quadrature and field maps. This is the relevant application speedup comparison.
Both paths include true/local vector transfers and element assembly. Preparation
has already constructed the new cache in either case: this comparison does not
measure the old preparation cost or old peak memory use.

For `hdiv-mass`, `optimized` is the new CPU contraction and
`mfem_pa_reference` is the retained MFEM application using the same PA data.
This ratio measures the primal mass improvement from the latest batch. Full
checks still compare the independent stateless kernel, which reevaluates mapping.
Mass-only runs use primal preparation and report zero variation-cache elements.

The new tangent cache adds 12 doubles per eligible quadrature point (96 bytes),
plus shared reference displacement tables. Existing frozen mapping data remains
available for the reference/fallback implementation. Initial preparation may
therefore increase; compare preparation plus the application's actual number of
repeated calls when judging the total benefit. The earlier `hdiv_isolation_01`
user run measured a 3.13x median application speedup on the standard mesh; this
is separate from the new scalar/hydrostatic optimizations.

For a longer optimized-only profiling window after correctness passes:

```sh
./cmake-build-release-homebrew/system_isolation_profile_harness \
  --system hdiv-displacement --implementation optimized --check none \
  --samples 10 --iterations 20 --warmup 3 \
  --output hdiv_optimized_profile_01
```

Use a separate directory for each run. Avoid concurrent builds or other heavy
jobs while collecting comparisons. To inspect another resolution, use
`--refinements N`; to change the number of direction/flux pairs, use
`--directions N`. These are local operator tests, not demonstrations of final
stellar accuracy or distributed correctness.

## Derivative implementation

For computational-mesh coordinates X, the mapped H(div) mass tensor is

\[
M = J^T J / \det J, \qquad J = \partial x_{physical}/\partial X.
\]

The fast path contracts shared reference displacement gradients before applying
the cached mesh inverse. In the stellar domain, delta J is grad(delta u). For
Kelvin compactification, the existing Kelvin radial-factor calculation supplies
the fixed scale and its gradient:

\[
\delta J = a\,\nabla_X\delta u + \delta u (\nabla_X a)^T.
\]

Only `a * J_mesh^-1` and `grad_X(a)` are added to the point cache. The directional
mass action on a computational H(div) vector g is evaluated as

\[
\delta M g = \frac{\delta J^T(Jg) + J^T[\delta Jg -
\operatorname{tr}(J^{-1}\delta J)Jg]}{\det J}.
\]

This avoids computing unused inverse-mapping, inverse-element, physical-position,
and quadrature-weight derivatives, and avoids constructing the full mass-tensor
derivative. The fixed computational-mesh Piola factors, signed DOFs, primal/dual
DOF transformations, quadrature weights and true/local transfers are retained.
There is no change to equations, integration order, or solver tolerances.

The specialization requires three dimensions, an H(div) reference table, and
VALUE/GRAD displacement elements. Compactified elements additionally require
the concrete Kelvin map and a differentiable compactification element. Other
maps use the retained general implementation; merely declaring a map affine
does not select the Kelvin specialization.

## Compile and regression checks

Configure the release build with
`CMAKE_CATCH_DISCOVER_TESTS_DISCOVERY_MODE=PRE_TEST`, so compiling test targets
does not execute them to enumerate cases. Discovery occurs when the user runs
CTest. Configure/build commands are:

```sh
cmake -S . -B cmake-build-release-homebrew \
  -DCMAKE_CATCH_DISCOVER_TESTS_DISCOVERY_MODE=PRE_TEST
cmake --build cmake-build-release-homebrew \
  --target system_isolation_profile_harness tests sandbox --parallel 2
```

Focused regression cases for the user to run:

```sh
./cmake-build-release-homebrew/tests '*Prepared Hdiv*,*Prepared Mapped Hdiv*,Kelvin Prepared Jacobian Factors*'
```

Focused scalar/hydrostatic regression cases for the user to run after building:

```sh
./cmake-build-release-homebrew/tests '*Prepared Mass Normalization*,*Prepared Angular Momentum*,*Prepared Hydrostatic*'
```

These existing suites now also check retained-reference agreement, lazy row
construction, selective row invalidation, reuse across unrelated updates, and
angular-momentum rejection/recovery after rows have already been built. Existing
finite differences, transpose pairing and context lifecycle tests remain active.

## Closure and force implementation

All changes preserve quadrature, equations, field maps, signed element DOFs,
primal/dual transformations, and true/local transfers. There is no tolerance
based dropping of closure or vacuum terms.

- Closure couplings have supported-coordinate entry points for enthalpy alone
  and displacement alone. The preconditioner calls these rather than executing
  a complete action with known zero columns. The complete action still includes
  every column. Its geometric scalar remains
  `weightedResidual * tr(K * du/dxi)`, evaluated with a small direct contraction.
- Pressure uses the existing physical test gradients G and computes H=du/dx.
  Its displacement contribution is `p*w*(G*H-tr(H)*G)`. This avoids constructing
  the inverse-Jacobian variation and the matrix of all gradient variations.
- Gravity evaluates the existing expression
  `w_ref * [F*(delta_rho*g + rho*delta_g) + rho*(du/dxi)*(J_mesh^-1*g)]`.
  The last term contracts the reference gradients with a vector directly.
  Density interpolation and test-basis transpose are done per element; H(div)
  reference interpolation keeps the existing mesh Piola factor.
- Rotation uses shared reference value/gradient tables, bulk interpolation and
  transpose application, and a cached 3x3 centrifugal acceleration derivative.
  The force variation is
  `w * [(delta_rho + rho*delta_log_w)*a + rho*delta_a]`.
  The acceleration derivative is rebuilt with the existing preparation lifecycle.

The new paths add per-element scratch buffers reused between elements and
shared reference tables for rotation; they do not add large per-point dense
Jacobian blocks. Existing data and reference paths are retained. Reference
applications do not increment production column/complete application counters.

## Scalar and hydrostatic derivatives

For the supported stellar VALUE/GRAD displacement field, let `B_a` be the
reference basis, `K` the inverse deformed element Jacobian, and `w` the mapped
quadrature weight. An element displacement direction satisfies

```
delta x_c = sum_a B_a delta u_ac
delta log(w) = sum_acj K_jc (dB_a/dxi_j) delta u_ac
```

The mass row integrates `w delta rho + rho w delta log(w)`. The moment-of-inertia
row integrates `w r_perp^2 delta rho + rho w [r_perp^2 delta log(w) +
2 r_perp dot delta x]`. Angular momentum applies `Omega delta I + I delta Omega`.
The local coefficient vectors are assembled with signed element DOFs and dual
DOF transformations, then paired with prolonged true-DOF directions. The final
scalar retains the existing MPI sum. Keeping these as local duals avoids
double-counting shared true DOFs. Mass transpose uses the transpose prolongation.

Hydrostatic displacement contracts
`w [(h + Phi - Psi - C) delta log(w) - grad(Psi) dot delta x]`, then applies the
existing enthalpy test-basis transpose and assembly. It does not construct a
full mapping variation or repeatedly evaluate reference shapes. Only 3D interior
VALUE/GRAD elements use its fast path. Scalar row caching supports interior
VALUE/GRAD elements (mass in dimensions 1-3; angular momentum is already 3D).
Unsupported configurations retain the original general application. Density or
geometry changes invalidate scalar rows; Omega/target-only updates reuse them.
The equations, quadrature rules and solver tolerances are unchanged.

These include comparison with the stateless derivative, the general exterior-map
fallback, primal-to-linearization transitions, candidate rejection/recovery,
and Kelvin factor checks. The harness adds independent finite differences and
multiple direction pairs. Compilation alone does not validate their outcomes.

## Preparation and tensor implementation details

Gravity forms the residual quadrature force from the already computed
`rho * w_ref * F * g_ref`; rotation uses `rho * w * acceleration`.
Each then applies the cached displacement test-basis transpose. The optimized
preparation visits geometry once, retains element DOF transforms and true/local
assembly, and synchronizes candidate rejection before collective assembly.
`PrepareReference` retains the separate stateless residual pass. Switching
preparation implementations invalidates the relevant cached result even if
physical dependency revisions are unchanged.

Pressure retains the same local enthalpy matrix and its application. It packs
`-P'(h) * w * grad(test)` once per element and accumulates 32-row by 8-column
matrix tiles with contiguous row access. The original per-quadrature assembly
remains available through `PrepareReference`. EOS, mapping and finite-result
checks remain active; no quadrature points or matrix entries are dropped.

The scalar reference-table cache now owns small one-dimensional value/gradient
tables and a copied lexicographic-to-native DOF map for H1 hexahedra.
Cartesian quadrature ordering and the reconstruction of the existing full
values/gradients are checked once before publishing tensor support. Unsupported
elements/rules use the existing path. Evaluation contracts x, y and z in turn
and produces displacement values and reference gradients, then the hydrostatic
operator applies the same inverse-Jacobian contraction, physical coefficients,
test-basis transpose and assembly. Scratch is reused for one element; no dense
per-element displacement Jacobian is added. The immutable tables own all tensor
data, including when the FE, quadrature rule or cache that created them is gone.