Update numerical strategy documentation with verified evidence

This commit is contained in:
2026-09-17 12:09:57 -04:00
parent 8b307b43d3
commit b9e6794999
6 changed files with 63 additions and 35 deletions

View File

@@ -17,7 +17,7 @@ gravity and retained local systems must be square. A globally empty gravity
system is rejected by the prepared linear backend. Gather/injection require
preallocated, nonoverlapping storage.
`PreparedGravitySubsystem` owns restricted operator/inverse workspaces and the
`PreparedGravitySubsystem` owns gravity operator/preconditioner workspaces and the
existing prepared linear backend. It borrows the full normalized operator,
inverse, and communicator at stable addresses. It is neither movable nor
copyable. Preparation records the root preparation generation. After candidate
@@ -26,15 +26,17 @@ the subsystem; stale applications and solves fail. The subsystem does not
prepare a candidate, change an accepted state, or commit a step.
The exact gravity action is the principal restriction of the root Jacobian.
The preconditioner is the corresponding restriction of the supplied root
inverse. This reuses existing normalization, gravity boundary conditions, and
preconditioning recipes, but does not assert that the restricted inverse is an
exact gravity inverse. Every solve retains the backend's independently checked
true-defect gate. Both wrappers preallocate full-vector workspaces; applications
perform gather/scatter and the existing root actions without allocating their
own vectors. Full root actions may do unnecessary non-gravity work; a specialized
gravity action/inverse adapter remains a future optimization requiring equality
tests against this reference restriction.
The default automatic policy uses the existing compact physical gravity action
when a declared compile-time capability and collectively checked canonical
partition permit it. Otherwise it injects, applies, and restricts the full root
operator. The selected preconditioner similarly uses a supported compact
physical gravity block or the supplied root inverse's restriction. Neither
choice asserts an exact gravity inverse. Both paths retain the same diagonal
normalization and boundary maps, persistent scratch storage, and the backend's
independently checked true-defect gate. `RootRestrictedGravityApplications`
remains an explicit reference policy. Equality tests and measured application
costs are recorded in
[`GRAVITY_COMPACT_APPLICATIONS_2026-09-17.md`](GRAVITY_COMPACT_APPLICATIONS_2026-09-17.md).
Attempted solves, completed inner iterations, failed calls, completed solve time,
and the last completed solve report are available without history allocation.
@@ -81,5 +83,10 @@ overlapping storage, exact restricted solves, true-defect failure, nonfinite
inputs, stale operator/inverse preparation, locally empty MPI partitions,
globally empty rejection, preserved backend options, zero affine curvature at
an off-manifold base, and the second-order correction at curved trial geometry.
The root integration campaign compiles these components and tests real stellar
states; this branch does not claim a new validated stellar equilibrium.
The integration campaign compiled these components and passed their serial and
supported two-rank tests, including locally empty partitions. Real stellar
serial fixtures also passed compact/reference comparisons with and without the
central-density border. Full stellar MPI operation remains unvalidated because
the existing logical radial surface interpolation is restricted to one rank.
Algebraic tests alone do not establish a virial-qualified stellar equilibrium;
the separate model campaign applies the unchanged physical acceptance checks.