Merge branch 'Doc' into 'master'

Extend and fix documentation

See merge request pycodegen/lbmpy!79

.gitlab-ci.yml

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

doc/sphinx/methods.rst

@@ -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:
 

lbmpy/boundaries/boundaryconditions.py

@@ -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}}

lbmpy/methods/__init__.py

@@ -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']

lbmpy/methods/centeredcumulant/__init__.py

 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']

lbmpy/methods/centeredcumulant/centered_cumulants.py

@@ -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")):

lbmpy/methods/centeredcumulant/centeredcumulantmethod.py

@@ -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,

lbmpy/methods/centeredcumulant/force_model.py

@@ -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):

lbmpy/methods/creationfunctions.py

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