MeanField/reports/branch_consolidation.md

Completed branch consolidation — 20 September 2026

The complete local delivery is identified by research-handoff-2026-09-20. main contains the tested descendant of d7acb0d assembled on integration/research-consolidation-20260920. No remote branch was pushed and no research branch or worktree was deleted.

The useful changes from the hypothesis branches were already largely combined in the cumulative research history, often through cherry-picks. Consolidation verified their final contents instead of forcing every historical tip into the ancestry or reintroducing old driver versions.

• Retained the optimized baseline, safeguards, optional central constraint, typed numerical policies, gravity-Schur refinement, cached cross actions, native all-m harmonic surface, density-order controls, checked restarts, physical diagnostics, model slices, tests and experiment recipes.
• Preserved the existing user quadrature formatting edit in 6950dc6.
• Imported the missing log-density assessment and standalone reference script through b1fe359. They remain deferred research; density is still an independent Q2 field and no log-density runtime or new positivity policy was enabled.
• Kept Q3 displacement. The failed Q4 change remains isolated; its findings are included in the report.
• Archived the unsuccessful one-way material-to-gravity recipe under archive/one_way_gravity_completion/; its old driver/default change was not adopted. Experimental corrections/coarse solvers remain explicit options.
• Preserved existing library defaults. All-m L4/restart160 are explicit sandbox choices; stellar LDU plus gravity-Schur is a measured research candidate.

The report's consolidation-validation section and validation/ records give this delivery's actual checks. The exact original audit is preserved in archive/branch_audit_initial.md. The table and source audit below describe the pre-consolidation d7acb0d comparison; in particular, old main=75cc638 and the then-missing log assessment are historical states, not the completed result.

---

MeanField branch consolidation audit — 20 September 2026

This is a read-only source/history audit. No source files, branch references, worktrees or artifacts were changed by the auditor; this document is its only output. No numerical test was run. Conclusions refer to integration commit d7acb0d399aac5ac4c36d834a954c1c959042b81 unless a different revision is named.

Recommendation

Use research/coupled-convergence-study-20260919 (d7acb0d) as the integration base and advance main to a tested consolidation descendant. It is a descendant of current main (75cc638) and contains all successful cumulative implementation work, all current experiment infrastructure, and most unsuccessful-study records. It already incorporates most topic branches by cherry-pick or equivalent integration; blindly merging every branch would reintroduce obsolete driver versions or failed defaults and create unnecessary conflicts.

Preserve historical branches. Record their disposition in the consolidated report. A branch need not become an ancestor of main to have its useful contents incorporated; the patch/content mapping below supplies that provenance. Do not use an ours merge to falsely suggest discarded behavior was adopted.

Two divergent topics merit explicit treatment:

1. Log-density assessment: import the two final files from research/log-density-assessment-20260919 (90580b2) as deferred research documentation/reference: experiments/LOG_DENSITY_ASSESSMENT_2026-09-19.md and experiments/log_density_reference_model.py. The six unique commits change only these files. There is no FEM log-density implementation to merge, and adding the historical assessment does not enable positivity enforcement or contradict the current decision to defer it.
2. One-way material-to-gravity completion: preserve the final README, recipe and case manifest from research/gravity-coupling-20260916 (db0ddd3) in a clearly historical/archived experiment location, or retain the branch with a report link and extracted evidence. Do not transplant its old driver or make its prescription the default. This was a measured counterexample, not the later successful two-way LDU policy.

The failed Q4 displacement implementation remains isolated on research/shape-field-displacement-q4-20260918; its final report and comparison scripts are already present in the integration branch with Q3 restored. There is no scientific reason to activate Q4 during consolidation.

Main checkout preservation

At audit start, /Users/tboudreaux/Programming/4DSTAR/MeanField was on research/numerical-strategies-20260917 at 10adf7e, not on main. The only tracked local edit was formatting in libmeanfield/interface/quadrature/mfem.cppm: method declaration wrapping, no signature/semantic change. Preserve it explicitly by backup/commit or an exactly reapplied patch; it is the user's work. Numerous untracked result folders, CSVs, archives, build trees, .cex, .codex, scripts and optimization report files were also present. This audit does not classify those as deletable.

main, origin/main and local/main all pointed to 75cc638 at audit start. Do not push remote main without further authorization; local integration is the requested action. No AGENTS.md exists in the programming checkout or its checked ancestors. The project mirror's AGENTS.md says every file under sources/ is read-only; do not relocate or change synced sources.

Branch-by-branch disposition

“Ancestor” means reachable from d7acb0d. “Patch-equivalent” means all topic commits reported by git cherry d7acb0d <topic> have equivalent patches in the integration history. “Semantically integrated” covers build-registration and combined cherry-picks whose exact patch IDs differ but final source was inspected. This is more discriminating than treating every plus-sign from git cherry as missing code.

Branch	Tip	Status and action
integration/research-consolidation-20260920	b1fe359	New consolidation descendant, created during this audit: adds preserved user formatting (6950dc6) and six log-assessment documentation/reference commits (549b1a7 through b1fe359) after d7acb0d. These were not represented in the base snapshot.
main	75cc638	Ancestor; already represented. No additional merge.
research/baseline-20260916	80cc3d8	Ancestor; already represented. No additional merge.
research/central-constraint-20260916	2e19c2c	All 4 unique topic commits patch-equivalent; already represented. No additional merge.
research/combined-20260916	95d9fba	Ancestor; already represented. No additional merge.
research/coupled-convergence-study-20260919	d7acb0d	Ancestor; already represented. No additional merge.
research/coupled-shape-coarse-20260918	4a6c1b5	Semantically integrated: two equivalent commits; isolated test-registration 4a6c1b5 is already in CMakeLists. Keep diagnostic-only coarse experiment; no additional merge.
research/coupled-trial-correction-20260918	46249d0	Ancestor; already represented. No additional merge.
research/damped-coupled-trial-20260918	db854c0	Ancestor; already represented. No additional merge.
research/density-order-study-20260919	ef76e0c	Ancestor; already represented. No additional merge.
research/diagnostic-campaign-20260917	7a07cae	Ancestor; already represented. No additional merge.
research/experiment-harness-20260916	899cb18	All 1 unique topic commits patch-equivalent; already represented. No additional merge.
research/gravity-compact-application-20260917	ff1b889	Semantically integrated: seven equivalent patches; e599900 and 2c64a92 module/test registration already present. No additional merge.
research/gravity-consistent-schur-20260918	c10d019	All 2 unique topic commits patch-equivalent; already represented. No additional merge.
research/gravity-coupling-20260916	db0ddd3	Not integrated: failed one-way completion. Archive README/recipe/manifest and retain branch. Do not adopt old driver or policy.
research/gravity-coupling-ablation-20260919	38c7184	Ancestor; already represented. No additional merge.
research/gravity-curvature-correction-20260917	3762c74	Semantically integrated: four equivalent patches; e599900 registration already present. Keep opt-in; no additional merge.
research/gravity-direction-diagnostics-20260917	47775a9	All 1 unique topic commits patch-equivalent; already represented. No additional merge.
research/gravity-prepared-roundoff-20260917	782827c	All 1 unique topic commits patch-equivalent; already represented. No additional merge.
research/gravity-reduced-newton-20260917	d25d141	Semantically integrated: seven equivalent patches; 5952691 registration already present. Keep opt-in; no additional merge.
research/gravity-trial-diagnostics-20260917	7f4b068	All 2 unique topic commits patch-equivalent; already represented. No additional merge.
research/krylov-20260916	7127383	All 4 unique topic commits patch-equivalent; already represented. No additional merge.
research/krylov-window-20260916	1f9184b	Semantically integrated: documentation identical, sandbox restart is 160. 937d2f2 was integrated alongside other sandbox changes; no additional merge.
research/linear-coupling-study-20260919	0e6688f	Semantically integrated: core wrapper/tests identical; one patch equivalent and 1d95602 integrated as 2398118 with adjusted surrounding driver/build context. Frozen experiment only.
research/log-density-assessment-20260919	90580b2	Not integrated: six documentation/reference-only commits. Import final assessment and reference script as deferred research; no positivity/runtime change.
research/model-slices-20260919	5da3f42	Semantically integrated: seven equivalent patches; 966a4d4 integrated as 9bac57a. Slice implementation/plotter content identical. No additional merge.
research/n3-compatible-family-20260919	1d746b0	Ancestor; already represented. No additional merge.
research/n3-linear-ablation-20260919	e78af98	Ancestor; already represented. No additional merge.
research/n3-live-field-feedback-20260919	1ed03f5	Ancestor; already represented. No additional merge.
research/negative-density-diagnosis-20260919	7ed4d23	Ancestor; already represented. No additional merge.
research/nonlinear-step-obstruction-20260918	2944dd5	Ancestor; already represented. No additional merge.
research/numerical-strategies-20260917	10adf7e	Ancestor; already represented. No additional merge.
research/polynomial-endpoint-certification-20260917	cc6f4b0	All 1 unique topic commits patch-equivalent; already represented. No additional merge.
research/polynomial-positive-newton-20260917	9aefb36	Semantically integrated: eight equivalent patches; a773c9a registration already present. Available explicit strategy only, not a default; do not enable.
research/preconditioner-benchmarks-20260918	dc1da62	Ancestor; already represented. No additional merge.
research/preconditioner-cached-cross-actions-20260918	07769e7	All 1 unique topic commits patch-equivalent; already represented. No additional merge.
research/pressure-obstruction-20260917	c6572d3	All 3 unique topic commits patch-equivalent; already represented. No additional merge.
research/reduced-smooth-surface-20260918	2171b8b	Ancestor; already represented. No additional merge.
research/shape-curvature-20260917	b24e6e0	All 1 unique topic commits patch-equivalent; already represented. No additional merge.
research/shape-field-displacement-q4-20260918	785a7ae	Implementation intentionally excluded: retain Q3. Final report/comparison scripts already identical in integration, preserving negative result.
research/shape-field-weak-response-20260918	6ceda61	Ancestor; already represented. No additional merge.
research/spherical-harmonic-surface-20260919	1148c09	Ancestor; already represented. No additional merge.

Verified false-positive unmerged commits

The following unique patch IDs do not indicate missing capabilities:

• 4a6c1b5: tests/solver/plateau_coupled_coarse.cpp is already registered at CMakeLists line 391.
• e599900, 2c64a92, 5952691, a773c9a: gravity subsystem/reduction, compact gravity, polynomial admissibility modules and tests are already in CMakeLists and the exported mean_field module. Reapplying isolated registration commits would only duplicate source entries or conflict.
• 937d2f2: sandbox explicitly uses FGMRES restart 160. The final Krylov-window report is byte-identical to the topic branch.
• 1d95602: plateau_surface_border_schur.hpp and its regression tests are byte-identical to the final topic branch. Integration commits 2398118 and 522a2cf carry the implementation and followup test changes.
• 966a4d4: physical-plane slice headers and current plotter are byte-identical to the final topic branch. Integration starts at 9bac57a, with final label changes at 07799bc and 2c6523b.
• Q4 topic 785a7ae: SHAPE_FIELD_WEAK_RESPONSE_2026-09-18.md, compare_shape_order_runs.py and plot_shape_surface_comparison.py are already byte-identical to the topic tip. The source-order change from 4be1a23 is deliberately absent.

What is active versus selectable at d7acb0d

It is essential that the consolidated report distinguish library defaults, example configuration, diagnostic-driver defaults, and recommended research candidates.

Layer	Current behavior	Consolidation recommendation
Independent physical fields	Density remains independent DG Q2; enthalpy independent H1 Q3; displacement H1 Q3; gravity RT2/Q2; reference geometry Q4	Retain. Do not import the Q4 trial or log-density runtime.
Density approximation configuration	MEAN_FIELD_DENSITY_POLYNOMIAL_ORDER=2 compile-time CMake/registry option independent of other fields; uniform increment remains available	Retain configurable order and corrected closure quadrature. Default stays Q2.
Surface factory default	Two-argument makeStellarDiscretization remains NodalRadialSurface, with power-law radial interior and fixed-infinity radial vacuum extensions	Preserve compatibility; avoid silently changing all clients.
Sandbox preferred surface	Explicit SphericalHarmonicSurface maximum degree 4, all real m, 25 coefficients, coupled with all fields	Retain explicit preferred candidate; nodal remains selectable.
Harmonic surface limit	Single MPI rank; sampled basis rank and trace contracts checked. H1 nodal surface surrogate explicitly rejects harmonic coordinates	Report this limitation; do not imply general distributed harmonic support.
Normalization	Existing PhysicalRieszDiagonal in sandbox; harmonic reference trace metric adds correct primal/dual coefficient scaling	Retain. This is coordinate scaling, not an exact surface response inverse.
Sandbox physical model	n=1, J=0, fixed total mass/angular momentum; central density is Lane–Emden seed data only	Retain. Central constraint remains explicitly specifiable for n=3 studies, not a hidden universal constraint.
Library FGMRES option default	FGMRESOptions.restartLength=50	Unchanged by research. Do not claim it is 160 globally.
Sandbox FGMRES configuration	Restart 160; Newton maximum 30; relative nonlinear target 1e-8, linear target .03/cap 200	Retain known baseline.
Diagnostic no-argument controls	Nodal surface, restart 40, independent preconditioner, baseline strategy; runs require output. Campaign manifests explicitly select harmonic/restart160 variants	Keep manifests authoritative; do not confuse convenient CLI defaults with the latest experimental configuration.
Warm-start guard	Reused linear correction is reset if its fresh full-J true residual is nonfinite or worse than the cold RHS norm	Retain correctness/performance safeguard; endpoint true-residual check remains authoritative.
makePreconditioner()	Default stellar structure: independent material/surface and gravity inverse, with generated scalar-border completion	Preserve default until matched full convergence evidence warrants promotion.
Default material inverse	SurfaceThenMaterialTriangular with diagonal density/enthalpy/surface solves; exact prepared h-to-density EOS cross derivative and surface-to-material actions included	Retain. Do not describe it as missing h-to-density coupling.
Default gravity inverse	GravityApproximateLDU; matrix-free Chebyshev order5/powerIterations20 mass inverse, three fixed AMG cycles	Preserve base comparator; refined consistent Schur remains available.
Consistent gravity Schur	Typed GravityConsistentSchurLDU, fixed number of sweeps; library policy defaults 1 sweep/relaxation1, diagnostic default relaxation .5	Retain useful optional implementation and measured manifests; do not conflate the option defaults.
Live experimental recipes	gravity-schur, stellar-ldu, stellar-ldu-gravity-schur live in experiments owning recipe layer	Retain. LDU+gravity is currently best live candidate for the tested compatible rotating n3/gravity-curvature configuration, not established universal default.
Newton numerical defaults	SampledEnthalpy, MonolithicGravity, UncorrectedTrial	Preserve. No added positivity forcing or auxiliary corrections execute by default.
Optional Newton paths	Polynomial enthalpy certificate/repair, gravity-curvature, reduced gravity, fully coupled and damped second-order corrections	Preserve explicit selection and tests as experimental tools; no general convergence claim.
Coarse surface/scalar Schur	Experiment-only frozen wrapper; reconstruct after changed Jacobian	Retain diagnostic infrastructure. Do not promote; lower iteration counts did not generally justify setup/application expense.
Restart initializer	Explicit diagnostic API validates state/layout/coordinate provenance, prepares/refreshes transactionally, clears warm starts, rolls back failures	Retain. Unconverged snapshots require explicit experimental override.
Model slices	Optional experiment export/plot of actual mapped stellar domain; xz/xy/yz/offset options; signed fields retained	Retain. Display approximation/refinement is distinct from FEM convergence or physical validation.

Source anchors: sandbox.cpp; libmeanfield/interface/equilibrium/stellar_discretization.cppm; libmeanfield/interface/field/field_registry.cppm; libmeanfield/interface/normalization/stellar_equilibrium.cppm; libmeanfield/interface/preconditioning/{stellar_recipe,stellar_structure,material_surface,gravity_field}.cppm; libmeanfield/interface/solver/{linear_backend,newton_numerics,stellar_context}.cppm; experiments/plateau_diagnostic.cpp; experiments/plateau_newton_preconditioner.hpp.

Why the failed one-way branch stays historical

db0ddd3 documents a same-state n3,J0 cold-seed control with original material/gravity subcomponents unchanged, only MaterialThenGravityTriangular replacing independence. At restart160/cap200/target .03, true defect improves .0402590 to .0381781 but both fail; solve cost rises 98.915 to117.712s (19%). At restart40, defect worsens .0563080 to .0715826. Direction norm doubles .757644 to1.540825; sampled admissible step tightens .152435 to .0913461. This is not an improvement sufficient for default promotion. It does not rule out the later two-way LDU with better gravity inverse.

The branch's shared harness commit ad86e2e includes some source changes also represented later in the main cumulative harness; it is not all useful missing code simply because patch-id differs. Importing its old plateau_diagnostic.cpp would erase subsequent functionality.

Useful cumulative integration already present

• Baseline 80cc3d8 snapshots the user's optimized prepared-operator/reference-table/mapping/normalization path and diagnostics that were not in old main. The main-to-d7 diff includes this earlier user performance work; do not attribute every changed file to the subsequent AI-led numerical experiments.
• Optional central-density example cleanup, restart160 example choice and safeguarded warm starts are cumulative by 95d9fba.
• Pressure/shape diagnostic instrumentation and typed Newton numerical strategies are integrated by 10adf7e; prepared gravity arithmetic and compact application fixes are included.
• Consistent Schur, prepared cross-action reuse and honest full-cost frozen benchmarking are integrated by dc1da62.
• Coupled/damped trial tools and their bounded negative/conditional results are integrated by db854c0.
• Q3-restored weak-response/Q4 comparison report, reduced surface experiments and native all-m harmonic surface are integrated by 1148c09.
• Negative-density localization, independent density-order configuration, closure quadrature repair and audited order studies are integrated by ef76e0c.
• Checked restart, frozen coupled coarse trials, physically compatible n3 controls, slices and final convergence/cost/virial evidence are integrated by d7acb0d.

Consolidation and validation risks

1. Do not promote experimental settings merely because they enter main. Main can contain tested optional research modules. The final report must explicitly state which settings are defaults, preferred research candidates and failed historical alternatives.
2. Preserve source provenance. Campaign numerical executables were copied from specific producer commits. Main integration changes do not retroactively change the meaning of old runs. Keep original commands, metadata, hashes and branch tips, and include relocation manifests when moving results.
3. Preserve old paths carefully. Many tracked research reports and JSON manifests refer to evidence under workspace diagnostics/ using worktree-relative or absolute paths. Relocation requires either stable links or a documented path mapping and adjusted browse links. Do not rewrite original run metadata/hashes simply to make them look current.
4. Untracked build trees have absolute cache paths. Moving them may invalidate rebuilds. Preserve them as historical artifacts or use explicit compatible links; configure a fresh consolidation build instead of treating a moved cache as portable.
5. Do not rerun a full campaign unnecessarily. A source-equivalent integration needs targeted build/smoke/regression checks around added files and resolved conflicts, not new scientific claims. The previous 24-case audit is a provenance check, not proof that every model converged.
6. Harmonic support is serial. A two-rank rejection test is not MPI solver validation. Report this accurately.
7. No end-to-end target claim. The latest compatible rotating n3 LDU endpoint remains unconverged; energy/h virial1.81141e-5 and both rho-pressure virials fail1e-5. No 50%-critical calibration exists. Lower finite-budget residuals are not measured mathematical floors.
8. Documentation import is not new policy. The log-density reference model is historical isolated analysis. Keep its label explicit and do not present it as an implemented solver option.

Audit limits

This audit checks ancestry, patch equivalence, source content, defaults and recorded evidence. It does not constitute a new exhaustive correctness review of all 57k lines added since old main, nor a numerical rerun. Exact source comparisons established the particular equivalences above; registration line numbers refer to d7acb0d and can shift during consolidation. The parent integrator should record the final consolidation SHA, any actual conflicts/resolutions, validation results, and the eventual status of the preserved user formatting edit.

Consolidation update

After the base-snapshot audit, the integrator preserved the user formatting change as 6950dc6 and imported all six log-density documentation/reference commits, ending at b1fe359 on integration/research-consolidation-20260920. Consequently the earlier base-snapshot recommendation to import the log assessment is fulfilled. No numerical behavior was added by those seven commits. The original branch table entries otherwise describe their relationship to d7acb0d, not their eventual status after consolidation.