In [1]:
from lbmpy.session import *
from lbmpy.stencils import get_stencil

# Demo: Stencils¶

A stencils is a tuple of directions, where each direction is again a tuple with as many entries as there are dimensions. Technically a stencil is only a nested tuple. The stencils submodule already has a predefined set of commonly used stencils. A common notation for stencils in the lattice Boltzmann literature is the DxQy notation, where x is the dimension of the space, and y the number of directions. For example D2Q9 is a two-dimensional stencil with 9 directions:

In [2]:
stencil = get_stencil("D2Q9")
stencil
Out[2]:
$\displaystyle \left( \left( 0, \ 0\right), \ \left( 0, \ 1\right), \ \left( 0, \ -1\right), \ \left( -1, \ 0\right), \ \left( 1, \ 0\right), \ \left( -1, \ 1\right), \ \left( 1, \ 1\right), \ \left( -1, \ -1\right), \ \left( 1, \ -1\right)\right)$
In [3]:
plt.figure(figsize=(3, 3))
ps.stencil.plot(stencil)

In the literature there is no agreement or convention of the direction ordering. Thus the getStencil function takes an optional parameter defining the ordering.

In [4]:
stencil = get_stencil("D2Q9", ordering='counterclockwise')
plt.figure(figsize=(3, 3))
ps.stencil.plot(stencil)

Compare this to the visualization above and note that only the direction order has changed. The LBM method is independent of the stencil ordering, as long as one order is consistently used everywhere.

The visualization routines take an optional data parameter, which has to be a sequence of information to attach to each direction. This info is then shown as labels instead of the direction index.

There are two ways to visualize 3D stencils - either as a 3D plot, or as three 2D plots:

In [5]:
ps.stencil.plot(get_stencil("D3Q19"), data=list(range(19)))
In [6]:
ps.stencil.plot(get_stencil("D3Q19"), slice=True, sliceAxis=2)