diff --git a/doc/sphinx/nbackend/arrays.rst b/doc/sphinx/nbackend/arrays.rst deleted file mode 100644 index b668d3c0a41ee7e78b8bc8dab77dd3898929f40d..0000000000000000000000000000000000000000 --- a/doc/sphinx/nbackend/arrays.rst +++ /dev/null @@ -1,6 +0,0 @@ -****** -Arrays -****** - -.. automodule:: pystencils.nbackend.arrays - :members: diff --git a/doc/sphinx/nbackend/ast.rst b/doc/sphinx/nbackend/ast.rst deleted file mode 100644 index ca0ccf2b9abf0c679eca1eaadc8f59d4212c6dfa..0000000000000000000000000000000000000000 --- a/doc/sphinx/nbackend/ast.rst +++ /dev/null @@ -1,6 +0,0 @@ -******************** -Abstract Syntax Tree -******************** - -.. automodule:: pystencils.nbackend.ast - :members: diff --git a/doc/sphinx/nbackend/expressions.rst b/doc/sphinx/nbackend/expressions.rst deleted file mode 100644 index 8dcf58b61235ecc98f8189e5981de52241b12ffb..0000000000000000000000000000000000000000 --- a/doc/sphinx/nbackend/expressions.rst +++ /dev/null @@ -1,15 +0,0 @@ -*********************** -Expression Manipulation -*********************** - -Variables and Constants -======================= - -.. automodule:: pystencils.nbackend.typed_expressions - :members: - -Functions -========= - -.. automodule:: pystencils.nbackend.functions - :members: diff --git a/doc/sphinx/nbackend/type_system.rst b/doc/sphinx/nbackend/type_system.rst deleted file mode 100644 index 75d126ddbc23033005cddc1337c20135baa0d298..0000000000000000000000000000000000000000 --- a/doc/sphinx/nbackend/type_system.rst +++ /dev/null @@ -1,6 +0,0 @@ -*************** -The Type System -*************** - -.. automodule:: pystencils.nbackend.types - :members: diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..378eac25d311703f3f2cd456d8036da525cd0366 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +build diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000000000000000000000000000000000000..d0c3cbf1020d5c292abdedf27627c6abe25e2293 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000000000000000000000000000000000000..747ffb7b3033659bdd2d1e6eae41ecb00358a45e --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/_static/img/logo.png b/docs/source/_static/img/logo.png new file mode 100644 index 0000000000000000000000000000000000000000..784183cd932787cfce3cf6c38e77622f40699e8f Binary files /dev/null and b/docs/source/_static/img/logo.png differ diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..cd608643b8ae6604632745106524421bccb4b719 --- /dev/null +++ b/docs/source/api/index.rst @@ -0,0 +1,10 @@ +############# +API Reference +############# + +.. toctree:: + :maxdepth: 2 + + sympyextensions/index + kernelcreation/index + types/index diff --git a/docs/source/api/kernelcreation/index.rst b/docs/source/api/kernelcreation/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..582ee16682f913cd8e1fac5a97d90eda505588f7 --- /dev/null +++ b/docs/source/api/kernelcreation/index.rst @@ -0,0 +1,14 @@ +*************** +Kernel Creation +*************** + +The primary interface for creating numerical kernels in pystencils is the function `create_kernel`. + + +.. autoclass:: pystencils.CreateKernelConfig + :members: + +.. autofunction:: pystencils.create_kernel + +.. autoclass:: pystencils.backend.KernelFunction + :members: diff --git a/docs/source/api/sympyextensions/astnodes.rst b/docs/source/api/sympyextensions/astnodes.rst new file mode 100644 index 0000000000000000000000000000000000000000..4d5c4b89f410ba7bcbde695819eb4b7351fcd71b --- /dev/null +++ b/docs/source/api/sympyextensions/astnodes.rst @@ -0,0 +1,9 @@ +---------------- +Kernel Structure +---------------- + +.. automodule:: pystencils.sympyextensions.astnodes + +.. autoclass:: pystencils.sympyextensions.AssignmentCollection + :members: + diff --git a/docs/source/api/sympyextensions/field.rst b/docs/source/api/sympyextensions/field.rst new file mode 100644 index 0000000000000000000000000000000000000000..a435c716c7fe044d8f56cef599ea247297fb4a75 --- /dev/null +++ b/docs/source/api/sympyextensions/field.rst @@ -0,0 +1,9 @@ +------------------------- +Fields (pystencils.field) +------------------------- + +.. automodule:: pystencils.field + :members: + +.. autoclass:: pystencils.sympyextensions.ConditionalFieldAccess + :members: diff --git a/docs/source/api/sympyextensions/index.rst b/docs/source/api/sympyextensions/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..606a36771e583f244d008483768ceae237ec8177 --- /dev/null +++ b/docs/source/api/sympyextensions/index.rst @@ -0,0 +1,10 @@ +***************** +Symbolic Language +***************** + +.. toctree:: + :maxdepth: 1 + + field + astnodes + diff --git a/docs/source/api/types/basic_types.rst b/docs/source/api/types/basic_types.rst new file mode 100644 index 0000000000000000000000000000000000000000..7a8156c45a4a57f5056d9e4accd7b2d9f93526fc --- /dev/null +++ b/docs/source/api/types/basic_types.rst @@ -0,0 +1,6 @@ + +Data Type Class Hierarchy +------------------------- + +.. automodule:: pystencils.types.basic_types + :members: diff --git a/docs/source/api/types/index.rst b/docs/source/api/types/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..2ac0410f6bc572ccfa0d589d4555f08692deaf70 --- /dev/null +++ b/docs/source/api/types/index.rst @@ -0,0 +1,18 @@ +********** +Data Types +********** + +Type System Module (pystencils.types) +------------------------------------- + +.. automodule:: pystencils.types + +.. autofunction:: pystencils.types.create_type +.. autofunction:: pystencils.types.create_numeric_type + +.. toctree:: + :maxdepth: 1 + + basic_types + quick + diff --git a/docs/source/api/types/quick.rst b/docs/source/api/types/quick.rst new file mode 100644 index 0000000000000000000000000000000000000000..34bc3cae51a45348109f77238b357136afb4da83 --- /dev/null +++ b/docs/source/api/types/quick.rst @@ -0,0 +1,6 @@ +Data Type Abbreviations +----------------------- + + +.. automodule:: pystencils.types.quick + :members: \ No newline at end of file diff --git a/docs/source/backend/arrays.rst b/docs/source/backend/arrays.rst new file mode 100644 index 0000000000000000000000000000000000000000..c1b09d44c398fe789b5be1df819169f37fe022a0 --- /dev/null +++ b/docs/source/backend/arrays.rst @@ -0,0 +1,6 @@ +****** +Arrays +****** + +.. automodule:: pystencils.backend.arrays + :members: diff --git a/docs/source/backend/ast.rst b/docs/source/backend/ast.rst new file mode 100644 index 0000000000000000000000000000000000000000..68aca4ee5cc089c5c49e1ebd4e54f2221e16943b --- /dev/null +++ b/docs/source/backend/ast.rst @@ -0,0 +1,9 @@ +******************** +Abstract Syntax Tree +******************** + +.. automodule:: pystencils.backend.ast.structural + :members: + +.. automodule:: pystencils.backend.ast.expressions + :members: diff --git a/doc/sphinx/nbackend/index.rst b/docs/source/backend/index.rst similarity index 63% rename from doc/sphinx/nbackend/index.rst rename to docs/source/backend/index.rst index 752fa9ccb6a3a1413ec6c6aad2be9752bbd19893..3ee952ad9e7193a61be26cab2c6dfb02a2a44302 100644 --- a/doc/sphinx/nbackend/index.rst +++ b/docs/source/backend/index.rst @@ -1,6 +1,6 @@ -############################################################# -Developer's Reference: Code Generation Backend (``nbackend``) -############################################################# +############################################## +Developer's Reference: Code Generation Backend +############################################## These pages provide a detailed overview of the next-gen code generation backend ``nbackend`` currently being @@ -11,8 +11,6 @@ all code generation functionality currently implemented in *pystencils* version :maxdepth: 1 rationale - type_system - expressions arrays ast kernelcreation diff --git a/doc/sphinx/nbackend/jit.rst b/docs/source/backend/jit.rst similarity index 69% rename from doc/sphinx/nbackend/jit.rst rename to docs/source/backend/jit.rst index 71541527f7389eece9a7ef94826bbf1e566cbad4..f7a02dbd4d331046c99c8afccebf5764fc1225ec 100644 --- a/doc/sphinx/nbackend/jit.rst +++ b/docs/source/backend/jit.rst @@ -2,5 +2,5 @@ Just-In-Time Compilation ************************ -.. automodule:: pystencils.nbackend.jit +.. automodule:: pystencils.backend.jit :members: diff --git a/doc/sphinx/nbackend/kernelcreation.rst b/docs/source/backend/kernelcreation.rst similarity index 51% rename from doc/sphinx/nbackend/kernelcreation.rst rename to docs/source/backend/kernelcreation.rst index 8232a23a1caedec164fdaa0bc0739df795d325f7..b07f62158debb80bb33db56243ee3f1807310061 100644 --- a/doc/sphinx/nbackend/kernelcreation.rst +++ b/docs/source/backend/kernelcreation.rst @@ -2,5 +2,5 @@ Kernel Creation *************** -.. automodule:: pystencils.nbackend.kernelcreation +.. automodule:: pystencils.kernelcreation diff --git a/doc/sphinx/nbackend/rationale.rst b/docs/source/backend/rationale.rst similarity index 100% rename from doc/sphinx/nbackend/rationale.rst rename to docs/source/backend/rationale.rst diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000000000000000000000000000000000000..ae9c01750e4de9143ca92826ab97c9f77c6e2d22 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,51 @@ +import datetime +import re + +from pystencils import __version__ as pystencils_version + +project = "pystencils" +html_logo = "_static/img/logo.png" + +copyright = ( + f"{datetime.datetime.now().year}, Martin Bauer, Markus Holzer, Frederik Hennig" +) +author = "Martin Bauer, Markus Holzer, Frederik Hennig" + +version = re.sub(r"(\d+\.\d+)\.\d+(.*)", r"\1\2", pystencils_version) +version = re.sub(r"(\.dev\d+).*?$", r"\1", version) +# The full version, including alpha/beta/rc tags. +release = pystencils_version + +language = "en" +default_role = "any" +pygments_style = "sphinx" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.doctest", + "sphinx.ext.intersphinx", + "sphinx.ext.mathjax", + "sphinx.ext.napoleon", +] + +templates_path = ["_templates"] +exclude_patterns = [] + +autodoc_member_order = "bysource" +autodoc_typehints = "description" + +intersphinx_mapping = { + "python": ("https://docs.python.org/3.8", None), + "numpy": ("https://docs.scipy.org/doc/numpy/", None), + "matplotlib": ("https://matplotlib.org/", None), + "sympy": ("https://docs.sympy.org/latest/", None), +} + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "furo" +html_static_path = ["_static"] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..a62225f96fe6a31f9bddfd06ad4616bc6f6f4001 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,18 @@ + +Welcome to pystencils's documentation! +====================================== + +.. toctree:: + :maxdepth: 1 + + api/index.rst + backend/index.rst + + + +.. Indices and tables +.. ================== + +.. * :ref:`genindex` +.. * :ref:`modindex` +.. * :ref:`search` diff --git a/pyproject.toml b/pyproject.toml index 0ccdca068869e749a6bdea135182b99e14245d69..5ef106e59e61780f49518cc33c6fc0dd21daf853 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -46,7 +46,7 @@ use_cython = [ ] doc = [ 'sphinx', - 'sphinx_rtd_theme', + 'furo', 'nbsphinx', 'sphinxcontrib-bibtex', 'sphinx_autodoc_typehints', diff --git a/src/pystencils/backend/arrays.py b/src/pystencils/backend/arrays.py index 16203ac1cffc467d0e8b4f5f56a4b75ae0aaa791..421426afc4b1d80da9a9b5b418911ca397f3fdeb 100644 --- a/src/pystencils/backend/arrays.py +++ b/src/pystencils/backend/arrays.py @@ -19,7 +19,7 @@ or even the field shape must be fixed. The code generation backend models such requirements and assumptions as *constraints*. Constraints are external to the arrays themselves. They are created by the AST passes which -require them and exposed through the `PsKernelFunction` class to the compiler kernel's runtime +require them and exposed through the `KernelFunction` class to the compiler kernel's runtime environment. It is the responsibility of the runtime environment to fulfill all constraints. For example, if an array ``arr`` should have both a fixed shape and fixed strides, diff --git a/src/pystencils/backend/jit/__init__.py b/src/pystencils/backend/jit/__init__.py index b3340a9ab7ffb0be2ea9812b0684178102105e20..7938f70831bb077bd5bef0ecafaba92729b71a42 100644 --- a/src/pystencils/backend/jit/__init__.py +++ b/src/pystencils/backend/jit/__init__.py @@ -2,7 +2,7 @@ JIT compilation in the ``nbackend`` is managed by subclasses of `JitBase`. A JIT compiler may freely be created and configured by the user. It can then be passed to `create_kernel` using the ``jit`` argument of -`CreateKernelConfig`, in which case it is hooked into the `PsKernelFunction.compile` method +`CreateKernelConfig`, in which case it is hooked into the `KernelFunction.compile` method of the generated kernel function:: my_jit = MyJit() @@ -29,6 +29,7 @@ Both are available here through `LegacyCpuJit` and `LegacyGpuJit`. from .jit import JitBase, NoJit, LegacyCpuJit, LegacyGpuJit no_jit = NoJit() +"""Disables just-in-time compilation for a kernel.""" __all__ = [ "JitBase", diff --git a/src/pystencils/backend/kernelcreation/__init__.py b/src/pystencils/backend/kernelcreation/__init__.py index c3846e2c9144602b6f4aa20f05ffa25a5e63787b..dea2db23214eb41f27ed54578d7af7b463f00867 100644 --- a/src/pystencils/backend/kernelcreation/__init__.py +++ b/src/pystencils/backend/kernelcreation/__init__.py @@ -92,7 +92,7 @@ and vectorization on CPU platforms with vector capabilities. Finalization ^^^^^^^^^^^^ -At last, the kernel is packed up as a `PsKernelFunction`. +At last, the kernel is packed up as a `KernelFunction`. It is furthermore annotated with constraints collected during the translation, and returned to the user. """ diff --git a/src/pystencils/backend/kernelfunction.py b/src/pystencils/backend/kernelfunction.py index 45ec32603f6669b808ba33c3a1c97f64a427314d..97837492b65cf24d2954bad72d1711d454c8925b 100644 --- a/src/pystencils/backend/kernelfunction.py +++ b/src/pystencils/backend/kernelfunction.py @@ -137,7 +137,7 @@ class KernelFunction: @property def name(self) -> str: return self._name - + @name.setter def name(self, n: str): self._name = n diff --git a/src/pystencils/config.py b/src/pystencils/config.py index cb82785dff55e0b413fef95cff46cd2b5553c61c..2d3327104dd6d5989b58a5dfc646f125e7bf94ad 100644 --- a/src/pystencils/config.py +++ b/src/pystencils/config.py @@ -110,7 +110,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 `nbackend.jit.no_jit`. + To explicitly disable JIT compilation, pass `pystencils.nbackend.jit.no_jit`. """ function_name: str = "kernel" @@ -122,18 +122,18 @@ class CreateKernelConfig: Options: - `None`: Required ghost layers are inferred from field accesses - `int`: A uniform number of ghost layers in each spatial coordinate is applied - - `Sequence[int, tuple[int, int]]`: Ghost layers are specified for each spatial coordinate. + - ``Sequence[int, tuple[int, int]]``: Ghost layers are specified for each spatial coordinate. In each coordinate, a single integer specifies the ghost layers at both the lower and upper iteration limit, while a pair of integers specifies the lower and upper ghost layers separately. When manually specifying ghost layers, it is the user's responsibility to avoid out-of-bounds memory accesses. - If `ghost_layers=None` is specified, the iteration region may otherwise be set using the `iteration_slice` option. + If ``ghost_layers=None`` is specified, the iteration region may otherwise be set using the `iteration_slice` option. """ iteration_slice: None | Sequence[slice] = None """Specifies the kernel's iteration slice. - `iteration_slice` may only be set if `ghost_layers = None`. + `iteration_slice` may only be set if ``ghost_layers=None``. If it is set, a slice must be specified for each spatial coordinate. TODO: Specification of valid slices and their behaviour """ diff --git a/src/pystencils/datahandling/datahandling_interface.py b/src/pystencils/datahandling/datahandling_interface.py index d7a49bab0473fe0be8b7bb95a11a7df9ffb70cbb..33b565e82fdce9a12e516ca4165fd53fe53799af 100644 --- a/src/pystencils/datahandling/datahandling_interface.py +++ b/src/pystencils/datahandling/datahandling_interface.py @@ -3,7 +3,7 @@ from typing import Callable, Dict, Iterable, Optional, Sequence, Tuple, Union import numpy as np -from pystencils.enums import Target, Backend +from pystencils.enums import Target from pystencils.field import Field, FieldType @@ -18,7 +18,6 @@ class DataHandling(ABC): """ _GPU_LIKE_TARGETS = [Target.GPU] - _GPU_LIKE_BACKENDS = [Backend.CUDA] # ---------------------------- Adding and accessing data ----------------------------------------------------------- @property diff --git a/src/pystencils/datahandling/parallel_datahandling.py b/src/pystencils/datahandling/parallel_datahandling.py index c0ddc9a464f4d2ebded2e0530100c098ea6728da..9edd1d437e2ddb47130fe9d32def60f398d069b6 100644 --- a/src/pystencils/datahandling/parallel_datahandling.py +++ b/src/pystencils/datahandling/parallel_datahandling.py @@ -7,7 +7,6 @@ import waLBerla as wlb from pystencils.datahandling.blockiteration import block_iteration, sliced_block_iteration from pystencils.datahandling.datahandling_interface import DataHandling -from pystencils.enums import Backend from pystencils.field import Field, FieldType from pystencils.sympyextensions.typed_sympy import FieldPointerSymbol from pystencils.utils import DotDict diff --git a/src/pystencils/datahandling/serial_datahandling.py b/src/pystencils/datahandling/serial_datahandling.py index 0f5ddb431a869f3326f25b46a4f276268d2afd44..4eb341df52b93050efef3791d32939fb33d31883 100644 --- a/src/pystencils/datahandling/serial_datahandling.py +++ b/src/pystencils/datahandling/serial_datahandling.py @@ -254,12 +254,12 @@ class SerialDataHandling(DataHandling): self.to_gpu(name) def run_kernel(self, kernel_function, **kwargs): - arrays = self.gpu_arrays if kernel_function.ast.backend in self._GPU_LIKE_BACKENDS else self.cpu_arrays + arrays = self.gpu_arrays if kernel_function.target.is_gpu() else self.cpu_arrays kernel_function(**{**arrays, **kwargs}) def get_kernel_kwargs(self, kernel_function, **kwargs): result = {} - result.update(self.gpu_arrays if kernel_function.ast.backend in self._GPU_LIKE_BACKENDS else self.cpu_arrays) + result.update(self.gpu_arrays if kernel_function.target.is_gpu() else self.cpu_arrays) result.update(kwargs) return [result] diff --git a/src/pystencils/kernelcreation.py b/src/pystencils/kernelcreation.py index a79c68c59db3d3ee1fb8d60d21f8372c6b06bd59..b2fe4b664fe391b98bd222147c2bf92e274735a3 100644 --- a/src/pystencils/kernelcreation.py +++ b/src/pystencils/kernelcreation.py @@ -36,8 +36,17 @@ __all__ = ["create_kernel"] def create_kernel( assignments: AssignmentCollection | list[Assignment] | Assignment, config: CreateKernelConfig = CreateKernelConfig(), -): - """Create a kernel function from an assignment collection.""" +) -> KernelFunction: + """Create a kernel function from a set of assignments. + + Args: + assignments: The kernel's sequence of assignments, expressed using SymPy + config: The configuration for the kernel translator + + Returns: + The numerical kernel in pystencil's internal representation, ready to be + exported or compiled + """ ctx = KernelCreationContext( default_dtype=config.default_dtype, index_dtype=config.index_dtype diff --git a/src/pystencils/runhelper/db.py b/src/pystencils/runhelper/db.py index acbe5dfa9236105a39f2fbb9bad76bd5b95ac9df..0acf53bc63ca05d79614b7c85fc66c6ecf5c982b 100644 --- a/src/pystencils/runhelper/db.py +++ b/src/pystencils/runhelper/db.py @@ -9,7 +9,7 @@ from blitzdb.backends.file.backend import serializer_classes from blitzdb.backends.file.utils import JsonEncoder from pystencils.cpu.cpujit import get_compiler_config -from pystencils import CreateKernelConfig, Target, Backend, Field +from pystencils import CreateKernelConfig, Target, Field import json import sympy as sp diff --git a/src/pystencils/sympyextensions/__init__.py b/src/pystencils/sympyextensions/__init__.py index 1f0a4c5f4c10fd9b008f9a073f20f3ba546351c0..fd1145bcbc0422247873c9c3c4864a50f80db48d 100644 --- a/src/pystencils/sympyextensions/__init__.py +++ b/src/pystencils/sympyextensions/__init__.py @@ -3,7 +3,8 @@ from .astnodes import ( AugmentedAssignment, AddAugmentedAssignment, AssignmentCollection, - SymbolGen + SymbolGen, + ConditionalFieldAccess ) from .typed_sympy import TypedSymbol, CastFunc from .simplificationstrategy import SimplificationStrategy @@ -63,6 +64,7 @@ __all__ = [ "AddAugmentedAssignment", "AssignmentCollection", "SymbolGen", + "ConditionalFieldAccess", "TypedSymbol", "CastFunc", "SimplificationStrategy", diff --git a/src/pystencils/types/__init__.py b/src/pystencils/types/__init__.py index 140151b2b902436f9138b7ad5ea57f96fbf4b2cc..98fd2dd242a7a5b9791517261a61f3f0dfe2eb66 100644 --- a/src/pystencils/types/__init__.py +++ b/src/pystencils/types/__init__.py @@ -1,3 +1,13 @@ +""" +The `pystencils.types` module contains the set of classes used by pystencils +to model data types. Data types are used extensively within the code generator, +but can safely be ignored by most users unless you wish to force certain types on +symbols, generate mixed-precision kernels, et cetera. + +For more user-friendly and less verbose access to the type modelling system, refer to +the `pystencils.types.quick` submodule. +""" + from .basic_types import ( PsType, PsCustomType, diff --git a/src/pystencils/types/basic_types.py b/src/pystencils/types/basic_types.py index 4648c32101cf4c5bb8494854983c28031e19808b..f62571922a0ebe77dba3029c113ee6cfc5f9819b 100644 --- a/src/pystencils/types/basic_types.py +++ b/src/pystencils/types/basic_types.py @@ -291,17 +291,15 @@ class PsNumericType(PsType, ABC): """Class to model numeric types, which are all types that may occur at the top-level inside arithmetic-logical expressions. - Constants - --------- + **Constants** Every numeric type has to act as a factory for compile-time constants of that type. - The `PsTypedConstant` class relies on `create_constant` to instantiate constants + The `PsConstant` class relies on `create_constant` to instantiate constants of a given numeric type. The object returned by `create_constant` must implement the necessary arithmetic operations, and its arithmetic behaviour must match the given type. `create_constant` should fail whenever its input cannot safely be interpreted as the given - type. As for which interpretations are considered 'safe', it should be as restrictive as possible. - However, `create_constant` must *never* fail for the literals ``0``, ``1`` and ``-1``. + type. """ @abstractmethod diff --git a/src/pystencils/types/quick.py b/src/pystencils/types/quick.py index 60ec516f10819a0e0ff3e0354b7899a6e5b0ee02..7e8628f6157173259bf5b073411ebaa63df0a71f 100644 --- a/src/pystencils/types/quick.py +++ b/src/pystencils/types/quick.py @@ -1,8 +1,4 @@ -"""Abbreviations and creation functions for pystencils type-modelling classes -for quick, user-friendly construction and compact pattern matching. - -This module is meant to be included whole, e.g. as `from pystencils.nbackend.types.quick import *` -""" +"""Quick access to the pystencils data type system.""" from __future__ import annotations @@ -29,7 +25,7 @@ def create_type(type_spec: UserTypeSpec) -> PsType: """Create a pystencils type object from a variety of specifications. Possible arguments are: - - Strings ('str'): will be parsed as common C types, throwing an exception if that fails. + - Strings (`str`): will be parsed as common C types, throwing an exception if that fails. To construct a `PsCustomType` instead, use the constructor of `PsCustomType` or its abbreviation ``types.quick.Custom`` instead - Python builtin data types (instances of `type`): Attempts to interpret Python numeric types like so: @@ -39,7 +35,7 @@ def create_type(type_spec: UserTypeSpec) -> PsType: - Supported Numpy scalar data types (see https://numpy.org/doc/stable/reference/arrays.scalars.html) are converted to pystencils scalar data types - Instances of `numpy.dtype`: Attempt to interpret scalar types like above, and structured types as structs. - - Instances of `PsAbstractType` will be returned as they are + - Instances of `PsType` will be returned as they are """ from .parsing import parse_type_string, interpret_python_type, interpret_numpy_dtype @@ -56,7 +52,7 @@ def create_type(type_spec: UserTypeSpec) -> PsType: def create_numeric_type(type_spec: UserTypeSpec) -> PsNumericType: - """Like `make_type`, but only for numeric types.""" + """Like `create_type`, but only for numeric types.""" dtype = create_type(type_spec) if not isinstance(dtype, PsNumericType): raise ValueError( @@ -66,31 +62,31 @@ def create_numeric_type(type_spec: UserTypeSpec) -> PsNumericType: Custom = PsCustomType -"""`Custom(name)` matches `PsCustomType(name)`""" +"""Custom data types are modelled only by their name.""" Scalar = PsScalarType -"""`Scalar()` matches any subclass of `PsScalarType`""" +"""``Scalar()`` matches any subclass of ``PsScalarType``""" Ptr = PsPointerType -"""`Ptr(t)` matches `PsPointerType(base_type=t)`""" +"""``Ptr(t)`` matches ``PsPointerType(base_type=t)``""" Arr = PsArrayType -"""`Arr(t, s)` matches PsArrayType(base_type=t, size=s)""" +"""``Arr(t, s)`` matches ``PsArrayType(base_type=t, size=s)``""" Bool = PsBoolType -"""Bool() matches PsBoolType()""" +"""``Bool()`` matches ``PsBoolType()``""" AnyInt = PsIntegerType -"""`AnyInt(width)` matches both `PsUnsignedIntegerType(width)` and `PsSignedIntegerType(width)`""" +"""``AnyInt(width)`` matches both ``PsUnsignedIntegerType(width)`` and ``PsSignedIntegerType(width)``""" UInt = PsUnsignedIntegerType -"""`UInt(width)` matches `PsUnsignedIntegerType(width)`""" +"""``UInt(width)`` matches ``PsUnsignedIntegerType(width)``""" Int = PsSignedIntegerType -"""`Int(width)` matches `PsSignedIntegerType(width)`""" +"""``Int(width)`` matches ``PsSignedIntegerType(width)``""" SInt = PsSignedIntegerType -"""`SInt(width)` matches `PsSignedIntegerType(width)`""" +"""``SInt(width)` matches `PsSignedIntegerType(width)``""" Fp = PsIeeeFloatType -"""`Fp(width)` matches `PsIeeeFloatType(width)`""" +"""``Fp(width)` matches `PsIeeeFloatType(width)``"""