MeanField/reports/sources/original_audits/preconditioner_audit_notes.md

Preconditioner and normalization audit — 2026-09-16

Read-only inspection of the current working source in /Users/tboudreaux/Programming/4DSTAR/MeanField. No solver fixes, source edits, builds, or new numerical runs were performed by this audit subtask. Existing numerical results below are explicitly historical. The repository is dirty and contains substantial performance work newer than HEAD 75cc638; line references identify the inspected working source.

Current default: exact implementation, not inferred intent

The sandbox selects PhysicalRieszDiagonal{radius,G}, default stellar preconditioning, and FGMRES(restart 40): sandbox.cpp:118.

The physical unknowns grouped for preconditioning are material/surface (rho,q,h), gravity (g,Phi), then the generated scalar constraints. The preconditioner is a composition of three approximations:

1. Material/surface is surface-first triangular. Solve q = Dq^-1 bq, subtract the actual surface-to-material Jacobian actions, solve h = Dh^-1 (bh-Ahq q), then solve rho = Drho^-1 (brho-Arhoq q-Arhoh h). Thus the current EOS derivative and surface-to-material actions ARE included. Material-to-surface feedback is omitted. Drho is the closure density mass diagonal; Dh is the hydrostatic enthalpy mass diagonal, with replaced surface rows set to one. Dq is the raw positive boundary mass diagonal, without an operator-fitted coefficient or EOS/rotation-dependent stiffness. default selection, action, diagonals, surface assembly.

2. Gravity is approximate LDU. The mixed flux mass inverse is a degree-5 matrix-free Chebyshev action with 20 power iterations at setup; the positive potential-Schur surrogate is B diag(Mg)^-1 B^T, inverted approximately with three fixed BoomerAMG cycles. Gravity recovery makes two mass-inverse applications. Note that the Schur surrogate continues to use the mass DIAGONAL even though flux recovery uses the more accurate Chebyshev approximation; this is a deliberate approximation, not an exact factorization. default, LDU, surrogate, fixed AMG.

3. Material/surface and gravity are independent before scalar bordering. Their cross-couplings are available, but the default calls each subsystem inverse separately. A small dense border Schur S = D-C Atilde^-1 B is assembled by probing every scalar border column and inverted directly. For the stationary default the already-computed W=Atilde^-1 B is cached and used for recovery. This border is exact relative to the selected approximate structure inverse, not the exact stellar Jacobian. independent action, border construction, cached recovery.

Other available policies are material/surface LDU, reverse triangular order, calibrated surface mass, fitted surface mass-plus-stiffness, and both stellar cross-coupling triangular orders/LDU. Availability is not evidence of quality for rotating models.

Lifecycle checks are substantial: stale gravity and material inverses are rejected; changes to geometry rebuild their relevant diagonals and gravity surrogate. Material thermodynamic diagonals are reused when geometry is unchanged because the rho–rho and h–h derivatives are mass operators; the EOS derivative resides in a separately prepared live coupling. This reuse is not, by itself, evidence of a stale high-n EOS approximation. material refresh, gravity refresh, closure density diagonal.

Normalization: what is and is not established

Physical scales are derived from fixed target mass, branch reference radius, and G: rho*=M/R³, g*=GM/R², h*=GM/R, Omega*=sqrt(GM/R³), J*=M sqrt(GMR), F*=GM²/R². Neither target J nor Omega enters a denominator; zero rotation is not singular in these scale formulas. scale derivation.

The Gram diagonals are reference finite-element volume mass diagonals for rho,h,Phi; reference RT mass diagonal for g; and a boundary mass diagonal for q. For a field block with scale s and diagonal d, state normalization is sqrt(d)/s, while weak residual normalization is 1/(s sqrt(d)). Replaced pressure-surface enthalpy rows use point metric one; generated scalar constraints use metric one. The central-density residual is correctly classified as an enthalpy residual, despite its density target. assembly and block assignment, factor formulas, hybrid rows, scalar dimensional declaration.

These maps are frozen throughout Newton unless explicitly refreshed. They do not adapt to central concentration, EOS derivatives, effective surface gravity, or rotation. They define the merit/Krylov norm; they are not a Jacobian approximation. Reference exterior weighting is a computational norm choice and does not by itself mean the exterior must be physically accurate everywhere. The important diagnostic is whether exterior residuals consume the solve budget while interior structure and virial balance are already accurate.

Let physical state x=R xhat, residual Fhat=L F, and physical approximate inverse P^-1. The wrappers implement exactly Jhat=LJR and Phat^-1=R^-1 P^-1 L^-1. Therefore

Jhat Phat^-1 = L (J P^-1) L^-1.

This is an especially useful diagnostic inference: changing only state scaling cancels from the consistently right-preconditioned Krylov operator in exact arithmetic. Row scaling changes the Euclidean residual geometry and nonlinear merit; it does not remove an actual null direction. A claim that variable scaling alone fixes the present solver would require an identified finite-precision or inconsistent-transform mechanism. Jacobian wrapper, inverse wrapper.

The source includes round-trip, scaled-operator, synthetic conditioning, and direct-versus-assembled Gram diagonal tests. They establish algebra and assembly expectations when run; they do not establish mesh-independent merit weighting for every n/rotation or full physical-unit invariance. Raw reference measures are used without total-volume/area normalization, surface point rows are counted individually, and the phase border is inserted directly into a weak enthalpy coefficient. Before making broad claims about dimensional invariance, test a physically equivalent length/mass unit change through the complete discretization, not only the characteristic-scale formulas. This is an audit gap, not demonstrated causation of the plateau at the current fixed units.

Existing numerical evidence: historical, not a new convergence experiment

The September 3 campaign is explicitly a nonrotating n=3 projected Lane–Emden seed. Its full-system results precede the current normalized Newton stack. Surface-first, uncalibrated mass and independent stellar subsystems won the available full-system comparisons. Scalar surface calibration and material LDU improved isolated solves but did not transfer to the complete operator; the surface action varied over approximately three orders of magnitude across sampled modes. The fitted H1 mass-plus-stiffness surrogate was also unreliable. campaign.

Chebyshev-5/AMG-3 achieved true relative residual 1.19e-4 after a 36-iteration fixed-budget manufactured full-system solve; the historical residual was 93.8% gravity-gradient and 6.2% Poisson by squared norm. However, a physical RHS experiment with restart 20 stagnated near relative residual 0.9998 after 48 iterations, motivating equation normalization and restart studies. These are strong reasons to test actual physical RHSs and recompute true residuals, but cannot be presented as measurements of today's normalized plateau. campaign results.

Hypotheses to discriminate, without changing the algorithm

1. Global coupled modes are poorly represented by independent structure blocks. The code omits the rho→gravity→h and shape↔gravity feedback loops from its principal approximate inverse; the scalar Schur inherits those omissions. High n changes the strength and localization of these loops. This is a strong structural hypothesis, but there is no present proof that it dominates a recorded plateau. Test the physical Newton RHS at one frozen plateau with identical total Jacobian budgets and longer restart; record which residual blocks remain. Only after diagnosis compare opt-in cross-factorization policies, using true residual reduction per time. Earlier stronger coupling policies were worse, so “more coupling” alone is not a recommendation.

2. Surface restoring action becomes poorly matched by the raw surface mass diagonal. Default Dq has no state-dependent stiffness, whereas the true surface residual contains material, gravity, and rotation dependence. This is particularly plausible approaching mass shedding, but cannot explain a low-rotation threshold without state-specific mode evidence. Probe smooth radial, oblate quadrupole, and a few high-frequency surface modes through the full normalized Jacobian and approximate inverse; include induced material/gravity completion when interpreting a surface Schur mode. Do not extrapolate isolated Aqq tuning to the coupled model.

3. Nonlinear admissibility rather than linear conditioning can control high-n progress. For n=1, dρ/dh is constant. For n>1 it tends to zero as h→0, and the closure's preparation rejects any negative h at its quadrature points. The standalone EOS itself clips negative h to zero, so merely inspecting its public formula misses this solver-domain restriction. Record minimum h, trial failure source, step length, and predicted versus actual reduction. Repeated h-domain rejection with accurate linear solves would rank this above preconditioner tuning. EOS derivative, closure rejection.

4. Frozen residual weighting can make the reported plateau differ from the physical milestone. Separate full normalized norm, each normalized block norm, interior gravity defects, and virial error. If almost all remaining norm is exterior gravity while virial/interior quantities satisfy their tolerances, the computational stopping target may be the issue. If virial remains bad, exterior inaccuracies cannot simply be dismissed: their influence on interior gravity must be assessed.

5. Border/constraint compatibility needs explicit measurement. Fixed-central-density adds lambda_c e_c to the weak enthalpy equation, alongside its phase condition; a small total residual does not imply the unmodified hydrostatic equation if lambda_c is appreciable. Export lambda_c, its actual normalized contribution, the tiny approximate Schur matrix, and its singular values in normalized coordinates. A well-conditioned approximate border Schur does not prove the exact coupled system is well-conditioned. central border.

Economical frozen-state instrumentation

At every accepted state, report ||F||, normalized block norms, true ||J dx+F||/||F||, solver-reported residual, iteration/restart count, accepted alpha, rejection reasons, minimum h/rho/Jacobian determinant, virial balances, mass/J errors, and phase-border contribution. Two Jacobian finite-difference directions (actual Newton direction and an oblate/shape direction), with several step sizes that remain admissible, would separate an inconsistent derivative from a poor solve.

Public access through the default context is available without editing production code:

state.physicalInverse->Refresh(); // only when the physical problem is prepared
const auto &grouped = state.physicalInverse->GetGroupedPreconditioner();
const auto &S = grouped.GetFactorization().GetSchurComplement();
const auto &structure = grouped.GetStructurePreconditioner();
const auto &material = structure.GetMaterialSurfacePreconditioner();
const auto &gravity = structure.GetGravityPreconditioner();
const auto &coordinates = state.physicalInverse->GetCoordinateMap();
const auto &normalization = state.normalizedOperator->GetNormalization();
mfem::Vector L(state.physicalInverse->Height());
mfem::Vector V(state.physicalInverse->Height());
coordinates.PackResidual(normalization.ResidualFactors(), L);
coordinates.PackCorrection(normalization.StateFactors(), V);
const int start = grouped.GetCouplings().StructureSize();
mfem::DenseMatrix Shat(S.Height(), S.Width());
for (int i=0; i<S.Height(); ++i)
    for (int j=0; j<S.Width(); ++j)
        Shat(i,j) = L(start+i) * S(i,j) / V(start+j);

Compute SVD of Shat, not raw dimensional S. This is tiny and cheap; serial runs avoid distributed scalar ownership complications. Exporting the entries for external SVD is sufficient. Material diagonal min/max/floor/regularized-count getters are already public, as are gravity mass inverse, potential Schur surrogate, and factorization statistics. The current context refreshes the inverse during PrepareTrialCommit, and WithState requires a ready context, so the final accepted-state Schur is current. An explicit no-op refresh in an independent diagnostic remains harmless; preparations performed outside the context must respect the lifecycle.

The later experiment-only helper preconditioner_diagnostics.hpp implements these exports plus a variable-scaling invariance check and full-Jacobian actions on border-completed directions. It does not change state, instantiate alternate preconditioner policies, or solve any extra equations. Its expected cost is three Jv plus one Jv per generated scalar border coordinate. Compilation and execution are coordinated by the root task.

No hypothesis above is presented as the established cause before the root task's new runs are available. Virial <=1e-5 is the primary model acceptance milestone; pointwise interior accuracy and checks for nonphysical constraint forcing remain necessary companions. Exterior error is relevant through interior gravitational influence and numerical conditioning, not as an independent accuracy target.