MeanField/experiments/README.md

Accuracy experiments

This directory is deliberately separate from tests/. It uses Catch2 only as an MPI-aware runner, selector, configuration host, and failure reporter. A run fails only when the calculation is invalid (for example, non-finite output or a failed linear solve); measured accuracy is written as data, not as a regression tolerance.

experiment_main.cpp registers the experiment Catch2 reporter. It collects rows recorded with record_experiment_result and writes one wide CSV table on MPI rank zero. Each row carries sweep parameters and numerical metrics, so results can be plotted or compared across commits.

The initial budget has three sweeps at fixed mesh and polynomial orders:

1. linear-solver tolerance: 1e-8, 1e-10, 1e-12, 1e-14;
2. production quadrature boost: 0, 4, 8;
3. reference-space decomposition: numerical field/potential error, analytic projection error, and numerical-to-projection gap.

Run only the budget and choose its output path with:

./mean_field_experiments --experiment-output gravity_budget.csv --catch2 "[accuracy]"

Reduced stellar-surface conditioning experiments

stellar_null_space_experiments is a dedicated diagnostic executable rather than an ordinary verification or validation test. It constructs the analytic n = 3 Lane-Emden seed and probes only directions representable by the reduced surface coordinates: uniform radial homology, three translation-like radial dipoles, an axisymmetric oblate quadrupole, and a degree-12 zonal spherical harmonic. Tangential, rotational, stellar-interior-only, and vacuum-only mesh motions are deliberately absent because they are generated coordinates rather than root unknowns.

The experiment prints rank-zero progress messages while it builds the seed, solves its gravity field, and completes each surface-mode case. The reachability probe records the surface-to-volume lift amplification, complete root Jacobian response by block, and centered-difference agreement at zero and half the Keplerian angular speed. Run it with:

mpirun -np 1 ./cmake-build-debug-homebrew/stellar_null_space_experiments \
    --experiment-output reduced_surface_reachability.csv \
    --catch2 "[null_space][surface_modes][reachability]"

The gravity-completed probe solves the linearized mixed gravity subsystem for the gravity-gradient and gravity-potential variations accompanying each reduced surface mode. It then measures the complete reduced root response:

mpirun -np 1 ./cmake-build-debug-homebrew/stellar_null_space_experiments \
    --experiment-output gravity_completed_surface_modes.csv \
    --catch2 "[null_space][surface_modes][gravity_completed]"

The gravity solver prints its convergence summary, while the experiment prints the current mode and completed-case count. This probe prepares each rotation state only once and does not repeat the expensive nonlinear finite-difference calculations from the reachability diagnostic.

The surface-frequency probe injects normalized zonal spherical harmonics over a range of angular degrees. For each degree it lifts the unit surface pattern once, samples the coefficients of det(I + a grad(d)) at the production geometry-inspection points, and locates the positive and negative critical fractional amplitudes without repeatedly rebuilding trial geometries. It also records the minimum determinant at fractional amplitudes 1e-4, 1e-3, and 1e-2:

mpirun -np 1 ./cmake-build-debug-homebrew/stellar_null_space_experiments \
    --experiment-output surface_frequency_limits.csv \
    --catch2 "[surface_modes][frequency_limit]"

The coupled conditioning probe evaluates an extension-aware n = 3 homology direction together with the nonuniform reduced surface modes. Its density and enthalpy tangents include the coordinate-composition terms generated by the non-affine interior extension, and its gravity variation is completed through the discrete mixed subsystem so the fixed-infinity exterior response is consistent. The probe prepares the equilibrium once, reuses one restricted gravity operator and preconditioner, and uses analytic Jacobian actions:

mpirun -np 1 ./cmake-build-release-homebrew/stellar_null_space_experiments \
    --experiment-output coupled_surface_conditioning.csv \
    --catch2 "[null_space][surface_modes][conditioning]"

The CSV reports prescribed and gravity-completed responses by residual block, the response normalized by the completed direction, lift conditioning where applicable, and the convergence of each restricted gravity solve.

The homology mass-cancellation experiment evaluates the signed decomposition

delta M = delta M_density + delta M_geometry

without solving gravity or preparing the complete coupled operator. The two default-build cases provide the registered-order baseline and one uniform spatial refinement:

mpirun -np 1 ./cmake-build-release-homebrew/stellar_null_space_experiments \
    --experiment-output homology_mass_h0_p0.csv \
    --catch2 "[null_space][homology][mass_normalization][p_refinement]"

mpirun -np 1 ./cmake-build-release-homebrew/stellar_null_space_experiments \
    --experiment-output homology_mass_h1_p0.csv \
    --catch2 "[null_space][homology][mass_normalization][h_refinement]"

A reproducible one-level uniform polynomial refinement uses a separate build so all registered field families and their quadrature policies see the same compile-time order increment:

cmake -S . -B cmake-build-release-homebrew-p1 -G Ninja \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_MAKE_PROGRAM=/opt/homebrew/bin/ninja \
    -DCMAKE_C_COMPILER=/opt/homebrew/opt/llvm/bin/clang \
    -DCMAKE_CXX_COMPILER=/opt/homebrew/opt/llvm/bin/clang++ \
    -DUMFPACK_DIR=/opt/homebrew/lib/cmake/UMFPACK \
    -DXAD_DIR=/usr/local/lib/cmake/XAD \
    -Dhypre_DIR=/usr/local/lib/cmake/HYPRE \
    -Dmfem_DIR=/usr/local/lib/cmake/mfem \
    -DBoost_DIR=/opt/homebrew/anaconda3/lib/cmake/Boost-1.82.0 \
    -DMEAN_FIELD_UNIFORM_POLYNOMIAL_ORDER_INCREMENT=1
cmake --build cmake-build-release-homebrew-p1 \
    --target stellar_null_space_experiments -j 8
mpirun -np 1 \
    ./cmake-build-release-homebrew-p1/stellar_null_space_experiments \
    --experiment-output homology_mass_h0_p1.csv \
    --catch2 "[null_space][homology][mass_normalization][p_refinement]"

A whole-Jacobian dense singular-value experiment is intentionally deferred. The checked-in sandbox.smesh is too large for a useful dense SVD, and the current matrix-free root operator does not provide a transpose action needed by a scalable smallest-singular-value method.

The executable needs the same dependencies, generated module mapping, and configuration registration as the existing Catch2 test executable. Add experiment_main.cpp and gravity_accuracy_budget.cpp as a second executable next to that target; do not add them to the ordinary test executable.