Language Modelling (pystencilssfg.lang)#

Expressions#

class pystencilssfg.lang.expressions.SfgVar(name, dtype)#

C++ Variable.

Parameters:
  • name (str) – Name of the variable. Must be a valid C++ identifer.

  • dtype (str | type | dtype | PsType) – Data type of the variable.

class pystencilssfg.lang.expressions.SfgKernelParamVar(param)#
Parameters:

param (Parameter)

class pystencilssfg.lang.expressions.DependentExpression(expr, depends, includes=None)#

Wrapper around a C++ expression code string, annotated with a set of variables and a set of header files this expression depends on.

Parameters:
  • expr (str) – C++ Code string of the expression

  • depends (Iterable[SfgVar | AugExpr]) – Iterable of variables and/or AugExpr from which variable and header dependencies are collected

  • includes (Optional[Iterable[HeaderFile]]) – Iterable of header files which this expression additionally depends on

class pystencilssfg.lang.expressions.VarExpr(var)#
Parameters:

var (SfgVar)

class pystencilssfg.lang.expressions.AugExpr(dtype=None)#

C++ expression augmented with variable dependencies and a type-dependent interface.

AugExpr is the primary class for modelling C++ expressions in pystencils-sfg. It stores both an expression’s code string, the set of variables (SfgVar) the expression depends on, as well as any headers that must be included for the expression to be evaluated. This dependency information is used by the composer and postprocessing system to infer function parameter lists and automatic header inclusions.

Construction and Binding

Constructing an AugExpr is a two-step process comprising construction and binding. An AugExpr can be constructed with our without an associated data type. After construction, the AugExpr object is still unbound; it does not yet hold any syntax.

Syntax binding can happen in two ways:

  • Calling var on an unbound AugExpr turns it into a variable with the given name. This variable expression takes its set of required header files from the required_headers field of the data type of the AugExpr.

  • Using bind, an unbound AugExpr can be bound to an arbitrary string of code. The bind method mirrors the interface of str.format to combine sub-expressions and collect their dependencies. The format static method is a wrapper around bind for expressions without a type.

An AugExpr can be bound only once.

C++ API Mirroring

Subclasses of AugExpr can mimic C++ APIs by defining factory methods that build expressions for C++ method calls, etc., from a list of argument expressions.

Parameters:

dtype (Union[str, type, dtype, PsType, None]) – Optional, data type of this expression interface

var(name)#

Bind an unbound AugExpr instance as a new variable of given name.

Parameters:

name (str)

static format(fmt, *deps, **kwdeps)#

Create a new AugExpr by combining existing expressions.

Return type:

AugExpr

Parameters:

fmt (str)

bind(fmt, *deps, require_headers=(), **kwdeps)#

Bind an unbound AugExpr instance to an expression.

Parameters:
class pystencilssfg.lang.expressions.CppClass(*args, const=False, ref=False, **kwargs)#

Convenience base class for C++ API mirroring.

Example

To reflect a C++ class (template) in pystencils-sfg, you may create a subclass of CppClass like this:

>>> class MyClassTemplate(CppClass):
...     template = lang.cpptype("mynamespace::MyClassTemplate< {T} >", "MyHeader.hpp")

Then use AugExpr initialization and binding to create variables or expressions with this class:

>>> var = MyClassTemplate(T="float").var("myObj")
>>> var
myObj
>>> str(var.dtype).strip()
'mynamespace::MyClassTemplate< float >'
Parameters:
pystencilssfg.lang.expressions.cppclass(template_str, include=())#

Convience class decorator for CppClass. It adds to the decorated class the variable template via cpptype and sets CppClass as a base clase.

>>> @cppclass("MyClass", "MyClass.hpp")
... class MyClass:
...    pass
Parameters:
pystencilssfg.lang.expressions.VarLike: TypeAlias = pystencilssfg.lang.expressions.AugExpr | pystencilssfg.lang.expressions.SfgVar | pystencils.sympyextensions.typed_sympy.TypedSymbol#

Things that may act as a variable.

Variable-like objects are entities from pystencils and pystencils-sfg that define a variable name and data type. Any VarLike object can be transformed into a canonical representation (i.e. SfgVar) using asvar.

pystencilssfg.lang.expressions.ExprLike: TypeAlias = str | pystencilssfg.lang.expressions.AugExpr | pystencilssfg.lang.expressions.SfgVar | pystencils.sympyextensions.typed_sympy.TypedSymbol#

Things that may act as a C++ expression.

This type combines all objects that pystencils-sfg can handle in the place of C++ expressions. These include all valid variable types (VarLike), plain strings, and complex expressions with variable dependency information (AugExpr).

The set of variables an expression depends on can be determined using depends.

pystencilssfg.lang.expressions.asvar(var)#

Cast a variable-like object to its canonical representation,

Parameters:

var (AugExpr | SfgVar | TypedSymbol) – Variable-like object

Returns:

Variable cast as SfgVar.

Return type:

SfgVar

Raises:

ValueError – If given a non-variable AugExpr, a TypedSymbol with a DynamicType, or any non-variable-like object.

pystencilssfg.lang.expressions.depends(expr)#

Determine the set of variables an expression depends on.

Parameters:

expr (str | AugExpr | SfgVar | TypedSymbol) – Expression-like object to examine

Returns:

Set of variables the expression depends on

Return type:

set[SfgVar]

Raises:

ValueError – If the argument was not a valid expression

pystencilssfg.lang.expressions.includes(obj)#

Determine the set of header files an expression depends on.

Parameters:
Returns:

Set of headers the expression depends on

Return type:

set[HeaderFile]

Raises:

ValueError – If the argument was not a valid variable or expression

Header Files#

class pystencilssfg.lang.headers.HeaderFile(filepath, system_header=False)#

Represents a C++ header file.

Parameters:
  • filepath (str)

  • system_header (bool)

filepath: str#

(Relative) path of this header file

system_header: bool = False#

Whether or not this is a system header.

Data Types#

class pystencilssfg.lang.types.VoidType(const=False)#

C++ void type.

Parameters:
  • args (Any)

  • kwargs (Any)

Return type:

Any

class pystencilssfg.lang.types.CppType(*template_args, const=False, **template_kwargs)#
Parameters:
  • 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.

class pystencilssfg.lang.types.TypeClass_T#

Python type variable bound to CppType.

alias of TypeVar(‘TypeClass_T’, bound=CppType)

class pystencilssfg.lang.types.CppTypeFactory(tclass)#

Type Factory returned by cpptype.

Parameters:

tclass (type[TypeClass_T])

property includes: frozenset[HeaderFile]#

Set of headers required by this factory’s type

property template_string: str#

Template string of this factory’s type

pystencilssfg.lang.types.cpptype(template_str, include=())#

Describe a C++ type template, associated with a set of required header files.

This function allows users to define C++ type templates using Python format string syntax. The types may furthermore be annotated with a set of header files that must be included in order to use the type.

>>> opt_template = lang.cpptype("std::optional< {T} >", "<optional>")
>>> opt_template.template_string
'std::optional< {T} >'

This function returns a CppTypeFactory object, which in turn can be called to create an instance of the C++ type template. Therein, the template_str argument is treated as a Python format string: The positional and keyword arguments passed to the returned type factory are passed through machinery that is based on str.format to produce the actual type name.

>>> int_option = opt_template(T="int")
>>> int_option.c_string().strip()
'std::optional< int >'

The factory may also create reference types when the ref=True is specified.

>>> int_option_ref = opt_template(T="int", ref=True)
>>> int_option_ref.c_string().strip()
'std::optional< int >&'
Parameters:
Returns:

A factory used to instantiate the type template

Return type:

CppTypeFactory

class pystencilssfg.lang.types.Ref(base_type, const=False)#

C++ reference type.

Parameters:
  • args (Any)

  • kwargs (Any)

Return type:

Any

Extraction Protocols#

class pystencilssfg.lang.extractions.SupportsFieldExtraction(*args, **kwargs)#

Protocol for field pointer and indexing extraction.

Objects adhering to this protocol are understood to provide expressions for the base pointer, shape, and stride properties of a field. They can therefore be passed to sfg.map_field.

abstract _extract_ptr()#

Extract the field base pointer.

Return an expression which represents the base pointer of this field data structure.

Return type:

AugExpr

abstract _extract_size(coordinate)#

Extract field size in a given coordinate.

If coordinate is valid for this field (i.e. smaller than its dimensionality), return an expression representing the logical size of this field in the given dimension. Otherwise, return None.

Return type:

AugExpr | None

Parameters:

coordinate (int)

abstract _extract_stride(coordinate)#

Extract field stride in a given coordinate.

If coordinate is valid for this field (i.e. smaller than its dimensionality), return an expression representing the memory linearization stride of this field in the given dimension. Otherwise, return None.

Return type:

AugExpr | None

Parameters:

coordinate (int)

class pystencilssfg.lang.extractions.SupportsVectorExtraction(*args, **kwargs)#

Protocol for component extraction from a vector.

Objects adhering to this protocol are understood to provide access to the entries of a vector and can therefore be passed to sfg.map_vector.

C++ Standard Library (pystencilssfg.lang.cpp)#

Quick Access#

Implementation#

class pystencilssfg.lang.cpp.StdMdspan(T, extents, index_type=PsIntegerType(width=64, signed=False, const=False), layout_policy=None, ref=False, const=False)#

Represents an std::mdspan instance.

The std::mdspan provides non-owning views into contiguous or strided n-dimensional arrays. It has been added to the C++ STL with the C++23 standard. As such, it is a natural data structure to target with pystencils kernels.

Concerning Headers and Namespaces

Since std::mdspan is not yet widely adopted (libc++ ships it as of LLVM 18, but GCC libstdc++ does not include it yet), you might have to manually include an implementation in your project (you can get a reference implementation at kokkos/mdspan). However, when working with a non-standard mdspan implementation, the path to its the header and the namespace it is defined in will likely be different.

To tell pystencils-sfg which headers to include and which namespace to use for mdspan, use StdMdspan.configure; for instance, adding this call before creating any mdspan objects will set their namespace to std::experimental, and require <experimental/mdspan> to be imported:

>>> from pystencilssfg.lang.cpp import std
>>> std.mdspan.configure("std::experimental", "<experimental/mdspan>")

Creation from pystencils fields

Using from_field, mdspan objects can be created directly from Field instances. The extents of the mdspan type will be inferred from the field; each fixed entry in the field’s shape will become a fixed entry of the mdspan’s extents.

The mdspan’s layout_policy defaults to std::layout_stride, which might not be the optimal choice depending on the memory layout of your fields. You may therefore override this by specifying the name of the desired layout policy. To map pystencils field layout identifiers to layout policies, consult the following table:

pystencils Layout Name

mdspan Layout Policy

"fzyx" "soa" "f" "reverse_numpy"

std::layout_left

"c" "numpy"

std::layout_right

"zyxf" "aos"

std::layout_stride

The array-of-structures ("aos", "zyxf") layout has no equivalent layout policy in the C++ standard, so it can only be mapped onto layout_stride.

Parameters:
classmethod configure(namespace='std', header='<mdspan>')#

Configure the namespace and header std::mdspan is defined in.

Parameters:
_extract_ptr()#

Extract the field base pointer.

Return an expression which represents the base pointer of this field data structure.

Return type:

AugExpr

_extract_size(coordinate)#

Extract field size in a given coordinate.

If coordinate is valid for this field (i.e. smaller than its dimensionality), return an expression representing the logical size of this field in the given dimension. Otherwise, return None.

Return type:

AugExpr | None

Parameters:

coordinate (int)

_extract_stride(coordinate)#

Extract field stride in a given coordinate.

If coordinate is valid for this field (i.e. smaller than its dimensionality), return an expression representing the memory linearization stride of this field in the given dimension. Otherwise, return None.

Return type:

AugExpr | None

Parameters:

coordinate (int)

static from_field(field, extents_type=PsIntegerType(width=64, signed=False, const=False), layout_policy=None, ref=False, const=False)#

Creates a std::mdspan instance for a given pystencils field.

Parameters:
class pystencilssfg.lang.cpp.StdVector(T, unsafe=False, ref=False, const=False)#
Parameters:
_extract_ptr()#

Extract the field base pointer.

Return an expression which represents the base pointer of this field data structure.

Return type:

AugExpr

_extract_size(coordinate)#

Extract field size in a given coordinate.

If coordinate is valid for this field (i.e. smaller than its dimensionality), return an expression representing the logical size of this field in the given dimension. Otherwise, return None.

Return type:

AugExpr | None

Parameters:

coordinate (int)

_extract_stride(coordinate)#

Extract field stride in a given coordinate.

If coordinate is valid for this field (i.e. smaller than its dimensionality), return an expression representing the memory linearization stride of this field in the given dimension. Otherwise, return None.

Return type:

AugExpr | None

Parameters:

coordinate (int)

class pystencilssfg.lang.cpp.StdTuple(*element_types, const=False, ref=False)#
Parameters:
class pystencilssfg.lang.cpp.StdSpan(T, ref=False, const=False)#
Parameters:

T (str | type | dtype | PsType)

_extract_ptr()#

Extract the field base pointer.

Return an expression which represents the base pointer of this field data structure.

Return type:

AugExpr

_extract_size(coordinate)#

Extract field size in a given coordinate.

If coordinate is valid for this field (i.e. smaller than its dimensionality), return an expression representing the logical size of this field in the given dimension. Otherwise, return None.

Return type:

AugExpr | None

Parameters:

coordinate (int)

_extract_stride(coordinate)#

Extract field stride in a given coordinate.

If coordinate is valid for this field (i.e. smaller than its dimensionality), return an expression representing the memory linearization stride of this field in the given dimension. Otherwise, return None.

Return type:

AugExpr | None

Parameters:

coordinate (int)

GPU Runtime APIs#

class pystencilssfg.lang.gpu.Dim3Interface(*args, const=False, ref=False, **kwargs)#

Interface definition for the dim3 struct of Cuda and HIP.

Parameters:
ctor(dim0=1, dim1=1, dim2=1)#

Constructor invocation of dim3

property x: AugExpr#

The x coordinate member.

property y: AugExpr#

The y coordinate member.

property z: AugExpr#

The z coordinate member.

property dims: tuple[AugExpr, AugExpr, AugExpr]#

x, y, and z as a tuple.

class pystencilssfg.lang.gpu.ProvidesGpuRuntimeAPI(*args, **kwargs)#

Protocol definition for a GPU runtime API provider.

dim3: type[Dim3Interface]#

The dim3 struct type for this GPU runtime

stream_t: type[AugExpr]#

The stream_t type for this GPU runtime

class pystencilssfg.lang.gpu.CudaAPI(*args, **kwargs)#

Reflection of the CUDA runtime API

class dim3(*args, const=False, ref=False, **kwargs)#

Implements Dim3Interface for CUDA

Parameters:
class stream_t(*args, const=False, ref=False, **kwargs)#
Parameters:
pystencilssfg.lang.gpu.cuda#

Alias for CudaAPI

class pystencilssfg.lang.gpu.HipAPI(*args, **kwargs)#

Reflection of the HIP runtime API

class dim3(*args, const=False, ref=False, **kwargs)#

Implements Dim3Interface for HIP

Parameters:
class stream_t(*args, const=False, ref=False, **kwargs)#
Parameters:
pystencilssfg.lang.gpu.hip#

Alias for HipAPI