diff --git a/docs/.gitignore b/docs/.gitignore index a5ee0b4af2a1f335d8d7bad76bc01d2e32f0a68d..be765e19aae423d5341d8ea05a3a0d74ff16cf66 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,4 +1,4 @@ build # sphinx.ext.autosummary generated files -source/reference/autoapi +**/autoapi diff --git a/docs/source/_static/css/fixtables.css b/docs/source/_static/css/fixtables.css new file mode 100644 index 0000000000000000000000000000000000000000..3bb5ae2f02f9751051ffdc3e1ecdaa5f8c21c498 --- /dev/null +++ b/docs/source/_static/css/fixtables.css @@ -0,0 +1,3 @@ +table.docutils { + width: 100%; +} diff --git a/docs/source/_templates/autosummary/entire_class.rst b/docs/source/_templates/autosummary/entire_class.rst new file mode 100644 index 0000000000000000000000000000000000000000..8643ade9ab822e8b1ffebc5f3f7ba96db5d0824f --- /dev/null +++ b/docs/source/_templates/autosummary/entire_class.rst @@ -0,0 +1,6 @@ +{{ fullname | escape | underline}} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + :members: diff --git a/docs/source/backend/ast.rst b/docs/source/backend/ast.rst index 823ee1d97a2919df3ab349090439e7c62a2bc358..84ccb01f3911338870ff16ba028018b07c37cdad 100644 --- a/docs/source/backend/ast.rst +++ b/docs/source/backend/ast.rst @@ -17,23 +17,117 @@ Inheritance Diagram Base Classes ------------ -.. automodule:: pystencils.backend.ast.astnode - :members: +.. module:: pystencils.backend.ast.astnode + +.. autosummary:: + :toctree: autoapi + :nosignatures: + :template: autosummary/entire_class.rst + + PsAstNode + PsLeafMixIn + Structural Nodes ---------------- -.. automodule:: pystencils.backend.ast.structural - :members: +.. module:: pystencils.backend.ast.structural + +.. autosummary:: + :toctree: autoapi + :nosignatures: + :template: autosummary/entire_class.rst + + PsBlock + PsStatement + PsAssignment + PsDeclaration + PsLoop + PsConditional + PsEmptyLeafMixIn + PsPragma + PsComment + Expressions ----------- -.. automodule:: pystencils.backend.ast.expressions - :members: +.. module:: pystencils.backend.ast.expressions + +.. autosummary:: + :toctree: autoapi + :nosignatures: + :template: autosummary/entire_class.rst + + PsExpression + PsLvalue + PsSymbolExpr + PsConstantExpr + PsLiteralExpr + PsBufferAcc + PsSubscript + PsMemAcc + PsLookup + PsCall + PsTernary + PsNumericOpTrait + PsIntOpTrait + PsBoolOpTrait + PsUnOp + PsNeg + PsAddressOf + PsCast + PsBinOp + PsAdd + PsSub + PsMul + PsDiv + PsIntDiv + PsRem + PsLeftShift + PsRightShift + PsBitwiseAnd + PsBitwiseXor + PsBitwiseOr + PsAnd + PsOr + PsNot + PsRel + PsEq + PsNe + PsGe + PsLe + PsGt + PsLt + PsArrayInitList + SIMD Nodes ---------- -.. automodule:: pystencils.backend.ast.vector - :members: +.. module:: pystencils.backend.ast.vector + +.. autosummary:: + :toctree: autoapi + :nosignatures: + :template: autosummary/entire_class.rst + + PsVectorOp + PsVecBroadcast + PsVecMemAcc + + +Utility +------- + +.. currentmodule:: pystencils.backend.ast + +.. autosummary:: + :toctree: autoapi + :nosignatures: + + expressions.evaluate_expression + dfs_preorder + dfs_postorder + util.AstEqWrapper + util.determine_memory_object diff --git a/docs/source/conf.py b/docs/source/conf.py index 0ac5f7514402b74fc12308c5e03b240c4195c635..9a4592e2ed194fc7d1d73f6351e2223c229fc1ff 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -61,6 +61,9 @@ inheritance_graph_attrs = { html_theme = "furo" html_static_path = ["_static"] +html_css_files = [ + 'css/fixtables.css', +] # NbSphinx configuration diff --git a/docs/source/migration.rst b/docs/source/migration.rst index d68900b3d9972cd768f23cba497e303694498080..ea59d8881a66f992ee2ab99f166deea9e4f70c39 100644 --- a/docs/source/migration.rst +++ b/docs/source/migration.rst @@ -51,7 +51,7 @@ Code using any of these two should not require any changes, except: - *Importing `TypedSymbol` and `create_type`:* Both `TypedSymbol` and `create_type` should now be imported directly from the ``pystencils`` namespace. - *Custom data types:* `TypedSymbol` used to accept arbitrary strings as data types. - This is no longer possible; instead, import `pystencils.types.PsCustomType <pystencils.types.types.PsCustomType>` and use it to describe + This is no longer possible; instead, import `pystencils.types.PsCustomType` and use it to describe custom data types unknown to pystencils, as in ``TypedSymbol("xs", PsCustomType("std::vector< int >"))`` All old data type classes (such as ``BasicType``, ``PointerType``, ``StructType``, etc.) have been removed diff --git a/docs/source/reference/index.rst b/docs/source/reference/index.rst index 32860e9170b498d97be9c3755511f5c2f818a80a..7da7b5795a76c01ead467215c1deb514e4fd186c 100644 --- a/docs/source/reference/index.rst +++ b/docs/source/reference/index.rst @@ -10,5 +10,5 @@ These pages list the public APIs of pystencils, with advice on how to use them. :maxdepth: 2 symbolic_language - kernelcreation/index + kernelcreation types diff --git a/docs/source/reference/kernelcreation.rst b/docs/source/reference/kernelcreation.rst new file mode 100644 index 0000000000000000000000000000000000000000..7ea20d6b64f0371754143a7468c430c46f6254ec --- /dev/null +++ b/docs/source/reference/kernelcreation.rst @@ -0,0 +1,61 @@ +.. _page_kernel_creation: + +*************** +Kernel Creation +*************** + +Targets +======= + +.. module:: pystencils.target + +.. autosummary:: + :toctree: autoapi + :nosignatures: + :template: autosummary/recursive_class.rst + + Target + + +Configuration +============= + +.. module:: pystencils.config + +.. autosummary:: + :toctree: autoapi + :nosignatures: + :template: autosummary/entire_class.rst + + CreateKernelConfig + CpuOptimConfig + OpenMpConfig + VectorizationConfig + GpuIndexingConfig + + +Creation +======== + +.. module:: pystencils.kernelcreation + +.. autosummary:: + :toctree: autoapi + :nosignatures: + + create_kernel + + +Kernel Parameters and Function Objects +====================================== + +.. module:: pystencils.backend.kernelfunction + +.. autosummary:: + :toctree: autoapi + :nosignatures: + :template: autosummary/entire_class.rst + + KernelParameter + KernelFunction + GpuKernelFunction diff --git a/docs/source/reference/kernelcreation/index.rst b/docs/source/reference/kernelcreation/index.rst deleted file mode 100644 index d86d5104e43582124ca5ea970b52af958e19d248..0000000000000000000000000000000000000000 --- a/docs/source/reference/kernelcreation/index.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. _page_kernel_creation: - -*************** -Kernel Creation -*************** - -The primary interface for creating numerical kernels in pystencils is the function `create_kernel`. - -Targets -======= - -.. automodule:: pystencils.target - :members: - -Configuration -============= - -.. automodule:: pystencils.config - :members: - -Creation -======== - -.. autofunction:: pystencils.create_kernel - -Kernel Parameters and Function Objects -====================================== - -.. automodule:: pystencils.backend.kernelfunction - :members: diff --git a/docs/source/reference/types.rst b/docs/source/reference/types.rst index 5a740c05818e632abfa1f7ca810d275c48ead77a..7b0ef5dc1a44b0e6a0f60c9f19dfb32bba80b682 100644 --- a/docs/source/reference/types.rst +++ b/docs/source/reference/types.rst @@ -2,16 +2,21 @@ Type System *********** -.. automodule:: pystencils.types +.. module:: pystencils.types -Basic Functions -------------------------------------- +Type Creation and Conversion +---------------------------- -.. autofunction:: pystencils.types.create_type -.. autofunction:: pystencils.types.create_numeric_type -.. autofunction:: pystencils.types.constify -.. autofunction:: pystencils.types.deconstify +.. autosummary:: + :toctree: autoapi + :nosignatures: + + create_type + create_numeric_type + UserTypeSpec + constify + deconstify Data Type Class Hierarchy @@ -21,18 +26,59 @@ Data Type Class Hierarchy :top-classes: pystencils.types.PsType :parts: 1 -.. autoclass:: pystencils.types.PsType - :members: +.. autosummary:: + :toctree: autoapi + :nosignatures: + :template: autosummary/entire_class.rst -.. automodule:: pystencils.types.types - :members: + PsType + PsCustomType + PsStructType + PsDereferencableType + PsPointerType + PsArrayType + PsNumericType + PsScalarType + PsVectorType + PsIntegerType + PsBoolType + PsUnsignedIntegerType + PsSignedIntegerType + PsIeeeFloatType Data Type Abbreviations ----------------------- -.. automodule:: pystencils.types.quick - :members: +.. module:: pystencils.types.quick + +The `pystencils.types.quick` module contains aliases of most of the above data type classes, +in order to reduce verbosity of code using the type system. + +.. autosummary:: + + Custom + Scalar + Ptr + Arr + Bool + AnyInt + UInt + Int + SInt + Fp + + +Exceptions +---------- + +.. currentmodule:: pystencils.types + +.. autosummary:: + :toctree: autoapi + :nosignatures: + + pystencils.types.PsTypeError Implementation Details diff --git a/src/pystencils/types/exception.py b/src/pystencils/types/exception.py index 9cf7db5af44e67b9ccfce77fdc19549452a9d082..58997c6cc253be2af9011cf8d3d540c07e28c85f 100644 --- a/src/pystencils/types/exception.py +++ b/src/pystencils/types/exception.py @@ -1,2 +1,2 @@ class PsTypeError(Exception): - """Indicates a type error in the pystencils AST.""" + """Indicates an error relating to incorrect usage of a pystencils type.""" diff --git a/src/pystencils/types/parsing.py b/src/pystencils/types/parsing.py index c7a54d1a0831f9f7d01039f19e8e9f1395fe09c4..e398b14e3fe39306e25f180033314d29f94d9e76 100644 --- a/src/pystencils/types/parsing.py +++ b/src/pystencils/types/parsing.py @@ -12,6 +12,7 @@ from .types import ( ) UserTypeSpec = str | type | np.dtype | PsType +"""Valid arguments for `create_type`.""" def create_type(type_spec: UserTypeSpec) -> PsType: @@ -21,8 +22,7 @@ def create_type(type_spec: UserTypeSpec) -> PsType: The ``type_spec`` argument can be any of the following: - 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`. + Custom types must be created explicitly using `PsCustomType`. - Python builtin data types (instances of `type`): Attempts to interpret Python numeric types like so: - `int` becomes a signed 64-bit integer - `float` becomes a double-precision IEEE-754 float diff --git a/src/pystencils/types/quick.py b/src/pystencils/types/quick.py index 146528c65ebfe66074b6412002db4ca151fde898..1c54b5436ee53de746e0b98115c12294f2ef46ee 100644 --- a/src/pystencils/types/quick.py +++ b/src/pystencils/types/quick.py @@ -15,31 +15,31 @@ from .types import ( ) Custom = PsCustomType -"""Custom data types are modelled only by their name.""" +"""Alias of `PsCustomType`""" Scalar = PsScalarType -"""``Scalar()`` matches any subclass of ``PsScalarType``""" +"""Alias of `PsScalarType`""" Ptr = PsPointerType -"""``Ptr(t)`` matches ``PsPointerType(base_type=t)``""" +"""Alias of `PsPointerType`""" Arr = PsArrayType -"""``Arr(t, s)`` matches ``PsArrayType(base_type=t, size=s)``""" +"""Alias of `PsArrayType`""" Bool = PsBoolType -"""``Bool()`` matches ``PsBoolType()``""" +"""Alias of `PsBoolType`""" AnyInt = PsIntegerType -"""``AnyInt(width)`` matches both ``PsUnsignedIntegerType(width)`` and ``PsSignedIntegerType(width)``""" +"""Alias of `PsIntegerType`""" UInt = PsUnsignedIntegerType -"""``UInt(width)`` matches ``PsUnsignedIntegerType(width)``""" +"""Alias of `PsUnsignedIntegerType`""" Int = PsSignedIntegerType -"""``Int(width)`` matches ``PsSignedIntegerType(width)``""" +"""Alias of `PsSignedIntegerType`""" SInt = PsSignedIntegerType -"""``SInt(width)`` matches ``PsSignedIntegerType(width)``""" +"""Alias of `PsSignedIntegerType`""" Fp = PsIeeeFloatType -"""``Fp(width)`` matches ``PsIeeeFloatType(width)``""" +"""Alias of `PsIeeeFloatType`"""