Language Modelling (pystencilssfg.lang
)#
Expressions#
- class pystencilssfg.lang.expressions.SfgVar(name, dtype)#
C++ 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:
- 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. AnAugExpr
can be constructed with our without an associated data type. After construction, theAugExpr
object is still unbound; it does not yet hold any syntax.Syntax binding can happen in two ways:
Calling
var
on an unboundAugExpr
turns it into a variable with the given name. This variable expression takes its set of required header files from therequired_headers
field of the data type of theAugExpr
.Using
bind
, an unboundAugExpr
can be bound to an arbitrary string of code. Thebind
method mirrors the interface ofstr.format
to combine sub-expressions and collect their dependencies. Theformat
static method is a wrapper aroundbind
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
- 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 >'
- pystencilssfg.lang.expressions.cppclass(template_str, include=())#
Convience class decorator for CppClass. It adds to the decorated class the variable
template
viacpptype
and setsCppClass
as a base clase.>>> @cppclass("MyClass", "MyClass.hpp") ... class MyClass: ... pass
- Parameters:
template_str (str)
include (str | HeaderFile | Iterable[str | HeaderFile])
- 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
) usingasvar
.
- 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:
- Raises:
ValueError – If given a non-variable
AugExpr
, aTypedSymbol
with aDynamicType
, 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:
- 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:
expr – Expression-like object to examine
obj (str | AugExpr | SfgVar | TypedSymbol | PsType)
- Returns:
Set of headers the expression depends on
- Return type:
- Raises:
ValueError – If the argument was not a valid variable or expression
Header Files#
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
- 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
- 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, thetemplate_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 onstr.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:
template_str (
str
) – Format string defining the type templateinclude (
Union
[str
,HeaderFile
,Iterable
[str
|HeaderFile
]]) – Either the name of a header file, or a sequence of names of header files
- Returns:
A factory used to instantiate the type template
- Return type:
- 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:
- 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, returnNone
.
- 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
, useStdMdspan.configure
; for instance, adding this call before creating anymdspan
objects will set their namespace tostd::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 fromField
instances. The extents of themdspan
type will be inferred from the field; each fixed entry in the field’s shape will become a fixed entry of themdspan
’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"
"c"
"numpy"
"zyxf"
"aos"
The array-of-structures (
"aos"
,"zyxf"
) layout has no equivalent layout policy in the C++ standard, so it can only be mapped ontolayout_stride
.- Parameters:
- classmethod configure(namespace='std', header='<mdspan>')#
Configure the namespace and header
std::mdspan
is defined in.- Parameters:
namespace (str)
header (str | HeaderFile)
- _extract_ptr()#
Extract the field base pointer.
Return an expression which represents the base pointer of this field data structure.
- Return type:
- _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, returnNone
.
- _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, returnNone
.
- 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.
- class pystencilssfg.lang.cpp.StdVector(T, unsafe=False, ref=False, const=False)#
-
- _extract_ptr()#
Extract the field base pointer.
Return an expression which represents the base pointer of this field data structure.
- Return type:
- _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, returnNone
.
- class pystencilssfg.lang.cpp.StdTuple(*element_types, const=False, ref=False)#
- class pystencilssfg.lang.cpp.StdSpan(T, ref=False, const=False)#
-
- _extract_ptr()#
Extract the field base pointer.
Return an expression which represents the base pointer of this field data structure.
- Return type:
- _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, returnNone
.
GPU Runtime APIs#
- class pystencilssfg.lang.gpu.Dim3Interface(*args, const=False, ref=False, **kwargs)#
Interface definition for the
dim3
struct of Cuda and HIP.- ctor(dim0=1, dim1=1, dim2=1)#
Constructor invocation of
dim3
- 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
-
dim3:
- 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
- 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