MeanField/readme.md

mean_field C++ module

Emily M. Boudreaux

July 15, 2026

Dartmouth College

Funded by the European Research Council: No. 101071505: 4D-STAR

This is a simple module testing the numerical implementation of mean_field eqautions of stellar structure in 3D using Finite Elements.

This module is not intended for scientific use; rather, this will inform latter development of SERiF

Key Goals

• Validation of discritization, truncation, and projection errors in MFEM in the context of pulsation mode identification. More specifically, we aim to confirm that a solution to the mean field equations may be found on a reasonably sized and ordered mesh such that the uncertainties introduced into mode identification by our model are below the order of accuracy of the forthcoming PLATO instrument.
• Further, we aim to validate that, when solved with a polytropic equation of state, a model in this framework can virialize to within one part in 10^6
• 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 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, the branch disposition record, and the report build instructions. Raw results have been preserved and organized under working/. The model slice guide 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.

Building

Unlike the rest of the SERiF ecosystem this project is built with CMake (due to some experimentation with C++ modules, which are not well supported by meson). Note that this project is developed for internal 4D-STAR testing and has not been developed with the intention of being portable. Numerous packages are required to be preinstalled and no testing has been done to confirm if this works over a variety of targets. Broadly one must install

• stroid
• CLI11
• mfem (with MPI, Hypre, and UMFPack)
• libconfig
• cmake
• a recent version of clang or gcc which supports modules (note the default clang on mac will not work, you must use homebrew clang)
• ninja
• cmake

Once those dependencies are installed, a fresh build on the development Mac uses:

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.