Reuse prepared gravity force for stellar cross preconditioning

experiments/PRECONDITIONER_CACHED_CROSS_ACTION_2026-09-18.md

@@ -0,0 +1,40 @@
+# Prepared gravity-to-material preconditioner action
+
+The stellar-structure gravity-to-material coupling used
+`PreparedDisplacementResidualOperator::ApplyGravityGradientJacobianAction`, which
+delegates to the standalone gravity-gradient force column. That column evaluates
+the legacy geometry kernel during each application. The full stellar Jacobian
+instead uses the already prepared complete gravity-force action, including its
+cached tensor path.
+
+The cross preconditioner now calls that same prepared gravity-force action with
+zero density and displacement variations. These zero vectors are allocated and
+initialized once with the cross operator. For a fixed prepared state,
+
+\[
+  D F_{\mathrm{gravity\ force}}[0,0,\delta q]
+  = (D_q F_{\mathrm{gravity\ force}})\delta q.
+\]
+
+The existing domain-deformation adjoint then maps this mechanical action into the
+shape row. Gravity-potential coupling into hydrostatic equilibrium and pressure
+boundary-row replacement remain unchanged. Pressure and rotational complete
+actions are not invoked: they have no gravity-gradient column.
+
+This is a preconditioner execution-path change. It changes no equation,
+quadrature selection, cross-block approximation, factorization policy, default,
+or full Newton-Jacobian implementation. Prepared and legacy force evaluations
+may differ by floating-point evaluation order; numerical equality is tested with
+the existing `2e-12` scaled norm criterion.
+
+The material-to-gravity cross action already uses the same prepared gravity
+Jacobian as the full stellar operator and is unchanged. This patch does not
+optimize other material/surface policies or standalone partial-column APIs.
+
+The existing stellar-structure FEM integration test now compares three dense
+gravity directions against both the legacy partial-column calculation and the
+restricted full Jacobian, checking surface and enthalpy rows separately. It
+repeats after density and shape changes, checks repeated application after full-J
+scratch use, and verifies that these applications do not reprepare the force.
+The tests are supplied for the coordinated build; no timing improvement is
+claimed before measurement on the frozen benchmark state.