Demystify the parameters of LBMConfig
LBMConfig defines all parameters which are used to derive the LBM collision operator. However, for new users (and even for long time users) it is often very hard to tell which parameters even make sense in certain situations.
There are some parameters that always make sense. For example the
streaming_pattern or the
field_name. No matter what operator is derived every streaming pattern can be applied and the name of the field is obviously independent of all other definitions.
On the other side, there are parameters that are very specific to specific methods. For example
galilean_correction only belongs to D3Q27 cumlumat methods. Or
weighted only belongs to orthogonal MRT methods. When a user defines combinations that do not work together two situations appear.
The first and maybe most dangerous situation is that the parameter is just ignored. For example if
Method.SRT is used as the method and
weighted would be set to
True it is just ignored that a user wanted to weight something here. While in this case, it might be obvious (at least for somewhat experienced users) it is still dangerous. There are more combinations that are not so obvious. For example when
compressible is set to
False and cumulants are derived it is just ignored, because our cumulants are only defined for compressible LB methods or that
equilibrium_order < 4 has no effect for cumulant methods because they are defined to be at least fourth-order accurate in the equilibrium. In this situation, one really needs to know the theory quite well to understand why the combination makes no sense. Even for advanced users, this might end up as a pitfall.
The second situation is that combinations produce errors because they do not make sense or because our derivation is not general enough. An example would be defining a fluctuating LB method for an SRT scheme. This produces
Fluctuations can only be added to weighted-orthogonal methods. While a user has quite a good explanation of what happens here it is still a bit frustrating that such combinations are not explained at least in some documentation.
But also not all combinations produce such nice error messages. Most others just fail due to some mysterious error caused by SymPy when the derivation starts.