From 571f032398d0d4edeb892269d23c9df1f5ce9af9 Mon Sep 17 00:00:00 2001
From: Martin Bauer <martin.bauer@fau.de>
Date: Mon, 6 May 2019 17:03:22 +0200
Subject: [PATCH] More documentation
---
pystencils_walberla/codegen.py | 54 ++++++++++++++++++++++++++++++++++
setup.py | 2 +-
2 files changed, 55 insertions(+), 1 deletion(-)
diff --git a/pystencils_walberla/codegen.py b/pystencils_walberla/codegen.py
index 84c73f0..5a2df56 100644
--- a/pystencils_walberla/codegen.py
+++ b/pystencils_walberla/codegen.py
@@ -18,6 +18,31 @@ def generate_sweep(generation_context, class_name, assignments,
namespace='pystencils', field_swaps=(), staggered=False, varying_parameters=(),
inner_outer_split=False,
**create_kernel_params):
+ """Generates a waLBerla sweep from a pystencils representation.
+
+ The constructor of the C++ sweep class expects all kernel parameters (fields and parameters) in alphabetical order.
+ Fields have to passed using BlockDataID's pointing to walberla fields
+
+ Args:
+ generation_context: build system context filled with information from waLBerla's CMake. The context for example
+ defines where to write generated files, if OpenMP is available or which SIMD instruction
+ set should be used. See waLBerla examples on how to get a context.
+ class_name: name of the generated sweep class
+ assignments: list of assignments defining the stencil update rule
+ namespace: the generated class is accessible as walberla::<namespace>::<class_name>
+ field_swaps: sequence of field pairs (field, temporary_field). The generated sweep only gets the first field
+ as argument, creating a temporary field internally which is swapped with the first field after
+ each iteration.
+ staggered: set to True to create staggered kernels, in this case assignments has to be a tuple with arguments
+ to `pystencils.create_staggered_kernel`
+ varying_parameters: Depending on the configuration, the generated kernels may receive different arguments for
+ different setups. To not have to adapt the C++ application when then parameter change,
+ the varying_parameters sequence can contain parameter names, which are always expected by
+ the C++ class constructor even if the kernel does not need them.
+ inner_outer_split: if True generate a sweep that supports separate iteration over inner and outer regions
+ to allow for communication hiding.
+ **create_kernel_params: remaining keyword arguments are passed to `pystencils.create_kernel`
+ """
if hasattr(assignments, 'all_assignments'):
assignments = assignments.all_assignments
@@ -76,6 +101,16 @@ def generate_sweep(generation_context, class_name, assignments,
def generate_pack_info_for_field(generation_context, class_name: str, field: Field,
direction_subset: Optional[Tuple[Tuple[int, int, int]]] = None,
**create_kernel_params):
+ """Creates a pack info for a pystencils field assuming a pull-type stencil, packing all cell elements.
+
+ Args:
+ generation_context: see documentation of `generate_sweep`
+ class_name: name of the generated class
+ field: pystencils field for which to generate pack info
+ direction_subset: optional sequence of directions for which values should be packed
+ otherwise a D3Q27 stencil is assumed
+ **create_kernel_params: remaining keyword arguments are passed to `pystencils.create_kernel`
+ """
if not direction_subset:
direction_subset = tuple((i, j, k) for i, j, k in product(*[(-1, 0, 1)] * 3))
@@ -86,6 +121,15 @@ def generate_pack_info_for_field(generation_context, class_name: str, field: Fie
def generate_pack_info_from_kernel(generation_context, class_name: str, assignments: Sequence[Assignment],
**create_kernel_params):
+ """Generates a waLBerla GPU PackInfo from a (pull) kernel.
+
+ Args:
+ generation_context: see documentation of `generate_sweep`
+ class_name: name of the generated class
+ assignments: list of assignments from the compute kernel - generates PackInfo for "pull" part only
+ i.e. the kernel is expected to only write to the center
+ **create_kernel_params: remaining keyword arguments are passed to `pystencils.create_kernel`
+ """
reads = set()
for a in assignments:
reads.update(a.rhs.atoms(Field.Access))
@@ -101,6 +145,16 @@ def generate_pack_info(generation_context, class_name: str,
directions_to_pack_terms: Dict[Tuple[Tuple], Sequence[Field.Access]],
namespace='pystencils',
**create_kernel_params):
+ """Generates a waLBerla GPU PackInfo
+
+ Args:
+ generation_context: see documentation of `generate_sweep`
+ class_name: name of the generated class
+ directions_to_pack_terms: maps tuples of directions to read field accesses, specifying which values have to be
+ packed for which direction
+ namespace: inner namespace of the generated class
+ **create_kernel_params: remaining keyword arguments are passed to `pystencils.create_kernel`
+ """
items = [(e[0], sorted(e[1], key=lambda x: str(x))) for e in directions_to_pack_terms.items()]
items = sorted(items, key=lambda e: e[0])
directions_to_pack_terms = OrderedDict(items)
diff --git a/setup.py b/setup.py
index 056df54..bc19a62 100644
--- a/setup.py
+++ b/setup.py
@@ -38,7 +38,7 @@ setup(name='pystencils_walberla',
author='Martin Bauer',
license='AGPLv3',
author_email='martin.bauer@fau.de',
- url='https://i10git.cs.fau.de/software/pystencils/',
+ url='https://i10git.cs.fau.de/pycodegen/pystencils_walberla',
packages=['pystencils_walberla'],
install_requires=['pystencils[alltrafos]', 'jinja2'],
package_data={'pystencils_walberla': ['templates/*']},
--
GitLab