Moment Transforms (lbmpy.moment_transforms)¶
The moment_transforms
module provides an ecosystem for transformation of quantities between
lattice Boltzmann population space and other spaces of observable quantities. Currently, transforms
to raw and central moment space are available.
The common base class lbmpy.moment_transforms.AbstractMomentTransform
defines the interface all transform classes share.
This interface, together with the fundamental principles all transforms adhere to, is explained
in the following.
Principles of Collision Space Transforms¶
Each class of this module implements a bijective map \(\mathcal{M}\) from population space to raw moment or central moment space, capable of transforming the particle distribution function \(\mathbf{f}\) to (almost) arbitrary userdefined moment sets.
Monomial and Polynomial Moments¶
We discriminate monomial and polynomial moments. The monomial moments are the canonical basis of their corresponding space. Polynomial moments are defined as linear combinations of this basis. Monomial moments are typically expressed by exponent tuples \((\alpha, \beta, \gamma)\). The monomial raw moments are defined as
and the monomial central moments are given by
Polynomial moments are, in turn, expressed by polynomial expressions \(p\) in the coordinate symbols \(x\), \(y\) and \(z\). An exponent tuple \((\alpha, \beta, \gamma)\) corresponds directly to the mixed monomial expression \(x^{\alpha} y^{\beta} z^{\gamma}\). Polynomial moments are then constructed as linear combinations of these monomials. For example, the polynomial
defines both the polynomial raw moment
and central moment
Transformation Matrices¶
The collision space basis for an MRT LB method on a \(DdQq\) lattice is spanned by a set of \(q\) polynomial quantities, given by polynomials \(\left( p_i \right)_{i=0, \dots, q1}\). Through the polynomials, a polynomialization matrix \(P\) is defined such that
Both rules can also be written using matrix multiplication, such that
Further, there exists a mapping from raw to central moment space using (monomial or polynomial)
shift matrices (see set_up_shift_matrix
) such that
Working with the transformation matrices, those mappings can easily be inverted. This module provides classes that derive efficient implementations of these transformations.
Moment Aliasing¶
For a collision space transform to be invertible, exactly \(q\) independent polynomial quantities of the collision space must be chosen. In that case, since all transforms discussed here are linear, the space of populations is isomorphic to the chosen moment space. The important word here is ‘independent’. Even if \(q\) distinct moment polynomials are chosen, due to discrete lattice artifacts, they might not span the entire collision space if chosen wrongly. The discrete lattice structure gives rise to moment aliasing effects. The most simple such effect occurs in the monomial raw moments, where are all nonzero even and all odd exponents are essentially the same. For example, we have \(m_{400} = m_{200}\) or \(m_{305} = m_{101}\). This rule holds on every directneighborhood stencil. Sparse stencils, like \(D3Q15\), may introduce additional aliases. On the \(D3Q15\) stencil, due to its structure, we have also \(m_{112} = m_{110}\) and even \(m_{202} = m_{220} = m_{022} = m_{222}\).
Including aliases in a set of monomial moments will lead to a noninvertible transform and is hence not possible. In polynomials, however, aliases may occur without breaking the transform. Several established sets of polynomial moments, like in orthogonal raw moment space MRT methods, will comprise \(q\) polynomials \(\mathbf{M}\) that in turn are built out of \(r > q\) monomial moments \(\mathbf{m}\). In that set of monomials, nonindependent moments have to be included by definition. Since the full transformation matrix \(M^P = PM\) is still invertible, this is not a problem in general. If, however, the two steps of the transform are computed separately, it becomes problematic, as the matrices \(M \in \mathbb{R}^{r \times q}\) and \(P \in \mathbb{R}^{q \times r}\) are not invertible on their own.
But there is a remedy. By eliminating aliases from the moment polynomials, they can be reduced to a new set of polynomials based on a nonaliased reduced vector of monomial moments \(\tilde{\mathbf{m}} \in \mathbb{R}^{q}\), expressed through the reduced matrix \(\tilde{P}\).
Interfaces and Usage¶
Construction¶
All moment transform classes expect either a sequence of exponent tuples or a sequence of polynomials that define the set of quantities spanning the destination space. If polynomials are given, the exponent tuples of the underlying set of monomials are extracted automatically. Depending on the implementation, moment aliases may be eliminated in the process, altering both the polynomials and the set of monomials.
Forward and Backward Transform¶
The core functionality of the transform classes is given by the methods forward_transform
and backward_transform
.
They return assignment collections containing the equations to compute moments from populations, and vice versa.
Symbols Used¶
Unless otherwise specified by the user, monomial and polynomial quantities occur in the transformation equations according to the naming conventions listed in the following table:
Monomial 
Polynomial 

PreCollision Raw Moment 
\(m_{\alpha \beta \gamma}\) 
\(M_{i}\) 
PostCollision Raw Moment 
\(m_{post, \alpha \beta \gamma}\) 
\(M_{post, i}\) 
PreCollision Central Moment 
\(\kappa_{\alpha \beta \gamma}\) 
\(K_{i}\) 
PostCollision Central Moment 
\(\kappa_{post, \alpha \beta \gamma}\) 
\(K_{post, i}\) 
These symbols are also exposed by the member properties pre_collision_symbols
, post_collision_symbols
,
pre_collision_monomial_symbols
and post_collision_monomial_symbols
.
Forward Transform¶
Implementations of the lbmpy.moment_transforms.AbstractMomentTransform.forward_transform
method
derive equations for the transform from population to moment space, to compute precollision moments
from precollision populations. The returned AssignmentCollection
has the pre_collision_symbols
as lefthand sides of its main assignments, computed from the given pdf_symbols
and, potentially,
the macroscopic density and velocity. Depending on the implementation, the pre_collision_monomial_symbols
may be part of the assignment collection in the form of subexpressions.
Backward Transform¶
Implementations of lbmpy.moment_transforms.AbstractMomentTransform.backward_transform
contain the postcollision
polynomial quantities as free symbols of their equation righthand sides, and compute the postcollision populations
from those. The PDF symbols are the lefthand sides of the main assignments.
Absorption of Conserved Quantity Equations¶
Transformations from the population space to any space of observable quantities may absorb the equations
defining the macroscopic quantities entering the equilibrium (typically the density \(\rho\) and the
velocity \(\mathbf{u}\)). This means that the forward_transform
will possibly rewrite the
assignments given in the constructor argument conserved_quantity_equations
to reduce
the total operation count. For example, in the transformation step from populations to
raw moments (see lbmpy.moment_transforms.PdfsToMomentsByChimeraTransform
), \(\rho\) can be aliased as the zerothorder moment
\(m_{000}\). Assignments to the conserved quantities will then be part of the AssignmentCollection
returned by forward_transform
and need not be added to the collision rule separately.
Simplification¶
Both forward_transform
and backward_transform
expect a keyword argument simplification
which can be used to direct simplification steps applied during the derivation of the transformation
equations. Possible values are:
False
or'none'
: No simplification is to be appliedTrue
or'default'
: A default simplification strategy specific to the implementation is applied.The actual simplification steps depend strongly on the nature of the equations. They are defined by the implementation. It is the responsibility of the implementation to select the most effective simplification strategy.
'default_with_cse'
: Same as'default'
, but with an additional pass of common subexpression elimination.
Working With Monomials¶
In certain situations, we want the forward_transform
to yield equations for the monomial symbols \(m_{\alpha \beta \gamma}\)
and \(\kappa_{\alpha \beta \gamma}\) only, and the backward_transform
to return equations that also expect these symbols as input.
In this case, it is not sufficient to pass a set of monomials or exponent tuples to the constructor, as those are still treated as
polynomials internally. Instead, both transform methods expose keyword arguments return_monomials
and start_from_monomials
, respectively.
If set to true, equations in the monomial moments are returned. They are best used only together with the exponent_tuples
constructor argument
to have full control over the monomials. If polynomials are passed to the constructor, the behaviour of these flags is generally not welldefined,
especially in the presence of aliases.
The Transform Classes¶
Abstract Base Class¶
 class AbstractMomentTransform(stencil, equilibrium_density, equilibrium_velocity, moment_exponents=None, moment_polynomials=None, conserved_quantity_equations=None, background_distribution=None, pre_collision_symbol_base=None, post_collision_symbol_base=None, pre_collision_monomial_symbol_base=None, post_collision_monomial_symbol_base=None)¶
Abstract Base Class for classes providing transformations between moment spaces.
 property pre_collision_symbols¶
List of symbols corresponding to the precollision quantities that will be the lefthand sides of assignments returned by
forward_transform()
.
 property post_collision_symbols¶
List of symbols corresponding to the postcollision quantities that are input to the righthand sides of assignments returned by:func:
backward_transform
.
 property pre_collision_monomial_symbols¶
List of symbols corresponding to the precollision monomial quantities that might exist as lefthand sides of subexpressions in the assignment collection returned by
forward_transform()
.
 property post_collision_monomial_symbols¶
List of symbols corresponding to the postcollision monomial quantities that might exist as lefthand sides of subexpressions in the assignment collection returned by
backward_transform()
.
 abstract forward_transform(*args, **kwargs)¶
Implemented in a subclass, will return the forward transform equations.
 abstract backward_transform(*args, **kwargs)¶
Implemented in a subclass, will return the backward transform equations.
 property absorbs_conserved_quantity_equations¶
Whether or not the given conserved quantity equations will be included in the assignment collection returned by
forward_transform()
, possibly in simplified form.
Moment Space Transforms¶
 class PdfsToMomentsByMatrixTransform(stencil, moment_polynomials, equilibrium_density, equilibrium_velocity, conserved_quantity_equations=None, **kwargs)¶
Transform between populations and moment space spanned by a polynomial basis, using matrixvector multiplication.
 property absorbs_conserved_quantity_equations¶
Whether or not the given conserved quantity equations will be included in the assignment collection returned by
forward_transform()
, possibly in simplified form.
 forward_transform(pdf_symbols, simplification=True, subexpression_base='sub_f_to_M', return_monomials=False)¶
Returns an assignment collection containing equations for precollision polynomial moments, expressed in terms of the precollision populations by matrixmultiplication.
The moment transformation matrix \(M\) provided by
lbmpy.moments.moment_matrix()
is used to compute the precollision moments as \(\mathbf{M} = M \cdot \mathbf{f}\), which is returned elementwise. Parameters
pdf_symbols – List of symbols that represent the precollision populations
simplification – Simplification specification. See
AbstractMomentTransform
subexpression_base – The base name used for any subexpressions of the transformation.
return_monomials – Return equations for monomial moments. Use only when specifying
moment_exponents
in constructor!
 backward_transform(pdf_symbols, simplification=True, subexpression_base='sub_k_to_f', start_from_monomials=False)¶
Returns an assignment collection containing equations for postcollision populations, expressed in terms of the postcollision polynomial moments by matrixmultiplication.
The moment transformation matrix \(M\) provided by
lbmpy.moments.moment_matrix()
is inverted and used to compute the precollision moments as \(\mathbf{f}^{\ast} = M^{1} \cdot \mathbf{M}_{\mathrm{post}}\), which is returned elementwise.Simplifications
If simplification is enabled, the equations for populations \(f_i\) and \(f_{\bar{i}}\) of opposite stencil directions \(\mathbf{c}_i\) and \(\mathbf{c}_{\bar{i}} =  \mathbf{c}_i\) are split into their symmetric and antisymmetric parts \(f_i^{\mathrm{sym}}, f_i^{\mathrm{anti}}\), such that
\[ \begin{align}\begin{aligned}f_i = f_i^{\mathrm{sym}} + f_i^{\mathrm{anti}}\\f_{\bar{i}} = f_i^{\mathrm{sym}}  f_i^{\mathrm{anti}}\end{aligned}\end{align} \] Parameters
pdf_symbols – List of symbols that represent the postcollision populations
simplification – Simplification specification. See
AbstractMomentTransform
subexpression_base – The base name used for any subexpressions of the transformation.
start_from_monomials – Return equations for monomial moments. Use only when specifying
moment_exponents
in constructor!
 class PdfsToMomentsByChimeraTransform(stencil, moment_polynomials, equilibrium_density, equilibrium_velocity, conserved_quantity_equations=None, **kwargs)¶
Transform between populations and moment space spanned by a polynomial basis, using the rawmoment chimera transform in the forward direction and matrixvector multiplication in the backward direction.
 property absorbs_conserved_quantity_equations¶
Whether or not the given conserved quantity equations will be included in the assignment collection returned by
forward_transform()
, possibly in simplified form.
 get_cq_to_moment_symbols_dict(moment_symbol_base)¶
Returns a dictionary mapping the density and velocity symbols to the correspondig zeroth and firstorder raw moment symbols
 forward_transform(pdf_symbols, simplification=True, subexpression_base='sub_f_to_m', return_monomials=False)¶
Returns an assignment collection containing equations for precollision polynomial moments, expressed in terms of the precollision populations, using the raw moment chimera transform.
The chimera transform for raw moments is given by [GSchonherrPK15] :
\[\begin{split}f_{xyz} &:= f_i \text{ such that } c_i = (x,y,z)^T \\ m_{xy\gamma} &:= \sum_{z \in \{1, 0, 1\} } f_{xyz} \cdot z^{\gamma} \\ m_{x\beta \gamma} &:= \sum_{y \in \{1, 0, 1\}} m_{xy\gamma} \cdot y^{\beta} \\ m_{\alpha \beta \gamma} &:= \sum_{x \in \{1, 0, 1\}} m_{x\beta \gamma} \cdot x^{\alpha}\end{split}\]The obtained raw moments are afterward combined to the desired polynomial moments.
Conserved Quantity Equations
If given, this transform absorbs the conserved quantity equations and simplifies them using the monomial raw moment equations, if simplification is enabled.
DeAliasing
If more than \(q\) monomial moments are extracted from the polynomial set, the polynomials are dealiased by eliminating aliases according to the stencil using
lbmpy.moments.non_aliased_polynomial_raw_moments
.Simplification
If simplification is enabled, the absorbed conserved quantity equations are  if possible  rewritten using the monomial symbols. If the conserved quantities originate somewhere else than in the lowerorder moments (like from an external field), they are not affected by this simplification. Furthermore, aliases and constants are propagated in the chimera equations.
 Parameters
pdf_symbols – List of symbols that represent the precollision populations
simplification – Simplification specification. See
AbstractMomentTransform
subexpression_base – The base name used for any subexpressions of the transformation.
return_monomials – Return equations for monomial moments. Use only when specifying
moment_exponents
in constructor!
 backward_transform(pdf_symbols, simplification=True, subexpression_base='sub_k_to_f', start_from_monomials=False)¶
Returns an assignment collection containing equations for postcollision populations, expressed in terms of the postcollision polynomial moments by matrixmultiplication.
The postcollision monomial moments \(\mathbf{m}_{\mathrm{post}}\) are first obtained from the polynomials. Then, the monomial transformation matrix \(M_r\) provided by
lbmpy.moments.moment_matrix()
is inverted and used to compute the postcollision populations as \(\mathbf{f}_{\mathrm{post}} = M_r^{1} \cdot \mathbf{m}_{\mathrm{post}}\).DeAliasing
See
PdfsToMomentsByChimeraTransform.forward_transform
.Simplifications
If simplification is enabled, the equations for populations \(f_i\) and \(f_{\bar{i}}\) of opposite stencil directions \(\mathbf{c}_i\) and \(\mathbf{c}_{\bar{i}} =  \mathbf{c}_i\) are split into their symmetric and antisymmetric parts \(f_i^{\mathrm{sym}}, f_i^{\mathrm{anti}}\), such that
\[ \begin{align}\begin{aligned}f_i = f_i^{\mathrm{sym}} + f_i^{\mathrm{anti}}\\f_{\bar{i}} = f_i^{\mathrm{sym}}  f_i^{\mathrm{anti}}\end{aligned}\end{align} \] Parameters
pdf_symbols – List of symbols that represent the postcollision populations
simplification – Simplification specification. See
AbstractMomentTransform
subexpression_base – The base name used for any subexpressions of the transformation.
start_from_monomials – Return equations for monomial moments. Use only when specifying
moment_exponents
in constructor!
Central Moment Space Transforms¶
 class PdfsToCentralMomentsByMatrix(stencil, moment_polynomials, equilibrium_density, equilibrium_velocity, **kwargs)¶
Transform from populations to central moment space by matrixvector multiplication.
 forward_transform(pdf_symbols, simplification=True, subexpression_base='sub_f_to_k', return_monomials=False)¶
Returns an assignment collection containing equations for precollision polynomial central moments, expressed in terms of the precollision populations by matrixmultiplication.
The central moment transformation matrix \(K\) provided by
lbmpy.moments.moment_matrix()
is used to compute the precollision moments as \(\mathbf{K} = K \cdot \mathbf{f}\), which are returned elementwise. Parameters
pdf_symbols – List of symbols that represent the precollision populations
simplification – Simplification specification. See
AbstractMomentTransform
subexpression_base – The base name used for any subexpressions of the transformation.
return_monomials – Return equations for monomial moments. Use only when specifying
moment_exponents
in constructor!
 backward_transform(pdf_symbols, simplification=True, subexpression_base='sub_k_to_f', start_from_monomials=False)¶
Returns an assignment collection containing equations for postcollision populations, expressed in terms of the postcollision polynomial central moments by matrixmultiplication.
The moment transformation matrix \(K\) provided by
lbmpy.moments.moment_matrix()
is inverted and used to compute the precollision moments as \(\mathbf{f}^{\ast} = K^{1} \cdot \mathbf{K}_{\mathrm{post}}\), which is returned elementwise. Parameters
pdf_symbols – List of symbols that represent the postcollision populations
simplification – Simplification specification. See
AbstractMomentTransform
subexpression_base – The base name used for any subexpressions of the transformation.
start_from_monomials – Return equations for monomial moments. Use only when specifying
moment_exponents
in constructor!
 class BinomialChimeraTransform(stencil, moment_polynomials, equilibrium_density, equilibrium_velocity, conserved_quantity_equations=None, **kwargs)¶
Transform from populations to central moments using a chimera transform implementing the binomial expansion.
 property absorbs_conserved_quantity_equations¶
Whether or not the given conserved quantity equations will be included in the assignment collection returned by
forward_transform()
, possibly in simplified form.
 forward_transform(pdf_symbols, simplification=True, subexpression_base='sub_f_to_k', return_monomials=False)¶
Returns equations for polynomial central moments, computed from precollision populations through a cascade of three steps.
First, the monomial raw moment vector \(\mathbf{m}\) is computed using the rawmoment chimera transform (see
lbmpy.moment_transforms.PdfsToMomentsByChimeraTransform
).Second, we obtain monomial central moments from monomial raw moments using the binomial chimera transform:
\[\begin{split}\kappa_{ab\gamma} &:= \sum_{c = 0}^{\gamma} \binom{\gamma}{c} v_z^{\gamma  c} m_{abc} \\ \kappa_{a\beta\gamma} &:= \sum_{b = 0}^{\beta} \binom{\beta}{b} v_z^{\beta  b} \kappa_{ab\gamma} \\ \kappa_{\alpha\beta\gamma} &:= \sum_{a = 0}^{\alpha} \binom{\alpha}{a} v_z^{\alpha  a} \kappa_{a\beta\gamma} \\\end{split}\]Lastly, the polynomial central moments are computed using the polynomialization matrix as \(\mathbf{K} = P \mathbf{\kappa}\).
Conserved Quantity Equations
If given, this transform absorbs the conserved quantity equations and simplifies them using the raw moment equations, if simplification is enabled.
Simplification
If simplification is enabled, the absorbed conserved quantity equations are  if possible  rewritten using the monomial symbols. If the conserved quantities originate somewhere else than in the lowerorder moments (like from an external field), they are not affected by this simplification.
The raw moment chimera transform is simplified by propagation of aliases.
The equations of the binomial chimera transform are simplified by expressing conserved raw moments in terms of the conserved quantities, and subsequent propagation of aliases, constants, and any expressions that are purely products of conserved quantities.
DeAliasing
If more than \(q\) monomial moments are extracted from the polynomial set, they are dealiased and reduced to a set of only \(q\) moments using the same rules as for raw moments. For polynomialization, a special reduced matrix \(\tilde{P}\) is used, which is computed using
lbmpy.moments.central_moment_reduced_monomial_to_polynomial_matrix
. Parameters
pdf_symbols – List of symbols that represent the precollision populations
simplification – Simplification specification. See
AbstractMomentTransform
subexpression_base – The base name used for any subexpressions of the transformation.
return_monomials – Return equations for monomial moments. Use only when specifying
moment_exponents
in constructor!
 backward_transform(pdf_symbols, simplification=True, subexpression_base='sub_k_to_f', start_from_monomials=False)¶
Returns an assignment collection containing equations for postcollision populations, expressed in terms of the postcollision polynomial central moments by three steps.
The postcollision monomial central moments \(\mathbf{\kappa}_{\mathrm{post}}\) are first obtained from the polynomials through multiplication with \(P^{1}\).
Afterward, monomial postcollision raw moments are obtained from monomial central moments using the binomial chimera transform:
\[\begin{split}m^{\ast}_{ab\gamma} &:= \sum_{c = 0}^{\gamma} \binom{\gamma}{c} v_z^{\gamma  c} \kappa^{\ast}_{abc} \\ m^{\ast}_{a\beta\gamma} &:= \sum_{b = 0}^{\beta} \binom{\beta}{b} v_z^{\beta  b} m^{\ast}_{ab\gamma} \\ m^{\ast}_{\alpha\beta\gamma} &:= \sum_{a = 0}^{\alpha} \binom{\alpha}{a} v_z^{\alpha  a} m^{\ast}_{a\beta\gamma} \\\end{split}\]Finally, the monomial raw moment transformation matrix \(M_r\) provided by
lbmpy.moments.moment_matrix()
is inverted and used to compute the precollision moments as \(\mathbf{f}_{\mathrm{post}} = M_r^{1} \cdot \mathbf{m}_{\mathrm{post}}\).DeAliasing:
See
PdfsToCentralMomentsByShiftMatrix.forward_transform
.Simplifications
If simplification is enabled, the inverse shift matrix equations are simplified by recursively inserting lowerorder moments into equations for higherorder moments. To this end, these equations are factored recursively by the velocity symbols.
The equations of the binomial chimera transform are simplified by propagation of aliases.
Further, the equations for populations \(f_i\) and \(f_{\bar{i}}\) of opposite stencil directions \(\mathbf{c}_i\) and \(\mathbf{c}_{\bar{i}} =  \mathbf{c}_i\) are split into their symmetric and antisymmetric parts \(f_i^{\mathrm{sym}}, f_i^{\mathrm{anti}}\), such that
\[ \begin{align}\begin{aligned}f_i = f_i^{\mathrm{sym}} + f_i^{\mathrm{anti}}\\f_{\bar{i}} = f_i^{\mathrm{sym}}  f_i^{\mathrm{anti}}\end{aligned}\end{align} \] Parameters
pdf_symbols – List of symbols that represent the postcollision populations
simplification – Simplification specification. See
AbstractMomentTransform
subexpression_base – The base name used for any subexpressions of the transformation.
start_from_monomials – Return equations for monomial moments. Use only when specifying
moment_exponents
in constructor!
 class FastCentralMomentTransform(stencil, moment_polynomials, equilibrium_density, equilibrium_velocity, conserved_quantity_equations=None, **kwargs)¶
Transform from populations to central moments, using the fast centralmoment transform equations introduced by [GSchonherrPK15].
Attention: The fast central moment transform has originally been designed for the D3Q27 stencil, and is also tested and safely usable with D2Q9 and D3Q19. While the forward transform does not pose any problems, the backward equations may be inefficient, or even not cleanly derivable for other stencils. Use with care!
 forward_transform(pdf_symbols, simplification=True, subexpression_base='sub_f_to_k', return_monomials=False)¶
Returns an assignment collection containing equations for precollision polynomial central moments, expressed in terms of the precollision populations.
The monomial central moments are computed from populations through the centralmoment chimera transform:
\[\begin{split}f_{xyz} &:= f_i \text{ such that } c_i = (x,y,z)^T \\ \kappa_{xy\gamma} &:= \sum_{z \in \{1, 0, 1\} } f_{xyz} \cdot (z  u_z)^{\gamma} \\ \kappa_{x\beta \gamma} &:= \sum_{y \in \{1, 0, 1\}} \kappa_{xy\gamma} \cdot (y  u_y)^{\beta} \\ \kappa_{\alpha \beta \gamma} &:= \sum_{x \in \{1, 0, 1\}} \kappa_{x\beta \gamma} \cdot (x  u_x)^{\alpha}\end{split}\]The polynomial moments are afterward computed from the monomials by matrixmultiplication using the polynomialization matrix \(P\).
DeAliasing
If more than \(q\) monomial moments are extracted from the polynomial set, they are dealiased and reduced to a set of only \(q\) moments using the same rules as for raw moments. For polynomialization, a special reduced matrix \(\tilde{P}\) is used, which is computed using
lbmpy.moments.central_moment_reduced_monomial_to_polynomial_matrix
. Parameters
pdf_symbols – List of symbols that represent the precollision populations
simplification – Simplification specification. See
AbstractMomentTransform
subexpression_base – The base name used for any subexpressions of the transformation.
return_monomials – Return equations for monomial moments. Use only when specifying
moment_exponents
in constructor!
 backward_transform(pdf_symbols, simplification=True, subexpression_base='sub_k_to_f', start_from_monomials=False)¶
Returns an assignment collection containing equations for postcollision populations, expressed in terms of the postcollision polynomial central moments using the backward fast central moment transform.
First, monomial central moments are obtained from the polynomial moments by multiplication with \(P^{1}\). Then, the elementwise equations of the matrix multiplication \(K^{1} \cdot \mathbf{K}\) with the monomial central moment matrix (see
PdfsToCentralMomentsByMatrix
) are recursively simplified by extracting certain linear combinations of velocities, to obtain equations similar to the ones given in [GSchonherrPK15].The backward transform is designed for D3Q27, inherently generalizes to D2Q9, and is tested for D3Q19. It also returns correct equations for D3Q15, whose efficiency is however questionable.
DeAliasing:
See
FastCentralMomentTransform.forward_transform
. Parameters
pdf_symbols – List of symbols that represent the postcollision populations
simplification – Simplification specification. See
AbstractMomentTransform
subexpression_base – The base name used for any subexpressions of the transformation.
start_from_monomials – Return equations for monomial moments. Use only when specifying
moment_exponents
in constructor!
 class PdfsToCentralMomentsByShiftMatrix(stencil, moment_polynomials, equilibrium_density, equilibrium_velocity, conserved_quantity_equations=None, **kwargs)¶
Transform from populations to central moments using a shift matrix.
 property absorbs_conserved_quantity_equations¶
Whether or not the given conserved quantity equations will be included in the assignment collection returned by
forward_transform()
, possibly in simplified form.
 forward_transform(pdf_symbols, simplification=True, subexpression_base='sub_f_to_k', return_monomials=False)¶
Returns equations for polynomial central moments, computed from precollision populations through a cascade of three steps.
First, the monomial raw moment vector \(\mathbf{m}\) is computed using the rawmoment chimera transform (see
lbmpy.moment_transforms.PdfsToMomentsByChimeraTransform
). Then, the monomial shift matrix \(N\) provided bylbmpy.moments.set_up_shift_matrix
is used to compute the monomial central moment vector as \(\mathbf{\kappa} = N \mathbf{m}\). Lastly, the polynomial central moments are computed using the polynomialization matrix as \(\mathbf{K} = P \mathbf{\kappa}\).Conserved Quantity Equations
If given, this transform absorbs the conserved quantity equations and simplifies them using the raw moment equations, if simplification is enabled.
Simplification
If simplification is enabled, the absorbed conserved quantity equations are  if possible  rewritten using the monomial symbols. If the conserved quantities originate somewhere else than in the lowerorder moments (like from an external field), they are not affected by this simplification.
The relations between conserved quantities and raw moments are used to simplify the equations obtained from the shift matrix. Further, these equations are simplified by recursively inserting lowerorder moments into equations for higherorder moments.
DeAliasing
If more than \(q\) monomial moments are extracted from the polynomial set, they are dealiased and reduced to a set of only \(q\) moments using the same rules as for raw moments. For polynomialization, a special reduced matrix \(\tilde{P}\) is used, which is computed using
lbmpy.moments.central_moment_reduced_monomial_to_polynomial_matrix
. Parameters
pdf_symbols – List of symbols that represent the precollision populations
simplification – Simplification specification. See
AbstractMomentTransform
subexpression_base – The base name used for any subexpressions of the transformation.
return_monomials – Return equations for monomial moments. Use only when specifying
moment_exponents
in constructor!
 backward_transform(pdf_symbols, simplification=True, subexpression_base='sub_k_to_f', start_from_monomials=False)¶
Returns an assignment collection containing equations for postcollision populations, expressed in terms of the postcollision polynomial central moments by matrixmultiplication including the shift matrix.
The postcollision monomial central moments \(\mathbf{\kappa}_{\mathrm{post}}\) are first obtained from the polynomials through multiplication with \(P^{1}\). The shiftmatrix is inverted as well, to obtain the monomial raw moments as \(\mathbf{m}_{post} = N^{1} \mathbf{\kappa}_{post}\). Finally, the monomial raw moment transformation matrix \(M_r\) provided by
lbmpy.moments.moment_matrix()
is inverted and used to compute the precollision moments as \(\mathbf{f}_{\mathrm{post}} = M_r^{1} \cdot \mathbf{m}_{\mathrm{post}}\).DeAliasing:
See
PdfsToCentralMomentsByShiftMatrix.forward_transform
.Simplifications
If simplification is enabled, the inverse shift matrix equations are simplified by recursively inserting lowerorder moments into equations for higherorder moments. To this end, these equations are factored recursively by the velocity symbols.
Further, the equations for populations \(f_i\) and \(f_{\bar{i}}\) of opposite stencil directions \(\mathbf{c}_i\) and \(\mathbf{c}_{\bar{i}} =  \mathbf{c}_i\) are split into their symmetric and antisymmetric parts \(f_i^{\mathrm{sym}}, f_i^{\mathrm{anti}}\), such that
\[ \begin{align}\begin{aligned}f_i = f_i^{\mathrm{sym}} + f_i^{\mathrm{anti}}\\f_{\bar{i}} = f_i^{\mathrm{sym}}  f_i^{\mathrm{anti}}\end{aligned}\end{align} \] Parameters
pdf_symbols – List of symbols that represent the postcollision populations
simplification – Simplification specification. See
AbstractMomentTransform
subexpression_base – The base name used for any subexpressions of the transformation.
start_from_monomials – Return equations for monomial moments. Use only when specifying
moment_exponents
in constructor!
Cumulant Space Transforms¶
 class CentralMomentsToCumulantsByGeneratingFunc(stencil, cumulant_polynomials, equilibrium_density, equilibrium_velocity, cumulant_exponents=None, pre_collision_symbol_base='C', post_collision_symbol_base='C_post', pre_collision_monomial_symbol_base='c', post_collision_monomial_symbol_base='c_post', **kwargs)¶
 property required_central_moments¶
The required central moments as a sorted list of exponent tuples
 forward_transform(central_moment_base='kappa', simplification=True, subexpression_base='sub_k_to_C', return_monomials=False)¶
Implemented in a subclass, will return the forward transform equations.
 backward_transform(central_moment_base='kappa_post', simplification=True, subexpression_base='sub_C_to_k', start_from_monomials=False)¶
Implemented in a subclass, will return the backward transform equations.