doc/sphinx/api.rst

@@ -5,13 +5,13 @@ API Reference
    :maxdepth: 1
 
    scenarios.rst
-   kernelcreation.rst
-   methodcreation.rst
+   enums.rst
    stencils.rst
-   methods.rst
+   kernelcreation.rst
+   equilibrium.rst
+   moment_transforms.rst
    maxwellian_equilibrium.rst
    continuous_distribution_measures.rst
    moments.rst
    cumulants.rst
-   forcemodels.rst
    zbibliography.rst

doc/sphinx/boundary_conditions.rst

+*******************
+Boundary Conditions
+*******************
+
+.. automodule:: lbmpy.boundaries.boundaryconditions
+   :members:

doc/sphinx/enums.rst

+************
+Enumerations
+************
+
+.. automodule:: lbmpy.enums
+   :members:

doc/sphinx/equilibrium.rst

+*********************************************
+Equilibrium Distributions (lbmpy.equilibrium)
+*********************************************
+
+.. automodule:: lbmpy.equilibrium
+
+
+Abstract Base Class
+===================
+
+.. autoclass:: lbmpy.equilibrium.AbstractEquilibrium
+    :members:
+    :private-members: _monomial_raw_moment, _monomial_central_moment, _monomial_cumulant
+
+Generic Discrete Equilibria
+===========================
+
+Use the following class for custom discrete equilibria.
+
+.. autoclass:: lbmpy.equilibrium.GenericDiscreteEquilibrium
+    :members:
+
+Maxwellian Equilibria for Hydrodynamics
+=======================================
+
+The following classes represent the continuous and the discrete variant of the Maxwellian equilibrium for
+hydrodynamics.
+
+.. autoclass:: lbmpy.equilibrium.ContinuousHydrodynamicMaxwellian
+    :members:
+
+.. autoclass:: lbmpy.equilibrium.DiscreteHydrodynamicMaxwellian
+    :members:

doc/sphinx/lbmpy.bib

@@ -6,7 +6,8 @@
   number={4},
   pages={043309},
   year={2015},
-  publisher={APS}
+  publisher={APS},
+  doi={10.1103/PhysRevE.92.043309},
 }
 
 @PHDTHESIS{luo1993lattice,
@@ -16,7 +17,7 @@
    school = {GEORGIA INSTITUTE OF TECHNOLOGY.},
      year = 1993,
    adsurl = {http://adsabs.harvard.edu/abs/1993PhDT.......233L},
-  adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+  adsnote = {Provided by the SAO/NASA Astrophysics Data System},
 }
 
 @Article{guo2002discrete,
@@ -28,8 +29,24 @@
   number    = {4},
   pages     = {046308},
   publisher = {APS},
+  doi = {10.1103/PhysRevE.65.046308},
 }
 
+@article{HeForce,
+  title = {Discrete Boltzmann equation model for nonideal gases},
+  author = {He, Xiaoyi and Shan, Xiaowen and Doolen, Gary D.},
+  journal = {Physical Review E},
+  volume = {57},
+  issue = {1},
+  pages = {R13--R16},
+  numpages = {0},
+  year = {1998},
+  month = {1},
+  publisher = {APS},
+  doi = {10.1103/PhysRevE.57.R13}
+}
+
+
 @article{buick2000gravity,
   title={Gravity in a lattice Boltzmann model},
   author={Buick, JM and Greated, CA},
@@ -38,7 +55,15 @@
   number={5},
   pages={5307},
   year={2000},
-  publisher={APS}
+  publisher={APS},
+  doi = {10.1103/PhysRevE.61.5307},
+}
+
+@phdthesis{schiller2008thermal,
+  title={Thermal fluctuations and boundary conditions in the lattice Boltzmann method},
+  author={Schiller, Ulf Daniel},
+  year={2008},
+  school={Johannes Gutenberg Universit{\"a}t Mainz}
 }
 
 
@@ -60,12 +85,233 @@ year = {2018}
 
 
 @article{Semprebon2016,
-author = {Semprebon, Ciro and Kusumaatmaja, Halim},
-doi = {10.1103/PhysRevE.93.033305},
-keywords = {lbm,multiphase,phasefield},
-mendeley-tags = {lbm,multiphase,phasefield},
-pages = {1--11},
-title = {{Ternary free-energy lattice Boltzmann model with tunable surface tensions and contact angles}},
-volume = {033305},
-year = {2016}
-}
+  title = {Ternary free-energy lattice Boltzmann model with tunable surface tensions and contact angles},
+  author = {Semprebon, Ciro and Kr\"uger, Timm and Kusumaatmaja, Halim},
+  journal = {Phys. Rev. E},
+  volume = {93},
+  issue = {3},
+  pages = {033305},
+  numpages = {11},
+  year = {2016},
+  month = {Mar},
\ No newline at end of file
+  publisher = {American Physical Society},
+  doi = {10.1103/PhysRevE.93.033305},
+}
+
+@article{geier2015,
+author = {Geier, Martin and Sch{\"{o}}nherr, Martin and Pasquali, Andrea and Krafczyk, Manfred},
+title = {{The cumulant lattice Boltzmann equation in three dimensions: Theory and validation}},
+journal = {Computers \& Mathematics with Applications},
+volume = {70},
+number = {4},
+pages = {507-547},
+year = {2015},
+issn = {0898-1221},
+doi = {10.1016/j.camwa.2015.05.001},
+}
+
+@article{geier2017,
+author = {Geier, Martin and Pasquali, Andrea and Sch{\"{o}}nherr, Martin},
+title = {Parametrization of the Cumulant Lattice Boltzmann Method for Fourth Order Accurate Diffusion Part I},
+year = {2017},
+issue_date = {November 2017},
+publisher = {Academic Press Professional, Inc.},
+address = {USA},
+volume = {348},
+number = {C},
+issn = {0021-9991},
+url = {https://doi.org/10.1016/j.jcp.2017.05.040},
+doi = {10.1016/j.jcp.2017.05.040},
+journal = {J. Comput. Phys.},
+month = {nov},
+pages = {862–888},
+numpages = {27}
+}
+
+@Article{Coreixas2019,
+  title = {Comprehensive comparison of collision models in the lattice Boltzmann framework: Theoretical investigations},
+  author = {Coreixas, Christophe and Chopard, Bastien and Latt, Jonas},
+  journal = {Phys. Rev. E},
+  volume = {100},
+  issue = {3},
+  pages = {033305},
+  numpages = {46},
+  year = {2019},
+  month = {Sep},
+  publisher = {American Physical Society},
+  doi = {10.1103/PhysRevE.100.033305},
+  url = {https://link.aps.org/doi/10.1103/PhysRevE.100.033305}
+}
+
+@PhdThesis{Geier2006,
+  author = {Martin Geier},
+  school = {Department of Microsystems Technology IMTEK, University of Freiburg},
+  title  = {Ab inito derivation of the cascaded lattice Boltzmann automaton},
+  year   = {2006},
+}
+
+@article{Fakhari2018,
+title = {A phase-field lattice {Boltzmann} model for simulating multiphase flows in porous media: Application and comparison to experiments of {CO2} sequestration at pore scale},
+journal = {Advances in Water Resources},
+volume = {114},
+pages = {119-134},
+year = {2018},
+issn = {0309-1708},
+doi = {10.1016/j.advwatres.2018.02.005},
+author = {Fakhari, A. and Li, Y. and Bolster, D. and Christensen, K. T.},
+}
+
+@article{silva2010,
+title = {A study on the inclusion of body forces in the lattice Boltzmann BGK equation to recover steady-state hydrodynamics},
+journal = {Physica A: Statistical Mechanics and its Applications},
+volume = {390},
+number = {6},
+pages = {1085-1095},
+year = {2011},
+doi = {10.1016/j.physa.2010.11.037},
+author = {Silva, G. and Semiao, V.},
+keywords = {{Lattice Boltzmann} method, {BGK} collision operator, Steady-state flows, Body force driven flows}
+}
+
+@article{silva2020,
+  title = {Force methods for the two-relaxation-times lattice {Boltzmann}},
+  author = {Postma, B. and Silva, G.},
+  journal = {Phys. Rev. E},
+  volume = {102},
+  issue = {6},
+  year = {2020},
+  month = {12},
+  publisher = {American Physical Society},
+  doi = {10.1103/PhysRevE.102.063307},
+}
+
+@book{lbm_book,
+  doi = {10.1007/978-3-319-44649-3},
+  year = {2017},
+  publisher = {Springer International Publishing},
+  author = {Kr\"{u}ger, T. and Kusumaatmaja, H. and Kuzmin, A. and Shardt, O. and Silva, G. and Viggen, E. M.},
+  title = {The Lattice {Boltzmann} Method}
+}
+
+@article{Ansumali2003,
+	doi = {10.1209/epl/i2003-00496-6},
+	year = 2003,
+	month = {sep},
+	journal = {{IOP} Publishing},
+	volume = {63},
+	number = {6},
+	pages = {798--804},
+	author = {S Ansumali and I. V Karlin and H. C Öttinger},
+	title = {Minimal entropic kinetic models for hydrodynamics},
+	abstract = {We derive minimal discrete models of the Boltzmann equation consistent with equilibrium thermodynamics, and which recover correct hydrodynamics in arbitrary dimensions. A new discrete velocity model is proposed for the simulation of the Navier-Stokes-Fourier equation and is tested in the setup of Taylor vortex flow. A simple analytical procedure for constructing the equilibrium for thermal hydrodynamics is established. For the lattice Boltzmann method of isothermal hydrodynamics, the explicit analytical form of the equilibrium distribution is presented. This results in an entropic version of the isothermal lattice Boltzmann method with the simplicity and computational efficiency of the standard lattice Boltzmann model.}
+}
+
+@Article{raw_moments,
+  author  = {D. D'Humières},
+  journal = {Rarefied gas dynamics},
+  title   = {Generalized lattice-{Boltzmann} equations},
+  year    = {1992},
+}
+
+@article{FAKHARI201722,
+    author = "Abbas Fakhari and Diogo Bolster and Li-Shi Luo",
+    title = "A weighted multiple-relaxation-time lattice {Boltzmann} method for multiphase flows and its application to partial coalescence cascades",
+    journal = "Journal of Computational Physics",
+    year = "2017",
+    doi = "10.1016/j.jcp.2017.03.062"
+}
+
+@article{TRT,
+author = {Ginzburg Irina and Frederik Verhaeghe and D. D'Humières},
+year = {2008},
+month = {01},
+pages = {427-478},
+title = {Two-relaxation-time Lattice Boltzmann scheme: about parametrization, velocity, pressure and mixed boundary conditions},
+volume = {3},
+journal = {Communications in Computational Physics}
+}
+
+@Article{HeIncompressible,
+  author    = {Xiaoyi He and Li-Shi Luo},
+  journal   = {Journal of Statistical Physics},
+  title     = {Lattice Boltzmann Model for the Incompressible Navier{\textendash}Stokes Equation},
+  year      = {1997},
+  month     = {aug},
+  number    = {3/4},
+  pages     = {927--944},
+  volume    = {88},
+  doi       = {10.1023/b:joss.0000015179.12689.e4},
+  publisher = {Springer Science and Business Media {LLC}},
+}
+
+@Article{GruszczynskiCascadedPhaseFieldModel,
+  author    = {G. Gruszczy{\'{n}}ski and T. Mitchell and C. Leonardi and {\L}. {\L}aniewski-Wo{\l}{\l}k and T. Barber},
+  journal   = {Computers {\&} Mathematics with Applications},
+  title     = {A cascaded phase-field lattice Boltzmann model for the simulation of incompressible, immiscible fluids with high density contrast},
+  year      = {2020},
+  month     = {feb},
+  number    = {4},
+  pages     = {1049--1071},
+  volume    = {79},
+  doi       = {10.1016/j.camwa.2019.08.018},
+  publisher = {Elsevier {BV}},
+}
+
+@Article{Casson,
+  author    = {R. Ouared and B. Chopard},
+  journal   = {Journal of Statistical Physics},
+  title     = {Lattice {Boltzmann} Simulations of Blood Flow: {Non-Newtonian} Rheology and Clotting Processes},
+  year      = {2005},
+  doi       = {10.1007/s10955-005-8415-x},
+  publisher = {Springer Link},
+}
+
+@article{BouzidiBC,
+    author = {Bouzidi, M’hamed and Firdaouss, Mouaouia and Lallemand, Pierre},
+    title = "{Momentum transfer of a Boltzmann-lattice fluid with boundaries}",
+    journal = {Physics of Fluids},
+    year = {2001},
+    month = {11},
+    doi = {10.1063/1.1399290},
+    url = {https://doi.org/10.1063/1.1399290},
+}
+
+@Article{rozema15,
+  doi       = {10.1063/1.4928700},
+  year      = {2015},
+  month     = {aug},
+  publisher = {AIP Publishing},
+  volume    = {27},
+  number    = {8},
+  author    = {Wybe Rozema and Hyun J. Bae and Parviz Moin and Roel Verstappen},
+  title     = {Minimum-dissipation models for large-eddy simulation},
+  journal   = {Physics of Fluids}
+}
+
+@article{Han2021,
+   doi = {10.1088/1873-7005/ac1782},
+   url = {https://dx.doi.org/10.1088/1873-7005/ac1782}                    ,
+   year = {2021},
+   month = {aug},
+   publisher = {IOP Publishing},
+   volume = {53},
+   number = {4},
+   pages = {045506},
+   author = {Mengtao Han and Ryozo Ooka and Hideki Kikumoto},
+   title = {A wall function approach in lattice Boltzmann method: algorithm and validation using turbulent channel flow},
+   journal = {Fluid Dynamics Research}
+}
+
+@article{Maronga2020,
+ author = {Maronga, Bj{\"o}rn and Knigge, Christoph and Raasch, Siegfried},
+ year = {2020},
+ title = {{An Improved Surface Boundary Condition for Large-Eddy Simulations Based on Monin--Obukhov Similarity Theory: Evaluation and Consequences for Grid Convergence in Neutral and Stable Conditions}},
+ pages = {297--325},
+ volume = {174},
+ number = {2},
+ issn = {0006-8314},
+ journal = {{Boundary-layer meteorology}},
+ doi = {10.1007/s10546-019-00485-w}
+}
+
+@Comment{jabref-meta: databaseType:bibtex;}

doc/sphinx/maxwellian_equilibrium.rst

-**********************
-Maxwellian Equilibrium
-**********************
+*******************************
+Maxwellian Equilibrium (Legacy)
+*******************************
 
 .. automodule:: lbmpy.maxwellian_equilibrium
     :members:
@@ -11,7 +11,7 @@ Maxwellian Equilibrium
 
     .. autofunction:: lbmpy.maxwellian_equilibrium.continuous_maxwellian_equilibrium
 
-    .. autofunction:: lbmpy.maxwellian_equilibrium.get_moments_of_continuous_maxwellian_equilibrium
+    .. autofunction:: lbmpy.maxwellian_equilibrium.get_equilibrium_values_of_maxwell_boltzmann_function
 
     .. autofunction:: lbmpy.maxwellian_equilibrium.get_moments_of_discrete_maxwellian_equilibrium
 

doc/sphinx/methodcreation.rst

-Creating LBM methods
-====================
-
-This module is a lower level API to construct methods.
-When possible use the high level API.
-
-.. automodule:: lbmpy.methods.creationfunctions
-    :members:

doc/sphinx/methods.rst

-***********************
-Methods (lbmpy.methods)
-***********************
+********************************
+Collision models (lbmpy.methods)
+********************************
 
+This module defines the classes defining all types of lattice Boltzmann methods available in *lbmpy*,
+together with a set of factory functions used to create their instances. The factory functions are
+organized in three levels of abstraction. Objects of the method classes should be created only through
+these factory functions, never manually.
 
-LBM Method Interfaces
-=====================
+Methods in *lbmpy* can be distinguished into three categories:
+ - :ref:`methods_rawmomentbased`, including the classical single relaxation-time (SRT, BGK), two relaxation-time (TRT) 
+   and multiple relaxation-time (MRT) methods, as well as entropic variants of the TRT method.
+ - :ref:`methods_centralmomentbased`, which are multiple relaxation-time methods using relaxation in central moment space.
+ - :ref:`methods_cumulantbased`, multiple relaxation-time methods using relaxation in cumulant space.
 
-.. autoclass:: lbmpy.methods.AbstractLbMethod
+Abstract LB Method Base Class
+=============================
+
+.. autoclass:: lbmpy.methods.LbmCollisionRule
     :members:
 
-.. autoclass:: lbmpy.methods.AbstractConservedQuantityComputation
+.. autoclass:: lbmpy.methods.AbstractLbMethod
     :members:
 
+.. _methods_rawmomentbased:
 
+Raw Moment-based methods
+========================
 
+These methods are represented by instances of :class:`lbmpy.methods.momentbased.MomentBasedLbMethod` and will derive
+collision equations either in population space (SRT, TRT, entropic TRT), or in raw moment space (MRT variants).
 
-LBM with conserved zeroth and first order
-=========================================
+Creation Functions
+------------------
 
-.. autoclass:: lbmpy.methods.DensityVelocityComputation
+The following factory functions create raw moment-based methods using variants of the regular hydrodynamic maxwellian
+equilibrium.
+
+.. autofunction:: lbmpy.methods.create_srt
+
+.. autofunction:: lbmpy.methods.create_trt
+
+.. autofunction:: lbmpy.methods.create_trt_with_magic_number
+
+.. autofunction:: lbmpy.methods.create_mrt_orthogonal
+
+.. autofunction:: lbmpy.methods.create_trt_kbc
+
+
+Class
+-----
+
+.. autoclass:: lbmpy.methods.momentbased.MomentBasedLbMethod
     :members:
 
 
+.. _methods_centralmomentbased:
 
+Central Moment-based methods
+============================
 
-Moment-based methods
-====================
+These methods are represented by instances of :class:`lbmpy.methods.momentbased.CentralMomentBasedLbMethod` and will derive
+collision equations in central moment space.
 
 Creation Functions
 ------------------
 
-.. autofunction:: lbmpy.methods.create_srt
+The following factory functions create central moment-based methods using variants of the regular hydrodynamic maxwellian
+equilibrium.
 
-.. autofunction:: lbmpy.methods.create_trt
+.. autofunction:: lbmpy.methods.create_central_moment
 
-.. autofunction:: lbmpy.methods.create_trt_with_magic_number
+Class
+-----
 
-.. autofunction:: lbmpy.methods.create_mrt_orthogonal
+.. autoclass:: lbmpy.methods.momentbased.CentralMomentBasedLbMethod
+    :members:
+
+
+.. _methods_cumulantbased:
+
+Cumulant-based methods
+======================
+
+These methods are represented by instances of :class:`lbmpy.methods.cumulantbased.CumulantBasedLbMethod` and will derive
+collision equations in cumulant space.
 
-.. autofunction:: lbmpy.methods.create_with_continuous_maxwellian_eq_moments
+Creation Functions
+------------------
+
+The following factory functions create cumulant-based methods using the regular continuous hydrodynamic maxwellian equilibrium.
+
+.. autofunction:: lbmpy.methods.create_cumulant
 
-.. autofunction:: lbmpy.methods.create_with_discrete_maxwellian_eq_moments
+.. autofunction:: lbmpy.methods.create_with_monomial_cumulants
+
+.. autofunction:: lbmpy.methods.create_with_default_polynomial_cumulants
 
 
 Class
 -----
 
-.. autoclass:: lbmpy.methods.MomentBasedLbMethod
+.. autoclass:: lbmpy.methods.cumulantbased.CumulantBasedLbMethod
+    :members:
+
+
+
+Default Moment sets
+===================
+
+The following functions provide default sets of polynomial raw moments, central moments and cumulants
+to be used in MRT-type methods.
+
+.. autofunction:: lbmpy.methods.default_moment_sets.cascaded_moment_sets_literature
+
+.. autofunction:: lbmpy.methods.default_moment_sets.mrt_orthogonal_modes_literature
+
+
+
+Low-Level Method Creation Interface
+===================================
+
+The following classes and factory functions constitute the lower levels of abstraction in method creation.
+They are called from the higher-level functions described above, or, in special cases, by the user directly.
+
+Custom method variants in population space, raw and central moment space based on the hydrodynamic Maxwellian
+equilibrium may be created using either 
+:func:`lbmpy.methods.creationfunctions.create_with_discrete_maxwellian_equilibrium` or 
+:func:`create_with_continuous_maxwellian_equilibrium`.
+
+Methods may also be created using custom equilibrium distributions using
+:func:`lbmpy.methods.creationfunctions.create_from_equilibrium`.
+
+The desired collision space, and the transform classes defining the manner of transforming populations to that
+space and back, are defined using :class:`lbmpy.enums.CollisionSpace` and :class:`lbmpy.methods.CollisionSpaceInfo`.
+
+Collision Space Info
+--------------------
+
+.. autoclass lbmpy.methods.CollisionSpaceInfo
+    :members:
+
+Low-Level Creation Functions
+----------------------------
+
+.. autofunction:: lbmpy.methods.creationfunctions.create_with_discrete_maxwellian_equilibrium
+
+.. autofunction:: lbmpy.methods.creationfunctions.create_with_continuous_maxwellian_equilibrium
+
+.. autofunction:: lbmpy.methods.creationfunctions.create_from_equilibrium
+
+
+Conserved Quantity Computation
+==============================
+
+The classes of the conserved quantity computation (CQC) submodule define an LB Method's conserved quantities and
+the equations to compute them. For hydrodynamic methods, :class:`lbmpy.methods.DensityVelocityComputation` is
+the typical choice. For custom methods, however, a custom CQC class might have to be created.
+
+.. autoclass:: lbmpy.methods.AbstractConservedQuantityComputation
     :members:
 
+.. autoclass:: lbmpy.methods.DensityVelocityComputation
+    :members:
\ No newline at end of file

doc/sphinx/moment_transforms.rst

+*******************************************
+Moment Transforms (lbmpy.moment_transforms)
+*******************************************
+
+The ``moment_transforms`` module provides an ecosystem for transformation of quantities between
+lattice Boltzmann population space and other spaces of observable quantities. Currently, transforms
+to raw and central moment space are available.
+
+The common base class `lbmpy.moment_transforms.AbstractMomentTransform` defines the interface all transform classes share.
+This interface, together with the fundamental principles all transforms adhere to, is explained 
+in the following.
+
+Principles of Collision Space Transforms
+========================================
+
+Each class of this module implements a bijective map :math:`\mathcal{M}` from population space 
+to raw moment or central moment space, capable of transforming the particle distribution 
+function :math:`\mathbf{f}` to (almost) arbitrary user-defined moment sets.
+
+Monomial and Polynomial Moments
+-------------------------------
+
+We discriminate *monomial* and *polynomial* moments. The monomial moments are the canonical basis of their
+corresponding space. Polynomial moments are defined as linear combinations of this basis. Monomial moments are
+typically expressed by exponent tuples :math:`(\alpha, \beta, \gamma)`. The monomial raw moments are defined as
+
+.. math::
+    
+    m_{\alpha \beta \gamma} 
+        = \sum_{i = 0}^{q - 1} f_i c_{i,x}^{\alpha} c_{i,y}^{\beta} c_{i,z}^{\gamma}
+
+and the monomial central moments are given by
+
+.. math::
+    
+    \kappa_{\alpha \beta \gamma} 
+        = \sum_{i = 0}^{q - 1} 
+            f_i 
+            (c_{i,x} - u_x)^{\alpha} 
+            (c_{i,y} - u_y)^{\beta} 
+            (c_{i,z} - u_z)^{\gamma}.
+
+Polynomial moments are, in turn, expressed by
+polynomial expressions :math:`p` in the coordinate symbols :math:`x`, :math:`y` and :math:`z`.
+An exponent tuple :math:`(\alpha, \beta, \gamma)` corresponds directly 
+to the mixed monomial expression :math:`x^{\alpha} y^{\beta} z^{\gamma}`. Polynomial moments are then
+constructed as linear combinations of these monomials. For example, the polynomial
+
+.. math::
+
+    p(x,y,z) = x^2 + y^2 + z^2 + 1.
+
+defines both the polynomial raw moment
+
+.. math::
+
+    M = m_{200} + m_{020} + m_{002}
+
+and central moment
+
+.. math::
+
+    K = \kappa_{200} + \kappa_{020} + \kappa_{002}.
+
+
+Transformation Matrices
+-----------------------
+
+The collision space basis for an MRT LB method on a :math:`DdQq` lattice is spanned by a set of :math:`q`
+polynomial quantities, given by polynomials :math:`\left( p_i \right)_{i=0, \dots, q-1}`.
+Through the polynomials, a polynomialization matrix :math:`P` is defined such that
+
+.. math::
+
+    \mathbf{M} &= P \mathbf{m} \\
+    \mathbf{K} &= P \mathbf{\kappa}
+
+Both rules can also be written using matrix multiplication, such that
+
+.. math::
+    \mathbf{m} = M \mathbf{f} 
+    \qquad 
+    \mathbf{\kappa} = K \mathbf{f}.
+
+Further, there exists a mapping from raw to central moment space using (monomial or polynomial)
+shift matrices (see `set_up_shift_matrix`) such that
+
+.. math::
+    \mathbf{\kappa} = N \mathbf{m}
+    \qquad
+    \mathbf{K} = N^P \mathbf{M}.
+
+Working with the transformation matrices, those mappings can easily be inverted.
+This module provides classes that derive efficient implementations of these transformations.
+
+Moment Aliasing
+---------------
+
+For a collision space transform to be invertible, exactly :math:`q` independent polynomial quantities of
+the collision space must be chosen. In that case, since all transforms discussed here are linear, the space of
+populations is isomorphic to the chosen moment space. The important word here is 'independent'. Even if :math:`q`
+distinct moment polynomials are chosen, due to discrete lattice artifacts, they might not span the entire collision
+space if chosen wrongly. The discrete lattice structure gives rise to *moment aliasing* effects. The most simple such
+effect occurs in the monomial raw moments, where are all nonzero even and all odd exponents are essentially the same.
+For example, we have :math:`m_{400} = m_{200}` or :math:`m_{305} = m_{101}`. This rule holds on every direct-neighborhood
+stencil. Sparse stencils, like :math:`D3Q15`, may introduce additional aliases. On the :math:`D3Q15` stencil, due to its
+structure, we have also :math:`m_{112} = m_{110}` and even :math:`m_{202} = m_{220} = m_{022} = m_{222}`.
+
+Including aliases in a set of monomial moments will lead to a non-invertible transform and is hence not possible.
+In polynomials, however, aliases may occur without breaking the transform. Several established sets of polynomial
+moments, like in orthogonal raw moment space MRT methods, will comprise :math:`q` polynomials :math:`\mathbf{M}` that in turn are built
+out of :math:`r > q` monomial moments :math:`\mathbf{m}`. In that set of monomials, non-independent moments have to be included by definition.
+Since the full transformation matrix :math:`M^P = PM` is still invertible, this is not a problem in general. If, however, the
+two steps of the transform are computed separately, it becomes problematic, as the matrices :math:`M \in \mathbb{R}^{r \times q}`
+and :math:`P \in \mathbb{R}^{q \times r}` are not invertible on their own. 
+
+But there is a remedy. By eliminating aliases from the moment polynomials, they can be reduced to a new set of polynomials based
+on a non-aliased reduced vector of monomial moments :math:`\tilde{\mathbf{m}} \in \mathbb{R}^{q}`, expressed through the reduced
+matrix :math:`\tilde{P}`.
+
+
+Interfaces and Usage
+====================
+
+Construction
+------------
+
+All moment transform classes expect either a sequence of exponent tuples or a sequence of polynomials that define
+the set of quantities spanning the destination space. If polynomials are given, the exponent tuples of the underlying
+set of monomials are extracted automatically. Depending on the implementation, moment aliases may be eliminated in the
+process, altering both the polynomials and the set of monomials.
+
+
+Forward and Backward Transform
+------------------------------
+
+The core functionality of the transform classes is given by the methods ``forward_transform`` and ``backward_transform``.
+They return assignment collections containing the equations to compute moments from populations, and vice versa.
+
+Symbols Used
+^^^^^^^^^^^^
+
+Unless otherwise specified by the user, monomial and polynomial quantities occur in the transformation equations according
+to the naming conventions listed in the following table:
+
++--------------------------------+---------------------------------------------+----------------------+
+|                                |              Monomial                       |    Polynomial        |
++--------------------------------+---------------------------------------------+----------------------+
+| Pre-Collision Raw Moment       | :math:`m_{\alpha \beta \gamma}`             | :math:`M_{i}`        |
++--------------------------------+---------------------------------------------+----------------------+
+| Post-Collision Raw Moment      | :math:`m_{post, \alpha \beta \gamma}`       | :math:`M_{post, i}`  |
++--------------------------------+---------------------------------------------+----------------------+
+| Pre-Collision Central Moment   | :math:`\kappa_{\alpha \beta \gamma}`        | :math:`K_{i}`        |
++--------------------------------+---------------------------------------------+----------------------+
+| Post-Collision Central Moment  | :math:`\kappa_{post, \alpha \beta \gamma}`  | :math:`K_{post, i}`  |
++--------------------------------+---------------------------------------------+----------------------+
+
+These symbols are also exposed by the member properties `pre_collision_symbols`, `post_collision_symbols`, 
+`pre_collision_monomial_symbols` and `post_collision_monomial_symbols`.
+
+Forward Transform
+^^^^^^^^^^^^^^^^^
+
+Implementations of the `lbmpy.moment_transforms.AbstractMomentTransform.forward_transform` method 
+derive equations for the transform from population to moment space, to compute pre-collision moments
+from pre-collision populations. The returned ``AssignmentCollection`` has the `pre_collision_symbols` 
+as left-hand sides of its main assignments, computed from the given ``pdf_symbols`` and, potentially,
+the macroscopic density and velocity. Depending on the implementation, the `pre_collision_monomial_symbols`
+may be part of the assignment collection in the form of subexpressions. 
+
+Backward Transform
+^^^^^^^^^^^^^^^^^^
+
+Implementations of `lbmpy.moment_transforms.AbstractMomentTransform.backward_transform` contain the post-collision
+polynomial quantities as free symbols of their equation right-hand sides, and compute the post-collision populations
+from those. The PDF symbols are the left-hand sides of the main assignments.
+
+
+Absorption of Conserved Quantity Equations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Transformations from the population space to any space of observable quantities may *absorb* the equations 
+defining the macroscopic quantities entering the equilibrium (typically the density :math:`\rho` and the
+velocity :math:`\mathbf{u}`). This means that the ``forward_transform`` will possibly rewrite the
+assignments given in the constructor argument ``conserved_quantity_equations`` to reduce
+the total operation count. For example, in the transformation step from populations to
+raw moments (see `lbmpy.moment_transforms.PdfsToMomentsByChimeraTransform`), :math:`\rho` can be aliased as the zeroth-order moment
+:math:`m_{000}`. Assignments to the conserved quantities will then be part of the AssignmentCollection
+returned by ``forward_transform`` and need not be added to the collision rule separately. 
+
+Simplification
+^^^^^^^^^^^^^^
+
+Both ``forward_transform`` and ``backward_transform`` expect a keyword argument ``simplification``
+which can be used to direct simplification steps applied during the derivation of the transformation
+equations. Possible values are:
+
+- `False` or ``'none'``: No simplification is to be applied
+- `True` or ``'default'``: A default simplification strategy specific to the implementation is applied.
+    The actual simplification steps depend strongly on the nature of the equations. They are defined by
+    the implementation. It is the responsibility of the implementation to select the most effective
+    simplification strategy.
+- ``'default_with_cse'``: Same as ``'default'``, but with an additional pass of common subexpression elimination.
+
+
+Working With Monomials
+^^^^^^^^^^^^^^^^^^^^^^
+
+In certain situations, we want the ``forward_transform`` to yield equations for the monomial symbols :math:`m_{\alpha \beta \gamma}`
+and :math:`\kappa_{\alpha \beta \gamma}` only, and the ``backward_transform`` to return equations that also expect these symbols as input. 
+In this case, it is not sufficient to pass a set of monomials or exponent tuples to the constructor, as those are still treated as 
+polynomials internally. Instead, both transform methods expose keyword arguments ``return_monomials`` and ``start_from_monomials``, respectively.
+If set to true, equations in the monomial moments are returned. They are best used *only* together with the ``exponent_tuples`` constructor argument
+to have full control over the monomials. If polynomials are passed to the constructor, the behaviour of these flags is generally not well-defined,
+especially in the presence of aliases.
+
+
+The Transform Classes
+=====================
+
+Abstract Base Class
+-------------------
+
+.. autoclass:: lbmpy.moment_transforms.AbstractMomentTransform
+    :members:
+
+
+Moment Space Transforms
+-----------------------
+
+.. autoclass:: lbmpy.moment_transforms.PdfsToMomentsByMatrixTransform
+    :members:
+
+.. autoclass:: lbmpy.moment_transforms.PdfsToMomentsByChimeraTransform
+    :members:
+
+
+Central Moment Space Transforms
+-------------------------------
+
+.. autoclass:: lbmpy.moment_transforms.PdfsToCentralMomentsByMatrix
+    :members:
+
+.. autoclass:: lbmpy.moment_transforms.BinomialChimeraTransform
+    :members:
+
+.. autoclass:: lbmpy.moment_transforms.FastCentralMomentTransform
+    :members:
+
+.. autoclass:: lbmpy.moment_transforms.PdfsToCentralMomentsByShiftMatrix
+    :members:
+
+Cumulant Space Transforms
+-------------------------
+
+.. autoclass:: lbmpy.moment_transforms.CentralMomentsToCumulantsByGeneratingFunc
+    :members:
+