diff --git a/docs/Makefile b/docs/Makefile index d0c3cbf1020d5c292abdedf27627c6abe25e2293..2cfffacd09eadf196e4a978e8d503616e7bbecc7 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 f7a02dbd4d331046c99c8afccebf5764fc1225ec..79776eb67a93203fcbe9c1ef95e48cd8c9c9c888 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 0505685661f82a467eab3ae2adee38fb0adf6bd3..942e6070f2c997c7bf3e59d67e7c44bd53806e12 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 c3fa70ec29f99a728f276f2af8483caeceb43efa..700a9cf7f647962c26d5a942116a92f2f8b4fb8e 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 be60fb28e6578be4e8fa9783bd712ab16eb76347..a8d926f2ea830dfd4c15bd6e8dd0734ed1bc5d7b 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 028e4b88532cf1e3a803c056983c5d1f29cfd865..4f8b2660777dbe7a1fa535cfbbc2e64458a0d692 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 86f7f29400ee7991ab8faa19cdbe18bd562e16f4..e27b94b9ebec9197eb044cd05b5d55fd5ae17f1f 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 b516245fa9b001288857c2f6f48443b223f4112b..b6567e74a34e616fdbf340a92744bdde36dda218 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"