Consolidate numerical research and preserve a reproducible handoff

Document the baseline, hypotheses, measured results, failed approaches,
current policy defaults, and remaining rotating n=3 and virial limitations.
Include the authoritative LaTeX report, Pandoc-generated Markdown, compiled
PDF, source provenance, branch decisions, and consolidation validation.

Organize raw results and miscellaneous artifacts under working/ without
deleting them; version the directory guide, relocation hashes, archive
verifier, and report build/conversion checks. Keep build caches at their
original paths and clearly distinguish retained binaries from the validated
research build. Preserve experimental policies without promoting failed
trials to defaults.
This commit is contained in:
2026-09-20 09:10:27 -04:00
parent b1fe359760
commit e7e53ce682
54 changed files with 54425 additions and 6 deletions

View File

@@ -0,0 +1,3 @@
# Historical one-way material-to-gravity completion
Extracted unchanged from `research/gravity-coupling-20260916`, commit `db0ddd3`. These files document a negative experiment. They are excluded from the active build; the old driver and default-policy change were not adopted. The later stellar LDU experiments are different algorithms. The branch is retained for complete reconstruction.

View File

@@ -0,0 +1,17 @@
[
{
"id": "n3_J0_seed_probe160",
"arguments": [
"--index",
"3",
"--angular-momentum",
"0",
"--max-newton",
"0",
"--probes",
"--probe-restart",
"160"
],
"notes": "Fresh matched n3 seed, central homology phase retained. Compare both cold windows and test the restart160 correction without committing trials."
}
]

View File

@@ -0,0 +1,115 @@
# Material–gravity coupling candidate
This branch changes only the plateau experiment's preconditioner prescription.
The numerical baseline is commit `80cc3d83d752bd43b7be23cee3d7be6e67cd985f` with
independent material/surface and gravity subsystems; the matched run below uses
the shared diagnostic harness on top of it. The candidate uses the existing
`MaterialThenGravityTriangular` policy and copies the control's default material
and gravity descriptors verbatim: surface-then-material with its uncalibrated
diagonals, gravity approximate LDU, Chebyshev order 5, and three fixed AMG cycles.
The scalar border is prepared anew around the candidate. Its physical model,
normalization, Jacobian, and Newton acceptance rules are unchanged.
For structure blocks `[A B; C D]`, the candidate computes
```
m = Atilde^-1 b_material
g = Dtilde^-1 (b_gravity - C m)
```
The hypothesis is that completing the material correction's gravitational source
will reduce the Poisson-dominated defect seen on actual frozen Newton right-hand
sides. `C` includes both density and shape contributions, so success would support
their combined completion, not establish a density-only cause. Reverse gravity
feedback into hydrostatic and surface balance remains approximate; the added cross
action can also cost more than it saves.
## Controlled outcome: retain as a counterexample, do not promote
The Release executable compiled successfully with Homebrew Clang 22.1.8. On
16 September 2026 the candidate at
`8c1f823da22eac200de101e0393155b7bfcb90aa` was compared with the independent control
at `9bd4af699650e2a6bbe795c618e6ef3fbcb48e12`. Both used a fresh n=3, J=0 seed,
the central constraint, M=R_reference=G=1, K=0.36393905995216302,
rho_c=12.935114545826922, and:
```sh
plateau_diagnostic --index 3 --angular-momentum 0 --max-newton 0 \
--probes --probe-restart 160 --output /absolute/path/to/new-results
```
Each run performed cold window-40 and window-160 solves, with cap 200 and true
relative target 0.03. Each policy's own window-160 correction was then tested
without committing trials. This was a **frozen probe, not live Newton convergence**.
The seed-only driver exit code was 3; it did not indicate a build failure.
Build settings, mesh, root layout, seed physical measurements, initial residual
block norms, and accepted physical snapshot were identical. Mesh SHA-256 was
`ce11ae99e21e6c3bbfbee402acd2e191c1da0d8261d2227b4203f73f2f337a74`; snapshot SHA-256
was `a620600e2a8c7c5d54b628b7919749db47ef7c90822fa940925ae6cd99a68630`.
| Cold solve | Control true defect / RHS | Candidate true defect / RHS | Control / candidate seconds |
|---|---:|---:|---:|
| Window 40, 200 iterations | 0.0563080093 | 0.0715826233 | 98.873 / 117.956 |
| Window 160, 200 iterations | 0.0402590213 | 0.0381780551 | 98.915 / 117.712 |
Neither candidate solve passed. Window 160 improves the defect only 5.17% for
19.0% more solve time; window 40 worsens it by 27.1%. These are single-run solve
times, excluding setup and nonlinear diagnostics. At window 160, the candidate
reduces the gradient-relation defect substantially, but Poisson remains 87.96%
of its squared defect; hydrostatic and surface defects increase.
The selected correction norm grows from 0.757644 to 1.540825. Its sampled
thermodynamic alpha limit tightens from 0.152435 to 0.0913461, making the
candidate's alpha=0.1 trial inadmissible. The control's alpha=0.1 trial reduces F
from 0.0031005934 to 0.0029951212. The candidate's largest sampled admissible step,
alpha=0.01, gives F=0.0030693165. The sampling does not identify either direction's
optimal step. On admissible segments, the measured Taylor remainder follows
approximately 0.111780 alpha² for the control and 0.267383 alpha² for the
candidate; the larger candidate direction therefore has more finite-step
curvature. This is not evidence of a derivative inconsistency.
The candidate and control R160 corrections have normalized cosine 0.996157.
Their difference has norm 0.788889. For defects `r=Jp+F` on this identical system,
```
J(p_candidate-p_control) = r_candidate-r_control
||J(p_candidate-p_control)|| / ||p_candidate-p_control||
<= (||r_candidate||+||r_control||) / ||p_candidate-p_control||
<= 3.083e-4.
```
This identifies a weak direction in the current normalized coordinates, not a
particular symmetry, a physical error, or the full Jacobian condition number.
The old control R40 direction points nearly opposite to both R160 directions;
its comparison with the candidate gives cosine -0.987233 and a response upper
bound 1.571e-4. These bounds use existing true defects, not additional Jv probes.
No gauge or centering change follows from this evidence alone.
The scalar Schur is unchanged, as expected because this one-way completion adds
only gravity coordinates while the present scalar constraints depend on material.
Completed border columns show mixed density-source response: the central-column
Poisson defect falls from 315020.6 to 65499.5, while the Bernoulli-column defect
grows from 47.3016 to 56.3085. Both columns have q=0 and unchanged rho/h, isolating
density completion in those probes. Improving one column does not establish
improved full-system performance.
No state was advanced. The shared seed's P(h) energy/force virial errors remain
5.32642e-5 and 8.34070e-5, above the 1e-5 milestone. Trial virials and interior
errors were not measured. This result rejects promotion of this particular
one-way composition; it does not rule out two-way coupling, a better gravity
inverse, or a more accurate coupled Schur approximation.
Raw outputs remain outside the repository in the audit workspace under
`diagnostics/numerical_campaign_2026-09-16/{baseline_n3,gravity}/n3_J0_seed_probe160`.
The companion `coupling_comparison.md/.json`, `coupling_baseline_analysis.md`,
and `coupling_direction_comparisons.json` retain detailed analysis.
The existing diagnostic flags and output rules are described in
[the plateau README](plateau_diagnostic_README.md). `metadata.txt` identifies this
candidate as `material_then_gravity_triangular_default_subcomponents`.
The prescription is local to this experiment and uses the existing owning-value
and ADL preparation API. Production defaults and the physics-facing public API
are unchanged. No source-completion probes or additional policy variants are
included in this first candidate.

View File

@@ -0,0 +1,28 @@
#pragma once
// Experiment-only prescription. Include after `import mean_field;`.
#include <concepts>
#include <utility>
namespace experiment::material_gravity_candidate {
namespace pc = mean_field::preconditioning;
inline constexpr char Name[] = "material_then_gravity_triangular_default_subcomponents";
struct Prescription final : pc::StellarPreconditionerPrescriptionTag {};
// ADL binds this owning prescription to a prepared problem. Copy the default
// descriptors so that only the structure coupling policy changes. Preparing a
// new border also rebuilds its cached structure responses and scalar Schur.
template <pc::DefaultStellarPreconditionerAvailableFor Problem>
[[nodiscard]] auto prepareStellarPreconditioner(Prescription, const Problem &problem) {
auto defaults = pc::stellarStructureBlock(problem);
static_assert(std::same_as<typename decltype(defaults)::Factorization, pc::IndependentStellarSubsystems>,
"This experiment expects an independent-subsystems baseline.");
auto structure = pc::stellarStructureBlock(
problem, defaults.materialSurfaceComponent(), defaults.gravityComponent(),
pc::MaterialThenGravityTriangular{});
auto block = pc::specificationBorderBlock(problem, std::move(structure), pc::backend::DenseDirect{});
return pc::prepare(problem, std::move(block));
}
} // namespace experiment::material_gravity_candidate