Commit 78fd2f4a authored by Markus Holzer's avatar Markus Holzer Committed by Michael Kuron
Browse files

Extend and fix documentation

parent 60cc8e15
......@@ -202,7 +202,6 @@ build-documentation:
- export PYTHONPATH=`pwd`
- pip install git+https://gitlab-ci-token:${CI_JOB_TOKEN}@i10git.cs.fau.de/pycodegen/pystencils.git@master#egg=pystencils
- mkdir html_doc
- sphinx-build -b html doc html_doc
- sphinx-build -W -b html doc html_doc
tags:
- docker
......
This diff is collapsed.
......@@ -49,6 +49,33 @@ Class
.. autoclass:: lbmpy.methods.momentbased.MomentBasedLbMethod
:members:
Cumulant-based methods
======================
Creation Functions
------------------
.. autofunction:: lbmpy.methods.create_with_polynomial_cumulants
.. autofunction:: lbmpy.methods.create_with_monomial_cumulants
.. autofunction:: lbmpy.methods.create_with_default_polynomial_cumulants
.. autofunction:: lbmpy.methods.create_centered_cumulant_model
Utility
-------
.. autofunction:: lbmpy.methods.centeredcumulant.get_default_polynomial_cumulants_for_stencil
.. autoclass:: lbmpy.methods.centeredcumulant.CenteredCumulantForceModel
:members:
Class
-----
.. autoclass:: lbmpy.methods.centeredcumulant.CenteredCumulantBasedLbMethod
:members:
......@@ -85,8 +85,8 @@ class LbBoundary:
class NoSlip(LbBoundary):
"""
No-Slip, (half-way) simple bounce back boundary condition, enforcing zero velocity at obstacle.
Extended for use with any streaming pattern.
No-Slip, (half-way) simple bounce back boundary condition, enforcing zero velocity at obstacle.
Extended for use with any streaming pattern.
Args:
name: optional name of the boundary.
......@@ -218,9 +218,9 @@ class UBB(LbBoundary):
class SimpleExtrapolationOutflow(LbBoundary):
r"""
Simple Outflow boundary condition :cite:`geier2015`, equation F.1 (listed below).
This boundary condition extrapolates missing populations from the last layer of
fluid cells onto the boundary by copying them in the normal direction.
Simple Outflow boundary condition :cite:`geier2015`, equation F.1 (listed below).
This boundary condition extrapolates missing populations from the last layer of
fluid cells onto the boundary by copying them in the normal direction.
.. math ::
f_{\overline{1}jkxyzt} = f_{\overline{1}jk(x - \Delta x)yzt}
......@@ -264,11 +264,11 @@ class SimpleExtrapolationOutflow(LbBoundary):
class ExtrapolationOutflow(LbBoundary):
r"""
Outflow boundary condition :cite:`geier2015`, equation F.2, with u neglected (listed below).
This boundary condition interpolates populations missing on the boundary in normal direction.
For this interpolation, the PDF values of the last time step are used. They are interpolated
between fluid cell and boundary cell. To get the PDF values from the last time step an index
array is used which stores them.
Outflow boundary condition :cite:`geier2015`, equation F.2, with u neglected (listed below).
This boundary condition interpolates populations missing on the boundary in normal direction.
For this interpolation, the PDF values of the last time step are used. They are interpolated
between fluid cell and boundary cell. To get the PDF values from the last time step an index
array is used which stores them.
.. math ::
f_{\overline{1}jkxyzt} = f_{\overline{1}jk(x - \Delta x)yz(t - \Delta t)} c \theta^{\frac{1}{2}}
......
......@@ -2,7 +2,8 @@ from lbmpy.methods.creationfunctions import (
create_mrt_orthogonal, create_mrt_raw, create_srt, create_trt, create_trt_kbc,
create_trt_with_magic_number, create_with_continuous_maxwellian_eq_moments,
create_with_discrete_maxwellian_eq_moments, mrt_orthogonal_modes_literature,
create_centered_cumulant_model, create_with_default_polynomial_cumulants)
create_centered_cumulant_model, create_with_default_polynomial_cumulants,
create_with_polynomial_cumulants, create_with_monomial_cumulants)
from lbmpy.methods.abstractlbmethod import AbstractLbMethod, RelaxationInfo
from lbmpy.methods.conservedquantitycomputation import AbstractConservedQuantityComputation
......@@ -15,4 +16,5 @@ __all__ = ['RelaxationInfo', 'AbstractLbMethod',
'create_mrt_orthogonal', 'create_mrt_raw',
'create_with_continuous_maxwellian_eq_moments', 'create_with_discrete_maxwellian_eq_moments',
'mrt_orthogonal_modes_literature', 'create_centered_cumulant_model',
'create_with_default_polynomial_cumulants']
'create_with_default_polynomial_cumulants', 'create_with_polynomial_cumulants',
'create_with_monomial_cumulants']
from .force_model import CenteredCumulantForceModel
from .centeredcumulantmethod import CenteredCumulantBasedLbMethod
from .centered_cumulants import get_default_polynomial_cumulants_for_stencil
__all__ = ["CenteredCumulantForceModel", "CenteredCumulantBasedLbMethod"]
__all__ = ['CenteredCumulantForceModel', 'CenteredCumulantBasedLbMethod',
'get_default_polynomial_cumulants_for_stencil']
......@@ -18,11 +18,15 @@ def get_default_polynomial_cumulants_for_stencil(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
- 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
Args:
stencil: can be D2Q9, D2Q19 or D3Q27
"""
x, y, z = MOMENT_SYMBOLS
if have_same_entries(stencil, get_stencil("D2Q9")):
......
......@@ -107,21 +107,34 @@ def relax_polynomial_cumulants(monomial_exponents, polynomials, relaxation_rates
class CenteredCumulantBasedLbMethod(AbstractLbMethod):
"""
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 :cite:`geier2015`.
Conserved quantities are relaxed in central moment space. This method supports an implicit forcing scheme
through :class:`lbmpy.methods.centeredcumulant.CenteredCumulantForceModel` where forces are applied by
shifting the central-moment frame of reference by :math:`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 :cite:`geier2015` 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 :class:`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.
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 :cite:`geier2015`.
Conserved quantities are relaxed in central moment space. This method supports an implicit forcing scheme
through :class:`lbmpy.methods.centeredcumulant.CenteredCumulantForceModel` where forces are applied by
shifting the central-moment frame of reference by :math:`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 :cite:`geier2015` 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 :class:`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.
Args:
stencil: see :func:`lbmpy.stencils.get_stencil`
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 :class:`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
"""
def __init__(self, stencil, cumulant_to_relaxation_info_dict, conserved_quantity_computation, force_model=None,
......
......@@ -6,11 +6,13 @@ from lbmpy.forcemodels import default_velocity_shift
class CenteredCumulantForceModel:
"""
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).
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).
Args:
force: force vector which should be applied to the fluid
"""
def __init__(self, force):
......
......@@ -10,14 +10,16 @@ from lbmpy.maxwellian_equilibrium import (
get_moments_of_continuous_maxwellian_equilibrium,
get_moments_of_discrete_maxwellian_equilibrium, get_weights)
from lbmpy.methods.abstractlbmethod import RelaxationInfo
from lbmpy.methods.centeredcumulant import CenteredCumulantBasedLbMethod
from lbmpy.methods.centeredcumulant.centered_cumulants import get_default_polynomial_cumulants_for_stencil
from lbmpy.methods.momentbased.moment_transforms import PdfsToCentralMomentsByShiftMatrix
from lbmpy.methods.centeredcumulant.cumulant_transform import CentralMomentsToCumulantsByGeneratingFunc
from lbmpy.methods.abstractlbmethod import RelaxationInfo
from lbmpy.methods.conservedquantitycomputation import DensityVelocityComputation
from lbmpy.methods.centeredcumulant import CenteredCumulantBasedLbMethod
from lbmpy.methods.momentbased.momentbasedmethod import MomentBasedLbMethod
from lbmpy.methods.momentbased.moment_transforms import PdfsToCentralMomentsByShiftMatrix
from lbmpy.moments import (
MOMENT_SYMBOLS, discrete_moment, exponents_to_polynomial_representations,
......@@ -215,6 +217,7 @@ def create_trt_with_magic_number(stencil, relaxation_rate, magic_number=sp.Ratio
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 :func:`lbmpy.methods.create_trt`
Args:
stencil: nested tuple defining the discrete velocity space. See :func:`lbmpy.stencils.get_stencil`
relaxation_rate: relaxation rate (inverse of the relaxation time)
......@@ -232,6 +235,7 @@ def create_trt_with_magic_number(stencil, relaxation_rate, magic_number=sp.Ratio
def create_mrt_raw(stencil, relaxation_rates, maxwellian_moments=False, **kwargs):
r"""
Creates a MRT method using non-orthogonalized moments.
Args:
stencil: nested tuple defining the discrete velocity space. See :func:`lbmpy.stencils.get_stencil`
relaxation_rates: relaxation rates (inverse of the relaxation times) for each moment
......@@ -483,11 +487,10 @@ def create_centered_cumulant_model(stencil, cumulant_to_rr_dict, force_model=Non
Args:
stencil: nested tuple defining the discrete velocity space. See :func:`lbmpy.stencils.get_stencil`
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
(see `lbmpy.methods.centeredcumulant.get_default_centered_cumulants_for_stencil`),
is mapped to a relaxation rate.
represented by an exponent tuple or in polynomial form is mapped to a relaxation rate.
See `get_default_polynomial_cumulants_for_stencil`
force_model: force model used for the collision. For cumulant LB method a good choice is
`lbmpy.methods.centeredcumulant.force_model`
`lbmpy.methods.centeredcumulant.CenteredCumulantForceModel`
equilibrium_order: approximation order of macroscopic velocity :math:`\mathbf{u}` in the equilibrium
c_s_sq: Speed of sound squared
galilean_correction: special correction for D3Q27 cumulant collisions. See Appendix H in
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment