# Velocity Sets and Unit System

## Velocity set

Scalar transport in nassu uses the **D3Q7** velocity set {footcite:t}`yoshida2010multiple`: a rest node plus six face-centred velocities.
This is the minimal three-dimensional velocity set that recovers isotropic diffusion.
The scalar lattice is independent of the fluid lattice (typically D3Q27); the two share only the spatial grid $(\Delta x, \Delta t)$.

```{figure} /_static/img/theory/scalar_transport/d3q7_vs_d3q27.svg
---
width: 70%
align: center
---
The scalar rides a reduced D3Q7 velocity set (rest plus six face-centred speeds), shown beside the fluid D3Q27. Both share the same grid spacing and time step; D3Q7 is sufficient for isotropic scalar diffusion, while the fluid needs the larger set to recover the stress tensor.
```

The weights are fixed to

| Set  | Velocities                 | $w_0$ | $w_{\pm}$ | $c_{s,\phi}^2$ |
| ---- | -------------------------- | ----- | --------- | -------------- |
| D3Q7 | $(0,0,0)$ + 6 face-centres | $1/4$ | $1/8$     | $1/4$          |

so the scalar speed of sound is $c_{s,\phi}^2 = 1/4$, distinct from the fluid's $c_s^2 = 1/3$.

For two-dimensional scalar transport the **D2Q5** set (a rest node plus four face-centred velocities) is the 2D analogue of D3Q7.

Larger velocity sets (D3Q15, D3Q19, D3Q27) are also accepted by the configuration; the symbolic and CUDA generation pipeline is parameterised by the chosen lattice.

```{admonition} Why D3Q7 and not the fluid's D3Q27
---
class: note
---
The advection-diffusion equation only requires the zeroth and first moments of the distribution to be recovered correctly. D3Q7 carries exactly enough velocities for that, at a fraction of the memory and bandwidth of D3Q27. The fluid needs the larger set to represent the stress tensor for LES; the scalar does not, so it runs on the minimal isotropic lattice.
```

## Equilibrium

The scalar equilibrium is the first-order Hermite expansion

$$g_i^{eq} = w_i\, \phi \left(1 + \frac{c_{i\alpha} u_\alpha}{c_{s,\phi}^2}\right)$$

where $u_\alpha$ is the fluid velocity at the same node.

Truncating at first order leaves an $O(u^2)$ error in the advective term of the recovered ADE that is not Galilean invariant {footcite:t}`Kruger2016-cv`.
For nassu's CWE target (low Mach number, low lattice velocity) this residual is small and the first-order form is used.

Diffusivity is linked to the relaxation time $\tau_g$ by

$$D = c_{s,\phi}^2\!\left(\tau_g - \tfrac{1}{2}\right) = \tfrac{1}{4}\!\left(\tau_g - \tfrac{1}{2}\right).$$

## Unit system

The fluid solver fixes lattice units via $\Delta x = \Delta t = 1$ at each refinement level, with physical scales set by $\Delta x_{\text{phys}}$ (m), $\Delta t_{\text{phys}}$ (s), and $\rho_{\text{ref}}$ ($\mathrm{kg/m^3}$).
Scalar transport adds one further reference value:

- $\phi_{\text{ref}}$ - reference scalar magnitude in physical units (e.g. K for temperature, $\mathrm{kg/m^3}$ for tracer concentration; dimensionless if the user prefers a normalised tracer).

Conversions between physical and lattice units are then

$$\phi_{\text{lat}} = \phi_{\text{phys}} / \phi_{\text{ref}}, \qquad
u_{\text{lat}} = u_{\text{phys}}\,\Delta t_{\text{phys}} / \Delta x_{\text{phys}}$$

$$D_{\text{lat}} = D_{\text{phys}}\,\Delta t_{\text{phys}} / \Delta x_{\text{phys}}^2,
\qquad
S_{\text{lat}} = S_{\text{phys}}\,\Delta t_{\text{phys}} / \phi_{\text{ref}}.$$

The relaxation time follows from the lattice diffusivity:

$$\tau_g = \frac{D_{\text{lat}}}{c_{s,\phi}^2} + \frac{1}{2} = 4\,D_{\text{lat}} + \frac{1}{2}.$$

The dimensionless numbers Reynolds, Peclet, Schmidt, and turbulent Schmidt are identical in lattice and physical units:

$$Re = \frac{u L}{\nu}, \qquad Pe = \frac{u L}{D},
\qquad Sc = \frac{\nu}{D}, \qquad Sc_t \approx 0.7.$$

When the Prandtl or Schmidt number is set through the relaxation times rather than directly, the differing sound speeds of the two lattices must be carried explicitly. The fluid viscosity uses $c_s^2 = 1/3$ and the scalar diffusivity uses $c_{s,\phi}^2 = 1/4$, so

$$\nu = c_s^2\!\left(\tau_f - \tfrac{1}{2}\right), \qquad
D = c_{s,\phi}^2\!\left(\tau_g - \tfrac{1}{2}\right),$$

$$Pr = \frac{\nu}{D} = \frac{4}{3}\,\frac{\tau_f - \tfrac{1}{2}}{\tau_g - \tfrac{1}{2}}
\qquad (\text{and } Sc \text{ likewise}).$$

The $4/3$ factor is the ratio $c_s^2 / c_{s,\phi}^2$.

```{important}
The simpler identity $Pr = (\tau_f - \tfrac{1}{2})/(\tau_g - \tfrac{1}{2})$ holds only when the two lattices share a sound speed. The fluid and scalar lattices do not ($c_s^2 = 1/3$ versus $c_{s,\phi}^2 = 1/4$), so this form omits the $4/3$ factor and sets the wrong diffusivity. Use the full expression above.
```

## Stability limits

The scalar pseudo-Mach number is

$$\mathrm{Ma}_\phi \equiv \frac{|u|}{c_{s,\phi}} = 2\,|u_{\text{lat}}|.$$

Because $c_{s,\phi}$ is smaller than the fluid speed of sound, the first-order equilibrium imposes a tighter velocity bound than the fluid kernel: $\mathrm{Ma}_\phi < 0.1$ requires $|u_{\text{lat}}| < 0.05$.
Configurations that exceed this bound trigger a validation warning when scalar transport is active.

```{admonition} Limits of validity: D3Q7 at high Peclet number
---
class: warning
---
For advection-dominated flows ($Pe = uL/D \gg 1$), D3Q7 lacks diagonal velocities and the scalar field can develop a directional bias aligned with the lattice axes. This is the practical limit of the minimal set; switch the scalar to D3Q27 to remove the anisotropy at higher memory cost.
```

```{footbibliography}
```