From 684eb58cfaed5105e54403706d1fc165bb0a568c Mon Sep 17 00:00:00 2001
From: Frederik Hennig <frederik.hennig@fau.de>
Date: Wed, 4 Dec 2024 15:41:20 +0100
Subject: [PATCH] update API in docs
---
docs/Makefile | 7 +++++-
docs/source/backend/jit.rst | 2 +-
docs/source/backend/objects.rst | 4 ++--
docs/source/reference/gpu_kernels.md | 10 ++++----
docs/source/reference/kernelcreation.md | 32 ++++++++++++-------------
src/pystencils/__init__.py | 2 ++
src/pystencils/codegen/__init__.py | 2 ++
src/pystencils/codegen/config.py | 2 +-
8 files changed, 35 insertions(+), 26 deletions(-)
diff --git a/docs/Makefile b/docs/Makefile
index d0c3cbf10..2cfffacd0 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -12,7 +12,12 @@ BUILDDIR = build
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-.PHONY: help Makefile
+clean:
+ rm -rf source/reference/generated
+ rm -rf source/backend/generated
+ @$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help clean Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
diff --git a/docs/source/backend/jit.rst b/docs/source/backend/jit.rst
index f7a02dbd4..79776eb67 100644
--- a/docs/source/backend/jit.rst
+++ b/docs/source/backend/jit.rst
@@ -2,5 +2,5 @@
Just-In-Time Compilation
************************
-.. automodule:: pystencils.backend.jit
+.. automodule:: pystencils.jit
:members:
diff --git a/docs/source/backend/objects.rst b/docs/source/backend/objects.rst
index 050568566..942e6070f 100644
--- a/docs/source/backend/objects.rst
+++ b/docs/source/backend/objects.rst
@@ -76,7 +76,7 @@ The above alignment property, for instance, may be added to a pointer symbol by
to document its assumption that the pointer be properly aligned, in order to emit aligned load and store instructions.
It then becomes the responsibility of the runtime system embedding the kernel to check this prequesite before calling the kernel.
To make sure this information becomes visible, any properties attached to symbols exposed as kernel parameters will also
-be added to their respective `KernelParameter` instance.
+be added to their respective `Parameter` instance.
Buffers
-------
@@ -110,7 +110,7 @@ The context makes sure to avoid name conflicts between buffers.
API Documentation
=================
-.. automodule:: pystencils.backend.properties
+.. automodule:: pystencils.codegen.properties
:members:
.. automodule:: pystencils.backend.memory
diff --git a/docs/source/reference/gpu_kernels.md b/docs/source/reference/gpu_kernels.md
index c3fa70ec2..700a9cf7f 100644
--- a/docs/source/reference/gpu_kernels.md
+++ b/docs/source/reference/gpu_kernels.md
@@ -49,9 +49,9 @@ ps.inspect(kernel)
```
The `kernel` object returned by the code generator in above snippet is an instance
-of the {py:class}`GpuKernelFunction` class.
-It extends {py:class}`KernelFunction` with some GPU-specific information.
-In particular, it defines the {any}`threads_range <GpuKernelFunction.threads_range>`
+of the {py:class}`GpuKernel` class.
+It extends {py:class}`Kernel` with some GPU-specific information.
+In particular, it defines the {any}`threads_range <GpuKernel.threads_range>`
property, which tells us how many threads the kernel is expecting to be executed with:
```{code-cell} ipython3
@@ -193,8 +193,8 @@ only a part of the triangle is being processed.
:nosignatures:
:template: autosummary/recursive_class.rst
- pystencils.backend.kernelfunction.GpuKernelFunction
- pystencils.backend.jit.gpu_cupy.CupyKernelWrapper
+ pystencils.codegen.GpuKernel
+ pystencils.jit.gpu_cupy.CupyKernelWrapper
```
:::{admonition} Developers To Do:
diff --git a/docs/source/reference/kernelcreation.md b/docs/source/reference/kernelcreation.md
index be60fb28e..a8d926f2e 100644
--- a/docs/source/reference/kernelcreation.md
+++ b/docs/source/reference/kernelcreation.md
@@ -37,7 +37,7 @@ and their effects on the generated kernel.
The primary way to invoke the code generation engine is through the `create_kernel` function.
It takes two arguments:
- the list of assignment that make up the kernel (optionally wrapped as an ``AssignmentCollection``),
-- and a configuration object, an instance of {any}`CreateKernelConfig <pystencils.config.CreateKernelConfig>`.
+- and a configuration object, an instance of {any}`CreateKernelConfig <pystencils.codegen.config.CreateKernelConfig>`.
```{eval-rst}
.. module:: pystencils.kernelcreation
@@ -81,7 +81,7 @@ The above snippet defines a five-point-stencil Jacobi update. A few noteworthy t
## Inspecting the Generated Code
-The object returned by the code generator, here named `kernel`, is an instance of the {any}`KernelFunction` class.
+The object returned by the code generator, here named `kernel`, is an instance of the {any}`Kernel` class.
This object stores the kernel's name, its list of parameters, the set of fields it operates on, and its hardware target.
Also, it of course holds the kernel itself, in the form of an [abstract syntax tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) (AST).
This tree can be printed out as compilable code in the target language (C++ or, in this case, CUDA),
@@ -105,7 +105,7 @@ their interaction and effects, use cases and caveats.
```{eval-rst}
-.. module:: pystencils.config
+.. module:: pystencils.codegen.config
.. autosummary::
:toctree: generated
@@ -131,14 +131,14 @@ their interaction and effects, use cases and caveats.
Pystencils supports code generation for a variety of CPU and GPU hardware.
```{eval-rst}
-.. currentmodule:: pystencils.config
+.. currentmodule:: pystencils.codegen.config
.. autosummary::
:nosignatures:
CreateKernelConfig.target
-.. module:: pystencils.target
+.. module:: pystencils.codegen.target
.. autosummary::
:toctree: generated
@@ -197,7 +197,7 @@ are using the `int32` data type, as specified in {py:data}`index_dtype <CreateKe
```{code-cell} ipython3
:tags: [remove-input]
-driver = ps.kernelcreation.get_driver(cfg, retain_intermediates=True)
+driver = ps.codegen.get_driver(cfg, retain_intermediates=True)
kernel = driver(assignments)
ps.inspect(driver.intermediates.materialized_ispace)
```
@@ -207,7 +207,7 @@ To learn more about inspecting code after different stages of the code generator
:::
```{eval-rst}
-.. currentmodule:: pystencils.config
+.. currentmodule:: pystencils.codegen.config
.. autosummary::
:nosignatures:
@@ -241,7 +241,7 @@ only one of which can be specified at a time:
:::
```{eval-rst}
-.. currentmodule:: pystencils.config
+.. currentmodule:: pystencils.codegen
.. autosummary::
:nosignatures:
@@ -281,7 +281,7 @@ boundary values or exchange data in MPI-parallel simulations.
##### Automatic Ghost Layers
The easiest way to define an iteration space with ghost layers
-is to set `ghost_layers=ps.config.AUTO`, which is also the default
+is to set `ghost_layers=ps.AUTO`, which is also the default
when no iteration space options are specified.
In this case, the code generator will examine the kernel to find the maximum range
of its stencil -- that is, the maximum neighbor offset encountered in any field access.
@@ -301,11 +301,11 @@ To illustrate, the following kernel accesses neighbor nodes with a maximum offse
```{code-cell} ipython3
ranged_update = ps.Assignment(u.center(), v[-2, -2] + v[2, 2])
-cfg = ps.CreateKernelConfig(ghost_layers=ps.config.AUTO)
+cfg = ps.CreateKernelConfig(ghost_layers=ps.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.AUTO`, its iteration space will look like this (yellow cells are included, purple cells excluded):
```{code-cell} ipython3
:tags: [remove-input]
@@ -516,7 +516,7 @@ assignments = [
```
```{code-cell} ipython3
-driver = ps.kernelcreation.get_driver(cfg, retain_intermediates=True)
+driver = ps.codegen.get_driver(cfg, retain_intermediates=True)
kernel = driver(assignments)
ps.inspect(driver.intermediates)
```
@@ -524,14 +524,14 @@ ps.inspect(driver.intermediates)
## API: Kernel Parameters and Function Objects
```{eval-rst}
-.. module:: pystencils.backend.kernelfunction
+.. module:: pystencils.codegen
.. autosummary::
:toctree: generated
:nosignatures:
:template: autosummary/entire_class.rst
- KernelParameter
- KernelFunction
- GpuKernelFunction
+ Parameter
+ Kernel
+ GpuKernel
```
diff --git a/src/pystencils/__init__.py b/src/pystencils/__init__.py
index 028e4b885..4f8b26607 100644
--- a/src/pystencils/__init__.py
+++ b/src/pystencils/__init__.py
@@ -7,6 +7,7 @@ from .codegen import (
VectorizationConfig,
OpenMpConfig,
GpuIndexingConfig,
+ AUTO
)
from .defaults import DEFAULTS
from . import fd
@@ -53,6 +54,7 @@ __all__ = [
"VectorizationConfig",
"GpuIndexingConfig",
"OpenMpConfig",
+ "AUTO",
"create_kernel",
"create_staggered_kernel",
"Kernel",
diff --git a/src/pystencils/codegen/__init__.py b/src/pystencils/codegen/__init__.py
index 86f7f2940..e27b94b9e 100644
--- a/src/pystencils/codegen/__init__.py
+++ b/src/pystencils/codegen/__init__.py
@@ -5,6 +5,7 @@ from .config import (
VectorizationConfig,
OpenMpConfig,
GpuIndexingConfig,
+ AUTO,
)
from .parameters import Parameter
from .kernel import Kernel, GpuKernel, GpuThreadsRange
@@ -17,6 +18,7 @@ __all__ = [
"VectorizationConfig",
"OpenMpConfig",
"GpuIndexingConfig",
+ "AUTO",
"Parameter",
"Kernel",
"GpuKernel",
diff --git a/src/pystencils/codegen/config.py b/src/pystencils/codegen/config.py
index b516245fa..b6567e74a 100644
--- a/src/pystencils/codegen/config.py
+++ b/src/pystencils/codegen/config.py
@@ -222,7 +222,7 @@ class CreateKernelConfig:
"""Just-in-time compiler used to compile and load the kernel for invocation from the current Python environment.
If left at `None`, a default just-in-time compiler will be inferred from the `target` parameter.
- To explicitly disable JIT compilation, pass `pystencils.backend.jit.no_jit`.
+ To explicitly disable JIT compilation, pass `pystencils.no_jit <pystencils.jit.no_jit>`.
"""
function_name: str = "kernel"
--
GitLab