# 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 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 – 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 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 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 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 – 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 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 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 moment-based 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 moment-based 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 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 – 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 non-orthogonalized 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='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_rate_getter, 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 – 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, Gram-Schmidt 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 . 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
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
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
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