Full Support for Zero-Centered Storage

This merge request introduces several changes into the heart of lbmpy to finally allow unrestricted usage of zero-centered PDF storage and to decouple storage format from compressibility. This requires several major incisions:

Conserved Quantity Computation

The DensityVelocityComputation class is updated. It shall now take compressible and zero_centered as separate arguments and handle populations and macroscopic quantities accordingly. The x_order_moment_symbol[s] properties are deprecated in favor of more specific symbol getters. A dedicated density_deviation_symbol is introduced to clearly separate density \rho, background density \rho_0 and density fluctuation \delta \rho, s.t. \rho = \rho_0 + \delta\rho in all situations. Depending on zero-centering, either \rho or \delta\rho are computed from PDFs, and the other one is inferred accordingly.

Equilibrium Formulations

So far, lbmpy separates formulations of its hydrodynamic equilibria into continuous vs. discrete and compressible vs. incompressible. The full-PDF storage format is implicitly assumed for the compressible case, while zero-centered storage is implicitly assumed in the incompressible case. This has been known to lead to a lot of confusion. In particular, the formation of the incompressible equilibrium moment values is quite hacky and not at all obvious.

With this MR, the hydrodynamic equilibrium shall be fully encapsulated in a dedicated class, which hides all technicalities of computing equilibrium moments and derivation of the equilibrium PDF (continuous or discrete). It will fully handle compressibility and zero-centering, and all information about the equilibrium will be held in one place. Once an instance of an equilibrium is created, it shall be immutable.

The hydrodynamic equilbria, both continuous and discrete, are derived from a common base class AbstractEquilibrium, which provides a common interface, as well as caching functionality for the computation of moments. It can be extended by custom subclasses for describing custom equilibrium distributions.

To date, instances of the *Method classes have only held a set of moments with associated equilibrium values. In the future, however, the method instances shall hold an equilibrium class instance instead of moment equilibrium values. It still manages its own moments and relaxation rate, but equilibrium values of moments are derived on demand, and only through the equilibrium object's interface.

Full vs. Delta-Equilibrium

The equation governing PDF storage is \vec{f} = \vec{w} + \delta\vec{f}, where \vec{w} are the lattice weights, and \delta\vec{f} are the fluctuations, which are the values to be stored in the zero-centered case. Equivalently, both compressible and incompressible equilibria can be expressed both in their absolute form or only by their deviation (delta) from the rest state Let \Psi be the continuous Maxwellian equilibrium. Like for the PDFs, the reference state, called background distribution, is \Psi (\rho_0, 0). Depending on compressibility and full or delta format, we obtain four different equilibria:

	compressible	incompressible
full	\Psi(\rho, \vec{u})	\Psi(\rho_0, \vec{u}) + \Psi(\delta\rho, 0)
delta	\Psi(\rho, \vec{u}) - \Psi(\rho_0, 0)	\Psi(\rho_0, \vec{u}) - \Psi(\rho_0, 0) + \Psi(\delta\rho, 0)

Regularly stored PDFs may be relaxed immediately to the full equilibria, and zero-centered PDFs can be immediately relaxed to the delta equilibria. To relax zero-centered PDFs against the full equilibria, the constant background part must first be added and subtracted again after the collision. This might be necessary because especially central moments of the delta-equilibria become more complicated, introducing velocity dependencies that degrade the CM method's numerical properties. Furthermore, it will definitely be necessary for cumulant LBMs, as cumulants of the delta-equilibrium are potentially undefined.

Analogously, in theory, you could relax the full PDF vector against the delta-equilibrium, but there isn't really a point to that, hence it is not supported.

Moment Transform Classes

Depending on zero-centering and choice of equilibrium (delta or full), the transformation of PDFs to moments and back might have to add in the constant background part. The transform classes are adapted accordingly.

Interface

All of this substructure shall be invisible to the everyday user, while at the same time providing a cleaner and easier to work with an ecosystem for the power user. All possible configurations for equilibrium are encapsulated in three arguments to the creation functions:

• compressible, default False
• zero_centered, default True,
• delta_equilibrium, default None, inferred according to the chosen method.

Supersedes !97 (closed). Depends on pystencils!285 (merged) and pystencils!286 (merged).

lbmpy/equilibrium/continuous_hydro_maxwellian.py

@@ -226,4 +226,15 @@ class ContinuousHydrodynamicMaxwellian(AbstractEquilibrium):
     def __repr__(self):
         return repr(self.continuous_equation)
 
+    def _repr_html_(self):
+        return f"""
+        <b>Continuous Hydrodynamic Maxwellian Equilibrium</b><br>
+        <ul>
+            <li>Compressible: {self._compressible}</li>
+            <li>Deviation Only: {self._deviation_only}</li>
+            <li>Order: {self._order}</li>
+            <li>Equation: ${sp.latex(self.continuous_equation)}$</li>
+        </ul>
+        """
+
 #   end class ContinuousHydrodynamicMaxwellian