diff --git a/docs/source/api/symbolic_language/astnodes.rst b/docs/source/api/symbolic_language/astnodes.rst index 4d5c4b89f410ba7bcbde695819eb4b7351fcd71b..ff31c98ecbb5822ef3b1fba8b18f577f2c352e0e 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 b0c3af6db67ff3cfb1e6a3d3603e84e6c4abb6cb..1b36842b8d704a4eed9faa1d499be83b0b508106 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 c546797cdb2e1c159a263b0ebfab333018464957..be60af414656314d0c64e75876208cd81ec3de80 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 dc254da0e340d518929d6eecb483defcdffbe185..976e6b2030d2350a0c7105f8a3a17cfcccf393fd 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.