# Theory & Methodology

This page documents, in full, the physics and numerics behind `yhgrcalc`. It is intended
to be self-contained: every coefficient and correlation used in the code is stated, derived
where practical, and referenced. If you only want to *use* the library, the
[Quickstart](quickstart.md) is enough — read on here if you want to understand or defend
the numbers in a report or review.

## 1. The boundary-layer meshing problem

In wall-bounded CFD, the near-wall region contains steep velocity and temperature gradients
inside a thin boundary layer. To resolve (or correctly model) these gradients, meshers grow
a stack of thin, high-aspect-ratio cells off the wall — variously called **inflation
layers**, **prism layers**, or **boundary layers**. Three quantities define such a stack:

1. the **first layer height** $y_H$ (the wall-adjacent cell thickness),
2. the **growth ratio** $r$ (each layer is $r\times$ the previous one), and
3. the **number of layers** $N$ (a user choice), which fixes the **final layer thickness**.

Choosing $y_H$ badly is the classic failure mode: too large and your wall treatment is
invalid; too small (with too few layers) and the growth ratio explodes, producing skewed,
poorly-graded cells. CFDPre computes $y_H$ from a **target $y^+$**, then solves for the
growth ratio that spans the boundary-layer thickness in exactly $N$ layers.

## 2. Wall units and $y^+$

The dimensionless wall distance $y^+$ is defined as

$$
y^+ = \frac{y\, u_\tau}{\nu} = \frac{y\, u_\tau\, \rho}{\mu},
$$

where $y$ is the distance from the wall, $u_\tau$ the **friction velocity**, $\nu=\mu/\rho$
the kinematic viscosity, $\rho$ the density, and $\mu$ the dynamic viscosity. The friction
velocity is built from the **wall shear stress** $\tau_w$:

$$
u_\tau = \sqrt{\frac{\tau_w}{\rho}}.
$$

The target $y^+$ encodes your wall-treatment strategy:

- $y^+ \approx 1$ — **wall-resolved** (low-Reynolds) modelling, integrating to the wall.
- $30 \lesssim y^+ \lesssim 300$ — **wall functions**, placing the first node in the
  logarithmic layer.

CFDPre takes $y^+$ as an input and inverts the definition above to get the wall distance.

## 3. The CFDPre pipeline

For a single call, the computation proceeds in this order:

1. Evaluate fluid properties at the given state (CoolProp).
2. Compute the flow velocity and Reynolds number.
3. Select the skin-friction correlation $c_f$ for the flow type and regime.
4. Form the wall shear stress $\tau_w$ and friction velocity $u_\tau$.
5. Invert $y^+$ to get the first-cell **centroid** height $y_p$.
6. Convert centroid height to **first layer height** $y_H = 2\,y_p$.
7. Determine the **boundary-layer thickness** $\delta_{99}$ to be spanned.
8. Solve the geometric-series equation for the **growth ratio** $r$.
9. Report the **final layer thickness** and run sanity checks.

Each step is detailed below.

## 4. Fluid properties (Step 1)

All thermophysical properties are evaluated at the supplied static temperature and pressure
using CoolProp's `PropsSI` interface:

| Property | Symbol | CoolProp key |
|---|---|---|
| Dynamic viscosity | $\mu$ | `V` |
| Thermal conductivity | $k$ | `L` |
| Specific heat ($c_p$) | $c_p$ | `C` |
| Density | $\rho$ | `D` |

From these, the kinematic viscosity $\nu = \mu/\rho$ and Prandtl number
$Pr = c_p\,\mu/k$ are derived. Using CoolProp means CFDPre works for real fluids across a
wide range of states — not just air at standard conditions.

## 5. Velocity and Reynolds number (Step 2)

**Internal flow.** The volumetric flow rate is $\dot V = \dot m / \rho$, and the bulk
(mean) velocity follows from continuity through a circular cross-section of diameter $D$
(the hydraulic diameter):

$$
V = \frac{\dot V}{\tfrac{\pi}{4} D^2}, \qquad
Re = \frac{V D}{\nu}.
$$

**External flow.** The free-stream velocity $V$ is supplied directly by the user
(`flow_velocity_mpersec`), and the characteristic length $L$ (passed as `hydraulicdia_mm`)
sets the Reynolds number:

$$
Re_L = \frac{V L}{\nu}.
$$

:::{admonition} Why external flow requires an explicit velocity
:class: warning
For external flow there is no flow area, so a mass-flow-based velocity is physically
meaningless. CFDPre therefore **requires** `flow_velocity_mpersec` when
`flow_type="external"` and raises a `ValueError` otherwise.
:::

## 6. Skin-friction coefficient (Step 3)

The skin-friction (Fanning) coefficient $c_f$ relates wall shear to dynamic pressure,

$$
\tau_w = \tfrac{1}{2}\rho V^2 c_f,
$$

so **every** correlation below is expressed in the Fanning convention to stay consistent
with this definition. (The Darcy friction factor $f_D = 4 c_f$ is a common alternative
convention — mixing the two is a frequent source of factor-of-four errors.)

### 6.1 Internal, laminar ($Re < 2300$)

For fully-developed laminar pipe flow the Fanning friction factor is exactly

$$
c_f = \frac{16}{Re}.
$$

This is not merely a correlation — it is exact. Substituting into the wall-shear definition
recovers the Hagen–Poiseuille result:

$$
\tau_w = \tfrac12 \rho V^2 \cdot \frac{16}{Re}
       = \tfrac12 \rho V^2 \cdot \frac{16\,\nu}{V D}
       = \frac{8\,\mu V}{D},
$$

which is the textbook wall shear stress for laminar pipe flow. CFDPre's laminar branch
reproduces this identity to machine precision.

### 6.2 Internal, turbulent ($Re \geq 2300$)

CFDPre uses the **Haaland (1983)** explicit approximation to the Colebrook equation. For a
pipe of absolute roughness $\varepsilon$ and diameter $D$,

$$
\frac{1}{\sqrt{f_D}} = -1.8 \log_{10}\!\left[
\left(\frac{6.9}{Re}\right) + \left(\frac{\varepsilon/D}{3.7}\right)^{1.11}
\right],
\qquad c_f = \frac{f_D}{4}.
$$

Haaland is valid across the **entire** turbulent range and for both smooth and rough
pipes. This is a deliberate improvement over the older Blasius form
$c_f = 0.079\,Re^{-1/4}$, which is only accurate for roughly $4\times10^3 < Re < 10^5$ and
**under-predicts** wall friction at higher Reynolds numbers. The roughness $\varepsilon$ is
exposed as `roughness_mm` and defaults to $0$ (hydraulically smooth), in which case the
roughness term vanishes and Haaland reduces to its smooth-pipe form.

:::{admonition} Transitional regime
:class: note
The band $2300 \lesssim Re \lesssim 4000$ is transitional and not described well by any
single correlation. CFDPre treats $Re \geq 2300$ as turbulent for simplicity; treat results
in this band as approximate.
:::

### 6.3 External, laminar ($Re_L < 5\times10^5$)

Flat-plate (Blasius) laminar boundary layer. CFDPre uses the **local** skin-friction
coefficient evaluated at the characteristic length,

$$
c_f = \frac{0.664}{\sqrt{Re_L}},
$$

which is the appropriate choice for placing the first cell at a representative location on
the surface (as opposed to the plate-averaged value $1.328/\sqrt{Re_L}$).

### 6.4 External, turbulent ($Re_L \geq 5\times10^5$)

Schlichting's empirical local skin-friction correlation for a turbulent flat-plate boundary
layer,

$$
c_f = \big(2\log_{10} Re_L - 0.65\big)^{-2.3},
$$

valid up to $Re_L \approx 10^9$.

## 7. Wall shear and friction velocity (Step 4)

With $c_f$ in hand,

$$
\tau_w = \tfrac12 \rho V^2 c_f, \qquad u_\tau = \sqrt{\tau_w/\rho}.
$$

## 8. First cell centroid height and first layer height (Steps 5–6)

Inverting the $y^+$ definition for the wall distance gives the height of the first cell
**centroid** (the point at which $y^+$ is conventionally evaluated):

$$
y_p = \frac{y^+\,\mu}{u_\tau\,\rho}.
$$

Because the centroid of the wall-adjacent cell sits at roughly its mid-height, the **first
layer height** — the quantity a mesher actually consumes — is twice the centroid distance:

$$
y_H = 2\,y_p.
$$

## 9. Boundary-layer thickness to span (Step 7)

The growth-ratio solve needs a target total thickness $\delta_{99}$ that the $N$ layers must
span.

**Internal flow.** In fully-developed pipe flow the boundary layer fills the duct, so the
natural outer limit is the pipe radius, $\delta_{99} = D/2$. However, meshing prisms all the
way to the centerline is rarely desirable; you typically grow prisms near the wall and
transition to a coarser core. CFDPre therefore lets you choose:

- `bl_thickness_mm` — an explicit total stack thickness (highest priority),
- `bl_thickness_fraction` — a fraction $f\in(0,1]$ of the radius, $\delta_{99} = f\,D/2$,
- otherwise the default $\delta_{99} = D/2$.

**External flow.** The boundary-layer thickness comes from the flat-plate correlation for
the regime:

$$
\delta_{99} =
\begin{cases}
\dfrac{4.91\,L}{\sqrt{Re_L}}, & Re_L < 5\times10^5 \quad\text{(laminar)},\\[2ex]
0.38\,L\,Re_L^{-1/5}, & Re_L \geq 5\times10^5 \quad\text{(turbulent)}.
\end{cases}
$$

An explicit `bl_thickness_mm` overrides this if supplied.

## 10. Growth ratio (Step 8)

The $N$ layer thicknesses form a geometric progression with first term $y_H$ and common
ratio $r$. Their sum must equal the boundary-layer thickness:

$$
y_H \big(1 + r + r^2 + \dots + r^{N-1}\big)
= y_H\,\frac{r^N - 1}{r - 1}
= \delta_{99}.
$$

Introducing the dimensionless ratio $\beta = \delta_{99}/y_H$ and rearranging gives the
polynomial CFDPre actually solves:

$$
r^N - \beta\,r + (\beta - 1) = 0.
$$

This has the trivial root $r=1$ (a uniform stack); the physical solution is the other real
root $r>1$, found with **Newton–Raphson** iteration. The derivative used is

$$
f(r) = r^N - \beta r + (\beta - 1), \qquad
f'(r) = N r^{N-1} - \beta.
$$

A solution requires $\delta_{99} > y_H$ (the stack must be thicker than a single first
layer); if not, CFDPre returns `nan` for the growth ratio and issues a warning (see §12).

## 11. Final layer thickness (Step 9)

The outermost (Nth) layer of the geometric stack is

$$
y_{\text{final}} = y_H\,r^{N-1}.
$$

This is reported as `Final Layer Thickness [m]` and is useful for checking that the prism
stack blends smoothly into the surrounding volume mesh.

## 12. Quality checks and warnings

CFDPre raises `UserWarning`s to flag mesh-quality problems rather than silently returning
questionable numbers:

- **Growth ratio too large.** If $r > 1.3$, a warning is issued. Ratios much above ~1.3
  produce abrupt cell-size jumps and degrade gradient resolution and solver robustness;
  increase `num_layers` or relax the target.
- **Boundary layer too thin to resolve.** If $\delta_{99} \leq y_H$ the geometric solve is
  ill-posed; CFDPre warns and returns `nan` for the growth ratio and final layer thickness.
  This usually means the inputs are inconsistent (e.g. far too few layers for the requested
  $y^+$, or an over-restricted `bl_thickness`).

## 13. Worked example

Using the headline internal-flow case — air at 50 °C and 10 bar, 2.5 kg/s through a 125 mm
duct, $y^+=1$, 8 layers:

| Quantity | Value |
|---|---|
| Density $\rho$ | 10.79 kg/m³ |
| Dynamic viscosity $\mu$ | 1.976 × 10⁻⁵ N·s/m² |
| Bulk velocity $V$ | 18.88 m/s |
| Reynolds number $Re$ | 1.289 × 10⁶ |
| Skin friction $c_f$ (Haaland) | 2.777 × 10⁻³ |
| Wall shear $\tau_w$ | 5.34 Pa |
| First cell centroid $y_p$ | 2.60 × 10⁻⁶ m |
| **First layer height $y_H$** | **5.21 × 10⁻⁶ m** |
| Boundary-layer thickness $\delta_{99}$ ($=D/2$) | 0.0625 m |
| **Growth ratio $r$** | **3.66** (⚠ exceeds 1.3) |
| Final layer thickness | 0.0454 m |

The growth ratio of 3.66 correctly triggers a warning: spanning 5.21 µm to 62.5 mm in only
8 layers is physically very aggressive. Restricting the stack to 30 % of the radius
(`bl_thickness_fraction=0.3`) lowers it to ~3.04; reaching a healthy ratio at this Reynolds
number genuinely needs 20–40+ layers.

## 14. Assumptions and limitations

- **Circular cross-section for internal velocity.** The bulk velocity uses
  $A = \tfrac{\pi}{4}D^2$. For strongly non-circular ducts, the hydraulic diameter
  reproduces the friction behaviour but not the exact flow area, so the derived velocity is
  approximate.
- **Fully-developed, single-phase, Newtonian flow** is assumed throughout.
- **Local correlations** are used for external flow; results represent a single
  representative station at $x = L$, not a plate-averaged value.
- **Transitional Reynolds numbers** (pipe $2300$–$4000$) are treated as turbulent.
- The $y_H = 2 y_p$ relation assumes the first-cell $y^+$ is evaluated at the cell centroid.
  Some meshers/solvers report $y^+$ at the first node or face; adjust if your convention
  differs.

## References

1. F. M. White, *Fluid Mechanics*, McGraw-Hill — laminar pipe flow ($c_f = 16/Re$),
   Hagen–Poiseuille relation.
2. S. E. Haaland (1983), "Simple and Explicit Formulas for the Friction Factor in Turbulent
   Pipe Flow," *Journal of Fluids Engineering*, 105(1), 89–90.
3. H. Schlichting & K. Gersten, *Boundary-Layer Theory*, Springer — flat-plate laminar
   ($0.664/\sqrt{Re}$, $\delta_{99}=4.91x/\sqrt{Re}$) and turbulent
   ($\delta_{99}=0.38x\,Re^{-1/5}$, local $c_f$) correlations.
4. C. F. Colebrook (1939), "Turbulent Flow in Pipes…," *Journal of the ICE* — the implicit
   friction-factor equation Haaland approximates.