From 07c66d675169e316af45a3aa9b4590f3fbfe2149 Mon Sep 17 00:00:00 2001
From: Frederik Hennig <frederik.hennig@fau.de>
Date: Thu, 20 Jun 2024 13:58:29 +0200
Subject: [PATCH] some fixes to the documentation
---
docs/source/api/kernelcreation/index.rst | 7 ++++-
docs/source/backend/ast.rst | 18 ++++++++++++
docs/source/backend/extensions.rst | 5 ++++
docs/source/backend/index.rst | 1 +
src/pystencils/backend/extensions/__init__.py | 29 +++++++++++++++++++
.../backend/extensions/foreign_ast.py | 6 ++--
src/pystencils/config.py | 9 ++++--
7 files changed, 68 insertions(+), 7 deletions(-)
create mode 100644 docs/source/backend/extensions.rst
diff --git a/docs/source/api/kernelcreation/index.rst b/docs/source/api/kernelcreation/index.rst
index 582ee1668..f455ab960 100644
--- a/docs/source/api/kernelcreation/index.rst
+++ b/docs/source/api/kernelcreation/index.rst
@@ -4,10 +4,15 @@ Kernel Creation
The primary interface for creating numerical kernels in pystencils is the function `create_kernel`.
+Configuration
+=============
-.. autoclass:: pystencils.CreateKernelConfig
+.. automodule:: pystencils.config
:members:
+Creation
+========
+
.. autofunction:: pystencils.create_kernel
.. autoclass:: pystencils.backend.KernelFunction
diff --git a/docs/source/backend/ast.rst b/docs/source/backend/ast.rst
index 0d0d794ab..41f230166 100644
--- a/docs/source/backend/ast.rst
+++ b/docs/source/backend/ast.rst
@@ -2,11 +2,29 @@
Abstract Syntax Tree
********************
+Inheritance Diagramm
+====================
+
+.. inheritance-diagram:: pystencils.backend.ast.astnode.PsAstNode pystencils.backend.ast.structural pystencils.backend.ast.expressions pystencils.backend.extensions.foreign_ast
+ :top-classes: pystencils.types.PsAstNode
+ :parts: 1
+
+
+Base Classes
+============
+
.. automodule:: pystencils.backend.ast.astnode
:members:
+Structural Nodes
+================
+
.. automodule:: pystencils.backend.ast.structural
:members:
+
+Expressions
+===========
+
.. automodule:: pystencils.backend.ast.expressions
:members:
diff --git a/docs/source/backend/extensions.rst b/docs/source/backend/extensions.rst
new file mode 100644
index 000000000..6fb95cda0
--- /dev/null
+++ b/docs/source/backend/extensions.rst
@@ -0,0 +1,5 @@
+************************************
+Extensions and Experimental Features
+************************************
+
+.. automodule:: pystencils.backend.extensions
diff --git a/docs/source/backend/index.rst b/docs/source/backend/index.rst
index e0e914b4d..f2fe9346d 100644
--- a/docs/source/backend/index.rst
+++ b/docs/source/backend/index.rst
@@ -16,6 +16,7 @@ who wish to customize or extend the behaviour of the code generator in their app
platforms
transformations
jit
+ extensions
Internal Representation
-----------------------
diff --git a/src/pystencils/backend/extensions/__init__.py b/src/pystencils/backend/extensions/__init__.py
index e69de29bb..9c699a3ff 100644
--- a/src/pystencils/backend/extensions/__init__.py
+++ b/src/pystencils/backend/extensions/__init__.py
@@ -0,0 +1,29 @@
+"""
+The module `pystencils.backend.extensions` contains extensions to the pystencils code generator
+beyond its core functionality.
+
+The tools and classes of this module are considered experimental;
+their support by the remaining code generator is limited.
+They can be used to model and generate code outside of the usual scope of pystencils,
+such as non-standard syntax and types.
+At the moment, the primary use case is the modelling of C++ syntax.
+
+
+Foreign Syntax Support
+======================
+
+.. automodule:: pystencils.backend.extensions.foreign_ast
+ :members:
+
+
+C++ Language Support
+====================
+
+.. automodule:: pystencils.backend.extensions.cpp
+ :members:
+
+"""
+
+from .foreign_ast import PsForeignExpression
+
+__all__ = ["PsForeignExpression"]
diff --git a/src/pystencils/backend/extensions/foreign_ast.py b/src/pystencils/backend/extensions/foreign_ast.py
index 06735a65a..55042ea83 100644
--- a/src/pystencils/backend/extensions/foreign_ast.py
+++ b/src/pystencils/backend/extensions/foreign_ast.py
@@ -14,12 +14,12 @@ class PsForeignExpression(PsExpression, ABC):
Foreign expressions are expressions whose properties are not modelled by the pystencils AST,
and which pystencils therefore does not understand.
- Support for foreign expressions by the code generator is therefore very limited;
- as a rule of thumb, only printing is supported.
- Type checking and most transformations will fail when encountering a `PsForeignExpression`.
There are many situations where non-supported expressions are needed;
the most common use case is C++ syntax.
+ Support for foreign expressions by the code generator is therefore very limited;
+ as a rule of thumb, only printing is supported.
+ Type checking and most transformations will fail when encountering a `PsForeignExpression`.
"""
__match_args__ = ("children",)
diff --git a/src/pystencils/config.py b/src/pystencils/config.py
index 8745dbfa7..d2af213c1 100644
--- a/src/pystencils/config.py
+++ b/src/pystencils/config.py
@@ -121,7 +121,7 @@ class VectorizationConfig:
@dataclass
class GpuIndexingConfig:
- """Configure index translation behaviour inside kernels generated for `Target.SYCL`."""
+ """Configure index translation behaviour for kernels generated for GPU targets."""
omit_range_check: bool = False
"""If set to `True`, omit the iteration counter range check.
@@ -134,10 +134,13 @@ class GpuIndexingConfig:
sycl_automatic_block_size: bool = True
"""If set to `True` while generating for `Target.SYCL`, let the SYCL runtime decide on the block size.
- If set to `True`, the kernel is generated for execution via ``parallel_for``-dispatch using
+ If set to `True`, the kernel is generated for execution via
+ `parallel_for <https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html#_parallel_for_invoke>`_
+ -dispatch using
a flat `sycl::range`. In this case, the GPU block size will be inferred by the SYCL runtime.
- If set to `False`, the kernel will receive an `nd_item` and has to be executed using ``parallel_for``
+ If set to `False`, the kernel will receive an `nd_item` and has to be executed using
+ `parallel_for <https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html#_parallel_for_invoke>`_
with an `nd_range`. This allows manual specification of the block size.
"""
--
GitLab