(chap_coding_guide)=
# Solver Framework Reference

## 1  Solver

1. **Thermo / species update** – solves energy and species equations
   ↳ updates density `ρ` and conductivity `k`.

2. **Velocity predictor** - momentum equation in Patankar implicit form
   - Assemble momentum coefficients
   - Solve for provisional velocity **v\***.

3. **Pressure correction**
   - Build RHS from mass-flux imbalance
   - Solve Poisson system for pressure correction *p′*
   - Correct velocity & pressure:
     ```{math}
     \vec{v} \leftarrow \vec{v}^* - d_f \nabla p', \qquad p \leftarrow p + \alpha_p p'
     ```

4. **Sparse matrix assembly & linear solve** – update all coupled fields.

---

## 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)                                        |

---

(math_code_map)=
## 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\) | `faceDensity*volFlux`, `rho_f*volFlux` | 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.

---

## 3  Momentum block (velocity predictor)

```{glossary}
`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.
```

### Key rule snippet

```c++
$vStar_D = vMainCoefficient / vStar_RelaxationFactor$
```

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

---

## 4  Pressure‑correction block

1. 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     |

2. The *face* coefficient `pPrimeCoefficient` is the Rhie–Chow term $d_f$. Every other pressure variable is assembled *from* this face value.

```{glossary}
`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'$.
```

### Matrix assembly snapshot

Equation per cell $P$:

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

```{code-block} text
// 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
```

```text
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.

### RHS build logic

1. Add temporal $Δ(\rho V)/Δt$ (`BDF`/`BDF2` blocks).
2. Subtract net mass flux (`tempMassFlux`, `faceMassFlux`).
3. 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'
$$

---

## 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`                     |

---


## 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}
$$

$$
\\nabla \\cdot \\left( \\frac{\\rho \\alpha_v}{a_P} \\nabla p' \\right) = \\nabla \\cdot \\left( \\rho \\vec{v}^* \\right)
$$