MeanField/experiments/NUMERICAL_STRATEGIES_2026-09-17.md

Optional Newton strategies: implementation and validation

The experiments start from 7a07cae. Each hypothesis has an isolated, build-configurable branch; the integration branch combines the implementations behind explicit typed policies. The default physical model, normalization, preconditioner prescription, and ordinary Newton path remain available. Central density is still an optional model specification.

Selection and ownership

Newton(options) retains its existing meaning. An expert numerical configuration can supply a third constructor argument:

namespace nl = mean_field::solver::nonlinear;
auto numerics = nl::NewtonNumerics{
    nl::PolynomialEnthalpy{},
    nl::GravityCurvatureCorrection{}
};
auto configuration = nl::Newton(options, nl::NormalizedResidualMetric{}, numerics);
auto solve = mean_field::solver::make(context, configuration);
auto report = solve.evaluate();

The enthalpy choices are SampledEnthalpy and PolynomialEnthalpy. Gravity choices are MonolithicGravity, GravityCurvatureCorrection, and EliminatedGravity. Their combinations are concrete C++ types. Unregistered policy types are rejected by concepts. Block identities come from the compiled equation form; mesh sizes, FE eligibility, arithmetic values, and distributed preparation generations are checked at runtime.

The context owns each prepared workspace. Numerical calls are statically dispatched; only destruction of the selected context-owned storage is erased. Workspaces are constructed when a solve selects them and are destroyed before their borrowed operator/backend dependencies. Reduced gravity recovers the outer backend prescription through GetConfiguration(); custom backends need that capability only when selecting elimination. Polynomial direction repair currently requires the normalized residual metric, because its derivative supplies the line-search slope.

1. Polynomial enthalpy feasibility

The implementation transforms the actual nodal polynomial to a tensor Bernstein representation using outward-rounded interval arithmetic. Adaptive subdivision either certifies nonnegativity, proves negativity through a negative polynomial value, or reports unresolved bounds. A negative Bernstein coefficient alone is never classified as a negative polynomial. Exact zero traces are retained algebraically.

The production adapter works in physical enthalpy coordinates; a general diagonal normalization need not preserve the polynomial encoded by normalized coefficients. It supports conforming scalar H1 hexahedral elements with the supported closed nodal tensor bases and runtime polynomial order. Unsupported spaces fail explicitly. Unsafe fast-math compilation is rejected. Gradual underflow and immutable FE spaces remain prerequisites.

An invalid or uncertifiable initial polynomial is rejected before a residual-based convergence declaration. For a valid base, a certified initial enthalpy field provides an immutable anchor. The repair family is

[ p_h(\beta)=(1-\beta)p_h+\beta(h_{\rm anchor}-h),\qquad 0\le\beta\le1. ]

Shared true DOFs and prescribed zero traces are preserved. Bernstein inequalities provide a sufficient lower bound on the repair fraction, and the full linear residual model selects a fraction within that feasible interval. The actual represented candidate is certified again after normalization and state addition. A non-descent repair fails explicitly. Backtracking uses the repaired direction's merit derivative and still evaluates the complete nonlinear residual.

This is a conservative feasible-direction method, not the solution of a constrained Newton optimization problem. It may be too restrictive or have no descent direction. It does not prove positivity of the independently represented density field. Unchanged feasible directions require one extra Jacobian action; a model-selected enthalpy repair requires three. Combining it with elimination also relifts gravity and recomputes the actual merit derivative.

2. Gravity curvature correction

Write the normalized state as retained variables u and gravity variables z, with gravity equations G(u,z). The gravity partition includes both gradient and potential equations and retains their boundary rows. Given a base x, Newton direction p, and trial y=x+alpha*p, solve

[ G_z(y),\delta z=-{G(y)-G(x)-\alpha G'(x)p}. ]

The right side removes only the nonlinear remainder. It vanishes on an affine gravity path even when the base gravity residual is nonzero; it is second order in the trial length when the operator is smooth. The base residual and Jacobian action are captured before trial preparation. The candidate inverse is refreshed before solving. Only the candidate's gravity coordinates change.

A fresh complete preparation verifies the intended gravity target and evaluates the full merit. A failed inner solve, failed preparation, or unacceptable corrected merit does not commit a state. Trial observers must publish the corrected physical and normalized vectors together. The tangent is distinct from the secant of this curved trial path.

3. Gravity elimination

The nonlinear trial path completes gravity at fixed retained variables. The initial state is also explicitly completed before defining the nonlinear convergence reference. Retained coordinates include density, enthalpy, shape, and all model specification borders; optional central-density borders remain optional.

For the partitioned Jacobian, the reduced action is

[ S=F_u-F_zG_z^{-1}G_u. ]

Right-hand-side condensation includes any remaining gravity defect, and lifting reconstructs the corresponding full correction. The retained projection of the supplied full inverse preconditions the reduced system. Every lifted outer correction must satisfy the original full normalized Jacobian residual tolerance. Candidate gravity completion is separately checked after fresh nonlinear preparation.

Tolerance-stopped inner Krylov solves approximate a linear Schur action. Flexible outer preconditioning does not make this action exact. Tight inner tolerances, directional derivative checks, and the full lifted residual gate control this limitation. Inner failure propagates explicitly. Operator actions never prepare or mutate the physical state.

The reference implementation restricts the full operator and supplied inverse. The default automatic application policy can instead reuse the existing physical gravity action and gravity inverse, with the same diagonal normalization. Compile-time capabilities recognize the physical runtime, specification couplings, block identities, and preconditioner factorization. A collective runtime comparison requires the canonical partition on every rank. Unknown runtimes or incompatible partitions use the reference path. The explicit RootRestrictedGravityApplications policy remains available for comparisons. This changes block applications, not the nonlinear equations.

Interpreting reports

The complete nonlinear residual remains the merit and convergence authority. Gravity residual reduction alone does not establish a stellar equilibrium. The existing physical checker separately requires solver convergence and all eight energy/force, enthalpy/density, and quadrature-order virial measurements to pass 1e-5; it also reports local EOS, force, sign, and conservation diagnostics.

For elimination, a successful linear backend report describes the reduced system; the lifted full-system true residual is a separate diagnostic. A propagated inner failure describes the gravity subsystem. Nested gravity solve times overlap the outer reduced solve time, and backend solve time excludes some condensation/lifting work. Use complete iteration and campaign wall times for performance comparisons, not a sum of these overlapping measurements.

Reproducibility and evidence

Branches:

• research/polynomial-positive-newton-20260917
• research/gravity-curvature-correction-20260917
• research/gravity-reduced-newton-20260917
• research/gravity-compact-application-20260917 (equivalent block applications)
• research/gravity-prepared-roundoff-20260917 (prepared-equation consistency)
• research/numerical-strategies-20260917 (combined production integration)

The campaign runner builds a committed clean source revision, copies an immutable executable, and records source, mesh, executable, input-state, and output hashes. Serial execution keeps timing comparisons interpretable. Each new run uses a fresh output directory. Frozen probes preserve accepted buffers and verify restoration; they never certify a final physical model.

First frozen and production observations (4ae2f3f)

The first immutable build is retained in the workspace under diagnostics/numerical_strategies_2026-09-17/frozen_v1, with its source and executable hashes. Its production observations are in models_v1, referencing the same frozen executable.

• n=1, J=0, polynomial policy: six accepted full Newton steps; final normalized residual 1.65157289693e-13. No direction repair. All eight virials pass; maximum 3.73091953522e-7. This reproduces the earlier converged control. It is a solver/virial milestone, not a pointwise continuum-accuracy certificate.
• n=1, J=0.1, captured iteration 2: the base certifies nonnegative; the original full trial is proved negative. Whole-mesh certification takes about 3–4 ms. The sufficient repair fraction is 0.9152726503; repaired trial polynomials certify and prepare, but tested step lengths 1, 0.5, 0.125 all increase the full residual. The linear model predicts its best step near 0.00825, with only about 0.46% residual reduction. This is evidence of an overly conservative coupled direction, not evidence that all feasible descent is impossible.
• Late rotating capture: the accepted polynomial is already proved negative. The policy returns invalid_base and preserves accepted buffers exactly. The first artifact's unvisited repair-report fields incorrectly defaulted to a certificate; the separate certificate file is correct, and commit 5f3eb0b fixes the report defaults to unresolved.
• n=1.5, J=0, frozen shape-curvature capture: base residual 1.78804469158e-4; raw full trial 2.18913190375e-3; curvature-corrected full trial 1.40702031008e-4. Gravity remainder drops from 2.18656200516e-3 to 1.37482284578e-12. Retained coordinates and accepted buffers are unchanged. Correction order measured over the smallest resolved steps is 1.999898.
• Reduced frozen action: Schur action and retained lifted full action differ by 6.71e-19; minimum central-difference relative error is 1.39e-6. The original difference grid has only one point sufficiently above the checker's arithmetic floor, so its trend result is honestly incomplete. The next build uses larger differences without relaxing thresholds.
• Production curvature run: intentionally stopped after six trial rejections at iteration zero, despite converged inner solves. Review identified that the fresh-equation consistency allowance omitted large cancelling gravity contributions. This incomplete run is preserved, including the explicit interruption record; it is not a convergence result.

Final tests and updated production results follow after execution.