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
- contained_moments(exponent_tuple, min_order=0, exclude_original=True)¶
Returns all moments contained in exponent_tuple, in the sense that their exponents are less than or equal to the corresponding exponents in exponent_tuple.
- 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)
- aliases_from_moment_list(moment_exponents, stencil)¶
Takes a list of moment exponent tuples and finds aliases within it according the given stencil. Two moments are aliases of each other on a stencil if they produce the same coefficients in the moment sum over all populations.
Apart from the obvious aliases (e.g.
(4,0,0)
to(2,0,0)
, etc), there are aliasing effects for example on the D3Q15 stencil, where some third and fourth order moments are the same.
- non_aliased_polynomial_raw_moments(polys, stencil, nested=False)¶
Takes a (potentially nested) list of raw moment polynomials and rewrites them by eliminating any aliased monomials.
All polynomials are expanded and occuring monomials are collected. Using
aliases_from_moment_list
, aliases are eliminated and substituted in the polynomials.Attention: Only use this method for monomials in raw moment space. It will produce wrong results if used for central moments, since there is no direct aliasing in central moment space!
- 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 \(\mathbf{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
- set_up_shift_matrix(moments, stencil, velocity_symbols=(u_0, u_1, u_2))¶
Sets up a shift matrix to shift raw moments to central moment space.
- Parameters
moments (-) – Sequence of polynomials or sequence of exponent tuples, sorted ascendingly by moment order.
stencil (-) – Nested tuple of lattice velocities
velocity_symbols (-) – Sequence of symbols corresponding to the shift velocity
- 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 \(< \mathbf{a},\mathbf{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, 1, 0),(0, 2, 0),(2, 0, 0)} True >>> extract_monomials([x**2 + y**2 + y, y + y**2], dim=2) == {(0, 1), (0, 2), (2, 0)} True
- 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)) >>> mons.sort() >>> monomial_to_polynomial_transformation_matrix(mons, polys) Matrix([ [2, 3, 7], [0, -5, 9]])
- central_moment_reduced_monomial_to_polynomial_matrix(polynomials, stencil, velocity_symbols=None)¶
Returns a transformation matrix from a reduced set of monomial central moments to a set of polynomial central moments.
Use for a set of \(q\) central moment polynomials that reduces to a too-large set of \(r > q\) monomials (as given by
extract_monomials
). Reduces the monomials by eliminating aliases in raw moment space, and computes a reduced polynomialization matrix \(\mathbf{P}^{r}\) that computes the given polynomials from the reduced set of monomials.
- 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