# 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, moment_transform_class=None, central_moment_transform_class=<class 'lbmpy.moment_transforms.centralmomenttransforms.PdfsToCentralMomentsByShiftMatrix'>)

Creates a moment-based 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 – instance of lbmpy.stencils.LBStenil

• 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 Navier-Stokes 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, an instance of lbmpy.methods.momentbased.CentralMomentBasedLbMethod is returned, and the the collision will be performed in the central moment space.

• moment_transform_class – Class implementing the transform from populations to moment space.

• central_moment_transform_class – Class implementing the transform from populations to central moment space.

Returns

Instance of either lbmpy.methods.momentbased.MomentBasedLbMethod or lbmpy.methods.momentbased.CentralMomentBasedLbMethod

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, moment_transform_class=None, central_moment_transform_class=<class 'lbmpy.moment_transforms.centralmomenttransforms.PdfsToCentralMomentsByShiftMatrix'>)

Creates a moment-based 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 – instance of lbmpy.stencils.LBStencil

• 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 Navier-Stokes 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, an instance of lbmpy.methods.momentbased.CentralMomentBasedLbMethod is returned, and the the collision will be performed in the central moment space.

• moment_transform_class – Class implementing the transform from populations to moment space.

• central_moment_transform_class – Class implementing the transform from populations to central moment space.

Returns

Instance of either lbmpy.methods.momentbased.MomentBasedLbMethod or lbmpy.methods.momentbased.CentralMomentBasedLbMethod

create_generic_mrt(stencil, moment_eq_value_relaxation_rate_tuples, compressible=False, force_model=None, moment_transform_class=<class 'lbmpy.moment_transforms.rawmomenttransforms.PdfsToMomentsByChimeraTransform'>)

Creates a generic moment-based LB method.

Parameters
• stencil – instance of lbmpy.stencils.LBStencil

• 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

• moment_transform_class – class to define the transformation to the moment space

create_from_equilibrium(stencil, equilibrium, moment_to_relaxation_rate_dict, compressible=False, force_model=None, moment_transform_class=<class 'lbmpy.moment_transforms.rawmomenttransforms.PdfsToMomentsByChimeraTransform'>)

Creates a moment-based LB method using a given equilibrium distribution function

Parameters
• stencil – instance of lbmpy.stencils.LBStencil

• 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

• moment_transform_class – class to define the transformation to the moment space

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 – instance of lbmpy.stencils.LBStencil

• 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 no-slip 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 function lbmpy.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 – instance of lbmpy.stencils.LBStencil

• 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 non-orthogonalized moments.

Parameters
• stencil – instance of lbmpy.stencils.LBStencil

• 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, nested_moments=None, maxwellian_moments=False, **kwargs)

Creates moment based LB method where the collision takes place in the central moment space.

Parameters
• stencil – instance of lbmpy.stencils.LBStencil

• relaxation_rates – relaxation rates (inverse of the relaxation times) for each moment

• nested_moments – a list of lists of modes, grouped by common relaxation times.

• 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='KBC-N4', 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 ‘KBC-Nx’ 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_rates, maxwellian_moments=False, weighted=None, nested_moments=None, **kwargs)

Returns an orthogonal multi-relaxation 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 – instance of lbmpy.stencils.LBStencil

• relaxation_rates – relaxation rates for the moments

• 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. If this argument is not provided, Gram-Schmidt orthogonalization of the default modes is performed. The default modes equal the raw moments except for the separation of the shear and bulk viscosity.

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.moment_transforms.centralmomenttransforms.PdfsToCentralMomentsByShiftMatrix'>, cumulant_transform_class=<class 'lbmpy.methods.centeredcumulant.cumulant_transform.CentralMomentsToCumulantsByGeneratingFunc'>)

Creates a cumulant lattice Boltzmann model.

Parameters
• stencil – instance of lbmpy.stencils.LBStencil

• 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 lbmpy.methods.default_moment_sets.cascaded_moment_sets_literature()

• 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 . Implemented in lbmpy.methods.centeredcumulant.galilean_correction

• central_moment_transform_class – Class which defines the transformation to the central moment space (see lbmpy.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
create_with_polynomial_cumulants(stencil, relaxation_rates, cumulant_groups, **kwargs)

Creates a cumulant lattice Boltzmann model based on a default polynomial set.

Parameters
• stencil – instance of lbmpy.stencils.LBStencil

• 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
create_with_monomial_cumulants(stencil, relaxation_rates, **kwargs)

Creates a cumulant lattice Boltzmann model based on a default polinomial set.

Parameters
• stencil – instance of lbmpy.stencils.LBStencil

• 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
create_with_default_polynomial_cumulants(stencil, relaxation_rates, **kwargs)

Creates a cumulant lattice Boltzmann model based on a default polynomial set.

Returns