16. Solver Framework Reference#

16.1. 1 Solver#

Thermo / species update – solves energy and species equations ↳ updates density ρ and conductivity k.
Velocity predictor - momentum equation in Patankar implicit form
- Assemble momentum coefficients
- Solve for provisional velocity v*.
Pressure correction
- Build RHS from mass-flux imbalance
- Solve Poisson system for pressure correction p′
- Correct velocity & pressure:
  
  (16.1.1)#\[\vec{v} \leftarrow \vec{v}^* - d_f \nabla p', \qquad p \leftarrow p + \alpha_p p'\]
Sparse matrix assembly & linear solve – update all coupled fields.

16.2. 2 Mesh & connectivity cheat‑sheet#

Name	Type	Meaning
`pos`	`store<vector3d>`	Cartesian coordinates of grid nodes $\vec{x}_i$
`face2node`	`multiMap`	Ordered nodes defining each face (RH‑rule)
`cl`, `cr`	`Map`	Cell indices left / right of face, so $\hat{\vec{n}}$ points $cl \rightarrow cr$
`upper`, `lower`	`multiMap`	Non‑zero structure of sparse matrix (transpose of `cl`/`cr`)
`geom_cells`	`constraint`	Set of actual physical cells (excludes ghost)

16.3. 2.5 Math-to-Code Naming Map#

The theory guide uses conventional mathematical symbols, while the implementation uses compact store names. The naming is not perfectly one-to-one, but there is enough overlap that a reader can usually use the following rules.

Code pattern	Typical mathematical meaning	Example
`Star`	provisional / predictor / pre-correction state	`vStar` (\leftrightarrow \vec{v}^{*})
`Prime`	correction quantity	`pPrime` (\leftrightarrow p’)
`Corrected`	post-correction field before iteration advance	`vCorrected`
`_D`, `_L`, `_U`, `_B`	diagonal, lower, upper, RHS of an assembled linear system	`pPrime_D`, `pPrime_B`
`MainCoefficient`	central coefficient (a_P)	`vMainCoefficient`

The most common solver-variable correspondences are:

Mathematical meaning	Theory notation	Common code name(s)	Notes
Cell-centered velocity vector	chapter-dependent (\vec{u}), (\vec{v}), or (\vec{V})	`v`	The code uses `v` consistently even when different chapters use different velocity symbols.
Provisional velocity after the momentum predictor	(\vec{v}^{*})	`vStar`	Output of the momentum predictor solve.
Corrected velocity after pressure correction	(\vec{v}^{k+1}), (\vec{v}^{new})	`vCorrected`	Starts from `vStar` and then receives pressure-correction updates.
Pressure correction	(p’)	`pPrime`	Solution of the pressure-correction equation.
Effective pressure correction actually used in updates	(p’)	`pPrime`	Solution of the pressure-correction equation and value used in downstream updates.
SIMPLER preliminary pressure	(\tilde{p}) or the separate pressure-equation unknown	`pStar`, `pStarLimited`	Distinct from `pPrime`; used in the SIMPLER pressure equation path.
Central momentum coefficient	(a_P)	`vMainCoefficient`	Raw diagonal of the discretized momentum equation.
Under-relaxed predictor diagonal	(a_P/\alpha_v)	`vStar_D`	Diagonal used in the `vStar` linear solve.
Pressure-free part of the momentum row	(\mathcal{H}_u)	`H(v)`	Code-level analogue of the non-pressure momentum RHS.
Face pressure-correction coefficient	(d_f) or face correction coefficient	`pPrimeCoefficient`	Face-based pressure-velocity coupling coefficient.
Provisional face volumetric flux	(\dot V_f^{*})	`volFluxStar`	The code stores a volumetric flux here, not a mass flux.
Corrected face volumetric flux	(\dot V_f^{corr})	`volFluxCorrected`	Used after pressure correction in subsequent transport assembly.
Face mass flux	(\dot m_f)	`faceDensityvolFlux`, `rho_fvolFlux`	Usually formed from density times volumetric flux rather than stored as a primary variable.
Velocity under-relaxation	(\alpha_v)	`vStar_RelaxationFactor`	Relaxation used in the velocity predictor.
Pressure-correction relaxation	(\alpha_p)	`pPrime_RelaxationFactor`	Used in the update (p \leftarrow p + \alpha_p p’).
SIMPLER pressure-equation relaxation	pressure-equation relaxation	`pStar_RelaxationFactor`	Separate from `pPrime_RelaxationFactor`.

The important caveat is that the theory guide usually writes mass flux as (\dot m_f), whereas large parts of the code store volumetric flux as volFlux* and only multiply by density when a mass flux is needed.

16.4. 3 Momentum block (velocity predictor)#

vMainCoefficient#: Raw diagonal $a_P$ from discretised momentum equation.
vStar_D#: $a_P/\alpha_v$ – under‑relaxed diagonal used in the velocity predictor solve.
vStar_RelaxationFactor#: Relaxation $\alpha_v\;(0<\alpha\le1)$.
vStar_L, vStar_U#: Off‑diagonal coefficients $a_N$ stored through lower and upper maps.
H(v)#: Source vector $b$ without $a_P v_P$ term.

16.4.1. Key rule snippet#

$vStar_D = vMainCoefficient / vStar_RelaxationFactor$

If a cell is iblanked ($iblank>1$) we force the diagonal to 1 to decouple it.

16.5. 4 Pressure‑correction block#

Anything that ends in _D, _L, _U, _B is part of the sparse matrix $\Matrix{A}_p p' = b_p$:

Suffix

Meaning

_D

diagonal $a_P$

_L

lower neighbour coeff

_U

upper neighbour coeff

_B

RHS / source term
The face coefficient pPrimeCoefficient is the Rhie–Chow term $d_f$. Every other pressure variable is assembled from this face value.

Suffix	Meaning
`_D`	diagonal \(a_P\)
`_L`	lower neighbour coeff
`_U`	upper neighbour coeff
`_B`	RHS / source term

pPrimeCoefficient#: Face factor (d_f = \rho_f,\alpha_v,F/\Delta x) used in Rhie–Chow interpolation. Computed per–face.
pPrime_RelaxationFactor#: Pressure under-relaxation $\alpha_p$.
pStar_RelaxationFactor#: Relaxation used by the separate SIMPLER pressure equation (pStar), not by the main pressure-correction update.
pPrime_D#: Under-relaxed diagonal $a_P^{(p)}/\alpha_p$ for the Poisson matrix.
pPrime_L, pPrime_U#: Lower / upper off-diagonals for sparse matrix $\Matrix{A}_p$. Assembed from pPrimeCoefficient.
pPrime_B#: Right-hand side $b_p$: mass-flux imbalance + relaxation terms.
pPrime#: Pressure correction $p'$. At convergence $p=p+\alpha_p p'$.

16.5.1. Matrix assembly snapshot#

Equation per cell $P$:

\[ a_P^{(p)} p'_P - \sum_N a_{PN}^{(p)} p'_N \,=\, b_P \]

// inside the pPrime_L/pPrime_U rule
pPrime_L =  -pPrimeCoefficient / α_p      # coefficient to right cell
pPrime_U =  -pPrimeCoefficient / α_p      # coefficient to left  cell
pPrime_D +=  pPrimeCoefficient / α_p      # accumulate diagonal

for every face f:
    d_f  = (ρ_f α_v) * (V_L/a_P_L + V_R/a_P_R)/2 * D_f
    pStar_D[L] += d_f/α_p
    pStar_D[R] += d_f/α_p
    pStar_L    = -d_f
    pStar_U    = -d_f

The pStar_* names in this sketch refer to the separate SIMPLER pressure-equation system. The directly corresponding pressure-correction system uses the pPrime_* names listed in the glossary above.

16.5.2. RHS build logic#

Add temporal $Δ(\rho V)/Δt$ (BDF/BDF2 blocks).
Subtract net mass flux (tempMassFlux, faceMassFlux).
Add relaxation $\;(1-α_p)a_Pp$ and convert to delta form.

At solve completion:

\[ \vec{v} \leftarrow \vec{v}^* - d_f \,\nabla p' , \qquad p \leftarrow p + \alpha_p p' \]

16.6. 5 Life‑cycle of the `pPrime` variables#

Stage	Variable	Triggering rule tag
Initialisation (it = 0)	`p_i`	`iteration build`
Assemble RHS	`pPrime_B`	`pPrimeTemp_B → pPrime_B`
Assemble coefficients	`pPrime_D/L/U`	rules containing `pPrimeCoefficient`
Linear solve	`pPrime`	`FSGS / LSGS / HYPRE` (selected via RC)
Out‑of‑loop update	`p_i(it+1)`	`iteration advance`

16.7. 7 Reference equations#

\[ \text{Momentum:}\qquad a_P \vec{v}_P = \sum_N a_N \vec{v}_N + b_v \]

\[ \text{Pressure-correction:}\qquad \Matrix{A}_p \, p' = b_p, \quad \Matrix{A}_p = \begin{bmatrix} pStar_D & pStar_U & \dots \end{bmatrix} \]

\[\begin{split} \\nabla \\cdot \\left( \\frac{\\rho \\alpha_v}{a_P} \\nabla p' \\right) = \\nabla \\cdot \\left( \\rho \\vec{v}^* \\right) \end{split}\]