3. Kernels

3.1. Macro Variables

3.1.1. Formula for Density (array named m0)

The density \(m0[idx]\) is computed as the sum of the distribution function values over all directions (from 0 to \(Q-1\)):

\[m0[idx] = \rho = \sum_{i=0}^{Q-1} s_i\]

Where:

\(s_i = pf(idx, i)\) is the distribution function for lattice direction \(i\).

3.1.2. Formula for Velocity (array of 3D Vector named m1)

The velocity components \(u_x\), \(u_y\), and \(u_z\) are calculated as the weighted sum of the distribution functions and the corresponding lattice velocity components \(e_{x,i}\), \(e_{y,i}\), and \(e_{z,i}\):

\[u_x = \sum_{i=0}^{Q-1} s_i \cdot e_{x,i}, \quad u_y = \sum_{i=0}^{Q-1} s_i \cdot e_{y,i}, \quad u_z = \sum_{i=0}^{Q-1} s_i \cdot e_{z,i}\]

Where:

\(s_i = pf(idx, i)\) is the distribution function for lattice direction \(i\).
\(e_{x,i}, e_{y,i}, e_{z,i}\) are the components of the lattice velocities for direction \(i\).

After computing the velocity components, they are normalized by the density \(\rho\) (if \(\rho \neq 0\)):

\[u_x = \frac{u_x}{\rho}, \quad u_y = \frac{u_y}{\rho}, \quad u_z = \frac{u_z}{\rho}\]

Finally, the velocity vector \(m1[idx]\) is stored as:

\[m1[idx] = \text{Vec3d}(u_x, u_y, u_z)\]

Where Vec3d represents the 3D velocity vector.

Operator name: macro_variables
Description: A functor for computing macroscopic variables (densities and flux) for lattice Boltzmann method.
Parameters: No parameters but you need to define lbm_parameters.

YAML example:

- macro_variables

3.2. Collision BGK

Operator name: bgk
Description: This operator implements the Bhatnagar-Gross-Krook (BGK) collision model for the Lattice Boltzmann Method (LBM). This model assumes a single relaxation time approach to approximate the collision process, driving the distribution functions toward equilibrium.
Parameters: No parameters but you need to define lbm_parameters.
Formula:

\[f_i(\mathbf{x} + \mathbf{e}_i, t + 1) = f_i(\mathbf{x}, t) - \frac{1}{\tau} \left( f_i(\mathbf{x}, t) - f_i^{\text{eq}}(\mathbf{x}, t) \right)\]

With:

\(f_i(\mathbf{x}, t)\) is the distribution function in the i-th direction at position x and time t,
\(f_i^{\text{eq}}(\mathbf{x}, t)\) is the equilibrium distribution function for the i-th direction at position x and time t,
\(\tau\) is the relaxation time parameter (LBMParameters).

YAML example:

- bgk

3.3. Collision MRT

Operator name: mrt
Description: This operator implements the Multiple-Relaxation-Time (MRT) collision model for the Lattice Boltzmann Method (LBM). This model assumes multiple relaxation times to approximate the collision process, driving the distribution functions toward equilibrium.
Parameters: No parameters but you need to define lbm_parameters.

YAML example:

- mrt

3.4. Streaming

The streaming step is divided into two parts (step1 and step2), and synchronization is required between these two steps to correctly update the ghost halos.

Operator name: streaming
Description: TO DO
Parameters:
- asynchrone: The asynchrone option controls the execution style: when true, it allows asynchronous operations with overlapping computation and communication, improving parallel performance. When false, it runs synchronously, ensuring sequential execution of operations and data updates.

YAML example:

- streaming:
   asynchrone: false

Note

asynchrone option is disabled.

3.5. Checkers

Checkers are analysis operators, declared in the checker: block, that inspect the simulation state without modifying it (useful for regression testing or post-processing).

3.5.1. Check Macro Quantities

Operator name: check_macro_quantities
Description: This operator checks macroscopic quantities (sum of densities, minimum and maximum velocity norm) against user-defined bounds, and aborts the simulation if any check fails. It is mainly used for regression testing (CI).
Parameters:
- density: Expected sum of all densities (optional, requires tol).
- tol: Tolerance, relative to density (optional).
- vmin: Minimal velocity norm allowed (default: 0).
- vmax: Maximal velocity norm allowed (optional).

YAML example:

checker:
  - check_macro_quantities:
     density: 1e6
     tol: 1e-6
     vmin: 0
     vmax: 0.1

3.5.2. Plane Velocity Profile

Operator name: plane_velocity_profile
Description: This operator computes, for each plane perpendicular to a chosen dimension (X, Y or Z), the average, minimum and maximum velocity norm over the fluid points of that plane, and dumps the result to a CSV file (columns: position avg min max).
Parameters:
- dimension: The dimension along which the profile is computed: "X", "Y" or "Z".
- dump_file: Name of the CSV file, formatted with the current timestep (default: profile_%010d.csv).
- output_directory: Base output directory for the profile files (default: hippoLBMOutputDir).

YAML example:

checker:
  - plane_velocity_profile:
     dimension: "Z"
     dump_file: "profile_%010d.csv"