Skip to content

Commit cd928ed

Browse files
sbryngelsonsbryngelson
committed
docs: document split-explicit acoustic substepping (low-Mach) integrator
1 parent f004f19 commit cd928ed

1 file changed

Lines changed: 121 additions & 0 deletions

File tree

‎docs/documentation/acousticSubstepping.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
@page acousticSubstepping Split-Explicit Acoustic Substepping (Low-Mach)
2+
3+
# Split-Explicit Acoustic Substepping
4+
5+
This page describes the `acoustic_substepping` time integrator, which relaxes the
6+
acoustic-CFL time-step restriction at low Mach number without introducing any global
7+
(elliptic / pressure-Poisson) solve. For the parameters that activate it, see
8+
@ref case "Case Files".
9+
10+
## Motivation
11+
12+
An explicit compressible solver is limited by the acoustic CFL condition,
13+
14+
\f[ \Delta t \;\lesssim\; \frac{\Delta x}{|u| + c}, \f]
15+
16+
where \f$c\f$ is the sound speed. When \f$c \gg |u|\f$ (low Mach number \f$M = |u|/c \ll 1\f$),
17+
this step is a factor of \f$\sim 1/M\f$ smaller than the time scale on which the flow
18+
itself evolves, \f$\Delta x/|u|\f$. The solver then spends almost all of its work
19+
resolving fast acoustic waves that carry little of the dynamics.
20+
21+
Pressure-projection and implicit-acoustic methods remove this restriction but require a
22+
global elliptic solve for the pressure each step. The associated global reductions and
23+
sparse linear solves scale poorly on GPU clusters. Acoustic substepping keeps the solver
24+
fully explicit, with the same nearest-neighbor halo-exchange communication pattern as the
25+
standard time stepper, and is well suited to GPU/exascale hardware.
26+
27+
The scheme follows the split-explicit approach of atmospheric dynamical cores
28+
(Klemp, Wicker & Skamarock; Wicker & Skamarock, *Mon. Wea. Rev.* 2002), adapted to MFC's
29+
Godunov finite-volume framework after Nazari & Nair, *J. Adv. Model. Earth Syst.* 2017.
30+
31+
## Method
32+
33+
Each SSP-RK3 stage splits the governing equations into a **slow** (advective) part,
34+
advanced once at the large advective step \f$\Delta t \sim \Delta x / |u|\f$, and a
35+
**fast** (acoustic) part subcycled on \f$n_s \approx (|u|+c)/|u|\f$ micro-steps of size
36+
\f$\Delta\tau = \Delta t / n_s\f$:
37+
38+
| Term | Mode | Discretization |
39+
|------|------|----------------|
40+
| Momentum advection \f$\nabla\!\cdot(\rho \mathbf{u}\otimes\mathbf{u})\f$ | slow | WENO + Riemann (contact-speed dissipation) |
41+
| Volume-fraction and viscous/source terms | slow | existing schemes |
42+
| Mass transport \f$\nabla\!\cdot(\alpha_k\rho_k \mathbf{u})\f$ | fast | 2nd-order centered, subcycled |
43+
| Energy transport \f$\nabla\!\cdot((\rho E + p)\mathbf{u})\f$ | fast | 2nd-order centered, subcycled |
44+
| Pressure gradient \f$\nabla p\f$ (momentum) | fast | 2nd-order centered, subcycled |
45+
46+
The expensive WENO + Riemann flux is evaluated once per RK stage and held frozen during
47+
the subcycle, while each acoustic micro-step is a low-order stencil. Because the costly
48+
work runs at the advective rate rather than the acoustic rate, the wall-clock cost drops
49+
by roughly \f$O(1/M)\f$ relative to the standard explicit scheme.
50+
51+
### Slow flux
52+
53+
The slow flux reuses the HLLC Riemann solver with two modifications, both active only
54+
when `acoustic_substepping` is set: the pressure term is removed from the momentum and
55+
energy flux (it is handled by the subcycle), and the numerical dissipation is capped to
56+
the contact wave speed \f$s_\star\f$. The latter is essential: the standard HLLC
57+
dissipation scales with \f$|u| \pm c\f$, which is unstable at the advective time step;
58+
restricting it to \f$s_\star\f$ makes the convective flux \f$|u|\f$-stable. Low-Mach
59+
accuracy of the convective flux is handled by the existing `low_Mach` correction.
60+
61+
### Acoustic substep
62+
63+
The acoustic micro-step (`s_acoustic_substep` in `src/simulation/m_acoustic_substep.fpp`)
64+
performs a forward–backward update: mass and energy transport are advanced first, the
65+
pressure is recomputed from the equation of state, and the momentum is then advanced with
66+
the new pressure gradient. The frozen slow forcing is added as a \f$\Delta\tau\f$-scaled
67+
source at each micro-step. To suppress the acoustic noise that a centered scheme would
68+
otherwise accumulate, a grad–div divergence damping term is applied; its discrete operator
69+
is rank-one and therefore annihilates discretely divergence-free (vortical) modes, damping
70+
only the compressive/acoustic content. The forward sweep computes flux divergences from a
71+
frozen snapshot of the conserved state and applies them afterward, which keeps the scheme
72+
species-mass conservative.
73+
74+
### Time step
75+
76+
`s_compute_dt` sets \f$\Delta t\f$ from the advective CFL (using \f$|u|\f$, not
77+
\f$|u|+c\f$) and computes \f$n_s\f$ from a domain-maximum reduction of
78+
\f$(|u|+c)/|u|\f$. The only global collective is that existing time-step reduction.
79+
80+
## Usage
81+
82+
| Parameter | Type | Description |
83+
|-----------|------|-------------|
84+
| `acoustic_substepping` | Logical | Enable the split-explicit low-Mach integrator |
85+
| `n_acoustic_substeps` | Integer | Fixed substep count; `0` auto-computes it each step (recommended) |
86+
| `acoustic_div_damp` | Real | Dimensionless grad–div damping coefficient (default `0.1`; stable for \f$\lesssim 0.5/\text{num\_dims}\f$) |
87+
88+
The mode requires `model_eqns = 2` (5-equation model), a CFL-based time step
89+
(`cfl_adap_dt` or `cfl_const_dt`), and `time_stepper = 3` (SSP-RK3). These constraints are
90+
enforced at input checking. It is incompatible with bubbles, immersed boundaries,
91+
(hypo/hyper)elasticity, chemistry, and phase change.
92+
93+
```python
94+
"model_eqns": 2,
95+
"time_stepper": 3,
96+
"cfl_adap_dt": "T",
97+
"cfl_target": 0.5,
98+
"acoustic_substepping": "T",
99+
"n_acoustic_substeps": 0,
100+
"acoustic_div_damp": 0.1,
101+
```
102+
103+
Multiple fluids (`num_fluids > 1`) are supported: the subcycle uses the stiffened-gas
104+
mixture equation of state and mixture velocity, and advects the volume fractions on the
105+
slow step. For `num_fluids = 1` the path reduces exactly to the single-fluid expressions.
106+
107+
The mode runs on CPU and on GPU through both OpenACC and OpenMP target offload, using the
108+
backend-agnostic `GPU_*` macros (see @ref gpuParallelization "GPU Parallelization").
109+
110+
## Scope and limitations
111+
112+
- Intended for **smooth** low-Mach flow. The acoustic substep is centered (non-upwinded),
113+
so flows with embedded shocks are out of scope.
114+
- First-order accurate in time (operator splitting); spatial order is unaffected.
115+
- Restricted to `model_eqns = 2`.
116+
117+
## Source files
118+
119+
- `src/simulation/m_acoustic_substep.fpp` — forward–backward subcycle kernel
120+
- `src/simulation/m_time_steppers.fpp` — `s_split_explicit_rk` orchestration and the two-CFL `s_compute_dt`
121+
- `src/simulation/m_riemann_solver_hllc.fpp` — slow-flux variant

0 commit comments

Comments
 (0)