Added doc to turbuence model

lbmpy/turbulence_models.py

@@ -18,6 +18,29 @@ def frobenius_norm(matrix, factor=1):
 
 
 def add_smagorinsky_model(collision_rule, smagorinsky_constant, omega_output_field=None):
+    r""" Adds a smagorinsky model to a lattice Boltzmann collision rule. To add the Smagorinsky model to a LB scheme
+        one has to first compute the strain rate tensor $S_{ij}$ in each cell, and compute the turbulent
+        viscosity :math:`nu_t` from it. Then the local relaxation rate has to be adapted to match the total viscosity
+        :math `\nu_{total}` instead of the standard viscosity :math `\nu_0`.
+
+        A fortunate property of LB methods is, that the strain rate tensor can be computed locally from the
+        non-equilibrium part of the distribution function. This is somewhat surprising, since the strain rate tensor
+        contains first order derivatives. The strain rate tensor can be obtained by
+
+        .. math ::
+            S_{ij} = - \frac{3 \omega_s}{2 \rho_{(0)}} \Pi_{ij}^{(neq)}
+
+        where :math `\omega_s` is the relaxation rate that determines the viscosity, :math `\rho_{(0)}` is :math `\rho`
+        in compressible models and :math `1` for incompressible schemes.
+        :math `\Pi_{ij}^{(neq)}` is the second order moment tensor of the non-equilibrium part of
+        the distribution functions
+        :math `f^{(neq)} = f - f^{(eq)}` and can be computed as
+
+        .. math ::
+            \Pi_{ij}^{(neq)} = \sum_q c_{qi} c_{qj} \; f_q^{(neq)}
+
+
+    """
     method = collision_rule.method
     omega_s = get_shear_relaxation_rate(method)
     if isinstance(omega_s, float) or isinstance(omega_s, int):

lbmpy/updatekernels.py

@@ -20,7 +20,7 @@ def create_lbm_kernel(collision_rule, src_field, dst_field=None, accessor=Stream
         src_field: field used for reading pdf values
         dst_field: field used for writing pdf values if accessor.is_inplace this parameter is ignored
         accessor: instance of PdfFieldAccessor, defining where to read and write values
-                  to create e.g. a fused stream-collide kernel
+                  to create e.g. a fused stream-collide kernel See 'fieldaccess.PdfFieldAccessor'
 
     Returns:
         LbmCollisionRule where pre- and post collision symbols have been replaced
@@ -61,10 +61,11 @@ def create_stream_only_kernel(stencil, src_field, dst_field=None, accessor=Strea
     """Creates a stream kernel, without collision.
 
     Args:
-        stencil: lattice Boltzmann stencil which is used
-        src_field: Field the pre-streaming values are read from
-        dst_field: Field the post-streaming values are written to
-        accessor: Field accessor which is used to create the update rule. See 'fieldaccess.PdfFieldAccessor'
+        stencil: lattice Boltzmann stencil which is used in the form of a tuple of tuples
+        src_field: field used for reading pdf values
+        dst_field: field used for writing pdf values if accessor.is_inplace this parameter is ignored
+        accessor: instance of PdfFieldAccessor, defining where to read and write values
+                  to create e.g. a fused stream-collide kernel See 'fieldaccess.PdfFieldAccessor'
 
     Returns:
         AssignmentCollection of the stream only update rule
@@ -117,11 +118,12 @@ def create_stream_pull_with_output_kernel(lb_method, src_field, dst_field=None,
 
     Args:
         lb_method: lattice Boltzmann method see 'creationfunctions.create_lb_method'
-        src_field: Field the pre-streaming values are read from
+        src_field: field used for reading pdf values
         dst_field: field used for writing pdf values if accessor.is_inplace this parameter is ignored
-        output: Dictonary which containes macroscopic quantities as keys which should be calculated and fields as
+        output: dictonary which containes macroscopic quantities as keys which should be calculated and fields as
                 values which should be used to write the data e.g.: {'density': density_field}
-        accessor: Field accessor which is used to create the update rule. See 'fieldaccess.PdfFieldAccessor'
+        accessor: instance of PdfFieldAccessor, defining where to read and write values
+                  to create e.g. a fused stream-collide kernel See 'fieldaccess.PdfFieldAccessor'
 
     Returns:
         AssignmentCollection of the stream only update rule