Type System

Type Creation and Conversion

create_type	Create a pystencils type object from a variety of specifications.
create_numeric_type	Like create_type, but only for numeric types.
UserTypeSpec	Represent a PEP 604 union type
constify	Adds the const qualifier to a given type.
deconstify	Removes the const qualifier from a given type.

Data Type Class Hierarchy

These are the classes that make up the type system internally. Most of the time, you will not be using them directly, so you can skip over this part unless you have very particular needs.

PsType	Base class for all pystencils types.
PsCustomType	Class to model custom types by their names.
PsStructType	Named or anonymous structured data type.
PsDereferencableType	Base class for subscriptable types.
PsPointerType	A C pointer with arbitrary base type.
PsArrayType	Multidimensional array of fixed shape.
PsNumericType	Numeric data type, i.e. any type that may occur inside arithmetic-logical expressions.
PsScalarType	Scalar numeric type.
PsVectorType	Packed vector of numeric type.
PsIntegerType	Signed and unsigned integer types.
PsBoolType	Boolean type.
PsUnsignedIntegerType	Unsigned integer types.
PsSignedIntegerType	Signed integer types.
PsIeeeFloatType	IEEE-754 floating point data types

Data Type Abbreviations

The pystencils.types.quick module contains aliases of most of the above data type classes, in order to reduce verbosity of code using the type system.

Custom	Alias of PsCustomType
Scalar	Alias of PsScalarType
Ptr	Alias of PsPointerType
Arr	Alias of PsArrayType
Bool	Alias of PsBoolType
AnyInt	Alias of PsIntegerType
UInt	Alias of PsUnsignedIntegerType
Int	Alias of PsSignedIntegerType
SInt	Alias of PsSignedIntegerType
Fp	Alias of PsIeeeFloatType

Exceptions

PsTypeError

Indicates an error relating to incorrect usage of a pystencils type.

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, ...]