Methods (lbmpy.methods)

LBM Method Interfaces

class LbmCollisionRule(lb_method, *args, **kwargs)

A pystencils AssignmentCollection that additionally holds an AbstractLbMethod

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 property relaxation_rates

Tuple containing the relaxation rates of each moment

property relaxation_matrix

Returns a qxq diagonal matrix which contains the relaxation rate for each moment on the diagonal

property symbolic_relaxation_matrix

Returns a qxq diagonal matrix which contains the relaxation rate for each moment on the diagonal. In contrast to the normal relaxation matrix all numeric values are replaced by sympy symbols

property subs_dict_relxation_rate

returns a dictonary which maps the replaced numerical relaxation rates to its original numerical value

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.

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.

../_images/moment_shift.svg
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() and equilibrium_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.

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), second_order_moment_symbols=(p_0, p_1, p_2, p_3, p_4, p_5, p_6, p_7, p_8))
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() and equilibrium_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, force_substitution=True)

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), force_substitution=True)

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, force_substitution=True)

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

Moment-based 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 – 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

lbmpy.methods.momentbased.MomentBasedLbMethod instance

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

lbmpy.methods.momentbased.MomentBasedLbMethod instance

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_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_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

Class

class MomentBasedLbMethod(stencil, moment_to_relaxation_info_dict, conserved_quantity_computation=None, force_model=None, moment_transform_class=<class 'lbmpy.moment_transforms.rawmomenttransforms.PdfsToMomentsByChimeraTransform'>)
property moment_space_collision

Returns whether collision is derived in terms of moments or in terms of populations only.

property conserved_quantity_computation

Returns an instance of class lbmpy.methods.AbstractConservedQuantityComputation

property relaxation_rates

Tuple containing the relaxation rates of each moment

property weights

Returns a sequence of weights, one for each lattice direction

get_equilibrium(conserved_quantity_equations=None, include_force_terms=False, pre_simplification=False, subexpressions=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

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.

Cumulant-based methods

Creation Functions

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

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 – 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

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

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 [GSchonherrPK15]. 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

lbmpy.methods.centeredcumulant.CenteredCumulantBasedLbMethod instance

Utility

class CenteredCumulantForceModel(force)

A force model to be used with the centered cumulant-based LB Method. It only shifts the macroscopic and equilibrium velocities and does not introduce a forcing term to the collision process. Forcing is then applied through relaxation of the first central moments in the shifted frame of reference (cf. https://doi.org/10.1016/j.camwa.2015.05.001).

Parameters

force – force vector which should be applied to the fluid

equilibrium_velocity_shift(density)

Some models also shift the velocity entering the equilibrium distribution. By default the shift is zero

Parameters

density – Density symbol which is needed for the shift

Class

class CenteredCumulantBasedLbMethod(stencil, cumulant_to_relaxation_info_dict, conserved_quantity_computation, force_model=None, galilean_correction=False, central_moment_transform_class=<class 'lbmpy.moment_transforms.centralmomenttransforms.PdfsToCentralMomentsByShiftMatrix'>, cumulant_transform_class=<class 'lbmpy.methods.centeredcumulant.cumulant_transform.CentralMomentsToCumulantsByGeneratingFunc'>)

This class implements cumulant-based lattice boltzmann methods which relax all the non-conserved 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 central-moment frame of reference by \(F/2\) and then relaxing the first-order central moments with a relaxation rate of two. This corresponds to the change-of-sign 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.moment_transforms.AbstractMomentTransform which can be specified by constructor argument. This allows the selection of the most efficient transformation for a given setup.

Parameters
  • stencil – see lbmpy.stencils.LBStencil

  • cumulant_to_relaxation_info_dict – a dictionary mapping cumulants in either tuple or polynomial formulation to a RelaxationInfo, which consists of the corresponding equilibrium cumulant and a relaxation rate

  • conserved_quantity_computation – instance of lbmpy.methods.AbstractConservedQuantityComputation. This determines how conserved quantities are computed, and defines the symbols used in the equilibrium moments like e.g. density and velocity

  • force_model – force model instance, or None if no forcing terms are required

  • galilean_correction – if set to True the galilean_correction is applied to a D3Q27 cumulant method

  • central_moment_transform_class – transform class to get from PDF space to the central moment space

  • cumulant_transform_class – transform class to get from the central moment space to the cumulant space

property relaxation_rates

Tuple containing the relaxation rates of each moment

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.

Default Moment sets

cascaded_moment_sets_literature(stencil)

Returns default groups of cumulants to be relaxed with common relaxation rates as stated in literature. Groups are ordered like this:

  • First group is density

  • Second group are the momentum modes

  • Third group are the shear modes

  • Fourth group is the bulk mode

  • Remaining groups do not govern hydrodynamic properties

Parameters

stencil – instance of lbmpy.stencils.LBStencil. Can be D2Q9, D3Q7, D3Q15, D3Q19 or D3Q27

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 – instance of lbmpy.stencils.LBStencil. Can be D2Q9, D3Q15, D3Q19 or D3Q27

  • is_weighted – whether to use weighted or unweighted orthogonality

MRT schemes as described in the following references are used