Constants, Memory Objects, and Functions

Constants, Memory Objects, and Functions#

Memory Objects: Symbols and Buffers#

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 buffers (PsBuffer), 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 buffers 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.

Symbols#

In the pystencils IR, instances of PsSymbol represent what is generally known as “virtual registers”. These are memory locations that are private to a function, cannot be aliased or pointed to, and will finally reside either in physical registers or on the stack. Each symbol has a name and a data type. The data type may initially be None, in which case it should soon after be determined by the Typifier.

Other than their front-end counterpart sympy.Symbol, PsSymbol instances are mutable; their properties can and often will change over time. As a consequence, they are not comparable by value: two PsSymbol instances with the same name and data type will in general not be equal. In fact, most of the time, it is an error to have two identical symbol instances active.

Creating Symbols#

During kernel translation, symbols never exist in isolation, but should always be managed by a KernelCreationContext. Symbols can be created and retrieved using add_symbol and find_symbol. A symbol can also be duplicated using duplicate_symbol, which assigns a new name to the symbol’s copy. The KernelCreationContext keeps track of all existing symbols during a kernel translation run and makes sure that no name and data type conflicts may arise.

Never call the constructor of PsSymbol directly unless you really know what you are doing.

Symbol Properties#

Symbols can be annotated with arbitrary information using symbol properties. Each symbol property type must be a subclass of PsSymbolProperty. It is strongly recommended to implement property types using frozen dataclasses. For example, this snippet defines a property type that models pointer alignment requirements:

@dataclass(frozen=True)
class AlignmentProperty(UniqueSymbolProperty)
    """Require this pointer symbol to be aligned at a particular byte boundary."""

    byte_boundary: int

Inheriting from UniqueSymbolProperty ensures that at most one property of this type can be attached to a symbol at any time. Properties can be added, queried, and removed using the PsSymbol properties API listed below.

Many symbol properties are more relevant to consumers of generated kernels than to the code generator itself. The above alignment property, for instance, may be added to a pointer symbol by a vectorization pass to document its assumption that the pointer be properly aligned, in order to emit aligned load and store instructions. It then becomes the responsibility of the runtime system embedding the kernel to check this prequesite before calling the kernel. To make sure this information becomes visible, any properties attached to symbols exposed as kernel parameters will also be added to their respective Parameter instance.

Buffers#

Buffers, as represented by the PsBuffer class, represent contiguous, n-dimensional, linearized cuboid blocks of memory. Each buffer has a fixed name and element data type, and will be represented in the IR via three sets of symbols:

  • The base pointer is a symbol of pointer type which points into the buffer’s underlying memory area. Each buffer has at least one, its primary base pointer, whose pointed-to type must be the same as the buffer’s element type. There may be additional base pointers pointing into subsections of that memory. These additional base pointers may also have deviating data types, as is for instance required for type erasure in certain cases. To communicate its role to the code generation system, each base pointer needs to be marked as such using the BufferBasePtr property, .

  • The buffer shape defines the size of the buffer in each dimension. Each shape entry is either a symbol or a constant.

  • The buffer strides define the step size to go from one entry to the next in each dimension. Like the shape, each stride entry is also either a symbol or a constant.

The shape and stride symbols must all have the same data type, which will be stored as the buffer’s index data type.

Creating and Managing Buffers#

Similarily to symbols, buffers are typically managed by the KernelCreationContext, which associates each buffer to a front-end Field. Buffers for fields can be obtained using get_buffer. The context makes sure to avoid name conflicts between buffers.

API Documentation#

class pystencils.codegen.properties.PsSymbolProperty#

Base class for symbol properties, which can be used to add additional information to symbols

class pystencils.codegen.properties.UniqueSymbolProperty#

Base class for unique properties, of which only one instance may be registered at a time.

class pystencils.codegen.properties.FieldShape(field, coordinate)#

Symbol acts as a shape parameter to a field.

Parameters:
class pystencils.codegen.properties.FieldStride(field, coordinate)#

Symbol acts as a stride parameter to a field.

Parameters:
class pystencils.codegen.properties.FieldBasePtr(field)#

Symbol acts as a base pointer to a field.

Parameters:

field (Field)

class pystencils.backend.memory.PsSymbol(name, dtype=None)#

A mutable symbol with name and data type.

Do not create objects of this class directly unless you know what you are doing; instead obtain them from a KernelCreationContext through KernelCreationContext.get_symbol. This way, the context can keep track of all symbols used in the translation run, and uniqueness of symbols is ensured.

Parameters:
apply_dtype(dtype)#

Apply the given data type to this symbol, raising a TypeError if it conflicts with a previously set data type.

Parameters:

dtype (PsType)

property properties: frozenset[PsSymbolProperty]#

Set of properties attached to this symbol

get_properties(prop_type)#

Retrieve all properties of the given type attached to this symbol

Return type:

set[PsSymbolProperty]

Parameters:

prop_type (type[PsSymbolProperty])

add_property(property)#

Attach a property to this symbol

Parameters:

property (PsSymbolProperty)

remove_property(property)#

Remove a property from this symbol. Does nothing if the property is not attached.

Parameters:

property (PsSymbolProperty)

class pystencils.backend.memory.BackendPrivateProperty#

Mix-in marker for symbol properties that are private to the backend and should not be exported to parameters

class pystencils.backend.memory.BufferBasePtr(buffer)#

Symbol acts as a base pointer to a buffer.

Parameters:

buffer (PsBuffer)

class pystencils.backend.memory.PsBuffer(name, element_type, base_ptr, shape, strides)#

N-dimensional contiguous linearized buffer in heap memory.

PsBuffer models the memory buffers underlying the Field class to the backend. Each buffer represents a contiguous block of memory that is non-aliased and disjoint from all other buffers.

Buffer shape and stride information are given either as constants or as symbols. All indexing expressions must have the same data type, which will be selected as the buffer’s index_dtype <PsBuffer.index_dtype>.

Each buffer has at least one base pointer, which can be retrieved via the PsBuffer.base_pointer property.

Parameters:
property name#

The buffer’s name

property base_pointer: PsSymbol#

Primary base pointer

property shape: list[PsSymbol | PsConstant]#

Buffer shape symbols and/or constants

property strides: list[PsSymbol | PsConstant]#

Buffer stride symbols and/or constants

property dim: int#

Dimensionality of this buffer

property index_type: PsIntegerType#

Index data type of this buffer; i.e. data type of its shape and stride symbols

property element_type: PsType#

Element type of this buffer

class pystencils.backend.constants.PsConstant(value, dtype=None)#

Type-safe representation of typed numerical constants.

This class models constants in the backend representation of kernels. A constant may be untyped, in which case its value may be any Python object.

If the constant is typed (i.e. its dtype is not None), its data type is used to check the validity of its value and to convert it into the type’s internal representation.

Instances of PsConstant are immutable.

Parameters:

  • value (Any) – The constant’s value

  • dtype (Optional[PsNumericType]) – The constant’s data type, or None if untyped.

interpret_as(dtype)#

Interprets this untyped constant with the given data type.

If this constant is already typed, raises an error.

Return type:

PsConstant

Parameters:

dtype (PsNumericType)

reinterpret_as(dtype)#

Reinterprets this constant with the given data type.

Other than interpret_as, this method also works on typed constants.

Return type:

PsConstant

Parameters:

dtype (PsNumericType)

property dtype: PsNumericType | None#

This constant’s data type, or None if it is untyped.

The data type of a constant always has const == True.

get_dtype()#

Retrieve this constant’s data type, throwing an exception if the constant is untyped.

Return type:

PsNumericType

class pystencils.backend.literals.PsLiteral(text, dtype)#

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 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. Instances of PsLiteral are immutable.

Parameters:

Functions supported by pystencils.

Every supported function might require handling logic in the following modules:

In most cases, typification of function applications will require no special handling.

class pystencils.backend.functions.PsFunction(name, num_args)#

Base class for functions occuring in the IR

Parameters:
property name: str#

Name of this function.

property arg_count: int#

Number of arguments this function takes

class pystencils.backend.functions.MathFunctions(value)#

Mathematical functions supported by the backend.

Each platform has to materialize these functions to a concrete implementation.

Exp = ('exp', 1)#
Log = ('log', 1)#
Sin = ('sin', 1)#
Cos = ('cos', 1)#
Tan = ('tan', 1)#
Sinh = ('sinh', 1)#
Cosh = ('cosh', 1)#
ASin = ('asin', 1)#
ACos = ('acos', 1)#
ATan = ('atan', 1)#
Sqrt = ('sqrt', 1)#
Abs = ('abs', 1)#
Floor = ('floor', 1)#
Ceil = ('ceil', 1)#
Min = ('min', 2)#
Max = ('max', 2)#
Pow = ('pow', 2)#
ATan2 = ('atan2', 2)#
class pystencils.backend.functions.PsMathFunction(func)#

Homogenously typed mathematical functions.

Parameters:

func (MathFunctions)

class pystencils.backend.functions.CFunction(name, param_types, return_type)#

A concrete C function.

Instances of this class represent a C function by its name, parameter types, and return type.

Parameters:

  • name (str) – Function name

  • param_types (Sequence[PsType]) – Types of the function parameters

  • return_type (PsType) – The function’s return type

static parse(obj)#

Parse the signature of a Python callable object to obtain a CFunction object.

The callable must be fully annotated with type-like objects convertible by create_type.

Return type:

CFunction

Contents