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

@@ -17,7 +17,31 @@ This module is not intended for scientific use; rather, this will inform latter
- We aim to develope numerical instrumentation which will be incorporated into SERiF including, but not limited to, preconditioners, integrators, and operators
- We aim to develope utility infrastructure which will be incorporated into SERiF including, but not limited to, quadrature boost policies, domain mapping, and user experience tools.
# Current Status [as of July 15, 2026]
# Current research status (20 September 2026)
The cumulative numerical investigations have been consolidated into `main`.
The preferred research surface is the coupled degree-four real spherical
harmonic prescription with all azimuthal orders (25 coefficients), explicitly
selected by the sandbox. Density remains independent DG Q2, enthalpy and
displacement remain H1 Q3, and the library's existing default policies remain
available unchanged.
Some low-index, slowly rotating models meet their algebraic and virial targets.
A fully converged moderately rotating n=3 model, validation against ESTER, and
50% of critical rotation have **not** been demonstrated. The current research
virial acceptance target is 1e-5; the earlier 1e-6 statement above is the original
aspiration. Stellar LDU plus gravity-Schur is a promising experimental recipe,
not a promoted universal solver default. Log density and new positivity
enforcement remain deferred.
Start with the [complete research report](reports/MeanField_research_handoff_2026-09-20.md),
the [branch disposition record](reports/branch_consolidation.md), and the
[report build instructions](reports/README.md). Raw results have been preserved
and organized under [working/](working/README.md). The
[model slice guide](experiments/MODEL_SLICES.md) explains physical-plane output
including the deformed stellar surface.
# Historical status (15 July 2026)
- Integrators for all mean field equations have been written. In other code these have been validated as self-consistent and consistent with analytic solutions generated with symbolic algebra tools. These tests will be incorporated into this module
- Gravitational Potential calculations have been rigorously tested for a number of cases including uniform spherical densities, polynomial spherical densities, rational spherical densities, uniform ellipsoidal densities, and rational ellipsoidal densities. These potentials only apply the density profile and the potential at infinity boundary condition
- We have shown that we can reach sufficient self-consistency and accuracy with the gravitational field such that the gravitational field representation will not prevent us achiveing the required virial ratio or mode identification accuracy.
@@ -36,15 +60,25 @@ and no testing has been done to confirm if this works over a variety of targets.
- ninja
- cmake
once those are installed then the following commands will in theory build mean_field
Once those dependencies are installed, a fresh build on the development Mac uses:
```bash
mkdir build
cd build & cmake .. -Gninja && ninja
./build/tests
cmake -S . -B working/builds/release -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_C_COMPILER=/opt/homebrew/opt/llvm/bin/clang \
-DCMAKE_CXX_COMPILER=/opt/homebrew/opt/llvm/bin/clang++
cmake --build working/builds/release --parallel 2 \
--target tests sandbox plateau_diagnostic
OMPI_MCA_btl=self,sm ./working/builds/release/tests --catch2
```
Adjust compiler and dependency locations for another machine. The consolidation
was validated using the isolated research worktree's Release build. Older build
directories in this checkout were preserved, and their binaries may be stale:
rebuild from the current source before using them. Do not transplant a CMake
cache from a different checkout.
should you wish to build this and you run into issues (as you likely will) you are welcome to email Emily Boudreaux (emily.boudreaux@dartmouth.edu); however, maintenance and support of this module
are not guaranteed. If SERiF has been released when you are reading this documentation we encourage you to look for that project on the 4D-STAR webpage (https://4d-star.org) as it inherits any and all scientific merit from this exploratory project.
# Funding
> 4D-STAR is funded by European Research Council (ERC) under the Horizon Europe programme (Synergy Grant agreement No. 101071505: 4D-STAR). Work for this project is funded by the European Union. Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union or the European Research Council.
> 4D-STAR is funded by European Research Council (ERC) under the Horizon Europe programme (Synergy Grant agreement No. 101071505: 4D-STAR). Work for this project is funded by the European Union. Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union or the European Research Council.