Equilibrium Distributions (lbmpy.equilibrium)¶
This module contains various classes encapsulating equilibrium distributions used in the lattice Boltzmann
method. These include both the continuous and the discretized variants of the Maxwellian equilibrium of
hydrodynamics. Furthermore, a lightweight wrapper class for custom discrete equilibria is provided.
Custom equilibria may also be implemented by manually overriding the abstract base class
lbmpy.equilibrium.AbstractEquilibrium
.
Abstract Base Class¶
- class AbstractEquilibrium(dim=3)¶
Abstract Base Class for description of equilibrium distribution functions used in lattice Boltzmann methods.
Equilibrium Representation:
This class provides the common interface for describing equilibrium distribution functions, which is then used by the various method classes in the derivation of collision equations. An equilibrium distribution is defined by either its continuous equation (see
continuous_equation
) or a set of discrete populations (seediscrete_populations
andlbmpy.equilibrium.GenericDiscreteEquilibrium
). The distribution function may be given either in its regular, absolute form; or only as its deviation from the rest state, represented by the background distribution (seebackground_distribution
).Computation of Statistical Modes:
The major computational task of an equilbrium class is the computation of the distribution’s statistical modes. For discrete distributions, the subclass
lbmpy.equilibrium.GenericDiscreteEquilibrium
provides a generic implementation for their computation. For continuous distributions, computation of raw moments, central moments, and cumulants is more complicated, but may also be simplified using special tricks.As the computation of statistical modes is a time-consuming process, the abstract base class provides caching functionality to avoid recomputing quantities that are already known.
Instructions to Override:
If you wish to model a simple custom discrete distribution, just using the class
lbmpy.equilibrium.GenericDiscreteEquilibrium
might already be sufficient. If, however, you need to implement more specific functionality, custom properties, a background distribution, etc., or if you wish to model a continuous distribution, you will have to set up a custom subclass ofAbstractEquilibrium
.A subclass must implement all abstract properties according to their docstrings. For computation of statistical modes, a large part of the infrastructure is already given in the abstract base class. The public interface for computing e.g. raw moments reduces the computation of polynomial moments to their contained monomials (for details on how moments are represented in lbmpy, see
lbmpy.moments
). The values of both polynomial and monomial moments, once computed, will be cached per instance of the equilibrium class. To take full advantage of the caching functionality, you will have to override only_monomial_raw_moment()
and its central moment and cumulant counterparts. These methods will be called only once for each monomial quantity when it is required for the first time. Afterward, the cached value will be used.- property dim¶
This distribution’s spatial dimensionality.
- abstract property deviation_only¶
Whether or not this equilibrium distribution is represented only by its deviation from the background distribution.
- abstract property continuous_equation¶
Returns the continuous equation defining this equilibrium distribution, or
None
if no such equation is available.
- abstract property discrete_populations¶
Returns the discrete populations of this equilibrium distribution as a tuple, or
None
if none are available.
- abstract property background_distribution¶
Returns this equilibrium distribution’s background distribution, which is the distribution the discrete populations are centered around in the case of zero-centered storage. If no background distribution is available,
None
must be returned.
- abstract property zeroth_order_moment_symbol¶
Returns a symbol referring to the zeroth-order moment of this distribution, which is the area under it’s curve.
- abstract property first_order_moment_symbols¶
Returns a vector of symbols referring to the first-order moment of this distribution, which is its mean value.
- moment(exponent_tuple_or_polynomial)¶
Returns this equilibrium distribution’s moment specified by
exponent_tuple_or_polynomial
.- Parameters
exponent_tuple_or_polynomial – Moment specification, see
lbmpy.moments
.
- moments(exponent_tuples_or_polynomials)¶
Returns a tuple of this equilibrium distribution’s moments specified by ‘exponent_tuple_or_polynomial’.
- Parameters
exponent_tuples_or_polynomials – Sequence of moment specifications, see
lbmpy.moments
.
- central_moment(exponent_tuple_or_polynomial, frame_of_reference)¶
Returns this equilibrium distribution’s central moment specified by
exponent_tuple_or_polynomial
, computed according to the givenframe_of_reference
.- Parameters
exponent_tuple_or_polynomial – Moment specification, see
lbmpy.moments
.frame_of_reference – The frame of reference with respect to which the central moment should be computed.
- central_moments(exponent_tuples_or_polynomials, frame_of_reference)¶
Returns a list this equilibrium distribution’s central moments specified by
exponent_tuples_or_polynomials
, computed according to the givenframe_of_reference
.- Parameters
exponent_tuples_or_polynomials – Sequence of moment specifications, see
lbmpy.moments
.frame_of_reference – The frame of reference with respect to which the central moment should be computed.
- cumulant(exponent_tuple_or_polynomial, rescale=True)¶
Returns this equilibrium distribution’s cumulant specified by
exponent_tuple_or_polynomial
.- Parameters
exponent_tuple_or_polynomial – Moment specification, see
lbmpy.moments
.rescale – If
True
, the cumulant value should be multiplied by the zeroth-order moment.
- cumulants(exponent_tuples_or_polynomials, rescale=True)¶
Returns a list of this equilibrium distribution’s cumulants specified by
exponent_tuples_or_polynomial
.- Parameters
exponent_tuples_or_polynomials – Sequence of moment specifications, see
lbmpy.moments
.rescale – If
True
, the cumulant value should be multiplied by the zeroth-order moment.
- abstract _monomial_raw_moment(exponents)¶
- abstract _monomial_central_moment(exponents, frame_of_reference)¶
- abstract _monomial_cumulant(exponents, rescale)¶
Generic Discrete Equilibria¶
Use the following class for custom discrete equilibria.
- class GenericDiscreteEquilibrium(stencil, equilibrium_pdfs, zeroth_order_moment_symbol, first_order_moment_symbols, deviation_only=False)¶
Class for encapsulating arbitrary discrete equilibria, given by their equilibrium populations.
This class takes both a stencil and a sequence of populations modelling a discrete distribution function and provides basic functionality for computing and caching that distribution’s statistical modes.
- Parameters
stencil – Discrete velocity set, see
lbmpy.stencils.LBStencil
.equilibrium_pdfs – List of q populations, describing the particle distribution on the discrete velocity set given by the stencil.
zeroth_order_moment_symbol – Symbol corresponding to the distribution’s zeroth-order moment, the area under it’s curve (see
zeroth_order_moment_symbol
).first_order_moment_symbols – Sequence of symbols corresponding to the distribution’s first-order moment, the vector of its mean values (see
first_order_moment_symbols
).deviation_only – Set to
True
if the given populations model only the deviation from a rest state, to be used in junction with the zero-centered storage format.
- property deviation_only¶
Whether or not this equilibrium distribution is represented only by its deviation from the background distribution.
- property discrete_populations¶
Returns the discrete populations of this equilibrium distribution as a tuple, or
None
if none are available.
- property background_distribution¶
Always returns
None
. To specify a background distribution, override this class.
- property zeroth_order_moment_symbol¶
Returns a symbol referring to the zeroth-order moment of this distribution, which is the area under it’s curve.
- property first_order_moment_symbols¶
Returns a vector of symbols referring to the first-order moment of this distribution, which is its mean value.
Maxwellian Equilibria for Hydrodynamics¶
The following classes represent the continuous and the discrete variant of the Maxwellian equilibrium for hydrodynamics.
- class ContinuousHydrodynamicMaxwellian(dim=3, compressible=True, deviation_only=False, order=None, rho=rho, rho_background=1, delta_rho=delta_rho, u=(u_0, u_1, u_2), v=(v_0, v_1, v_2), c_s_sq=c_s ** 2)¶
The standard continuous Maxwellian equilibrium distribution for hydrodynamics.
This class represents the Maxwellian equilibrium distribution of hydrodynamics in its continuous form in \(d\) dimensions [KrugerKK+17]:
\[\Psi \left( \rho, \mathbf{u}, \mathbf{\xi} \right) = \rho \left( \frac{1}{2 \pi c_s^2} \right)^{d/2} \exp \left( \frac{- (\mathbf{\xi} - \mathbf{u})^2 }{2 c_s^2} \right)\]Beyond this classic, ‘compressible’ form of the equilibrium, an alternative form known as the incompressible equilibrium of the LBM can be obtained by setting the flag
compressible=False
. The continuous incompressible equilibrium can be expressed as ([GruszczynskiML+20, HL97]):\[\Psi^{\mathrm{incomp}} \left( \rho, \mathbf{u}, \mathbf{\xi} \right) = \Psi \left( \rho_0, \mathbf{u}, \mathbf{\xi} \right) + \Psi \left( \delta\rho, \mathbf{0}, \mathbf{\xi} \right)\]Here, \(\rho_0\) (typically \(\rho_0 = 1\)) denotes the background density, and \(\delta\rho\) is the density deviation, such that the total fluid density amounts to \(\rho = \rho_0 + \delta\rho\).
To simplify computations when the zero-centered storage format is used for PDFs, both equilibrium variants can also be expressed in a deviation-only or delta-equilibrium form, which is obtained by subtracting the constant background distribution \(\Psi (\rho_0, \mathbf{0})\). The delta form expresses the equilibrium distribution only by its deviation from the rest state:
\[\begin{split}\delta\Psi \left( \rho, \mathbf{u}, \mathbf{\xi} \right) &= \Psi \left( \rho, \mathbf{u}, \mathbf{\xi} \right) - \Psi \left( \rho_0, \mathbf{0}, \mathbf{\xi} \right) \\ \delta\Psi^{\mathrm{incomp}} \left( \rho, \mathbf{u}, \mathbf{\xi} \right) &= \Psi^{\mathrm{incomp}} \left( \rho, \mathbf{u}, \mathbf{\xi} \right) - \Psi \left( \rho_0, \mathbf{0}, \mathbf{\xi} \right)\end{split}\]- Parameters
dim – Spatial dimensionality
compressible – If
False
, the incompressible equilibrium is createddeviation_only – If
True
, the delta-equilibrium is createdorder – The discretization order in velocity to which computed statistical modes should be truncated
rho – Symbol or value for the density
rho_background – Symbol or value for the background density
delta_rho – Symbol or value for the density deviation
u – Sequence of symbols for the macroscopic velocity
v – Sequence of symbols for the particle velocity \(\xi\)
c_s_sq – Symbol or value for the squared speed of sound
- property deviation_only¶
Whether or not this equilibrium distribution is represented only by its deviation from the background distribution.
- property continuous_equation¶
Returns the continuous equation defining this equilibrium distribution, or
None
if no such equation is available.
- property zeroth_order_moment_symbol¶
Returns a symbol referring to the zeroth-order moment of this distribution, which is the area under it’s curve.
- property first_order_moment_symbols¶
Returns a vector of symbols referring to the first-order moment of this distribution, which is its mean value.
- property background_distribution¶
Returns this equilibrium distribution’s background distribution, which is the distribution the discrete populations are centered around in the case of zero-centered storage. If no background distribution is available,
None
must be returned.
- property discrete_populations¶
Returns the discrete populations of this equilibrium distribution as a tuple, or
None
if none are available.
- central_moment(exponent_tuple_or_polynomial, velocity=None)¶
Returns this equilibrium distribution’s central moment specified by
exponent_tuple_or_polynomial
, computed according to the givenframe_of_reference
.- Parameters
exponent_tuple_or_polynomial – Moment specification, see
lbmpy.moments
.frame_of_reference – The frame of reference with respect to which the central moment should be computed.
- central_moments(exponent_tuples_or_polynomials, velocity=None)¶
Returns a list this equilibrium distribution’s central moments specified by
exponent_tuples_or_polynomials
, computed according to the givenframe_of_reference
.- Parameters
exponent_tuples_or_polynomials – Sequence of moment specifications, see
lbmpy.moments
.frame_of_reference – The frame of reference with respect to which the central moment should be computed.
- cumulant(exponent_tuple_or_polynomial, rescale=True)¶
Returns this equilibrium distribution’s cumulant specified by
exponent_tuple_or_polynomial
.- Parameters
exponent_tuple_or_polynomial – Moment specification, see
lbmpy.moments
.rescale – If
True
, the cumulant value should be multiplied by the zeroth-order moment.
- class DiscreteHydrodynamicMaxwellian(stencil, compressible=True, deviation_only=False, order=2, rho=rho, delta_rho=delta_rho, u=(u_0, u_1, u_2), c_s_sq=c_s ** 2)¶
The textbook discretization of the Maxwellian equilibrium distribution of hydrodynamics.
This class represents the default discretization of the Maxwellian in velocity space, computed from the distribution’s expansion in Hermite polynomials (cf. [KrugerKK+17]). In \(d\) dimensions, its populations \(f_i\) on a given stencil \((\mathbf{c}_i)_{i=0,\dots,q-1}\) are given by
\[f_i (\rho, \mathbf{u}) = w_i \rho \left( 1 + \frac{\mathbf{c}_i \cdot \mathbf{u}}{c_s^2} + \frac{(\mathbf{c}_i \cdot \mathbf{u})^2}{2 c_s^4} - \frac{\mathbf{u} \cdot \mathbf{u}}{2 c_s^2} \right).\]Here \(w_i\) denote the Hermite integration weights, also called lattice weights. The incompressible variant of this distribution [HL97] can be written as
\[f_i^{\mathrm{incomp}} (\rho, \mathbf{u}) = w_i \rho + w_i \rho_0 \left( \frac{\mathbf{c}_i \cdot \mathbf{u}}{c_s^2} + \frac{(\mathbf{c}_i \cdot \mathbf{u})^2}{2 c_s^4} - \frac{\mathbf{u} \cdot \mathbf{u}}{2 c_s^2} \right).\]Again, for usage with zero-centered PDF storage, both distributions may be expressed in a delta-form by subtracting their values at the background rest state at \(\rho = \rho_0\), \(\mathbf{u} = \mathbf{0}\), which are exactly the lattice weights:
\[\begin{split}\delta f_i &= f_i - w_i \\ \delta f_i^{\mathrm{incomp}} &= f_i^{\mathrm{incomp}} - w_i \\\end{split}\]- Parameters
stencil – Discrete velocity set for the discretization, see
lbmpy.stencils.LBStencil
compressible – If
False
, the incompressible equilibrium is createddeviation_only – If
True
, the delta-equilibrium is createdorder – The discretization order in velocity to which computed statistical modes should be truncated
rho – Symbol or value for the density
delta_rho – Symbol or value for the density deviation
u – Sequence of symbols for the macroscopic velocity
c_s_sq – Symbol or value for the squared speed of sound
- property deviation_only¶
Whether or not this equilibrium distribution is represented only by its deviation from the background distribution.
- property background_distribution¶
Returns the discrete Maxwellian background distribution, which amounts exactly to the lattice weights.
- central_moment(exponent_tuple_or_polynomial, velocity=None)¶
Returns this equilibrium distribution’s central moment specified by
exponent_tuple_or_polynomial
, computed according to the givenframe_of_reference
.- Parameters
exponent_tuple_or_polynomial – Moment specification, see
lbmpy.moments
.frame_of_reference – The frame of reference with respect to which the central moment should be computed.
- central_moments(exponent_tuples_or_polynomials, velocity=None)¶
Returns a list this equilibrium distribution’s central moments specified by
exponent_tuples_or_polynomials
, computed according to the givenframe_of_reference
.- Parameters
exponent_tuples_or_polynomials – Sequence of moment specifications, see
lbmpy.moments
.frame_of_reference – The frame of reference with respect to which the central moment should be computed.
- cumulant(exponent_tuple_or_polynomial, rescale=True)¶
Returns this equilibrium distribution’s cumulant specified by
exponent_tuple_or_polynomial
.- Parameters
exponent_tuple_or_polynomial – Moment specification, see
lbmpy.moments
.rescale – If
True
, the cumulant value should be multiplied by the zeroth-order moment.