Commit ddea6da8 authored by Markus Holzer's avatar Markus Holzer
Browse files

Added more documentation

parent 7c1a5ae9
Pipeline #34321 failed with stages
in 43 minutes and 35 seconds
......@@ -16,10 +16,10 @@ It even comes with an integrated Chapman Enskog analysis based on sympy!
Common test scenarios can be set up quickly:
from lbmpy.scenarios import create_channel
from pystencils import Target
from lbmpy.session import *
ch = create_channel(domain_size=(300, 100, 100), force=1e-7, method="trt",
ch = create_channel(domain_size=(300, 100, 100), force=1e-7, method=Method.TRT,
equilibrium_order=2, compressible=True,
relaxation_rates=[1.97, 1.6], optimization={'target': Target.GPU})
......@@ -69,11 +69,11 @@
%%%% Output: execute_result
<lbmpy.methods.momentbased.momentbasedmethod.MomentBasedLbMethod at 0x7f0d442c0fa0>
<lbmpy.methods.momentbased.momentbasedmethod.MomentBasedLbMethod at 0x7f49aed671c0>
%% Cell type:markdown id: tags:
The first column labeled "Moment" defines the collision space and thus the transformation matrix $C$.
The remaining columns specify the equilibrium vector in moment space $c^{(eq)}$ and the corresponding relaxation rate.
......@@ -131,11 +131,11 @@
%%%% Output: execute_result
<lbmpy.stencils.LBStencil at 0x7f0d442f2a90>
<lbmpy.stencils.LBStencil at 0x7f49aedd27c0>
%% Cell type:markdown id: tags:
### Orthogonal MRTs
......@@ -153,11 +153,11 @@
%%%% Output: execute_result
<lbmpy.methods.momentbased.momentbasedmethod.MomentBasedLbMethod at 0x7f0d39ecaee0>
<lbmpy.methods.momentbased.momentbasedmethod.MomentBasedLbMethod at 0x7f49aea33850>
%% Cell type:code id: tags:
``` python
lbm_config = LBMConfig(stencil=Stencil.D2Q9, method=Method.MRT, weighted=False)
......@@ -165,11 +165,11 @@
%%%% Output: execute_result
<lbmpy.methods.momentbased.momentbasedmethod.MomentBasedLbMethod at 0x7f0d39f23760>
<lbmpy.methods.momentbased.momentbasedmethod.MomentBasedLbMethod at 0x7f49aeb64fa0>
%% Cell type:markdown id: tags:
One can check if a method is orthogonalized:
......@@ -202,11 +202,11 @@
%%%% Output: execute_result
<lbmpy.methods.momentbased.centralmomentbasedmethod.CentralMomentBasedLbMethod at 0x7f0d39c84d90>
<lbmpy.methods.momentbased.centralmomentbasedmethod.CentralMomentBasedLbMethod at 0x7f49aeadb0a0>
%% Cell type:markdown id: tags:
The shift to the central moment space is done by applying a so-called shift matrix. Usually, this introduces a high numerical overhead. This problem is solved with lbmpy because each transformation stage can be specifically optimised individually. Therefore, it is possible to derive a CLBM with only a little numerical overhead.
......@@ -318,11 +318,11 @@
create_lb_method(LBMConfig(stencil=Stencil.D2Q9, method=Method.MRT, nested_moments=moments))
%%%% Output: execute_result
<lbmpy.methods.momentbased.momentbasedmethod.MomentBasedLbMethod at 0x7f0d39cceac0>
<lbmpy.methods.momentbased.momentbasedmethod.MomentBasedLbMethod at 0x7f49ae9359d0>
%% Cell type:markdown id: tags:
If one needs to also specify custom equilibrium moments the following approach can be used
......@@ -353,11 +353,11 @@
%%%% Output: execute_result
<lbmpy.methods.momentbased.momentbasedmethod.MomentBasedLbMethod at 0x7f0d39bf1c10>
<lbmpy.methods.momentbased.momentbasedmethod.MomentBasedLbMethod at 0x7f49ae8e9c10>
%% Cell type:markdown id: tags:
Instead of manually defining all entries in the method table, *lbmpy* has functions to fill the table according to a specific pattern. For example:
- for a full stencil (D2Q9, D3Q27) there exist exactly 9 or 27 linearly independent moments. These can either be taken as they are, or orthogonalized using Gram-Schmidt, weighted Gram-Schmidt or a Hermite approach
......@@ -379,11 +379,11 @@
%%%% Output: execute_result
<lbmpy.methods.momentbased.momentbasedmethod.MomentBasedLbMethod at 0x7f0d39bfbc70>
<lbmpy.methods.momentbased.momentbasedmethod.MomentBasedLbMethod at 0x7f49ae8ca190>
%% Cell type:markdown id: tags:
Our customized method can be directly passed into one of the scenarios. We can for example set up a channel flow with it. Since we used symbols as relaxation rates, we have to pass them in as `kernel_params`.
......@@ -9,9 +9,11 @@ Method parameters
- ``stencil='D2Q9'``: stencil name e.g. 'D2Q9', 'D3Q19'. See :func:`pystencils.stencils.get_stencil` for details
- ``method='srt'``: name of lattice Boltzmann method. This determines the selection and relaxation pattern of
moments/cumulants, i.e. which moment/cumulant basis is chosen, and which of the basis vectors are relaxed together
- ``stencil=Stencil.D2Q9``: All stencils are defined in :class: `lbmpy.enums.Stencil`.
From that :class:`lbmpy.stencils.LBStenil` class will be created.
- ``method=Method.SRT``: name of lattice Boltzmann method. Defined by :class: `lbmpy.enums.Method`.
This determines the selection and relaxation pattern of moments/cumulants, i.e. which moment/cumulant
basis is chosen, and which of the basis vectors are relaxed together
- ``srt``: single relaxation time (:func:`lbmpy.methods.create_srt`)
- ``trt``: two relaxation time, first relaxation rate is for even moments and determines the viscosity (as in SRT),
......@@ -46,10 +48,7 @@ General:
- ``equilibrium_order=2``: order in velocity, at which the equilibrium moment/cumulant approximation is
truncated. Order 2 is sufficient to approximate Navier-Stokes
- ``force_model=None``: possible values: ``None``, ``'simple'``, ``'luo'``, ``'guo'``/``'schiller'``,
``'buick'``/``'silva'``, ``'edm'``/``'kupershtokh'``, ``'he'``, ``'shanchen'``, ``'cumulant'``,
or an instance of a class implementing the same methods as the classes in :mod:`lbmpy.forcemodels`.
For details, see :mod:`lbmpy.forcemodels`
- ``force_model=None``: possibilities are defined in :class: `lbmpy.enums.ForceModel`
- ``force=(0,0,0)``: either constant force or a symbolic expression depending on field value
- ``maxwellian_moments=True``: way to compute equilibrium moments/cumulants, if False the standard
discretized LBM equilibrium is used, otherwise the equilibrium moments are computed from the continuous Maxwellian.
......@@ -182,6 +181,11 @@ Kernel functions are created in three steps:
The function :func:`create_lb_function` runs the whole pipeline, the other functions in this module
execute this pipeline only up to a certain step. Each function optionally also takes the result of the previous step.
Each of those functions is configured with three data classes. One to define the lattice Boltzmann method itself.
This class is called `LBMConfig`. The second one determines optimisations which are specific to the LBM. Optimisations
like the common supexpression elimination. The config class is called `LBMOptimisation`. The third
data class determines hardware optimisation. This can be found in the pystencils module as `CreateKernelConfig`.
With this class for example the target of the generated code is specified.
For example, to modify the AST one can run::
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment