Self-gravity (M8)

Self-gravity (#81) solves ${\mathrm{\nabla }}^2\mathrm{\Phi }=4\pi G(\rho -\overline{\rho })$ every Runge–Kutta stage and applies gravity through the cell potential. The design (the P0 comment on #81) uses the spatial discretisation of Mullen et al. (2021), with the 7-point Laplacian $L_h$:

• face gravity: $g_{d,i+1/2}=-({\mathrm{\Phi }}_{i+1}-{\mathrm{\Phi }}_i)/\mathrm{\Delta }{x}_d$;
• cell gravity: the mean of the cell's two faces;
• momentum: $\rho$ times the cell gravity;
• energy: $\frac{1}{2}\sum _d(g_{d,i+1/2}{F}_{d,i+1/2}^{\rho }+g_{d,i-1/2}{F}_{d,i-1/2}^{\rho })$, from the mass fluxes the continuity equation uses.

Summed over the cells, the energy source is $\sum _i{\mathrm{\Phi }}_i(F_{i+1/2}-F_{i-1/2})/\mathrm{\Delta }x$. So $E+\rho \mathrm{\Phi }$ is conserved exactly with a static potential, and $E+\frac{1}{2}\rho \mathrm{\Phi }$ with a self-consistent one: in the semi-discrete form, given a Poisson solve that is linear and symmetric, $\mathrm{\Phi }=4\pi GK\rho$ with $K=K^T$. P4 corrected the first claim, which asked for a round-off residual of the Poisson equation (see models). The scheme is second order.

The phases of #81 and the cases that verify them:

Phase	What it adds	Cases
P1	the potential path ([gravity] potential = linear)	SV-1
P2	the FFT Poisson solver, periodic	SV-2
P3	the coupling, one solve per Runge–Kutta stage ([gravity] self_gravity)	SV-3, SV-4, SV-5
P4	isolated boundaries (poisson_bc = isolated)	SV-6, SV-7, SV-8
P5a	the multigrid Poisson solver on AMR grids	SV-9
P5b	self-gravity on static AMR grids, the seam gravity work in the reflux	SV-10
P5c	the per-stage reflux, self-gravity under runtime AMR	SV-10 (reflux_cadence = stage), SV-11
P6	the regression cases selfgravity-jeans, selfgravity-amr-stage, selfgravity-star	—
#87 P1	Dirichlet faces in the multigrid solver, a DST-I coarsest level	SV-12
#87 P2	isolated boundaries on AMR, the symmetric James step	SV-13
#87 P3	isolated self-gravity on AMR in FLUME: the refusals lifted, a regrid that refines a boundary block fatal	SV-14

The figures are regenerated with make_doc_runs.sh <dir> <group> and make_doc_figures.py --only <figure> (src/tests/flume/verification/):

make_doc_runs.sh group	Executables it needs	make_doc_figures.py --only
selfgravity	exe/adam_flume_cpu, exe/test_poisson_fft (mode test-poisson-fft-gnu)	selfgravity-potential selfgravity-poisson
jeans	exe/adam_flume_cpu_fft (mode flume-cpu-gnu-fft)	selfgravity-jeans
isolated	exe/test_poisson_fft, exe/adam_flume_cpu_fft	selfgravity-isolated selfgravity-star
amr	exe/test_poisson_mg (mode test-poisson-mg-gnu), exe/adam_flume_cpu_fft	selfgravity-amr selfgravity-amr-jeans selfgravity-amr-regrid

Case	ID	What it verifies
Gravity from a cell potential	SV-1	the potential path reproduces the constant-g oracles of M7
The FFT Poisson solver	SV-2	the periodic solver is exact for $L_h$, second order against the continuum
Jeans modes	SV-3 to SV-5	the coupling: dispersion relation, growth rate, symmetry, exact $E+W$ exchange, scaling covariance
The isolated solver	SV-6	zero padding with the lattice Green's function: free-space potential of the mass on the grid
The n = 1 polytrope	SV-7, SV-8, SV-14	a star in equilibrium and a collapsing one under isolated self-gravity, uniform and on AMR
The multigrid solver on AMR grids	SV-9, SV-12, SV-13	the mimetic 2:1 coupling (symmetric and consistent), the FCG solver, Dirichlet faces, isolated boundaries by the symmetric James step
Jeans modes on a static AMR grid	SV-10	the multigrid coupling, the seam gravity work, the per-stage reflux
Self-gravity under runtime AMR	SV-11	the solver and $\mathrm{\Phi }$ follow every regrid; $E+W$ exact between regrids