Type System¶

The pystencils.types module contains the set of classes used by pystencils to model data types. Data types are used extensively within the code generator, but can safely be ignored by most users unless you wish to force certain types on symbols, generate mixed-precision kernels, et cetera.

Basic Functions¶

pystencils.types.create_type(type_spec)¶

Create a pystencils type object from a variety of specifications.

This function converts several possible representations of data types to an instance of PsType. The type_spec argument can be any of the following:

Strings (str): will be parsed as common C types, throwing an exception if that fails. To construct a PsCustomType instead, use the constructor of PsCustomType or its abbreviation types.quick.Custom.
Python builtin data types (instances of type): Attempts to interpret Python numeric types like so:
- int becomes a signed 64-bit integer
- float becomes a double-precision IEEE-754 float
- No others are supported at the moment
Supported Numpy scalar data types (see https://numpy.org/doc/stable/reference/arrays.scalars.html) are converted to pystencils scalar data types
Instances of numpy.dtype: Attempt to interpret scalar types like above, and structured types as structs.
Instances of PsType will be returned as they are

Parameters:: type_spec (str | type | dtype | PsType) – The data type, in one of the above formats
Return type:: PsType

pystencils.types.create_numeric_type(type_spec)¶

Like create_type, but only for numeric types.

Return type:: PsNumericType
Parameters:: type_spec (str | type | dtype | PsType) –

pystencils.types.constify(t)¶

Adds the const qualifier to a given type.

Return type:: TypeVar(T, bound= PsType)
Parameters:: t (T) –

pystencils.types.deconstify(t)¶

Removes the const qualifier from a given type.

Return type:: TypeVar(T, bound= PsType)
Parameters:: t (T) –

Data Type Class Hierarchy¶

Inheritance diagram of pystencils.types.meta.PsType, pystencils.types.types

class pystencils.types.PsType(const=False)¶

Base class for all pystencils types.

Parameters:

const (bool) – Const-qualification of this type
args (Any) –
kwargs (Any) –

Return type:

Any

property required_headers: set[str]¶: The set of header files required when this type occurs in generated code.

property itemsize: int | None¶: If this type has a valid in-memory size, return that size.

property numpy_dtype: dtype | None¶

A np.dtype object representing this data type.

Available both for backward compatibility and for interaction with the numpy-based runtime system.

class pystencils.types.types.PsCustomType(name, const=False)¶

Class to model custom types by their names.

Parameters:

name (str) – Name of the custom type.
args (Any) –
kwargs (Any) –

Return type:

Any

class pystencils.types.types.PsDereferencableType(base_type, const=False)¶

Base class for subscriptable types.

PsDereferencableType represents any type that may be dereferenced and may occur as the base of a subscript, that is, before the C [] operator.

Parameters:

base_type (PsType) – The base type, which is the type of the object obtained by dereferencing.
const (bool) – Const-qualification
args (Any) –
kwargs (Any) –

Return type:

Any

final class pystencils.types.types.PsPointerType(base_type, restrict=True, const=False)¶

A C pointer with arbitrary base type.

PsPointerType models C pointer types to arbitrary data, with support for restrict-qualified pointers.

Parameters:

args (Any) –
kwargs (Any) –

Return type:

Any

class pystencils.types.types.PsArrayType(base_type, length=None, const=False)¶

C array type of known or unknown size.

Parameters:

args (Any) –
kwargs (Any) –

Return type:

Any

class pystencils.types.types.PsStructType(members, name=None, const=False)¶

Named or anonymous structured data type.

A struct type is defined by its sequence of members. The struct may optionally have a name, although the code generator currently does not support named structs and treats them the same way as anonymous structs.

Parameters:

args (Any) –
kwargs (Any) –

Return type:

Any

class Member(name, dtype)¶

Parameters:

name (str) –
dtype (PsType) –

find_member(member_name)¶

Find a member by name

Return type:: Optional[Member]
Parameters:: member_name (str) –

property numpy_dtype: dtype¶

A np.dtype object representing this data type.

Available both for backward compatibility and for interaction with the numpy-based runtime system.

property itemsize: int¶: If this type has a valid in-memory size, return that size.

class pystencils.types.types.PsNumericType(const=False)¶

Numeric data type, i.e. any type that may occur inside arithmetic-logical expressions.

Constants

Every numeric type has to act as a factory for compile-time constants of that type. The PsConstant class relies on create_constant to instantiate constants of a given numeric type. The object returned by create_constant must implement the necessary arithmetic operations, and its arithmetic behaviour must match the given type.

create_constant should fail whenever its input cannot safely be interpreted as the given type.

Parameters:

args (Any) –
kwargs (Any) –

Return type:

Any

abstract create_constant(value)¶

Create the internal representation of a constant with this type.

Raises:: PsTypeError – If the given value cannot be interpreted in this type.
Return type:: Any
Parameters:: value (Any) –

class pystencils.types.types.PsScalarType(const=False)¶

Scalar numeric type.

Parameters:

args (Any) –
kwargs (Any) –

Return type:

Any

abstract create_literal(value)¶

Create a C numerical literal for a constant of this type.

Raises:: PsTypeError – If the given value’s type is not the numeric type’s compiler-internal representation.
Return type:: str
Parameters:: value (Any) –

abstract property width: int¶: Return this type’s width in bits.

class pystencils.types.types.PsVectorType(scalar_type, vector_entries, const=False)¶

Packed vector of numeric type.

Parameters:

element_type – Underlying scalar data type
num_entries – Number of entries in the vector
args (Any) –
kwargs (Any) –

Return type:

Any

property itemsize: int | None¶: If this type has a valid in-memory size, return that size.

property numpy_dtype¶

A np.dtype object representing this data type.

Available both for backward compatibility and for interaction with the numpy-based runtime system.

create_constant(value)¶

Create the internal representation of a constant with this type.

Raises:: PsTypeError – If the given value cannot be interpreted in this type.
Return type:: Any
Parameters:: value (Any) –

class pystencils.types.types.PsBoolType(const=False)¶

Boolean type.

Parameters:

args (Any) –
kwargs (Any) –

Return type:

Any

NUMPY_TYPE¶: alias of bool_

property width: int¶: Return this type’s width in bits.

property itemsize: int¶: If this type has a valid in-memory size, return that size.

property numpy_dtype: dtype | None¶

A np.dtype object representing this data type.

Available both for backward compatibility and for interaction with the numpy-based runtime system.

create_literal(value)¶

Create a C numerical literal for a constant of this type.

Raises:: PsTypeError – If the given value’s type is not the numeric type’s compiler-internal representation.
Return type:: str
Parameters:: value (Any) –

create_constant(value)¶

Create the internal representation of a constant with this type.

Raises:: PsTypeError – If the given value cannot be interpreted in this type.
Return type:: Any
Parameters:: value (Any) –

class pystencils.types.types.PsIntegerType(width, signed=True, const=False)¶

Signed and unsigned integer types.

PsIntegerType cannot be instantiated on its own, but only through PsSignedIntegerType and PsUnsignedIntegerType. This distinction is meant mostly to help in pattern matching.

Parameters:

args (Any) –
kwargs (Any) –

Return type:

Any

property width: int¶: Return this type’s width in bits.

property itemsize: int¶: If this type has a valid in-memory size, return that size.

property numpy_dtype: dtype | None¶

A np.dtype object representing this data type.

Available both for backward compatibility and for interaction with the numpy-based runtime system.

create_literal(value)¶

Create a C numerical literal for a constant of this type.

Raises:: PsTypeError – If the given value’s type is not the numeric type’s compiler-internal representation.
Return type:: str
Parameters:: value (Any) –

create_constant(value)¶

Create the internal representation of a constant with this type.

Raises:: PsTypeError – If the given value cannot be interpreted in this type.
Return type:: Any
Parameters:: value (Any) –

final class pystencils.types.types.PsSignedIntegerType(width, const=False)¶

Signed integer types.

Parameters:

args (Any) –
kwargs (Any) –

Return type:

Any

final class pystencils.types.types.PsUnsignedIntegerType(width, const=False)¶

Unsigned integer types.

Parameters:

args (Any) –
kwargs (Any) –

Return type:

Any

final class pystencils.types.types.PsIeeeFloatType(width, const=False)¶

IEEE-754 floating point data types

Parameters:

args (Any) –
kwargs (Any) –

Return type:

Any

property width: int¶: Return this type’s width in bits.

property itemsize: int¶: If this type has a valid in-memory size, return that size.

property numpy_dtype: dtype | None¶

A np.dtype object representing this data type.

Available both for backward compatibility and for interaction with the numpy-based runtime system.

property required_headers: set[str]¶: The set of header files required when this type occurs in generated code.

create_literal(value)¶

Create a C numerical literal for a constant of this type.

Raises:: PsTypeError – If the given value’s type is not the numeric type’s compiler-internal representation.
Return type:: str
Parameters:: value (Any) –

create_constant(value)¶

Create the internal representation of a constant with this type.

Raises:: PsTypeError – If the given value cannot be interpreted in this type.
Return type:: Any
Parameters:: value (Any) –

Data Type Abbreviations¶

Quick access to the pystencils data type system.

pystencils.types.quick.Custom¶: Custom data types are modelled only by their name.

pystencils.types.quick.Scalar¶: Scalar() matches any subclass of PsScalarType

pystencils.types.quick.Ptr¶: Ptr(t) matches PsPointerType(base_type=t)

pystencils.types.quick.Arr¶: Arr(t, s) matches PsArrayType(base_type=t, size=s)

pystencils.types.quick.Bool¶: Bool() matches PsBoolType()

pystencils.types.quick.AnyInt¶: AnyInt(width) matches both PsUnsignedIntegerType(width) and PsSignedIntegerType(width)

pystencils.types.quick.UInt¶: UInt(width) matches PsUnsignedIntegerType(width)

pystencils.types.quick.Int¶: Int(width) matches PsSignedIntegerType(width)

pystencils.types.quick.SInt¶: SInt(width) matches PsSignedIntegerType(width)

pystencils.types.quick.Fp¶: Fp(width) matches PsIeeeFloatType(width)

Implementation Details¶

Caching of Instances¶

To handle and compare types more efficiently, the pystencils type system customizes class instantiation to cache and reuse existing instances of types. This means, for example, if a 32-bit const unsigned integer type gets created in two places in the program, the resulting objects are exactly the same:

>>> from pystencils.types import PsUnsignedIntegerType
>>> t1 = PsUnsignedIntegerType(32, const=True)
>>> t2 = PsUnsignedIntegerType(32, const=True)
>>> t1 is t2
True

This mechanism is implemented by the metaclass PsTypeMeta. It is not perfect, however; some parts of Python that bypass the regular object creation sequence, such as pickle and copy.copy, may create additional instances of types.

class pystencils.types.meta.PsTypeMeta(name, bases, namespace, **kwargs)¶

Metaclass for the PsType hierarchy.

PsTypeMeta holds an internal cache of all created instances of PsType and overrides object creation such that whenever a type gets instantiated more than once with the same argument list, instead of creating a new object, the existing object is returned.

Extending the Type System¶

When extending the type system’s class hierarchy, new classes need to implement at least the internal method __args__. This method, when called on a type object, must return a hashable sequence of arguments – not including the const-qualifier – that can be used to recreate that exact type. It is used internally to compute hashes and compare equality of types, as well as for const-conversion.

pystencils.types.PsType.__args__(self)¶

Return the arguments used to create this instance, in canonical order, excluding the const-qualifier.

The tuple returned by this method must be hashable and for each instantiable subclass MyType of PsType, the following must hold:

t = MyType(< arguments >)
assert MyType(*t.__args__(), const=t.const) == t

Return type:: tuple[Any, ...]