From 7308f616b138fc2061e3ddbe71d3ac3c238ccf7e Mon Sep 17 00:00:00 2001
From: Frederik Hennig <frederik.hennig@fau.de>
Date: Thu, 12 Dec 2024 13:51:48 +0100
Subject: [PATCH] minor fixes; move kernelcreation API
---
docs/source/installation.md | 1 +
docs/source/reference/api/codegen.rst | 29 +++++++++++++++++++
docs/source/reference/api/index.rst | 1 +
docs/source/reference/kernelcreation.md | 37 +++++--------------------
4 files changed, 38 insertions(+), 30 deletions(-)
create mode 100644 docs/source/reference/api/codegen.rst
diff --git a/docs/source/installation.md b/docs/source/installation.md
index c369a7fa5..cea0acd2f 100644
--- a/docs/source/installation.md
+++ b/docs/source/installation.md
@@ -25,6 +25,7 @@ The following feature sets are available:
- `interactive` (**recommended**): Install dependencies for using pystencils interactively from
within Jupyter notebooks.
+ Setting this flag will cause pip to install `jupyter`, `matplotlib`, and `graphviz`, among others, alongside pystencils.
- `alltrafos` (**recommended**): Install dependencies to enable a wider set of code transformation.
These include [islpy](https://pypi.org/project/islpy/) for polyhedral loop transformations,
and [py-cpuinfo](https://pypi.org/project/py-cpuinfo/) for detecting the current hardware in order
diff --git a/docs/source/reference/api/codegen.rst b/docs/source/reference/api/codegen.rst
new file mode 100644
index 000000000..6418f32f6
--- /dev/null
+++ b/docs/source/reference/api/codegen.rst
@@ -0,0 +1,29 @@
+Code Generator and Configuration
+================================
+
+.. module:: pystencils.kernelcreation
+
+.. autosummary::
+ :toctree: generated
+ :nosignatures:
+
+ create_kernel
+
+.. module:: pystencils.config
+
+.. autosummary::
+ :toctree: generated
+ :nosignatures:
+ :template: autosummary/entire_class.rst
+
+ CreateKernelConfig
+ CpuOptimConfig
+ OpenMpConfig
+ VectorizationConfig
+ GpuIndexingConfig
+
+.. autosummary::
+ :toctree: generated
+ :nosignatures:
+
+ AUTO
\ No newline at end of file
diff --git a/docs/source/reference/api/index.rst b/docs/source/reference/api/index.rst
index 7a824422e..b19c6303e 100644
--- a/docs/source/reference/api/index.rst
+++ b/docs/source/reference/api/index.rst
@@ -10,3 +10,4 @@ Modules
field
sympyextensions
+ codegen
diff --git a/docs/source/reference/kernelcreation.md b/docs/source/reference/kernelcreation.md
index a9fa9a8fc..fc0b2248e 100644
--- a/docs/source/reference/kernelcreation.md
+++ b/docs/source/reference/kernelcreation.md
@@ -40,13 +40,11 @@ It takes two arguments:
- and a configuration object, an instance of {any}`CreateKernelConfig <pystencils.config.CreateKernelConfig>`.
```{eval-rst}
-.. module:: pystencils.kernelcreation
-
.. autosummary::
- :toctree: generated
:nosignatures:
- create_kernel
+ pystencils.kernelcreation.create_kernel
+ pystencils.config.CreateKernelConfig
```
For a simple kernel, an invocation of the code generator might look like this:
@@ -106,28 +104,6 @@ The code generation engine can be configured using a wide range of options.
This section aims at explaining the majority of these options,
their interaction and effects, use cases and caveats.
-```{eval-rst}
-
-.. module:: pystencils.config
-
-.. autosummary::
- :toctree: generated
- :nosignatures:
- :template: autosummary/entire_class.rst
-
- CreateKernelConfig
- CpuOptimConfig
- OpenMpConfig
- VectorizationConfig
- GpuIndexingConfig
-
-.. autosummary::
- :toctree: generated
- :nosignatures:
-
- AUTO
-```
-
### Target Specification
@@ -291,7 +267,8 @@ of its stencil -- that is, the maximum neighbor offset encountered in any field
If, for instance, a neighbor node in $x$-direction with offset $k$ is accessed by the kernel,
it cannot legally execute on the outermost $k$ layers of nodes in that direction since it would
access memory out-of-bounds.
-Therefore, an automatic number of $k$ ghost layers is inferred.
+Therefore, an automatic number of $k$ ghost layers at each domain border is inferred.
+As we can see in the example below, the number of inferred ghost layers at each domain border will be set to the maximum required in any dimension.
```{code-cell} ipython3
:tags: [remove-cell]
@@ -302,13 +279,13 @@ u, v = ps.fields("u, v: [2D]")
To illustrate, the following kernel accesses neighbor nodes with a maximum offset of two:
```{code-cell} ipython3
-ranged_update = ps.Assignment(u.center(), v[-2, -2] + v[2, 2])
+ranged_update = ps.Assignment(u.center(), v[-2, -1] + v[2, 1])
cfg = ps.CreateKernelConfig(ghost_layers=ps.config.AUTO)
kernel = ps.create_kernel(ranged_update, cfg)
```
-With `ghost_layers=ps.config.AUTO`, its iteration space will look like this (yellow cells are included, purple cells excluded):
+With `ghost_layers=ps.config.AUTO`, its iteration space will look like this (yellow cells are included, purple cells excluded).
```{code-cell} ipython3
:tags: [remove-input]
@@ -453,7 +430,7 @@ and use a step size of two:
$$
start(y)=
\begin{cases}
- 0 & \quad \text{if } y \% 2 = 0 \\
+ 0 & \quad \text{if } y \; \mathrm{rem} \; 2 = 0 \\
1 & \quad \text{otherwise}
\end{cases}
$$
--
GitLab