From 9c97cccb51c5596922cd027f0c9fc95bbf65e3a7 Mon Sep 17 00:00:00 2001
From: Frederik Hennig <frederik.hennig@fau.de>
Date: Wed, 22 Jan 2025 13:47:09 +0100
Subject: [PATCH] some minor code + docs cleanup
---
docs/source/api/codegen.md | 180 ++++++++++++++++++
docs/source/api/codegen.rst | 94 ---------
docs/source/migration.md | 12 +-
.../backend/kernelcreation/iteration_space.py | 6 +-
src/pystencils/codegen/config.py | 19 +-
.../test_data/datahandling_save_test.npz | Bin 410 -> 420 bytes
6 files changed, 195 insertions(+), 116 deletions(-)
create mode 100644 docs/source/api/codegen.md
delete mode 100644 docs/source/api/codegen.rst
diff --git a/docs/source/api/codegen.md b/docs/source/api/codegen.md
new file mode 100644
index 000000000..b739a4f33
--- /dev/null
+++ b/docs/source/api/codegen.md
@@ -0,0 +1,180 @@
+# Code Generation
+
+## Invocation
+
+```{eval-rst}
+.. module:: pystencils.codegen
+
+.. autosummary::
+ :toctree: generated
+ :nosignatures:
+
+ create_kernel
+```
+
+## Configuration
+
+```{eval-rst}
+.. module:: pystencils.codegen.config
+```
+
+The code generation driver (`create_kernel`, but also `DefaultKernelCreationDriver`) can be configured by
+passing it a `CreateKernelConfig` object.
+This object can be constructed incrementally:
+
+```Python
+cfg = ps.CreateKernelConfig()
+cfg.default_dtype = "float32"
+cfg.target = ps.Target.X86_AVX
+cfg.cpu.openmp.enable = True
+cfg.cpu.vectorize.enable = True
+cfg.cpu.vectorize.assume_inner_stride_one = True
+```
+
+### Options and Option Categories
+
+The following options and option categories are exposed by the configuration object:
+
+#### Target Specification
+
+```{eval-rst}
+.. current
+
+.. autosummary::
+
+ ~CreateKernelConfig.target
+```
+
+#### Data Types
+
+```{eval-rst}
+.. autosummary::
+
+ ~CreateKernelConfig.default_dtype
+ ~CreateKernelConfig.index_dtype
+```
+
+#### Iteration Space
+
+```{eval-rst}
+.. autosummary::
+
+ ~CreateKernelConfig.ghost_layers
+ ~CreateKernelConfig.iteration_slice
+ ~CreateKernelConfig.index_field
+```
+
+#### Kernel Constraint Checks
+
+```{eval-rst}
+.. autosummary::
+
+ ~CreateKernelConfig.allow_double_writes
+ ~CreateKernelConfig.skip_independence_check
+```
+
+#### Target-Specific Options
+
+The following categories with target-specific options are exposed:
+
+| | |
+|---------------------------|--------------------------|
+| {any}`cpu <CpuOptions>` | Options for CPU kernels |
+| {any}`gpu <GpuOptions>` | Options for GPU kernels |
+| {any}`sycl <SyclOptions>` | Options for SYCL kernels |
+
+
+#### Kernel Object and Just-In-Time Compilation
+
+```{eval-rst}
+.. autosummary::
+
+ ~CreateKernelConfig.function_name
+ ~CreateKernelConfig.jit
+```
+
+### Configuration System Classes
+
+```{eval-rst}
+
+.. autosummary::
+ :toctree: generated
+ :nosignatures:
+ :template: autosummary/recursive_class.rst
+
+ CreateKernelConfig
+ CpuOptions
+ OpenMpOptions
+ VectorizationOptions
+ GpuOptions
+ SyclOptions
+
+.. autosummary::
+ :toctree: generated
+ :nosignatures:
+
+ AUTO
+
+.. dropdown:: Implementation Details
+
+ .. autosummary::
+ :toctree: generated
+ :nosignatures:
+ :template: autosummary/entire_class.rst
+
+ Option
+ BasicOption
+ Category
+ ConfigBase
+
+```
+
+## Target Specification
+
+```{eval-rst}
+
+.. module:: pystencils.codegen.target
+
+.. autosummary::
+ :toctree: generated
+ :nosignatures:
+ :template: autosummary/recursive_class.rst
+
+ Target
+
+```
+
+## Code Generation Drivers
+
+```{eval-rst}
+.. module:: pystencils.codegen.driver
+
+.. autosummary::
+ :toctree: generated
+ :nosignatures:
+ :template: autosummary/entire_class.rst
+
+ DefaultKernelCreationDriver
+
+.. autosummary::
+ :toctree: generated
+ :nosignatures:
+
+ get_driver
+```
+
+## Output Code Objects
+
+```{eval-rst}
+.. currentmodule:: pystencils.codegen
+
+.. autosummary::
+ :toctree: generated
+ :nosignatures:
+ :template: autosummary/entire_class.rst
+
+ Kernel
+ GpuKernel
+ Parameter
+ GpuThreadsRange
+```
diff --git a/docs/source/api/codegen.rst b/docs/source/api/codegen.rst
deleted file mode 100644
index 1fb83fe5f..000000000
--- a/docs/source/api/codegen.rst
+++ /dev/null
@@ -1,94 +0,0 @@
-Code Generation
-===============
-
-.. module:: pystencils.codegen
-
-Invocation
-----------
-
-.. autosummary::
- :toctree: generated
- :nosignatures:
-
- create_kernel
-
-Configuration
--------------
-
-.. module:: pystencils.codegen.config
-
-.. autosummary::
- :toctree: generated
- :nosignatures:
- :template: autosummary/recursive_class.rst
-
- CreateKernelConfig
- CpuOptions
- OpenMpOptions
- VectorizationOptions
- GpuOptions
- SyclOptions
-
-.. autosummary::
- :toctree: generated
- :nosignatures:
-
- AUTO
-
-.. dropdown:: Configuration System Implementation Details
-
- .. autosummary::
- :toctree: generated
- :nosignatures:
- :template: autosummary/entire_class.rst
-
- Option
- BasicOption
- Category
- ConfigBase
-
-
-Target Specification
---------------------
-
-.. module:: pystencils.codegen.target
-
-.. autosummary::
- :toctree: generated
- :nosignatures:
- :template: autosummary/recursive_class.rst
-
- Target
-
-Code Generation Drivers
------------------------
-
-.. module:: pystencils.codegen.driver
-
-.. autosummary::
- :toctree: generated
- :nosignatures:
- :template: autosummary/entire_class.rst
-
- DefaultKernelCreationDriver
-
-.. autosummary::
- :toctree: generated
- :nosignatures:
-
- get_driver
-
-Output Code Objects
--------------------
-
-.. currentmodule:: pystencils.codegen
-
-.. autosummary::
- :toctree: generated
- :nosignatures:
- :template: autosummary/entire_class.rst
-
- Kernel
- GpuKernel
- Parameter
- GpuThreadsRange
diff --git a/docs/source/migration.md b/docs/source/migration.md
index c3cb17d0f..bb4a2cffb 100644
--- a/docs/source/migration.md
+++ b/docs/source/migration.md
@@ -48,12 +48,14 @@ cfg.ghost_layers = 2
for all index calculations and loop counters.
- *CPU Optimization Options:* Should now be set via the {any}`cpu <CpuOptions>` option category and its subcategories.
-.. dropdown:: Deprecated options of `CreateKernelConfig`
+:::{dropdown} Deprecated options of `CreateKernelConfig`
- - ``data_type``: Use ``default_dtype`` instead
- - ``cpu_openmp``: Set OpenMP-Options in the `cpu.openmp <OpenMpOptions>` category instead.
- - ``cpu_vectorize_info``: Set vectorization options in the `cpu.vectorize <VectorizationOptions>` category instead
- - ``gpu_indexing_params``: Set GPU indexing options in the `gpu <GpuOptions>` category instead
+- ``data_type``: Use ``default_dtype`` instead
+- ``cpu_openmp``: Set OpenMP-Options in the `cpu.openmp <OpenMpOptions>` category instead.
+- ``cpu_vectorize_info``: Set vectorization options in the `cpu.vectorize <VectorizationOptions>` category instead
+- ``gpu_indexing_params``: Set GPU indexing options in the `gpu <GpuOptions>` category instead
+
+:::
### Type Checking
diff --git a/src/pystencils/backend/kernelcreation/iteration_space.py b/src/pystencils/backend/kernelcreation/iteration_space.py
index f7425c06b..313377fd8 100644
--- a/src/pystencils/backend/kernelcreation/iteration_space.py
+++ b/src/pystencils/backend/kernelcreation/iteration_space.py
@@ -453,11 +453,7 @@ def create_full_iteration_space(
assert not ctx.fields.index_fields
- if not (
- (ghost_layers is not None)
- or (iteration_slice is not None)
- or infer_ghost_layers
- ):
+ if (ghost_layers is None) and (iteration_slice is None) and not infer_ghost_layers:
raise ValueError(
"One argument of `ghost_layers`, `iteration_slice`, and `infer_ghost_layers` must be set."
)
diff --git a/src/pystencils/codegen/config.py b/src/pystencils/codegen/config.py
index cb457f673..cbb3f4f32 100644
--- a/src/pystencils/codegen/config.py
+++ b/src/pystencils/codegen/config.py
@@ -82,17 +82,17 @@ class Option(Generic[Option_T, Arg_T]):
def is_set(self, obj) -> bool:
return getattr(obj, self._lookup, None) is not None
- def __set_name__(self, owner, name: str):
+ def __set_name__(self, owner: ConfigBase, name: str):
self._name = name
self._lookup = f"_{name}"
- def __get__(self, obj, objtype=None) -> Option_T | None:
+ def __get__(self, obj: ConfigBase, objtype: type[ConfigBase] | None = None) -> Option_T | None:
if obj is None:
return None
return getattr(obj, self._lookup, None)
- def __set__(self, obj, arg: Arg_T | None):
+ def __set__(self, obj: ConfigBase, arg: Arg_T | None):
if arg is not None and self._validator is not None:
value = self._validator(obj, arg)
else:
@@ -190,17 +190,17 @@ class Category(Generic[Category_T]):
def __init__(self, default: Category_T):
self._default = default
- def __set_name__(self, owner, name: str):
+ def __set_name__(self, owner: ConfigBase, name: str):
self._name = name
self._lookup = f"_{name}"
- def __get__(self, obj, objtype=None) -> Category_T:
+ def __get__(self, obj: ConfigBase, objtype: type[ConfigBase] | None = None) -> Category_T:
if obj is None:
return self._default
return cast(Category_T, getattr(obj, self._lookup, None))
- def __set__(self, obj, cat: Category_T):
+ def __set__(self, obj: ConfigBase, cat: Category_T):
setattr(obj, self._lookup, cat.copy())
@@ -208,12 +208,7 @@ class _AUTO_TYPE: ... # noqa: E701
AUTO = _AUTO_TYPE()
-"""Special value that can be passed to some options for invoking automatic behaviour.
-
-Currently, these options permit `AUTO`:
-
-- `ghost_layers <CreateKernelConfig.ghost_layers>`
-"""
+"""Special value that can be passed to some options for invoking automatic behaviour."""
@dataclass
diff --git a/tests/runtime/test_data/datahandling_save_test.npz b/tests/runtime/test_data/datahandling_save_test.npz
index d363a8a0aba1bb78a06314a19b887eb4c4975334..486c7ee74d4421d563c3b1c2e3739d8db6308b07 100644
GIT binary patch
literal 420
zcmWIWW@Zs#U|`??Vnv4TVm_%zAd7*Ofq|VtgrT@7Sud}kl953GECiAPO9ScIZ^U0o
z3!FR=a4cZ$yh%}WVwU7BU6409ZQ;7b3+7FW4+)wwLwtVxlu2Ad{F++6R|5m|&w1#0
zgl-SIU~n-Ih&Eig61XB%LAb!M;UN3(z^W;7OWiZstS&PI;B`?-amfI<h>=Nz8CNKQ
m0tEsZ7(p~N%mTcL)iepH3F@r?Z&o&t8B9Q!1*BELCISH25ot;Q
literal 410
zcmWIWW@Zs#U|`??Vnv4TVm_%5Ad7*Ofq|VtgrT@7Sud}kl953GECiAPO9ScIZ^U0o
z3!FR=a4cZ$yh%}WVwU7BU6409ZQ;7b3+7FW4+)wwLwtVxlu2Ad{F++6tX$&hDq>5R
zc1o#PaXF-{T)8-4wS(G&B!*`GZ;QWZ*n0I}`m&5M0Iy?Gic9G07)B-$W?W$d3JM5l
iU<A?7kP7f7R#Puf6Vyim-mGjOGnjxd3rI_WO#}cXWnnh}
--
GitLab