Rework of the Cumulant-Based Method

This MR updates the cumulant-based LB method to better fit into our updated modelling framework. Several components are changed:

Central Moment to Cumulant Transform

• Now derives equations for polynomial cumulants, with monomials as intermediary values
• No longer ignores cumulants of zeroth and first order
• No longer simplifies according to a-priori assumptions about zeroth and first order cumulants, but emits equations containing logarithms and exponentials that need to be simplified later

Cumulant-Based Method

• Renamed to CumulantBasedLbMethod
• Forces are now applied symmetrically in central moment space according to the given force model, no more 'implicit forcing'
• Zeroth and first order cumulants are now treated regularily
• The Galilean correction was extracted as an a-posteriori-modification

Force Models

• Introduced interface method symmetric_central_moment_forcing for use with the cumulant method and implemented it for Simple, Luo, Guo and He

Central Moment Transform

• Introduced BinomialChimeraTransform as a new central moment transform class.

Method Creation

• Cumulant-based methods are now created like all other methods using create_with_equilibrium, and are thus open for use with arbitrary custom equilibria

Simplification

The changes to the derivation did increase the FLOP count of the cumulant method slightly.

• Added insert_logs to eliminate exponentials and logarithms in the cumulant-based method
• Added expand_post_collision_central_moments to simplify post-collision equations
• Added insert_conserved_quantity_products and insert_half_force to simplify expressions in central moment and cumulant based methods that depend only on conserved quantitites or the body force

lbmpy/methods/cumulantbased/cumulant_simplifications.py

 import sympy as sp
 from pystencils.simp.subexpression_insertion import insert_subexpressions
 
+from warnings import warn
+
 
 def insert_logs(ac, **kwargs):
     def callback(exp):
@@ -11,6 +13,19 @@ def insert_logs(ac, **kwargs):
     return insert_subexpressions(ac, callback, **kwargs)
 
 
+def insert_log_products(ac, **kwargs):
+    def callback(asm):
+        rhs = asm.rhs
+        if isinstance(rhs, sp.log):
+            return True
+        if isinstance(rhs, sp.Mul):
+            if any(isinstance(arg, sp.log) for arg in rhs.args):
+                return True
+        return False
+
+    return insert_subexpressions(ac, callback, **kwargs)
+
+
 def expand_post_collision_central_moments(ac):
     if 'post_collision_monomial_central_moments' in ac.simplification_hints:
         subexpr_dict = ac.subexpressions_dict
@@ -21,3 +36,15 @@ def expand_post_collision_central_moments(ac):
         ac = ac.copy()
         ac.set_sub_expressions_from_dict(subexpr_dict)
     return ac
+
+
+def check_for_logarithms(ac):
+    logs = ac.atoms(sp.log)
+    if len(logs) > 0:
+        warn("""There are logarithms remaining in your cumulant-based collision operator!
+                This will let your kernel's performance and numerical accuracy deterioate severly.
+                Either you have disabled simplification, or it unexpectedly failed.
+                If the presence of logarithms is intended, please inspect the kernel to make sure
+                if this warning can be ignored.
+                Otherwise, if setting `simplification='auto'` in your optimization config does not resolve
+                the problem, try a different parametrization, or contact the developers.""")