lbmpy.lattice.Lattice

lbmpy.lattice.Lattice#

class Lattice(name, stencil, grid=None, *, dtype=DynamicType.NUMERIC_TYPE, layout=MemoryLayout.RIGHTMOST, timestep_symbol=None)#

Discrete particle distribution field for the lattice Boltzmann method.

The Lattice class provides an algebraic representation of the discrete particle distribution fields that form the basis of the lattice Boltzmann method. Its structure is defined by its stencil, which prescribes its spatial dimensionality and the velocity set of the LBM discretization scheme. Lattices are created either free-standing, or attached to the cells or vertices of a Patch.

Pre- and Post-Collision Depending on the simulation state, each site of a Lattice can be in one of two states: regular (also pre-collision) or post-collision. In the regular state, populations can be accessed via the f[offsets, ...](i) syntax (see also TensorField). To access post-collision populations, the special syntax f.post[offsets](i) must be used. A site transitions from regular to post-collision when a collision operator writes to f.post (overwriting the pre-collision populations in memory). Complementarily, the LBM streaming operation transitions sites back to the regular state (which becomes the pre-collision state of the next time step). This usually happens via the Advance operator.

Esoteric Twist The Lattice class has in-place streaming via the Esoteric Twist pattern [GS17] baked in. Per site, regular (f(i)) and post-collision (f.post(i)) populations are stored in the same memory according to the rules of EsoTwist. The alternating access scheme is controlled by a timestep counter (Lattice.t), which switches between 0 and 1 at runtime. The switch is performed by the Advance operator, which performs streaming as a zero-cost operation.

property stencil: StandardStencil#

Velocity set of this lattice

property spatial_rank: int#

Dimensionality of the spatial index space

property layout: MemoryLayout#

Memory layout of runtime buffers

property timestep_symbol: TypedSymbol#

Timestep symbol; used to store the current EsoTwist parity.

property t: TypedSymbol#

See Lattice.timestep_symbol.

property name: str#

The lattice’s name

property dtype: PsNumericType | DynamicType#

Lattice data type

property grid: PatchGrid | None#

This lattice’s parent patch grid

get_buffer_spec()#

Return the buffer specification defining the field’s memory properties

Return type:

FieldBufferSpec

get_iteration_limits()#

Return the iteration limits for kernels operating on this field

Return type:

IterationLimits

create_ndarray(array_module, spatial_shape, *, dtype=None, **kwargs)#

Create an array_module.ndarray backing this field, with the given inner_shape.

If this field is defined on a PatchGrid, spatial_shape must reflect the number of nodes on that grid (i.e. number of cells, number of vertices, etc…)

Parameters:

  • array_module (ModuleType) – Reference to the array module (NumPy, CuPy, DPNP)

  • spatial_shape (tuple[int, ...]) – Shape of the field’s spatial index space

  • dtype (type[generic] | dtype | None) – Data type of the field entries; if None, infer from the field type

  • kwargs – Keyword arguments forwarded to the array module’s array creation routine (ususally .zeros()).

view_ndarray(arr)#

Return a view into the inner region of the given ndarray backing this field

Return type:

TypeVar(TArray)

property post: LatticeAccessProxy[LatticeAccessPost]#

Access post-collision populations relative to the current site.

Usage:

#   Access the post-collision population at index `i` at the current site
f.post(i)

#   Access the post-collision population at index `i` at the north-eastern neighbor
f.post[1, 1](i)
property at: LatticeAccessProxy[AbsoluteLatticeAccessPre]#

Access regular populations at an absolute site index.

Usage:

#   Get population `i` at site `(x, y)`
f.at[x, y](i)
property post_at: LatticeAccessProxy[AbsoluteLatticeAccessPost]#

Access post-collision populations at an absolute site index.

Usage:

#   Get population `i` at site `(x, y)`
f.post_at[x, y](i)