Internal Code Representation (pystencilssfg.ir)

class pystencilssfg.SfgContext(outer_namespace=None, codestyle=SfgCodeStyle(indent_width=2, code_style='file', force_clang_format=False, clang_format_binary='clang-format'), argv=None, project_info=None)

Represents a header/implementation file pair in the code generator.

Source File Properties and Components

The SfgContext collects all properties and components of a header/implementation file pair (or just the header file, if header-only generation is used). These are:

  • The code namespace, which is combined from the outer_namespace and the pystencilssfg.SfgContext.inner_namespace. The outer namespace is meant to be set externally e.g. by the project configuration, while the inner namespace is meant to be set by the generator script.

  • The prelude comment is a block of text printed as a comment block at the top of both generated files. Typically, it contains authorship and licence information.

  • The set of included header files (pystencilssfg.SfgContext.includes).

  • Custom definitions, which are just arbitrary code strings.

  • Any number of kernel namespaces (pystencilssfg.SfgContext.kernel_namespaces), within which pystencils kernels are managed.

  • Any number of functions (pystencilssfg.SfgContext.functions), which are meant to serve as wrappers around kernel calls.

  • Any number of classes (pystencilssfg.SfgContext.classes), which can be used to build more extensive wrappers around kernels.

Order of Definitions

To honor C/C++ use-after-declare rules, the context preserves the order in which definitions, functions and classes are added to it. The header file printers implemented in pystencils-sfg will print the declarations accordingly. The declarations can retrieved in order of definition via declarations_ordered.

Parameters:

  • outer_namespace (str | None) –

  • codestyle (SfgCodeStyle) –

  • argv (Sequence[str] | None) –

  • project_info (Any) –

property argv: Sequence[str]

If this context was created by a pystencilssfg.SourceFileGenerator, provides the command line arguments given to the generator script, with configuration arguments for the code generator stripped away.

Otherwise, throws an exception.

property project_info: Any

Project-specific information provided by a build system.

property outer_namespace: str | None

Outer code namespace. Set by constructor argument outer_namespace.

property inner_namespace: str | None

Inner code namespace. Set by set_namespace.

property fully_qualified_namespace: str | None

Combined outer and inner namespaces, as outer_namespace::inner_namespace.

property codestyle: SfgCodeStyle

The code style object for this generation context.

property prelude_comment: str

The prelude is a comment block printed at the top of both generated files.

append_to_prelude(code_str)

Append a string to the prelude comment.

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

Parameters:

code_str (str) –

includes()

Includes of headers. Public includes are added to the header file, private includes are added to the implementation file.

Return type:

Generator[SfgHeaderInclude, None, None]

definitions()

Definitions are arbitrary custom lines of code.

Return type:

Generator[str, None, None]

add_definition(definition)

Add a custom code string to the header file.

Parameters:

definition (str) –

set_namespace(namespace)

Set the inner code namespace.

Throws an exception if the namespace was already set.

Parameters:

namespace (str) –

property default_kernel_namespace: SfgKernelNamespace

The default kernel namespace.

kernel_namespaces()

Iterator over all registered kernel namespaces.

Return type:

Generator[SfgKernelNamespace, None, None]

get_kernel_namespace(str)

Retrieve a kernel namespace by name, or None if it does not exist.

Return type:

Optional[SfgKernelNamespace]

add_kernel_namespace(namespace)

Adds a new kernel namespace.

If a kernel namespace of the same name already exists, throws an exception.

Parameters:

namespace (SfgKernelNamespace) –

functions()

Iterator over all registered functions.

Return type:

Generator[SfgFunction, None, None]

get_function(name)

Retrieve a function by name. Returns None if no function of the given name exists.

Return type:

Optional[SfgFunction]

Parameters:

name (str) –

add_function(func)

Adds a new function.

If a function or class with the same name exists already, throws an exception.

Parameters:

func (SfgFunction) –

classes()

Iterator over all registered classes.

Return type:

Generator[SfgClass, None, None]

get_class(name)

Retrieve a class by name, or None if the class does not exist.

Return type:

Optional[SfgClass]

Parameters:

name (str) –

add_class(cls)

Add a class.

Throws an exception if a class or function of the same name exists already.

Parameters:

cls (SfgClass) –

declarations_ordered()

All declared definitions, classes and functions in the order they were added.

Awareness about order is necessary due to the C++ declare-before-use rules.

Return type:

Generator[str | SfgFunction | SfgClass, None, None]

class pystencilssfg.ir.SfgCallTreeNode

Base class for all nodes comprising SFG call trees.

## Code Printing

For extensibility, code printing is implemented inside the call tree. Therefore, every instantiable call tree node must implement the method get_code. By convention, the string returned by get_code should not contain a trailing newline.

## Branching Structure

The branching structure of the call tree is managed uniformly through the children interface of SfgCallTreeNode. Each subclass must ensure that access to and modification of the branching structure through the children property and the child and set_child methods is possible, if necessary by overriding the property and methods.

abstract property children: Sequence[SfgCallTreeNode]

This node’s children

abstract get_code(ctx)

Returns the code of this node.

By convention, the code block emitted by this function should not contain a trailing newline.

Return type:

str

Parameters:

ctx (SfgContext) –

property required_includes: set[SfgHeaderInclude]

Return a set of header includes required by this node

class pystencilssfg.ir.SfgCallTreeLeaf

A leaf node of the call tree.

Leaf nodes must implement required_parameters for automatic parameter collection.

property children: Sequence[SfgCallTreeNode]

This node’s children

abstract property depends: set[SfgVar]

Set of objects this leaf depends on

class pystencilssfg.ir.SfgEmptyNode

A leaf node that does not emit any code.

Empty nodes must still implement required_parameters.

get_code(ctx)

Returns the code of this node.

By convention, the code block emitted by this function should not contain a trailing newline.

Return type:

str

Parameters:

ctx (SfgContext) –

class pystencilssfg.ir.SfgKernelCallNode(kernel_handle)
Parameters:

kernel_handle (SfgKernelHandle) –

property depends: set[SfgVar]

Set of objects this leaf depends on

get_code(ctx)

Returns the code of this node.

By convention, the code block emitted by this function should not contain a trailing newline.

Return type:

str

Parameters:

ctx (SfgContext) –

class pystencilssfg.ir.SfgCudaKernelInvocation(kernel_handle, num_blocks_code, threads_per_block_code, stream_code, depends)
Parameters:

  • kernel_handle (SfgKernelHandle) –

  • num_blocks_code (str) –

  • threads_per_block_code (str) –

  • stream_code (str | None) –

  • depends (set[SfgVar]) –

property depends: set[SfgVar]

Set of objects this leaf depends on

get_code(ctx)

Returns the code of this node.

By convention, the code block emitted by this function should not contain a trailing newline.

Return type:

str

Parameters:

ctx (SfgContext) –

class pystencilssfg.ir.SfgSequence(children)
Parameters:

children (Sequence[SfgCallTreeNode]) –

property children: Sequence[SfgCallTreeNode]

This node’s children

get_code(ctx)

Returns the code of this node.

By convention, the code block emitted by this function should not contain a trailing newline.

Return type:

str

Parameters:

ctx (SfgContext) –

class pystencilssfg.ir.SfgBlock(seq)
Parameters:

seq (SfgSequence) –

property children: Sequence[SfgCallTreeNode]

This node’s children

get_code(ctx)

Returns the code of this node.

By convention, the code block emitted by this function should not contain a trailing newline.

Return type:

str

Parameters:

ctx (SfgContext) –

class pystencilssfg.ir.SfgStatements(code_string, defines, depends)

Represents (a sequence of) statements in the source language.

This class groups together arbitrary code strings (e.g. sequences of C++ statements, cf. https://en.cppreference.com/w/cpp/language/statements), and annotates them with the set of symbols read and written by these statements.

It is the user’s responsibility to ensure that the code string is valid code in the output language, and that the lists of required and defined objects are correct and complete.

Parameters:

  • code_string (str) – Code to be printed out.

  • defined_params – Variables that will be newly defined and visible to code in sequence after these statements.

  • required_params – Variables that are required as input to these statements.

  • defines (Iterable[SfgVar]) –

  • depends (Iterable[SfgVar]) –

property depends: set[SfgVar]

Set of objects this leaf depends on

property required_includes: set[SfgHeaderInclude]

Return a set of header includes required by this node

get_code(ctx)

Returns the code of this node.

By convention, the code block emitted by this function should not contain a trailing newline.

Return type:

str

Parameters:

ctx (SfgContext) –

class pystencilssfg.ir.SfgFunctionParams(parameters)
Parameters:

parameters (Sequence[SfgVar]) –

property depends: set[SfgVar]

Set of objects this leaf depends on

property required_includes: set[SfgHeaderInclude]

Return a set of header includes required by this node

class pystencilssfg.ir.SfgRequireIncludes(includes)
Parameters:

includes (Sequence[SfgHeaderInclude]) –

property depends: set[SfgVar]

Set of objects this leaf depends on

property required_includes: set[SfgHeaderInclude]

Return a set of header includes required by this node

class pystencilssfg.ir.SfgBranch(cond, branch_true, branch_false=None)
Parameters:
property children: Sequence[SfgCallTreeNode]

This node’s children

get_code(ctx)

Returns the code of this node.

By convention, the code block emitted by this function should not contain a trailing newline.

Return type:

str

Parameters:

ctx (SfgContext) –

class pystencilssfg.ir.SfgSwitchCase(label, body)
Parameters:

  • label (str | SfgSwitchCase.DefaultCaseType) –

  • body (SfgSequence) –

property children: Sequence[SfgCallTreeNode]

This node’s children

get_code(ctx)

Returns the code of this node.

By convention, the code block emitted by this function should not contain a trailing newline.

Return type:

str

Parameters:

ctx (SfgContext) –

class pystencilssfg.ir.SfgSwitch(switch_arg, cases_dict, default=None)
Parameters:
property children: tuple[SfgCallTreeNode, ...]

This node’s children

get_code(ctx)

Returns the code of this node.

By convention, the code block emitted by this function should not contain a trailing newline.

Return type:

str

Parameters:

ctx (SfgContext) –

class pystencilssfg.ir.SfgKernelNamespace(ctx, name)

A namespace grouping together a number of kernels.

Parameters:
add(kernel, name=None)

Adds an existing pystencils AST to this namespace. If a name is specified, the AST’s function name is changed.

Parameters:

  • kernel (KernelFunction) –

  • name (str | None) –

create(assignments, name=None, config=None)

Creates a new pystencils kernel from a list of assignments and a configuration. This is a wrapper around pystencils.create_kernel with a subsequent call to add.

Parameters:

  • name (str | None) –

  • config (CreateKernelConfig | None) –

class pystencilssfg.ir.SfgKernelHandle(ctx, name, namespace, parameters)

A handle that represents a pystencils kernel within a kernel namespace.

Parameters:
class pystencilssfg.ir.SfgSymbolLike(param)
Parameters:

param (SymbolLike_T) –

class pystencilssfg.ir.SfgVisibility(value)

An enumeration.

class pystencilssfg.ir.SfgClassKeyword(value)

An enumeration.

class pystencilssfg.ir.SfgClassMember
class pystencilssfg.ir.SfgInClassDefinition(text)
Parameters:

text (str) –

class pystencilssfg.ir.SfgMemberVariable(name, dtype)
Parameters:

  • name (str) –

  • dtype (PsType) –

class pystencilssfg.ir.SfgMethod(name, tree, return_type=CustomType(void, const=False), inline=False, const=False)
Parameters:
class pystencilssfg.ir.SfgConstructor(parameters=(), initializers=(), body='')
Parameters:

  • parameters (Sequence[SfgVar]) –

  • initializers (Sequence[str]) –

  • body (str) –

class pystencilssfg.ir.SfgClass(class_name, class_keyword=SfgClassKeyword.CLASS, bases=())

Models a C++ class.

### Adding members to classes

Members are never added directly to a class. Instead, they are added to an [SfgVisibilityBlock][pystencilssfg.source_components.SfgVisibilityBlock] which defines their syntactic position and visibility modifier in the code. At the top of every class, there is a default visibility block accessible through the default property. To add members with custom visibility, create a new SfgVisibilityBlock, add members to the block, and add the block using append_visibility_block.

A more succinct interface for constructing classes is available through the [SfgClassComposer][pystencilssfg.composer.SfgClassComposer].

Parameters: