From d62cf63824a43e7499ac0363afc0471935fbadc2 Mon Sep 17 00:00:00 2001
From: Frederik Hennig <frederik.hennig@fau.de>
Date: Sun, 7 Apr 2024 16:57:01 +0200
Subject: [PATCH] Add documentation for transformations module. Fix some doc
comments.
---
docs/source/backend/index.rst | 1 +
docs/source/backend/transformations.rst | 7 +++
.../backend/kernelcreation/context.py | 2 +-
.../backend/transformations/__init__.py | 59 +++++++++++++++++--
.../hoist_loop_invariant_decls.py | 2 +-
.../backend/transformations/reshape_loops.py | 4 +-
6 files changed, 66 insertions(+), 9 deletions(-)
create mode 100644 docs/source/backend/transformations.rst
diff --git a/docs/source/backend/index.rst b/docs/source/backend/index.rst
index 1e3968bc0..df194bde9 100644
--- a/docs/source/backend/index.rst
+++ b/docs/source/backend/index.rst
@@ -14,6 +14,7 @@ who wish to customize or extend the behaviour of the code generator in their app
iteration_space
translation
platforms
+ transformations
jit
Internal Representation
diff --git a/docs/source/backend/transformations.rst b/docs/source/backend/transformations.rst
new file mode 100644
index 000000000..44bf4da23
--- /dev/null
+++ b/docs/source/backend/transformations.rst
@@ -0,0 +1,7 @@
+*******************
+AST Transformations
+*******************
+
+`pystencils.backend.transformations`
+
+.. automodule:: pystencils.backend.transformations
diff --git a/src/pystencils/backend/kernelcreation/context.py b/src/pystencils/backend/kernelcreation/context.py
index dc7851a24..263c2f48e 100644
--- a/src/pystencils/backend/kernelcreation/context.py
+++ b/src/pystencils/backend/kernelcreation/context.py
@@ -161,7 +161,7 @@ class KernelCreationContext:
def duplicate_symbol(self, symb: PsSymbol) -> PsSymbol:
"""Canonically duplicates the given symbol.
- A new symbol with the same data type an name ``symb.name + "__<counter>"`` is created,
+ A new symbol with the same data type, and new name ``symb.name + "__<counter>"`` is created,
added to the symbol table, and returned.
The ``counter`` reflects the number of previously created duplicates of this symbol.
"""
diff --git a/src/pystencils/backend/transformations/__init__.py b/src/pystencils/backend/transformations/__init__.py
index df2c8e495..518c402d2 100644
--- a/src/pystencils/backend/transformations/__init__.py
+++ b/src/pystencils/backend/transformations/__init__.py
@@ -3,15 +3,15 @@ This module contains various transformation and optimization passes that can be
executed on the backend AST.
Canonical Form
-^^^^^^^^^^^^^^
+==============
Many transformations in this module require that their input AST is in *canonical form*.
This means that:
- - Each symbol, constant, and expression node is annotated with a data type;
- - Each symbol has at most one declaration;
- - Each symbol that is never written to apart from its declaration has a ``const`` type; and
- - Each symbol whose type is *not* ``const`` has at least one non-declaring assignment.
+- Each symbol, constant, and expression node is annotated with a data type;
+- Each symbol has at most one declaration;
+- Each symbol that is never written to apart from its declaration has a ``const`` type; and
+- Each symbol whose type is *not* ``const`` has at least one non-declaring assignment.
The first requirement can be ensured by running the `Typifier` on each newly constructed subtree.
The other three requirements are ensured by the `CanonicalizeSymbols` pass,
@@ -23,6 +23,53 @@ to prove their legality.
Certain transformations, like the auto-vectorizer (TODO), state additional requirements, e.g.
the absence of loop-carried dependencies.
+
+Transformations
+===============
+
+Canonicalization
+----------------
+
+.. autoclass:: CanonicalizeSymbols
+ :members: __call__
+
+AST Cloning
+-----------
+
+.. autoclass:: CanonicalClone
+ :members: __call__
+
+Simplifying Transformations
+---------------------------
+
+.. autoclass:: EliminateConstants
+ :members: __call__
+
+.. autoclass:: EliminateBranches
+ :members: __call__
+
+Code Motion
+-----------
+
+.. autoclass:: HoistLoopInvariantDeclarations
+ :members: __call__
+
+Loop Reshaping Transformations
+------------------------------
+
+.. autoclass:: ReshapeLoops
+ :members:
+
+
+Code Lowering and Materialization
+---------------------------------
+
+.. autoclass:: EraseAnonymousStructTypes
+ :members: __call__
+
+.. autoclass:: SelectFunctions
+ :members: __call__
+
"""
from .canonicalize_symbols import CanonicalizeSymbols
@@ -30,6 +77,7 @@ from .canonical_clone import CanonicalClone
from .eliminate_constants import EliminateConstants
from .eliminate_branches import EliminateBranches
from .hoist_loop_invariant_decls import HoistLoopInvariantDeclarations
+from .reshape_loops import ReshapeLoops
from .erase_anonymous_structs import EraseAnonymousStructTypes
from .select_functions import SelectFunctions
from .select_intrinsics import MaterializeVectorIntrinsics
@@ -40,6 +88,7 @@ __all__ = [
"EliminateConstants",
"EliminateBranches",
"HoistLoopInvariantDeclarations",
+ "ReshapeLoops",
"EraseAnonymousStructTypes",
"SelectFunctions",
"MaterializeVectorIntrinsics",
diff --git a/src/pystencils/backend/transformations/hoist_loop_invariant_decls.py b/src/pystencils/backend/transformations/hoist_loop_invariant_decls.py
index 592003815..5824239e4 100644
--- a/src/pystencils/backend/transformations/hoist_loop_invariant_decls.py
+++ b/src/pystencils/backend/transformations/hoist_loop_invariant_decls.py
@@ -69,7 +69,7 @@ class HoistLoopInvariantDeclarations:
in particular, each symbol may have at most one declaration.
To ensure this, a `CanonicalizeSymbols` pass should be run before `HoistLoopInvariantDeclarations`.
- `HoistLoopInvariants` assumes that all `PsMathFunction`s are pure (have no side effects),
+ `HoistLoopInvariantDeclarations` assumes that all `PsMathFunction` s are pure (have no side effects),
but makes no such assumption about instances of `CFunction`.
"""
diff --git a/src/pystencils/backend/transformations/reshape_loops.py b/src/pystencils/backend/transformations/reshape_loops.py
index 07a37a05d..ea04cdff5 100644
--- a/src/pystencils/backend/transformations/reshape_loops.py
+++ b/src/pystencils/backend/transformations/reshape_loops.py
@@ -26,7 +26,7 @@ class ReshapeLoops:
) -> tuple[Sequence[PsBlock], PsLoop]:
"""Peel off iterations from the front of a loop.
- Removes `num_iterations` from the front of the given loop and returns them as a sequence of
+ Removes ``num_iterations`` from the front of the given loop and returns them as a sequence of
independent blocks.
Args:
@@ -36,7 +36,7 @@ class ReshapeLoops:
be executed, and omit their enclosing conditional.
Returns:
- (peeled_iters, loop): Tuple containing the peeled-off iterations as a sequence of blocks,
+ Tuple containing the peeled-off iterations as a sequence of blocks,
and the remaining loop.
"""
--
GitLab