# 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, cumulant=False, c_s_sq=1 / 3)

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

• cumulant – if True relax cumulants instead of moments

• c_s_sq – Speed of sound squared

Returns
create_with_continuous_maxwellian_eq_moments(stencil, moment_to_relaxation_rate_dict, compressible=False, force_model=None, equilibrium_order=2, cumulant=False, c_s_sq=1 / 3)

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.

create_generic_mrt(stencil, moment_eq_value_relaxation_rate_tuples, compressible=False, force_model=None, cumulant=False)

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

• cumulant – true for cumulant methods, False for moment-based methods

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()

create_mrt_raw(stencil, relaxation_rates, maxwellian_moments=False, **kwargs)

Creates a MRT method using non-orthogonalized moments.

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, is_cumulant)

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

• is_cumulant – whether a moment-based or cumulant-based model is desired

MRT schemes as described in the following references are used