diff --git a/docs/source/backend/arrays.rst b/docs/source/backend/arrays.rst
deleted file mode 100644
index c1b09d44c398fe789b5be1df819169f37fe022a0..0000000000000000000000000000000000000000
--- a/docs/source/backend/arrays.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-******
-Arrays
-******
-
-.. automodule:: pystencils.backend.arrays
- :members:
diff --git a/docs/source/backend/ast.rst b/docs/source/backend/ast.rst
index 68aca4ee5cc089c5c49e1ebd4e54f2221e16943b..0d0d794ab28ea230effa0b871e64c77d6a79dec2 100644
--- a/docs/source/backend/ast.rst
+++ b/docs/source/backend/ast.rst
@@ -2,6 +2,9 @@
Abstract Syntax Tree
********************
+.. automodule:: pystencils.backend.ast.astnode
+ :members:
+
.. automodule:: pystencils.backend.ast.structural
:members:
diff --git a/docs/source/backend/index.rst b/docs/source/backend/index.rst
index 3ee952ad9e7193a61be26cab2c6dfb02a2a44302..24567e6ff386988fdc725d71999e9e19ac21960a 100644
--- a/docs/source/backend/index.rst
+++ b/docs/source/backend/index.rst
@@ -2,16 +2,13 @@
Developer's Reference: Code Generation Backend
##############################################
-
-These pages provide a detailed overview of the next-gen code generation backend ``nbackend`` currently being
-developed for *pystencils*. This new backend is intended to consolidate and finally replace
-all code generation functionality currently implemented in *pystencils* version 1.x.
+These pages provide a detailed overview of the pystencils code generation backend
+as a reference for current and future developers of pystencils.
.. toctree::
:maxdepth: 1
- rationale
- arrays
+ symbols
ast
kernelcreation
jit
diff --git a/docs/source/backend/kernelcreation.rst b/docs/source/backend/kernelcreation.rst
index b07f62158debb80bb33db56243ee3f1807310061..2451b8a8c8d2aa424c0ddebd3d56bb499160c503 100644
--- a/docs/source/backend/kernelcreation.rst
+++ b/docs/source/backend/kernelcreation.rst
@@ -3,4 +3,5 @@ Kernel Creation
***************
.. automodule:: pystencils.kernelcreation
-
+ :members:
+
diff --git a/docs/source/backend/rationale.rst b/docs/source/backend/rationale.rst
deleted file mode 100644
index a69b73cd568c6cb537c657e2d5f9c5b277f2b3ae..0000000000000000000000000000000000000000
--- a/docs/source/backend/rationale.rst
+++ /dev/null
@@ -1,48 +0,0 @@
-***********************
-Rationale and Key Ideas
-***********************
-
-Expression Manipulation
-^^^^^^^^^^^^^^^^^^^^^^^
-
-The pystencils code generator was originally built based entirely on the computer algebra system SymPy.
-SymPy itself is ideal for the front-end representation of kernels using its mathematical language.
-In pystencils, however, SymPy was long used to model all mathematical expressions, from the continuous equations
-down to the bare C assignments, loop counters, and even pointer arithmetic.
-SymPy's unique properties, especially regarding automatic rewriting and simplification of expressions,
-while perfect for doing symbolic mathematics, have proven to be very problematic when used as the basis of
-an intermediate code representation.
-
-The primary problems caused by using SymPy for expression manipulation are these:
-
- - Assigning and checking types on SymPy expressions is not possible in a stable way. While a type checking
- pass over the expression trees may validate types early in the code generation process, often SymPy's auto-
- rewriting system will be triggered by changes to the AST at a later stage, silently invalidating type
- information.
- - SymPy will aggressively simplify constant expressions in a strictly mathematical way, which leads to
- semantically invalid transformations in contexts with fixed types. This problem especially concerns
- integer types, and division in integer contexts.
- - SymPy aggressively flattens expressions according to associativity, and freely reorders operands in commutative
- operations. While perfectly fine in symbolic mathematics, this behaviour makes it impossible to group
- and parenthesize operations for numerical or performance benefits. Another often-observed effect is that
- SymPy distributes constant factors across sums, strongly increasing the number of FLOPs.
-
-To avoid these problems, ``nbackend`` no longer uses SymPy for expression manipulation, but contains a native
-AST data structure for modelling expressions as in C code.
-
-Structure and Architecture of the Code Generator
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The code generation flow of *pystencils* has grown significantly over the years, to accomodate various different
-kinds of kernels, output dialects, and target platforms. Very often, extensions were retroactively integrated with
-a system that was not originally designed to support them. As a result, the code generator is now
-a very convoluted set of functions and modules, containing large volumes of hard-to-read code, much of it
-duplicated for several platforms.
-
-The design of the ``nbackend`` takes the benefit of hindsight to provide the same (and, in some cases, a broader) set of
-functionality through a much better structured software system. While the old code generator was implemented in an almost
-entirely imperative manner, the ``nbackend`` makes extensive use of object-oriented programming for knowledge representation,
-construction and internal representation of code, as well as analysis, transformation, and code generation tasks.
-As a result, the ``nbackend`` is much more modular, concise, easier to extend, and implemented in a much smaller volume of
-code.
-
diff --git a/docs/source/backend/symbols.rst b/docs/source/backend/symbols.rst
new file mode 100644
index 0000000000000000000000000000000000000000..66c8c43ba63c7740f033e7409cb5fc6f6be9bc07
--- /dev/null
+++ b/docs/source/backend/symbols.rst
@@ -0,0 +1,12 @@
+*****************************
+Symbols, Constants and Arrays
+*****************************
+
+.. autoclass:: pystencils.backend.symbols.PsSymbol
+ :members:
+
+.. autoclass:: pystencils.backend.constants.PsConstant
+ :members:
+
+.. automodule:: pystencils.backend.arrays
+ :members:
diff --git a/src/pystencils/backend/arrays.py b/src/pystencils/backend/arrays.py
index 421426afc4b1d80da9a9b5b418911ca397f3fdeb..aaae1356b3414d5a8edcc39f3247aff04e1c11c2 100644
--- a/src/pystencils/backend/arrays.py
+++ b/src/pystencils/backend/arrays.py
@@ -1,40 +1,3 @@
-"""
-The pystencils backend models contiguous n-dimensional arrays using a number of classes.
-Arrays themselves are represented through the `PsLinearizedArray` class.
-An array has a fixed name, dimensionality, and element type, as well as a number of associated
-variables.
-
-The associated variables are the *shape* and *strides* of the array, modelled by the
-`PsArrayShapeSymbol` and `PsArrayStrideSymbol` classes. They have integer type and are used to
-reason about the array's memory layout.
-
-
-Memory Layout Constraints
--------------------------
-
-Initially, all memory layout information about an array is symbolic and unconstrained.
-Several scenarios exist where memory layout must be constrained, e.g. certain pointers
-need to be aligned, certain strides must be fixed or fulfill certain alignment properties,
-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 `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,
-an optimization pass will have to add equality constraints like the following before replacing
-all occurences of the shape and stride variables with their constant value::
-
- constraints = (
- [PsKernelConstraint(s.eq(f)) for s, f in zip(arr.shape, fixed_size)]
- + [PsKernelConstraint(s.eq(f)) for s, f in zip(arr.strides, fixed_strides)]
- )
-
- kernel_function.add_constraints(*constraints)
-
-"""
-
from __future__ import annotations
from typing import Sequence
@@ -57,8 +20,7 @@ from ..defaults import DEFAULTS
class PsLinearizedArray:
"""Class to model N-dimensional contiguous arrays.
- Memory Layout, Shape and Strides
- --------------------------------
+ **Memory Layout, Shape and Strides**
The memory layout of an array is defined by its shape and strides.
Both shape and stride entries may either be constants or special variables associated with
@@ -67,7 +29,7 @@ class PsLinearizedArray:
Shape and strides may be specified at construction in the following way.
For constant entries, their value must be given as an integer.
For variable shape entries and strides, the Ellipsis `...` must be passed instead.
- Internally, the passed ``index_dtype`` will be used to create typed constants (`PsTypedConstant`)
+ Internally, the passed ``index_dtype`` will be used to create typed constants (`PsConstant`)
and variables (`PsArrayShapeSymbol` and `PsArrayStrideSymbol`) from the passed values.
"""
@@ -118,7 +80,7 @@ class PsLinearizedArray:
@property
def shape(self) -> tuple[PsArrayShapeSymbol | PsConstant, ...]:
- """The array's shape, expressed using `PsTypedConstant` and `PsArrayShapeSymbol`"""
+ """The array's shape, expressed using `PsConstant` and `PsArrayShapeSymbol`"""
return self._shape
@property
@@ -130,7 +92,7 @@ class PsLinearizedArray:
@property
def strides(self) -> tuple[PsArrayStrideSymbol | PsConstant, ...]:
- """The array's strides, expressed using `PsTypedConstant` and `PsArrayStrideSymbol`"""
+ """The array's strides, expressed using `PsConstant` and `PsArrayStrideSymbol`"""
return self._strides
@property