Velocity Space Representations (lbmpy.velocityspace)

This module contains mechanisms for defining velocity space discretizations, commonly reffered to as stencils, needed for lattice Boltzmann simulations.

The discrete stencil velocities can take integer/real values yielding on-/off-lattice stencils representations. On uniform grids, velocities of on-lattice stencils terminate on adjacent grid nodes thereby allowing for the traditional streaming operation; in contrast, the off-lattice stencil velocities terminate in between nodes and yield semi-Lagrangian schemes where velocities must first be interpolated onto the grid nodes before streaming. lbmpy allows users to declare if a stencil is OnLattice or OffLattice through the StencilType enum.

Warning

lbmpy currently does not support semi-Lagrangian lattice Boltzmann schemes.

The charcteristics common to all lbmpy stencils are encapsulated in the LBStencilBase class, while all specific realizations extend this base class. lbmpy currently provides the following stencil implementations:

  • Standard Stencils:

    The StandardStencil class extends LBStencilBase to encapsulate characteristics that are common to all standard, first-nearest-neighbour stencils. By extending StandardStencil, lbmpy provides users implementations of the D2Q9 and D3Q27 tensor-product stencils, along with the D3Q7, D3Q15 and D3Q19 prunes of the D3Q27 stencil.

  • Gauss Hermite Quadrature Stencils:

    Similar to StandardStencil, the GaussHermiteQuadratureStencil base class extends LBStencilBase and serves to encapsulate attributes common to stencils whose velocities are roots of Gauss-Hermite quadratures. Currently, lbmpy provides implementations of the 2D StencilType.OnLattice higher-order D2V17 and D2V37 stencils having 7th and 9th order accuracy respectively.

    Warning

    Higher-order stencils warrant additional considerations for boundary representations and the streaming operation. For end-to-end lattice Boltzmann simulations within the lbmpy framework, higher-order stencils can currently only be used on periodic domains. Additionally, the waLBerla backend does not currently support streaming patterns required for using higher-order stencils.

  • User Defined Stencils:

    The CustomStencil class also extends LBStencilBase and allows users to define custom stencils for their applications.

    Note

    Incorrect inputs may yield physically incorrect/inconsistent results without raising errors; users are recommended to carefully verify their CustomStencil inputs.

Instantiation

lbmpy stencils can be instantiated as given below.

  • Using the LBStencil Factory method

    • Pre-defined stencils

      from lbmpy import LBStencil, Stencil

# instantiate the D2Q9 stencil using lbmpy.enums.Stencil
stencil_1 = LBStencil(Stencil.D2Q9)
# instantiate the D2Q9 stencil using an upper-case string identifier
stencil_2 = LBStencil("D2Q9")
# instantiate the D2Q9 stencil using a lower-case string identifier
stencil_3 = LBStencil("d2q9")

assert(stencil_1 == stencil_2) # True
assert(stencil_1 == stencil_3) # True

    • Custom stencils

      from lbmpy import LBStencil
from lbmpy.velocityspace import StencilType

stencil = LBStencil("d2q9")

custom_stencil = LBStencil(
    stencil.stencil_entries,
    theta0=stencil.theta0,
    weights=stencil.weights,
    ordering="custom-ordering",
    stencil_name="custom-d2q9",
    stencil_type=StencilType.OnLattice,
)

  • Direct instantiation

    • Pre-defined stencils

      from lbmpy.velocityspace import D2Q9
stencil = D2Q9()

    • Custom stencils

      from lbmpy import LBStencil
from lbmpy.velocityspace import CustomStencil, StencilType

stencil = LBStencil("d2q9")

custom_stencil = CustomStencil(
    stencil.stencil_entries,
    theta0=stencil.theta0,
    weights=stencil.weights,
    ordering="custom-ordering",
    stencil_name="custom-d2q9",
    stencil_type=StencilType.OnLattice,
)

LBStencil Factory

class LBStencil(stencil: Stencil | str | tuple[tuple[int, ...], ...], *, theta0: Expr | None = None, weights: tuple[Expr, ...] | None = None, ordering: str | None = None, temperature: Expr | None = None, stencil_name: str | None = None, stencil_type: StencilType | None = None)

Factory class for lattice Boltzmann stencil implementations defined in the lbmpy.velocityspace module.

Stencils are represented in the DxQy notation, where d is the dimension (length of the velocity tuples) and y is the number of discrete velocities. For every dimension many different versions of a certain stencil is available. The reason for that is to ensure comparability with the literature. Internally the stencil is represented as a tuple of tuples, where the ordering of the tuples plays no role.

Parameters:

  • stencil – Can be tuple of tuples which represents the stencil, a string like ‘D2Q9’/’d2q9’ or an enum of lbmpy.enums.Stencil

  • theta0 – The lattice reference temperature. This argument must be specified for custom stencils and is not necessary for pre-defined stencils.

  • weights – The lattice weights. This argument must be specified for custom stencils and is not necessary for pre-defined stencils.

  • ordering – The LBM literature does not use a common order of the discrete velocities. Therefore, different common orderings are made available for pre-defined stencils to compare intermediate results with the literature. All orderings lead to the same method, they just have to be used consistently. If not provided, the default “walberla” ordering is used.

  • temperature – Stencil weights and velocities are, in the most general form, functions of temperature. Stencils can, therefore, be provided with a temperature to evaluate these quantities during run time. If not provided, temperature defaults to the lattice reference temperature.

  • stencil_name – The name of the stencil. This argument must be specified for custom stencils and is not necessary for pre-defined stencils.

  • stencil_type – lbmpy.velocityspace.StencilType enum representing the stencil type. This argument must be specified for custom stencils and is not necessary for pre-defined stencils.

StencilType

class StencilType(value)

The StencilType enumeration indicates the type of stencil employed for LB simulations.

OnLattice = 1

On-lattice stencils have velocities terminating on nodes allowing for traditional streaming.

OffLattice = 2

Off-lattice stencils terminate between nodes yielding semi-lagrangian LB schemes in which data needs to be interpolated on to the nodes followed by streaming. Currently semi-lagrangian schemes are not supported.

LBStencilBase

class LBStencilBase(velocities, theta=None, *, weights=None, ordering=None, stencil_name=None, stencil_type=StencilType.OnLattice)

Base Class for lattice Boltzmann stencils.

Parameters:

  • velocities (tuple[tuple[int, ...], ...]) – The ordered velocities associated with the stencil.

  • theta (Optional[Expr]) – Specifies the lattice temperature. For athermal simulations, \(\theta = \theta_0\), i.e., the lattice reference temperature or, equivalently, squared lattice speed of sound (\(c_s^2\)). For isothermal simulations, \(\theta\) is a constant, while for thermal simulations, \(\theta\) is a dynamically varying sympy symbol

  • weights (Optional[tuple[Expr, ...]]) – tuple of sympy expressions that describe the stencil weights for ordered stencil velocities

  • ordering (Optional[str]) – Layout of the stencil velocities. The ordering argument allows for comparisons against published results that employ different layouts for the same stencil.

  • stencil_name (Optional[str]) – Name of the stencil

  • stencil_type (StencilType) – type of stencil, namely, on-lattice or off-lattice. On-lattice stencils have velocities terminating on nodes allowing for traditional streaming, while off-lattice stencils terminate between nodes yielding semi-lagrangian LB schemes. Currently, streaming is possible only for on-lattice stencils.

property D

Stencil dimension.

property num_velocities

Number of stencil velocities.

property theta

Stencil operating temperature.

property theta0

Stencil reference temperature.

property speed_of_sound

Stencil speed of sound.

property stencil_type

Stencil stencil type.

property ordering

Stencil ordering.

property name: str | None

Name of the stencil.

property stencil_entries

Stencil velocity entries.

property weights: tuple[Expr, ...]

Stencil weights.

property inverse_stencil_entries

Inverse Stencil entries.

plot(slice=False, **kwargs)

Create a plot of the stencil.

index(direction)

Index of a stencil velocity in the specified direction.

inverse_index(direction)

Index of stencil velocity entry opposite to the specified direction.

Standard Stencils

class StandardStencil(velocities, ordering, stencil_name, theta)

Base class for first nearest neighbour stencils.

property generating_velocities

Cardinal one-dimensional velocities

property Q

Conventional notation for num_velocities

D2Q9

class D2Q9(ordering='walberla', temperature=None)

Implementation of the D2Q9 standard stencil.

Parameters:

  • ordering (str) – layout of the stencil entries. Currently supported orderings: walberla, counterclockwise, braunschweig, uk, lehmann

  • temperature (Optional[Expr]) – Lattice temperature (default \(\theta_0\) = 1/3)

D3Q27

class D3Q27(ordering='walberla', temperature=None)

Implementation of the D3Q27 standard stencil.

Parameters:

  • ordering (str) – layout of the stencil entries. Currently supported orderings: walberla, premnath, fakhari, lehmann, braunschweig

  • temperature (Optional[Expr]) – Lattice temperature (default \(\theta_0\) = 1/3)

D3Q7

class D3Q7(ordering='walberla', temperature=None)

Implementation of the D3Q7 standard stencil.

Parameters:

  • ordering (str) – layout of the stencil entries. Currently supported orderings: walberla

  • temperature (Optional[Expr]) – Lattice temperature (default \(\theta_0\) = 1/3)

D3Q15

class D3Q15(ordering='walberla', temperature=None)

Implementation of the D3Q19 standard stencil.

Parameters:

  • ordering (str) – layout of the stencil entries. Currently supported orderings: walberla, premnath, lehmann, fakhari

  • theta – Lattice temperature (default theta_0 = 1/3)

D3Q19

class D3Q19(ordering='walberla', temperature=None)

Implementation of the D3Q19 standard stencil.

Parameters:

  • ordering (str) – layout of the stencil entries. Currently supported orderings: walberla, counterclockwise, premnath, lehmann, braunschweig

  • temperature (Optional[Expr]) – Lattice temperature (default \(\theta_0\) = 1/3)

Gauss Hermite Quadrature Stencils

class GaussHermiteQuadratureStencil(velocities, ordering, stencil_name)

Base class for Gauss-Hermite quadrature stencils.

D2V17

class D2V17(ordering='walberla')

Implementation of the D2V17 higher-order stencil.

The velocity vectors of this stencil correspond to a seventh order Gauss-Hermite quadrature

D2V37

class D2V37(ordering='walberla')

Implementation of the D2V37 higher-order stencil.

The velocity vectors of this stencil correspond to a ninth order Gauss-Hermite quadrature

User Defined Stencils

class CustomStencil(velocities, theta0, weights, stencil_name, stencil_type, *, ordering=None, temperature=None)