Moments

Module Overview

This module provides functions to

  • generate moments according to certain patterns

  • compute moments of discrete probability distribution functions

  • create transformation rules into moment space

  • orthogonalize moment bases

Moment Representation

Moments can be represented in two ways:

  • by an index \(i,j\): defined as \(m_{ij} := \sum_{\mathbf{d} \in stencil} <\mathbf{d}, \mathbf{x}> f_i\)

  • or by a polynomial in the variables x,y and z. For example the polynomial \(x^2 y^1 z^3 + x + 1\) is describing the linear combination of moments: \(m_{213} + m_{100} + m_{000}\)

The polynomial description is more powerful, since one polynomial can express a linear combination of single moments. All moment polynomials have to use MOMENT_SYMBOLS (which is a module variable) as degrees of freedom.

Example

>>> from lbmpy.moments import MOMENT_SYMBOLS
>>> x, y, z = MOMENT_SYMBOLS
>>> second_order_moment = x*y + y*z

Functions

moment_multiplicity(exponent_tuple)

Returns number of permutations of the given moment tuple

Example: >>> moment_multiplicity((2,0,0)) 3 >>> list(moment_permutations((2,0,0))) [(0, 0, 2), (0, 2, 0), (2, 0, 0)]

pick_representative_moments(moments)

Picks the representative i.e. of each permutation group only one is kept

moment_permutations(exponent_tuple)

Returns all (unique) permutations of the given tuple

moments_of_order(order, dim=3, include_permutations=True)

All tuples of length ‘dim’ which sum equals ‘order’

moments_up_to_order(order, dim=3, include_permutations=True)

All tuples of length ‘dim’ which sum is smaller than ‘order’

moments_up_to_component_order(order, dim=3)

All tuples of length ‘dim’ where each entry is smaller or equal to ‘order’

extend_moments_with_permutations(exponent_tuples)

Returns all permutations of the given exponent tuples

exponent_to_polynomial_representation(exponent_tuple)

Converts an exponent tuple to corresponding polynomial representation

Example

>>> exponent_to_polynomial_representation( (2,1,3) )
x**2*y*z**3
exponents_to_polynomial_representations(sequence_of_exponent_tuples)

Applies exponent_to_polynomial_representation() to given sequence

polynomial_to_exponent_representation(polynomial, dim=3)

Converts a linear combination of moments in polynomial representation into exponent representation

:returns list of tuples where the first element is the coefficient and the second element is the exponent tuple

Example

>>> x , y, z = MOMENT_SYMBOLS
>>> set(polynomial_to_exponent_representation(1 + (42 * x**2 * y**2 * z) )) == {(42, (2, 2, 1)), (1, (0, 0, 0))}
True
moment_sort_key(moment)

Sort key function for moments to sort them by (in decreasing priority) order, number of occuring symbols, length of string representation, string representation

sort_moments_into_groups_of_same_order(moments)

Returns a dictionary mapping the order (int) to a list of moments with that order.

is_even(moment)

A moment is considered even when under sign reversal nothing changes i.e. \(m(-x,-y,-z) = m(x,y,z)\)

For the exponent tuple representation that means that the exponent sum is even e.g.
>>> x , y, z = MOMENT_SYMBOLS
>>> is_even(x**2 * y**2)
True
>>> is_even(x**2 * y)
False
>>> is_even((1,0,0))
False
>>> is_even(1)
True
get_moment_indices(moment_exponent_tuple)

Returns indices for a given exponent tuple:

Example

>>> get_moment_indices((2,1,0))
[0, 0, 1]
>>> get_moment_indices((0,0,3))
[2, 2, 2]
get_order(moment)

Computes polynomial order of given moment.

Examples

>>> x , y, z = MOMENT_SYMBOLS
>>> get_order(x**2 * y + x)
3
>>> get_order(z**4 * x**2)
6
>>> get_order((2,1,0))
3
non_aliased_moment(moment_tuple)

Takes a moment exponent tuple and returns the non-aliased version of it.

For first neighborhood stencils, all moments with exponents 3, 5, 7… are equal to exponent 1, and exponents 4, 6, 8… are equal to exponent 2. This is because first neighborhood stencils only have values d ∈ {+1, 0, -1}. So for example d**5 is always the same as d**3 and d, and d**6 == d**4 == d**2

Example

>>> non_aliased_moment((5, 4, 2))
(1, 2, 2)
>>> non_aliased_moment((9, 1, 2))
(1, 1, 2)
Return type

Tuple[int, …]

is_bulk_moment(moment, dim)

The bulk moment is x**2+y**2+z**2

is_shear_moment(moment, dim)

Shear moments are the quadratic polynomials except for the bulk moment. Linear combinations with lower-order polynomials don’t harm because these correspond to conserved moments.

discrete_moment(func, moment, stencil, shift_velocity=None)

Computes discrete moment of given distribution function

\[\sum_{d \in stencil} p(d) f_i\]

where \(p(d)\) is the moment polynomial where \(x, y, z\) have been replaced with the components of the stencil direction, and \(f_i\) is the i’th entry in the passed function sequence

Parameters
  • func – list of distribution functions for each direction

  • moment – can either be a exponent tuple, or a sympy polynomial expression

  • stencil – sequence of directions

  • shift_velocity – velocity vector u to compute central moments, the lattice velocity is replaced by (lattice_velocity - shift_velocity)

moment_matrix(moments, stencil, shift_velocity=None)

Returns transformation matrix to moment space

each row corresponds to a moment, each column to a direction of the stencil The entry i,j is the i’th moment polynomial evaluated at direction j

gram_schmidt(moments, stencil, weights=None)

Computes orthogonal set of moments using the method by Gram-Schmidt

Parameters
  • moments – sequence of moments, either in tuple or polynomial form

  • stencil – stencil as sequence of directions

  • weights – optional weights, that define the scalar product which is used for normalization. Scalar product \(< a,b > = \sum a_i b_i w_i\) with weights \(w_i\). Passing no weights sets all weights to 1.

Returns

set of orthogonal moments in polynomial form

get_default_moment_set_for_stencil(stencil)

Returns a sequence of moments that are commonly used to construct a LBM equilibrium for the given stencil

extract_monomials(sequence_of_polynomials, dim=3)

Returns a set of exponent tuples of all monomials contained in the given set of polynomials

Parameters
  • sequence_of_polynomials – sequence of polynomials in the MOMENT_SYMBOLS

  • dim – length of returned exponent tuples

>>> x, y, z = MOMENT_SYMBOLS
>>> extract_monomials([x**2 + y**2 + y, y + y**2])
{(0, 2, 0), (0, 1, 0), (2, 0, 0)}
>>> extract_monomials([x**2 + y**2 + y, y + y**2], dim=2)
{(0, 1), (0, 2), (2, 0)}
monomial_to_polynomial_transformation_matrix(monomials, polynomials)

Returns a transformation matrix from a monomial to a polynomial representation

Parameters
  • monomials – sequence of exponent tuples

  • polynomials – sequence of polynomials in the MOMENT_SYMBOLS

>>> x, y, z = MOMENT_SYMBOLS
>>> polys = [7 * x**2 + 3 * x + 2 * y **2,                  9 * x**2 - 5 * x]
>>> mons = list(extract_monomials(polys, dim=2))
>>> monomial_to_polynomial_transformation_matrix(mons, polys)
Matrix([
[ 3, 2, 7],
[-5, 0, 9]])
moment_equality_table(stencil, discrete_equilibrium=None, continuous_equilibrium=None, max_order=4, truncate_order=3)

Creates a table showing which moments of a discrete stencil/equilibrium coincide with the corresponding continuous moments

Parameters
  • stencil – list of stencil velocities

  • discrete_equilibrium – list of sympy expr to compute discrete equilibrium for each direction, if left to default the standard discrete Maxwellian equilibrium is used

  • continuous_equilibrium – continuous equilibrium, if left to default, the continuous Maxwellian is used

  • max_order – compare moments up to this order (number of rows in table)

  • truncate_order – moments are considered equal if they match up to this order

Returns

Object to display in an Jupyter notebook

moment_equality_table_by_stencil(name_to_stencil_dict, moments, truncate_order=3)

Creates a table for display in IPython notebooks that shows which moments agree between continuous and discrete equilibrium, group by stencils

Parameters
  • name_to_stencil_dict – dict from stencil name to stencil

  • moments – sequence of moments to compare - assumes that permutations have similar properties so just one representative is shown labeled with its multiplicity

  • truncate_order – compare up to this order