Composer API (pystencilssfg.composer)¶

class pystencilssfg.composer.SfgComposer(sfg)¶

Primary interface for constructing source files in pystencils-sfg.

The SfgComposer combines the SfgBasicComposer for the basic components (kernel namespaces, includes, definitions, and functions) and the SfgClassComposer for constructing struct s and class es.

Parameters:: sfg (SfgContext | SfgBasicComposer) –

class pystencilssfg.composer.SfgIComposer(ctx)¶

Parameters:: ctx (SfgContext) –

class pystencilssfg.composer.SfgBasicComposer(sfg)¶

Composer for basic source components, and base class for all composer mix-ins.

Parameters:: sfg (SfgContext | SfgIComposer) –

prelude(content)¶

Append a string to the prelude comment, to be printed at the top of both generated files.

The string should not contain C/C++ comment delimiters, since these will be added automatically during code generation.

Parameters:: content (str) –

define(*definitions)¶

Add custom definitions to the generated header file.

Parameters:: definitions (str) –

define_once(*definitions)¶

Same as define, but only adds definitions only if the same code string was not already added.

Parameters:: definitions (str) –

namespace(namespace)¶

Set the inner code namespace. Throws an exception if a namespace was already set.

Parameters:: namespace (str) –

generate(generator)¶

Invoke a custom code generator with the underlying context.

Parameters:: generator (CustomGenerator) –

property kernels: SfgKernelNamespace¶

The default kernel namespace.

Add kernels like:

sfg.kernels.add(ast, "kernel_name")
sfg.kernels.create(assignments, "kernel_name", config)

kernel_namespace(name)¶

Return the kernel namespace of the given name, creating it if it does not exist yet.

Return type:: SfgKernelNamespace
Parameters:: name (str) –

include(header_file, private=False)¶

Include a header file.

Parameters:

header_file (str) – Path to the header file. Enclose in <> for a system header.
private (bool) – If True, in header-implementation code generation, the header file is only included in the implementation file.

numpy_struct(name, dtype, add_constructor=True)¶

Add a numpy structured data type as a C++ struct

Return type:

SfgClass

Returns:

The created class object

Parameters:

name (str) –
dtype (dtype) –
add_constructor (bool) –

kernel_function(name, ast_or_kernel_handle)¶

Create a function comprising just a single kernel call.

Parameters:

ast_or_kernel_handle (KernelFunction | SfgKernelHandle) – Either a pystencils AST, or a kernel handle for an already registered AST.
name (str) –

function(name)¶

Add a function.

The syntax of this function adder uses a chain of two calls to mimic C++ syntax:

sfg.function("FunctionName")(
    # Function Body
)

The function body is constructed via sequencing (see make_sequence).

Parameters:: name (str) –

call(kernel_handle)¶

Use inside a function body to directly call a kernel.

When using call, the given kernel will simply be called as a function. To invoke a GPU kernel on a specified launch grid, use cuda_invoke or the interfaces of pystencilssfg.extensions.sycl instead.

Parameters:: kernel_handle (SfgKernelHandle) – Handle to a kernel previously added to some kernel namespace.
Return type:: SfgCallTreeNode

seq(*args)¶

Syntax sequencing. For details, see make_sequence

Return type:: SfgSequence
Parameters:: args (tuple | str | SfgCallTreeNode | SfgNodeBuilder) –

params(*args)¶

Use inside a function body to add parameters to the function.

Return type:: SfgFunctionParams
Parameters:: args (SfgVar) –

var(name, dtype)¶

Create a variable with given name and data type.

Return type:

SfgVar

Parameters:

name (str) –
dtype (str | type | dtype | PsType) –

init(lhs)¶

Create a C++ in-place initialization.

Usage:

obj = sfg.var("obj", "SomeClass")
sfg.init(obj)(arg1, arg2, arg3)

becomes

SomeClass obj { arg1, arg2, arg3 };

Return type:: SfgInplaceInitBuilder
Parameters:: lhs (SfgVar) –

property branch: SfgBranchBuilder¶

Use inside a function body to create an if/else conditonal branch.

The syntax is:

sfg.branch("condition")(
    # then-body
)(
    # else-body (may be omitted)
)

map_field(field, index_provider)¶

Map a pystencils field to a field data structure, from which pointers, sizes and strides should be extracted.

Parameters:

field (Field) – The pystencils field to be mapped
src_object – A IFieldIndexingProvider object representing a field data structure.
index_provider (IFieldExtraction | SrcField) –

Return type:

SfgDeferredFieldMapping

map_param(lhs, rhs, mapping)¶

Arbitrary parameter mapping: Add a single line of code to define a left-hand side object from one or multiple right-hand side dependencies.

Parameters:

lhs (SfgVar) –
rhs (SfgVar | Sequence[SfgVar]) –
mapping (str) –

map_vector(lhs_components, rhs)¶

Extracts scalar numerical values from a vector data type.

Parameters:

lhs_components (Sequence[SfgVar | Symbol]) – Vector components as a list of symbols.
rhs (SrcVector) – A SrcVector object representing a vector data structure.

class pystencilssfg.composer.SfgClassComposer¶

Composer for classes and structs.

This class cannot be instantiated on its own but must be mixed in with SfgBasicComposer. Its interface is exposed by SfgComposer.

class VisibilityContext(visibility)¶

Represent a visibility block in the composer syntax.

Returned by private, public, and protected.

Parameters:: visibility (SfgVisibility) –

class ConstructorBuilder(*params)¶

Composer syntax for constructor building.

Returned by constructor.

Parameters:: params (SfgVar) –

init(initializer)¶

Add an initialization expression to the constructor’s initializer list.

Return type:: ConstructorBuilder
Parameters:: initializer (str) –

body(body)¶

Define the constructor body

Parameters:: body (str) –

klass(class_name, bases=())¶

Create a class and add it to the underlying context.

Parameters:

class_name (str) – Name of the class
bases (Sequence[str]) – List of base classes

struct(class_name, bases=())¶

Create a struct and add it to the underlying context.

Parameters:

class_name (str) – Name of the struct
bases (Sequence[str]) – List of base classes

property public: VisibilityContext¶: Create a public visibility block in a class body

property protected: VisibilityContext¶: Create a protected visibility block in a class or struct body

property private: VisibilityContext¶: Create a private visibility block in a class or struct body

constructor(*params)¶

In a class or struct body or visibility block, add a constructor.

Parameters:: params (SfgVar) – List of constructor parameters

method(name, returns=CustomType(void, const=False), inline=False, const=False)¶

In a class or struct body or visibility block, add a method. The usage is similar to SfgBasicComposer.function.

Parameters:

name (str) – The method name
returns (str | type | dtype | PsType) – The method’s return type
inline (bool) – Whether or not the method should be defined in-line.
const (bool) – Whether or not the method is const-qualified.

pystencilssfg.composer.make_sequence(*args)¶

Construct a sequence of C++ code from various kinds of arguments.

make_sequence is ubiquitous throughout the function building front-end; among others, it powers the syntax of SfgComposer.function and SfgComposer.branch.

make_sequence constructs an abstract syntax tree for code within a function body, accepting various types of arguments which then get turned into C++ code. These are :rtype: SfgSequence

Strings (str) are printed as-is
Tuples (tuple) signify blocks, i.e. C++ code regions enclosed in { }
Sub-ASTs and AST builders, which are often produced by the syntactic sugar and factory methods of SfgComposer.

Its usage is best shown by example:

tree = make_sequence(
    "int a = 0;",
    "int b = 1;",
    (
        "int tmp = b;",
        "b = a;",
        "a = tmp;"
    ),
    SfgKernelCall(kernel_handle)
)

sfg.context.add_function("myFunction", tree)

will translate to

void myFunction() {
    int a = 0;
    int b = 0;
    {
        int tmp = b;
        b = a;
        a = tmp;
    }
    kernels::kernel( ... );
}

Parameters:: args (tuple | str | AugExpr | SfgCallTreeNode | SfgNodeBuilder) –
Return type:: SfgSequence