Additions to documentation

docs/source/api/symbolic_language/astnodes.rst

@@ -4,6 +4,6 @@ Kernel Structure
 
 .. automodule:: pystencils.sympyextensions.astnodes
 
-.. autoclass:: pystencils.sympyextensions.AssignmentCollection
+.. autoclass:: pystencils.AssignmentCollection
     :members:
 

docs/source/backend/objects.rst

-*****************************
-Symbols, Constants and Arrays
-*****************************
+****************************
+Constants and Memory Objects
+****************************
+
+Memory Objects: Symbols and Field Arrays
+========================================
+
+The Memory Model
+----------------
+
+In order to reason about memory accesses, mutability, invariance, and aliasing, the *pystencils* backend uses
+a very simple memory model. There are three types of memory objects:
+
+- Symbols (`PsSymbol`), which act as registers for data storage within the scope of a kernel
+- Field arrays (`PsLinearizedArray`), which represent a contiguous block of memory the kernel has access to, and
+- the *unmanaged heap*, which is a global catch-all memory object which all pointers not belonging to a field
+  array point into.
+
+All of these objects are disjoint, and cannot alias each other.
+Each symbol exists in isolation,
+field arrays do not overlap,
+and raw pointers are assumed not to point into memory owned by a symbol or field array.
+Instead, all raw pointers point into unmanaged heap memory, and are assumed to *always* alias one another:
+Each change brought to unmanaged memory by one raw pointer is assumed to affect the memory pointed to by
+another raw pointer.
+
+Classes
+-------
 
 .. autoclass:: pystencils.backend.symbols.PsSymbol
     :members:
 
-.. autoclass:: pystencils.backend.constants.PsConstant
+.. automodule:: pystencils.backend.arrays
     :members:
 
-.. autoclass:: pystencils.backend.literals.PsLiteral
+
+Constants and Literals
+======================
+
+.. autoclass:: pystencils.backend.constants.PsConstant
     :members:
 
-.. automodule:: pystencils.backend.arrays
+.. autoclass:: pystencils.backend.literals.PsLiteral
     :members:

src/pystencils/backend/ast/expressions.py

@@ -590,6 +590,15 @@ class PsNeg(PsUnOp, PsNumericOpTrait):
 
 
 class PsAddressOf(PsUnOp):
+    """Take the address of a memory location.
+    
+    .. DANGER::
+        Taking the address of a memory location owned by a symbol or field array
+        introduces an alias to that memory location.
+        As pystencils assumes its symbols and fields to never be aliased, this can
+        subtly change the semantics of a kernel. 
+        Use the address-of operator with utmost care.
+    """
     pass
 
 

src/pystencils/backend/literals.py

@@ -6,7 +6,7 @@ class PsLiteral:
     """Representation of literal code.
 
     Instances of this class represent code literals inside the AST.
-    These literals are not to be confused with C literals; the name `Literal` refers to the fact that
+    These literals are not to be confused with C literals; the name 'Literal' refers to the fact that
     the code generator takes them "literally", printing them as they are.
 
     Each literal has to be annotated with a type, and is considered constant within the scope of a kernel.