Skip to content
Snippets Groups Projects
Commit 3e77b5b6 authored by Frederik Hennig's avatar Frederik Hennig
Browse files

Refactor reference guide: Start introducing autosummary for improving API doc structure

parent 8c4d934b
Branches
No related tags found
1 merge request!425Refactor and Improve Documentation
Pipeline #70145 failed
build build
# sphinx.ext.autosummary generated files
source/reference/autoapi
{% extends "!autosummary/class.rst" %}
{% block methods %}
{% if methods %}
.. rubric:: {{ _('Methods') }}
.. autosummary::
:toctree:
{% for item in methods %}
~{{ name }}.{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
{% block attributes %}
{% if attributes %}
.. rubric:: {{ _('Attributes') }}
.. autosummary::
:toctree:
{% for item in attributes %}
~{{ name }}.{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
----------------
Kernel Structure
----------------
.. autoclass:: pystencils.AssignmentCollection
:members:
Fields API (pystencils.field)
=============================
.. automodule:: pystencils.field
:members:
.. autoclass:: pystencils.sympyextensions.ConditionalFieldAccess
:members:
Extensions to SymPy
===================
.. automodule:: pystencils.sympyextensions
Modelling Data Types
--------------------
.. automodule:: pystencils.sympyextensions.typed_sympy
:members:
Integer Operations
------------------
.. automodule:: pystencils.sympyextensions.integer_functions
:members:
...@@ -27,6 +27,7 @@ pygments_style = "sphinx" ...@@ -27,6 +27,7 @@ pygments_style = "sphinx"
extensions = [ extensions = [
"sphinx_design", "sphinx_design",
"sphinx.ext.autodoc", "sphinx.ext.autodoc",
"sphinx.ext.autosummary",
"sphinx.ext.doctest", "sphinx.ext.doctest",
"sphinx.ext.intersphinx", "sphinx.ext.intersphinx",
"sphinx.ext.mathjax", "sphinx.ext.mathjax",
......
...@@ -6,10 +6,10 @@ pystencils v2.0-dev Documentation ...@@ -6,10 +6,10 @@ pystencils v2.0-dev Documentation
:maxdepth: 1 :maxdepth: 1
:hidden: :hidden:
tutorials/index.rst tutorials/index
api/index.rst reference/index
migration.rst migration
backend/index.rst backend/index
.. note:: .. note::
You are currently viewing the documentation pages for the development revision |release| You are currently viewing the documentation pages for the development revision |release|
......
...@@ -9,6 +9,6 @@ These pages list the public APIs of pystencils, with advice on how to use them. ...@@ -9,6 +9,6 @@ These pages list the public APIs of pystencils, with advice on how to use them.
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
symbolic_language/index symbolic_language
kernelcreation/index kernelcreation/index
types types
...@@ -4,14 +4,6 @@ ...@@ -4,14 +4,6 @@
Symbolic Language Symbolic Language
***************** *****************
.. toctree::
:maxdepth: 1
:hidden:
field
astnodes
sympyextensions
Pystencils allows you to define near-arbitrarily complex numerical kernels in its symbolic Pystencils allows you to define near-arbitrarily complex numerical kernels in its symbolic
language, which is based on the computer algebra system `SymPy <https://www.sympy.org>`_. language, which is based on the computer algebra system `SymPy <https://www.sympy.org>`_.
The pystencils code generator is able to parse and translate a large portion of SymPy's The pystencils code generator is able to parse and translate a large portion of SymPy's
...@@ -31,6 +23,89 @@ The most important extension to SymPy brought by pystencils are *fields*. ...@@ -31,6 +23,89 @@ The most important extension to SymPy brought by pystencils are *fields*.
Fields are a symbolic representation of multidimensional cartesian numerical arrays, Fields are a symbolic representation of multidimensional cartesian numerical arrays,
as used in many stencil algorithms. as used in many stencil algorithms.
They are represented by the `Field` class. They are represented by the `Field` class.
Fields can be created from a textual description using the `fields <pystencils.fields>` function,
or, more concisely, using the factory methods `Field.create_generic` and `Field.create_fixed_size`.
It is also possible to create a field representing an existing numpy array,
including its shape, data type, and memory layout, using `Field.create_from_numpy_array`.
.. autosummary::
:toctree: autoapi
:nosignatures:
:template: autosummary/recursive_class.rst
pystencils.fields
pystencils.Field
.. autosummary::
:nosignatures:
pystencils.Field.create_generic
pystencils.Field.create_fixed_size
pystencils.Field.create_from_numpy_array
Assignments and Assignment Collections
======================================
Pystencils relies heavily on SymPy's `Assignment <sympy.codegen.ast.Assignment>` class.
Assignments are the fundamental components of pystencils kernels;
they are used both for assigning expressions to symbols
and for writing values to fields.
.. py:class:: pystencils.Assignment
Slightly monkey-patched version of `sympy.codegen.ast.Assignment`.
Assignments are combined and structured inside `assignment collections <pystencils.AssignmentCollection>`.
An assignment collection contains two separate lists of assignments:
- The **subexpressions** list contains assignments to symbols which can be reused in all subsequent assignments.
These are typically used to structure computations into parts
by precomputing (common) subexpressions
- The **main assignments** represent the actual effect of the kernel by storing the computation's results
into fields.
.. autosummary::
:toctree: autoapi
:nosignatures:
:template: recursive_class
pystencils.AssignmentCollection
Extensions to SymPy
===================
Pystencils comes with several extensions to the SymPy symbolic algebra system.
Expression Rewriting
--------------------
Typed Expressions
-----------------
When building numerical kernels with pystencils, it might at some point become
necessary to assert tighter control about the data types of symbols and expressions.
To achieve this, *pystencils* brings a few tools to the table:
.. autosummary::
:toctree: autoapi
pystencils.DynamicType
pystencils.TypedSymbol
pystencils.sympyextensions.CastFunc
Integer Operations
------------------
.. autosummary::
:toctree: autoapi
pystencils.sympyextensions.integer_functions.int_div
pystencils.sympyextensions.integer_functions.int_rem
Restrictions on SymPy Expressions Restrictions on SymPy Expressions
================================= =================================
......
File moved
...@@ -121,6 +121,14 @@ class Field: ...@@ -121,6 +121,14 @@ class Field:
>>> stencil = np.array([[0,0], [0,1], [0,-1]]) >>> stencil = np.array([[0,0], [0,1], [0,-1]])
>>> src, dst = fields("src(3), dst(3) : double[2D]") >>> src, dst = fields("src(3), dst(3) : double[2D]")
>>> assignments = [Assignment(dst[0,0](i), src[-offset](i)) for i, offset in enumerate(stencil)]; >>> assignments = [Assignment(dst[0,0](i), src[-offset](i)) for i, offset in enumerate(stencil)];
Args:
field_name: something
field_type: something
dtype: something
layout: something
shape: something
strides: something
""" """
@staticmethod @staticmethod
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment