Creating LBM methods¶
This module is a lower level API to construct methods. When possible use the high level API.

create_with_discrete_maxwellian_eq_moments
(stencil, moment_to_relaxation_rate_dict, compressible=False, force_model=None, equilibrium_order=2, c_s_sq=1/3, central_moment_space=False, central_moment_transform_class=<class 'lbmpy.methods.momentbased.moment_transforms.FastCentralMomentTransform'>)¶ Creates a momentbased LBM by taking a list of moments with corresponding relaxation rate.
These moments are relaxed against the moments of the discrete Maxwellian distribution.
 Parameters
stencil – nested tuple defining the discrete velocity space. See
get_stencil
moment_to_relaxation_rate_dict – dict that has as many entries as the stencil. Each moment, which can be represented by an exponent tuple or in polynomial form (see
lbmpy.moments
), is mapped to a relaxation rate.compressible – incompressible LBM methods split the density into \(\rho = \rho_0 + \Delta \rho\) where \(\rho_0\) is chosen as one, and the first moment of the pdfs is \(\Delta \rho\) . This approximates the incompressible NavierStokes equations better than the standard compressible model.
force_model – force model instance, or None if no external forces
equilibrium_order – approximation order of macroscopic velocity \(\mathbf{u}\) in the equilibrium
c_s_sq – Speed of sound squared
central_moment_space – If set to True and instance of
is returned. (lbmpy.methods.momentbased.centralmomentbasedmethod.CentralMomentBasedLbMethod) –
the collision will be performed in the central moment space. (Thus) –
central_moment_transform_class – class to transform PDFs to the central moment space.
 Returns

create_with_continuous_maxwellian_eq_moments
(stencil, moment_to_relaxation_rate_dict, compressible=False, force_model=None, equilibrium_order=2, c_s_sq=1/3, central_moment_space=False, central_moment_transform_class=<class 'lbmpy.methods.momentbased.moment_transforms.FastCentralMomentTransform'>)¶ Creates a momentbased LBM by taking a list of moments with corresponding relaxation rate. These moments are relaxed against the moments of the continuous Maxwellian distribution. For parameter description see
lbmpy.methods.create_with_discrete_maxwellian_eq_moments()
. By using the continuous Maxwellian we automatically get a compressible model. Parameters
stencil – nested tuple defining the discrete velocity space. See
get_stencil
moment_to_relaxation_rate_dict – dict that has as many entries as the stencil. Each moment, which can be represented by an exponent tuple or in polynomial form (see
lbmpy.moments
), is mapped to a relaxation rate.compressible – incompressible LBM methods split the density into \(\rho = \rho_0 + \Delta \rho\) where \(\rho_0\) is chosen as one, and the first moment of the pdfs is \(\Delta \rho\) . This approximates the incompressible NavierStokes equations better than the standard compressible model.
force_model – force model instance, or None if no external forces
equilibrium_order – approximation order of macroscopic velocity \(\mathbf{u}\) in the equilibrium
c_s_sq – Speed of sound squared
central_moment_space – If set to True and instance of
is returned. (lbmpy.methods.momentbased.centralmomentbasedmethod.CentralMomentBasedLbMethod) –
the collision will be performend in the central moment space. (Thus) –
central_moment_transform_class – class to transform PDFs to the central moment space.
 Returns

create_generic_mrt
(stencil, moment_eq_value_relaxation_rate_tuples, compressible=False, force_model=None)¶ Creates a generic momentbased LB method.
 Parameters
stencil – sequence of lattice velocities
moment_eq_value_relaxation_rate_tuples – sequence of tuples containing (moment, equilibrium value, relax. rate)
compressible – compressibility, determines calculation of velocity for force models
force_model – see create_with_discrete_maxwellian_eq_moments

create_from_equilibrium
(stencil, equilibrium, moment_to_relaxation_rate_dict, compressible=False, force_model=None)¶ Creates a momentbased LB method using a given equilibrium distribution function
 Parameters
stencil – see create_with_discrete_maxwellian_eq_moments
equilibrium – list of equilibrium terms, dependent on rho and u, one for each stencil direction
moment_to_relaxation_rate_dict – relaxation rate for each moment, or a symbol/float if all should relaxed with the same rate
compressible – see create_with_discrete_maxwellian_eq_moments
force_model – see create_with_discrete_maxwellian_eq_moments

create_srt
(stencil, relaxation_rate, maxwellian_moments=False, **kwargs)¶ Creates a single relaxation time (SRT) lattice Boltzmann model also known as BGK model.
 Parameters
stencil – nested tuple defining the discrete velocity space. See
lbmpy.stencils.get_stencil()
relaxation_rate – relaxation rate (inverse of the relaxation time) usually called \(\omega\) in LBM literature
maxwellian_moments – determines if the discrete or continuous maxwellian equilibrium is used to compute the equilibrium moments
 Returns

create_trt
(stencil, relaxation_rate_even_moments, relaxation_rate_odd_moments, maxwellian_moments=False, **kwargs)¶ Creates a two relaxation time (TRT) lattice Boltzmann model, where even and odd moments are relaxed differently. In the SRT model the exact wall position of noslip boundaries depends on the viscosity, the TRT method does not have this problem.
Parameters are similar to
lbmpy.methods.create_srt()
, but instead of one relaxation rate there are two relaxation rates: one for even moments (determines viscosity) and one for odd moments. If unsure how to choose the odd relaxation rate, use the functionlbmpy.methods.create_trt_with_magic_number()

create_trt_with_magic_number
(stencil, relaxation_rate, magic_number=3 / 16, **kwargs)¶ Creates a two relaxation time (TRT) lattice Boltzmann method, where the relaxation time for odd moments is determines from the even moment relaxation time and a “magic number”. For possible parameters see
lbmpy.methods.create_trt()
 Parameters
stencil – nested tuple defining the discrete velocity space. See
lbmpy.stencils.get_stencil()
relaxation_rate – relaxation rate (inverse of the relaxation time) usually called \(\omega\) in LBM literature
magic_number – magic number which is used to calculate the relxation rate for the odd moments.
 Returns

create_mrt_raw
(stencil, relaxation_rates, maxwellian_moments=False, **kwargs)¶ Creates a MRT method using nonorthogonalized moments.
 Parameters
stencil – nested tuple defining the discrete velocity space. See
lbmpy.stencils.get_stencil()
relaxation_rates – relaxation rates (inverse of the relaxation times) for each moment
maxwellian_moments – determines if the discrete or continuous maxwellian equilibrium is used to compute the equilibrium moments.
 Returns

create_central_moment
(stencil, relaxation_rates, maxwellian_moments=False, **kwargs)¶ Creates moment based LB method where the collision takes place in the central moment space.
 Parameters
stencil – nested tuple defining the discrete velocity space. See
lbmpy.stencils.get_stencil()
relaxation_rates – relaxation rates (inverse of the relaxation times) for each moment
maxwellian_moments – determines if the discrete or continuous maxwellian equilibrium is used to compute the equilibrium moments.
 Returns
lbmpy.methods.momentbased.CentralMomentBasedLbMethod
instance

create_trt_kbc
(dim, shear_relaxation_rate, higher_order_relaxation_rate, method_name='KBCN4', maxwellian_moments=False, **kwargs)¶ Creates a method with two relaxation rates, one for lower order moments which determines the viscosity and one for higher order moments. In entropic models this second relaxation rate is chosen subject to an entropy condition. Which moments are relaxed by which rate is determined by the method_name
 Parameters
dim – 2 or 3, leads to stencil D2Q9 or D3Q27
shear_relaxation_rate – relaxation rate that determines viscosity
higher_order_relaxation_rate – relaxation rate for higher order moments
method_name – string ‘KBCNx’ where x can be an number from 1 to 4, for details see “Karlin 2015: Entropic multi relaxation lattice Boltzmann models for turbulent flows”
maxwellian_moments – determines if the discrete or continuous maxwellian equilibrium is used to compute the equilibrium moments.

create_mrt_orthogonal
(stencil, relaxation_rate_getter, maxwellian_moments=False, weighted=None, nested_moments=None, **kwargs)¶ Returns an orthogonal multirelaxation time model for the stencils D2Q9, D3Q15, D3Q19 and D3Q27. These MRT methods are just one specific version  there are many MRT methods possible for all these stencils which differ by the linear combination of moments and the grouping into equal relaxation times. To create a generic MRT method use
create_with_discrete_maxwellian_eq_moments
 Parameters
stencil – nested tuple defining the discrete velocity space. See
get_stencil
relaxation_rate_getter – function getting a list of moments as argument, returning the associated relaxation
maxwellian_moments – determines if the discrete or continuous maxwellian equilibrium is used to compute the equilibrium moments
weighted – whether to use weighted or unweighted orthogonality
nested_moments – a list of lists of modes, grouped by common relaxation times. This is usually used in conjunction with
mrt_orthogonal_modes_literature
. If this argument is not provided, GramSchmidt orthogonalization of the default modes is performed.

mrt_orthogonal_modes_literature
(stencil, is_weighted)¶ Returns a list of lists of modes, grouped by common relaxation times. This is for commonly used MRT models found in literature.
 Parameters
stencil – nested tuple defining the discrete velocity space. See
get_stencil
is_weighted – whether to use weighted or unweighted orthogonality
MRT schemes as described in the following references are used

create_centered_cumulant_model
(stencil, cumulant_to_rr_dict, force_model=None, equilibrium_order=None, c_s_sq=1/3, galilean_correction=False, central_moment_transform_class=<class 'lbmpy.methods.momentbased.moment_transforms.FastCentralMomentTransform'>, cumulant_transform_class=<class 'lbmpy.methods.centeredcumulant.cumulant_transform.CentralMomentsToCumulantsByGeneratingFunc'>)¶ Creates a cumulant lattice Boltzmann model.
 Parameters
stencil – nested tuple defining the discrete velocity space. See
lbmpy.stencils.get_stencil()
cumulant_to_rr_dict – dict that has as many entries as the stencil. Each cumulant, which can be represented by an exponent tuple or in polynomial form is mapped to a relaxation rate. See
get_default_polynomial_cumulants_for_stencil
force_model – force model used for the collision. For cumulant LB method a good choice is
lbmpy.methods.centeredcumulant.CenteredCumulantForceModel
equilibrium_order – approximation order of macroscopic velocity \(\mathbf{u}\) in the equilibrium
c_s_sq – Speed of sound squared
galilean_correction – special correction for D3Q27 cumulant collisions. See Appendix H in [GSchonherrPK15]. Implemented in
lbmpy.methods.centeredcumulant.galilean_correction
central_moment_transform_class – Class which defines the transformation to the central moment space (see
lbmpy.methods.momentbased.moment_transforms
)cumulant_transform_class – Class which defines the transformation from the central moment space to the cumulant space (see
lbmpy.methods.centeredcumulant.cumulant_transform
)
 Returns
lbmpy.methods.centeredcumulant.CenteredCumulantBasedLbMethod
instance

create_with_polynomial_cumulants
(stencil, relaxation_rates, cumulant_groups, **kwargs)¶ Creates a cumulant lattice Boltzmann model based on a default polynomial set.
 Parameters
stencil – nested tuple defining the discrete velocity space. See
lbmpy.stencils.get_stencil()
relaxation_rates – relaxation rates for each cumulant group. If None are provided a list of symbolic relaxation rates is created and used. If only a list with one entry is provided this relaxation rate is used for determine the viscosity of the simulation. All other cumulants are relaxed with one. If a cumulant force model is provided the first order cumulants are relaxed with two to ensure that the force is applied correctly to the momentum groups
cumulant_groups – Nested sequence of polynomial expressions defining the cumulants to be relaxed. All cumulants within one group are relaxed with the same relaxation rate.
kwargs – See
create_centered_cumulant_model()
 Returns
lbmpy.methods.centeredcumulant.CenteredCumulantBasedLbMethod
instance

create_with_monomial_cumulants
(stencil, relaxation_rates, **kwargs)¶ Creates a cumulant lattice Boltzmann model based on a default polinomial set.
 Parameters
stencil – nested tuple defining the discrete velocity space. See
lbmpy.stencils.get_stencil()
relaxation_rates – relaxation rates for each cumulant group. If None are provided a list of symbolic relaxation rates is created and used. If only a list with one entry is provided this relaxation rate is used for determine the viscosity of the simulation. All other cumulants are relaxed with one. If a cumulant force model is provided the first order cumulants are relaxed with two to ensure that the force is applied correctly to the momentum groups
kwargs – See
create_centered_cumulant_model()
 Returns
lbmpy.methods.centeredcumulant.CenteredCumulantBasedLbMethod
instance

create_with_default_polynomial_cumulants
(stencil, relaxation_rates, **kwargs)¶ Creates a cumulant lattice Boltzmann model based on a default polynomial set.
Args: See
create_with_polynomial_cumulants()
. Returns
lbmpy.methods.centeredcumulant.CenteredCumulantBasedLbMethod
instance