Methods (lbmpy.methods)¶
LBM Method Interfaces¶

class
AbstractLbMethod
(stencil)¶ Abstract base class for all LBM methods.

property
stencil
¶ Discrete set of velocities, represented as nested tuple

property
pre_collision_pdf_symbols
¶ Tuple of symbols representing the pdf values before collision

property
post_collision_pdf_symbols
¶ Tuple of symbols representing the pdf values after collision

abstract
conserved_quantity_computation
()¶ Returns an instance of class
lbmpy.methods.AbstractConservedQuantityComputation

abstract
weights
()¶ Returns a sequence of weights, one for each lattice direction

abstract
get_equilibrium
()¶ Returns equation collection, to compute equilibrium values. The equations have the post collision symbols as left hand sides and are functions of the conserved quantities

abstract
get_collision_rule
()¶ Returns an LbmCollisionRule i.e. an equation collection with a reference to the method. This collision rule defines the collision operator.

property

class
AbstractConservedQuantityComputation
¶ This class defines how conserved quantities are computed as functions of the pdfs. Conserved quantities are used for output and as input to the equilibrium in the collision step
Depending on the method they might also be computed slightly different, e.g. due to a force model.
An additional method describes how to get the conserved quantities for the equilibrium for initialization. In most cases the inputs can be used directly, but for some methods they have to be altered slightly. For example in zero centered hydrodynamic schemes with force model, the density has to be decreased by one, and the given velocity has to be shifted dependent on the force.

abstract property
conserved_quantities
¶ Dict, mapping names (symbol) to dimensionality (int) For example: {‘density’ : 1, ‘velocity’ : 3} The naming strings can be used in
output_equations_from_pdfs()
andequilibrium_input_equations_from_init_values()

defined_symbols
(order='all')¶ Returns a dict, mapping names of conserved quantities to their symbols

abstract property
default_values
¶ Returns a dict of symbol to default value, where “default” means that the equilibrium simplifies to the weights if these values are inserted. Hydrodynamic example: rho=1, u_i = 0

abstract
equilibrium_input_equations_from_pdfs
(pdfs)¶ Returns an equation collection that defines all necessary quantities to compute the equilibrium as functions of the pdfs. For hydrodynamic LBM schemes this is usually the density and velocity.
 Parameters
pdfs – values or symbols for the pdf values

abstract
output_equations_from_pdfs
(pdfs, output_quantity_names_to_symbols)¶ Returns an equation collection that defines conserved quantities for output. These conserved quantities might be slightly different that the ones used as input for the equilibrium e.g. due to a force model.
 Parameters
pdfs – values for the pdf entries
output_quantity_names_to_symbols – dict mapping of conserved quantity names (See
conserved_quantities()
) to symbols or field accesses where they should be written to

abstract
equilibrium_input_equations_from_init_values
(**kwargs)¶ Returns an equation collection that defines all necessary quantities to compute the equilibrium as function of given conserved quantities. Parameters can be names that are given by symbol names of
conserved_quantities()
. For all parameters not specified each implementation should use sensible defaults. For example hydrodynamic schemes use density=1 and velocity=0.

abstract property
LBM with conserved zeroth and first order¶

class
DensityVelocityComputation
(stencil, compressible, force_model=None, zeroth_order_moment_symbol=rho, first_order_moment_symbols=(u_0, u_1, u_2))¶ 
property
conserved_quantities
¶ Dict, mapping names (symbol) to dimensionality (int) For example: {‘density’ : 1, ‘velocity’ : 3} The naming strings can be used in
output_equations_from_pdfs()
andequilibrium_input_equations_from_init_values()

defined_symbols
(order='all')¶ Returns a dict, mapping names of conserved quantities to their symbols

property
default_values
¶ Returns a dict of symbol to default value, where “default” means that the equilibrium simplifies to the weights if these values are inserted. Hydrodynamic example: rho=1, u_i = 0

equilibrium_input_equations_from_pdfs
(pdfs)¶ Returns an equation collection that defines all necessary quantities to compute the equilibrium as functions of the pdfs. For hydrodynamic LBM schemes this is usually the density and velocity.
 Parameters
pdfs – values or symbols for the pdf values

equilibrium_input_equations_from_init_values
(density=1, velocity=(0, 0, 0))¶ Returns an equation collection that defines all necessary quantities to compute the equilibrium as function of given conserved quantities. Parameters can be names that are given by symbol names of
conserved_quantities()
. For all parameters not specified each implementation should use sensible defaults. For example hydrodynamic schemes use density=1 and velocity=0.

output_equations_from_pdfs
(pdfs, output_quantity_names_to_symbols)¶ Returns an equation collection that defines conserved quantities for output. These conserved quantities might be slightly different that the ones used as input for the equilibrium e.g. due to a force model.
 Parameters
pdfs – values for the pdf entries
output_quantity_names_to_symbols – dict mapping of conserved quantity names (See
conserved_quantities()
) to symbols or field accesses where they should be written to

property
Momentbased methods¶
Creation Functions¶

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()
:param stencil: nested tuple defining the discrete velocity space. Seelbmpy.stencils.get_stencil()
:param relaxation_rate: relaxation rate (inverse of the relaxation time)usually called \(\omega\) in LBM literature
 Parameters
magic_number – magic number which is used to calculate the relxation rate for the odd moments.
 Returns

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.

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)¶ 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
 Returns

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)¶ 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
 Returns
Class¶

class
MomentBasedLbMethod
(stencil, moment_to_relaxation_info_dict, conserved_quantity_computation=None, force_model=None)¶ 
property
conserved_quantity_computation
¶ Returns an instance of class
lbmpy.methods.AbstractConservedQuantityComputation

property
weights
¶ Returns a sequence of weights, one for each lattice direction

get_equilibrium
(conserved_quantity_equations=None, include_force_terms=False)¶ Returns equation collection, to compute equilibrium values. The equations have the post collision symbols as left hand sides and are functions of the conserved quantities

get_collision_rule
(conserved_quantity_equations=None, pre_simplification=True)¶ Returns an LbmCollisionRule i.e. an equation collection with a reference to the method. This collision rule defines the collision operator.

property

class
CenteredCumulantBasedLbMethod
(stencil, cumulant_to_relaxation_info_dict, conserved_quantity_computation, force_model=None, galilean_correction=False, central_moment_transform_class=<class 'lbmpy.methods.momentbased.moment_transforms.FastCentralMomentTransform'>, cumulant_transform_class=<class 'lbmpy.methods.centeredcumulant.cumulant_transform.CentralMomentsToCumulantsByGeneratingFunc'>)¶ This class implements cumulantbased lattice boltzmann methods which relax all the nonconserved quantities as either monomial or polynomial cumulants. It is mostly inspired by the work presented in [GSchonherrPK15].
Conserved quantities are relaxed in central moment space. This method supports an implicit forcing scheme through
lbmpy.methods.centeredcumulant.CenteredCumulantForceModel
where forces are applied by shifting the centralmoment frame of reference by \(F/2\) and then relaxing the firstorder central moments with a relaxation rate of two. This corresponds to the changeofsign described in the paper. Classical forcing schemes can still be applied.The galilean correction described in [GSchonherrPK15] is also available for the D3Q27 lattice.
This method is implemented modularily as the transformation from populations to central moments to cumulants is governed by subclasses of
lbmpy.methods.momentbased.moment_transforms.AbstractMomentTransform
which can be specified by constructor argument. This allows the selection of the most efficient transformation for a given setup.
property
conserved_quantity_computation
¶ Returns an instance of class
lbmpy.methods.AbstractConservedQuantityComputation

property
weights
¶ Returns a sequence of weights, one for each lattice direction

get_equilibrium
(conserved_quantity_equations=None, subexpressions=False, pre_simplification=False, keep_cqc_subexpressions=True)¶ Returns equation collection, to compute equilibrium values. The equations have the post collision symbols as left hand sides and are functions of the conserved quantities
 Parameters
conserved_quantity_equations – equations to compute conserved quantities.
subexpressions – if set to false all subexpressions of the equilibrium assignments are plugged into the main assignments
pre_simplification – with or without pre_simplifications for the calculation of the collision
keep_cqc_subexpressions – if equilibrium is returned without subexpressions keep_cqc_subexpressions determines if also subexpressions to calculate conserved quantities should be plugged into the main assignments

get_collision_rule
(conserved_quantity_equations=None, pre_simplification=False)¶ Returns an LbmCollisionRule i.e. an equation collection with a reference to the method. This collision rule defines the collision operator.

property