MeanField/experiments/SPHERICAL_HARMONIC_SURFACE_2026-09-19.md

Native spherical harmonic surface candidate

Branch: research/spherical-harmonic-surface-20260919. Parent: 2171b8b76ad78856323fdbcf3d2c537d9039201f.

The preferred research candidate is degree 4 with all real azimuthal orders: 25 independent surface coefficients. This is a discretization choice, not a change to the physical model. The coefficients and interior fields belong to the same Newton system, including their full cross derivatives. The existing nodal radial prescription remains selectable for comparisons. The immediate physical target is rotation through 50% critical; this integration does not establish that target or choose a converged harmonic cutoff for it.

Coordinates and configuration

For reference boundary nodes with radial directions rhat_i, the scalar radial displacement is

q_i = sum_{l=0..L, |m|<=min(l,M)} a_lm Y_lm(rhat_i).

Omitting M retains every order. The real basis has unit integral of its square over solid angle, includes the Condon–Shortley phase, and uses negative orders for sine and positive orders for cosine. Coefficients have units of length; zero coefficients preserve the reference mesh. The catalog is ordered by increasing degree, then increasing signed order. Degree zero is a genuine one-parameter monopole.

Choice	Independent surface parameters
L=4, all m	25
L=4, maximum absolute m=2	19
L=4, m=0 only	5
L=8, all m	81

No odd-degree or azimuthal modes are silently removed. Restricting to m=0 constrains the shape about the fixed global z axis; it does not impose axisymmetry on the three-dimensional interior fields. The reference center is configurable, but changing the frame is not part of a Newton update.

auto discretization = equilibrium::makeStellarDiscretization(
    std::move(finiteElements),
    normalization::PhysicalRieszDiagonal{dimensions::LengthValue{radius}, G},
    deformation::SphericalHarmonicSurface{
        deformation::SphericalHarmonicSurfaceOptions{.maximumDegree = 4}
    }
);

Set maximumAzimuthalOrder = 0 in the options for the axisymmetric shape comparison. Mode counts and actual sampled independence are checked at compilation onto the mesh. Unresolved modes are rejected, not silently discarded. Prescription/extension compatibility and the coupled operator types remain compile-time constrained; degree, mesh rank and sample dimensions are runtime data.

The sandbox selects this candidate explicitly. Existing two-argument discretization calls retain their nodal behavior. Surface choice lives on the numerical discretization, so the physics-facing EOS, surface-pressure and mass/angular-momentum specification is unchanged.

Mathematical and architectural changes

• SphericalHarmonicSurface satisfies the existing surface-prescription contract and composes with the existing interior and fixed-infinity vacuum extensions. Its cached reference basis has exact forward and transpose actions and a zero derivative of the pullback.
• StellarDiscretizationFor owns typed surface/interior/vacuum prescriptions. The modern equilibrium compiler no longer constructs a hardcoded nodal surface.
• Normalization and the default material/surface inverse assemble a diagonal of the pulled-back reference vector trace mass matrix for modal coordinates. The state/residual Gram factors remain a primal/dual pair. The nodal assembly path is preserved.
• Reference metric assembly checks the FEM identity and an explicit canonical trace-layout capability. The erased bridge supports older volume-only deformation operators without claiming that arbitrary trace layouts can use this metric.
• The calibrated diagonal surface inverse supports the actual ordered parameters. The old nodal H1 surrogate explicitly rejects harmonic coordinates; implementing a projected H1 or a dense small surface Schur block is a later preconditioner experiment.

The mesh geometry and field orders are unchanged: Q4 reference geometry, Q3 displacement. Harmonic nodal samples are interpolated through the existing FE trace. Consequently the resulting surface is not an exact analytic harmonic graph between nodes, and the original reference-mesh interpolation error remains.

This differs deliberately from yesterday's frozen reduced-space diagnostic. That experiment retained a general nodal base q0, area-whitened its radial basis, and used separate normalized QR maps. The native prescription uses fixed raw reference coordinates from the seed onward. Equality of corresponding physical residuals and Jacobians is the validation criterion; identical Krylov trajectories under different diagonal metrics are not expected.

The implementation currently requires one MPI rank, consistent with the existing radial volume extension. Replicated global coefficients are not passed to distributed Newton inner products.

Validation and reproducibility

New tests cover the harmonic catalog and analytic low-order functions, derivative/transpose/pullback identities, genuine sampled alias rejection, equivalence to the same nodal geometry, coupled physical residual/Jacobian equivalence and centered differences with generated rotation, normalization before physical preparation, independent boundary integration of the metric, and default/calibrated inverse recovery. Unsupported metric layouts, a different current FEM and the unsupported H1 combination are rejected explicitly.

The live preset is spherical_harmonic_surface_cases_2026-09-19.json. Native use of the diagnostic driver is explicit:

--surface-prescription harmonics --surface-degree 4

Optionally add --surface-maximum-order 0. Legacy frozen nodal probes are excluded from native mode. Known harmonic snapshot metadata is rejected by legacy loaders; undocumented external snapshots still require the caller to supply compatible coordinates.

Every live case retains q14/q18 virial, EOS, positivity and hydrostatic observations. Additional artifacts contain the exact sampled basis, ordered coefficients, full nodal shape force and its component outside the harmonic span. The excluded force uses the Euclidean nodal-dual norm and is not the solver's normalized residual. Both geometry and force pullback equivalence are checked in the observer.

Evidence directory: ../../diagnostics/spherical_harmonic_surface_2026-09-19 relative to this checkout. Builds, tests, live cases and independent artifact audits run serially. Source reviews can run concurrently.

Implementation validation

• All 10 new harmonic cases passed: 4,273,672 assertions in 174.514 seconds. The large assertion count includes array-element checks; the substantive evidence is the independent analytic, adjoint, coupled finite-difference and nodal-equivalence tests.
• All 64 selected existing regression cases passed: 2,795,921 assertions in 643.882 seconds. These cover nodal/radial/domain deformation, normalization, material/surface preconditioning, modern equilibrium problems and the user API.
• The two-rank invocation exited successfully. It exercised the explicit harmonic rejection paths; tests requiring serial physical preparation were skipped. This does not establish distributed harmonic-solver support.
• The independent artifact auditor passed its valid fixture and rejected six deliberate corruptions (catalog, radial displacement, excluded force, norm, nonfinite data and coefficient count).

Clang initially exhausted its source-location budget when the new interfaces included all of MFEM. Narrowing their includes and moving the non-template metric assembly into an implementation file resolved the test-build failure without changing compiler flags or numerical behavior. The test executable and sandbox have built successfully; live driver/results are recorded below when complete.

A small modal residual or good virial balance alone is not proof of a physically accurate rotating model.