From c3ed7ca58b9b574c55d71f4e62b6334ac19db173 Mon Sep 17 00:00:00 2001
From: Frederik Hennig <frederik.hennig@fau.de>
Date: Tue, 15 Oct 2024 15:25:59 +0200
Subject: [PATCH] Additions to documentation
---
.../source/api/symbolic_language/astnodes.rst | 2 +-
docs/source/backend/objects.rst | 41 ++++++++++++++++---
src/pystencils/backend/ast/expressions.py | 9 ++++
src/pystencils/backend/literals.py | 2 +-
4 files changed, 46 insertions(+), 8 deletions(-)
diff --git a/docs/source/api/symbolic_language/astnodes.rst b/docs/source/api/symbolic_language/astnodes.rst
index 4d5c4b89f..ff31c98ec 100644
--- a/docs/source/api/symbolic_language/astnodes.rst
+++ b/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:
diff --git a/docs/source/backend/objects.rst b/docs/source/backend/objects.rst
index b0c3af6db..1b36842b8 100644
--- a/docs/source/backend/objects.rst
+++ b/docs/source/backend/objects.rst
@@ -1,15 +1,44 @@
-*****************************
-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:
diff --git a/src/pystencils/backend/ast/expressions.py b/src/pystencils/backend/ast/expressions.py
index c546797cd..be60af414 100644
--- a/src/pystencils/backend/ast/expressions.py
+++ b/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
diff --git a/src/pystencils/backend/literals.py b/src/pystencils/backend/literals.py
index dc254da0e..976e6b203 100644
--- a/src/pystencils/backend/literals.py
+++ b/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.
--
GitLab