psyclone.psyir.nodes.psy_data_node

This module implements a PSyData node, i.e. a node that at code creation time will create callbacks according to the PSyData API. This is the base class for nodes that e.g. create kernel extraction or profiling.

Classes

  • PSyDataNode: This class can be inserted into a schedule to instrument a set of nodes.

class psyclone.psyir.nodes.psy_data_node.PSyDataNode(ast=None, children=None, parent=None, options=None)

This class can be inserted into a schedule to instrument a set of nodes. Instrument means that calls to an external library using the PSyData API will be inserted before and after the child nodes, which will give that library access to fields and the fact that a region is executed. This can be used, for example, to add performance profiling calls, in-situ visualisation of data, or for writing fields to a file (e.g. for creating test cases, or using driver to run a certain kernel only). The node allows specification of a class string which is used as a prefix for the PSyData module name (prefix_psy_data_mod) and for the PSyDataType (prefix_PSyDataType).

Parameters:
  • ast (sub-class of fparser.two.Fortran2003.Base) – reference into the fparser2 parse tree corresponding to this node.

  • children (List[psyclone.psyir.nodes.Node]) – the PSyIR nodes that are children of this node. These will be made children of the child Schedule of this PSyDataNode.

  • parent (psyclone.psyir.nodes.Node) – the parent of this node in the PSyIR tree.

  • options (Optional[Dict[str, Any]]) – a dictionary with options for transformations.

  • options["prefix"] (str) – a prefix to use for the PSyData module name (prefix_psy_data_mod) and the PSyDataType (prefix_PSyDataType) - a “_” will be added automatically. It defaults to “”, which means the module name used will just be psy_data_mod, and the data type PSyDataType.

  • options["region_name"] (Tuple[str,str]) – an optional name to use for this PSyDataNode, provided as a 2-tuple containing a module name followed by a local name. The pair of strings should uniquely identify a region unless aggregate information is required (and is supported by the runtime library).

Raises:

InternalError – if a prefix is specified that is not listed in the configuration file.

Inheritance

Inheritance diagram of PSyDataNode
add_psydata_class_prefix(symbol)

Returns a string prefixed with the class-specific prefix, e.g. if the prefix string is “profile”, then the symbol “PSyDataType” will become “profilePSyDataType”. Typically the _prefix will contain a trailing “_”.

Parameters:

symbol (str) – the symbol name to add the prefix to.

Returns:

the symbol name with the class string as prefix.

Return type:

str

classmethod create(children, symbol_table, ast=None, options=None)

Creates a new (sub-class of a) PSyData node with the supplied ‘children’ nodes as its children. The symbols used by the PSyData API are added to the supplied symbol table. This is a class method so that it acts as a factory for the various sub-classes of PSyDataNode.

Parameters:
  • children (List[psyclone.psyir.nodes.Node]) – the PSyIR nodes that will become children of the new PSyData node.

  • symbol_table (psyclone.psyir.symbols.SymbolTable) – the associated SymbolTable to which symbols must be added.

  • options (Optional[Dict[str, Any]]) – a dictionary with options for transformations.

  • options[prefix"] (str) – a prefix to use for the PSyData module name (prefix_psy_data_mod) and the PSyDataType (prefix_PSyDataType) - a “_” will be added automatically. It defaults to “”, which means the module name used will just be psy_data_mod, and the data type PSyDataType.

  • options["region_name"] (Tuple[str,str]) – an optional name to use for this PSyDataNode, provided as a 2-tuple containing a module name followed by a local name. The pair of strings should uniquely identify a region unless aggregate information is required (and is supported by the runtime library).

Parent ast:

reference to fparser2 parse tree for the routine being instrumented with PSyData calls.

Raises:

TypeError – if the supplied children or symbol table are not of the correct type.

property fortran_module
Returns:

name of the PSyData interface Fortran module.

Return type:

str

gen_code(parent, options=None)

Creates the PSyData code before and after the children of this node.

TODO #1010: This method and the lower_to_language_level below contain duplicated logic, the gen_code method will be deleted when all APIs can use the PSyIR backends.

Parameters:
  • parent (psyclone.f2pygen.BaseGen) – the parent of this node in the f2pygen AST.

  • options (Optional[Dict[str, Any]]) – a dictionary with options for transformations.

  • options["pre_var_list"] (List[Tuple[str, str]]) – container name and variable name to be supplied before the first child. The container name is supported to be able to handle variables that are imported from a different container (module in Fortran).

  • options["post_var_list"] (List[Tuple[str, str]]) – container name and variable name to be supplied after the last child. The container name is supported to be able to handle variables that are imported from a different container (module in Fortran).

  • options["pre_var_postfix"] (str) – an optional postfix that will be added to each variable name in the pre_var_list.

  • options["post_var_postfix"] (str) – an optional postfix that will be added to each variable name in the post_var_list.

generate_symbols(symbol_table)

Generate the necessary symbols to import and use this PSyDataNode in the provided symbol_table if they don’t already exist.

Parameters:

symbol_table (psyclone.psyir.symbols.SymbolTable) – the associated SymbolTable to which symbols must be added.

lower_to_language_level(options=None)

Lowers this node (and all children) to language-level PSyIR. The PSyIR tree is modified in-place. This PSyDataNode is replaced by a pair of Fortran-specific CodeBlocks (representing the calls to the start and stop procedures) with the body (children) of the PSyDataNode inserted between them. This use of CodeBlocks means that currently only the Fortran backend is capable of producing code representing the PSyDataNode.

Parameters:
  • options (Optional[Dict[str, Any]]) – dictionary of the PSyData generation options.

  • options["pre_var_list"] (List[Tuple[str, str]]) – container- and variable-names to be supplied before the first child. The container names are supported to be able to handle variables that are imported from a different container (module in Fortran).

  • options["post_var_list"] (List[Tuple[str, str]]) – container- and variable-names to be supplied after the last child. The container names are supported to be able to handle variables that are imported from a different container (module in Fortran).

  • options["pre_var_postfix"] (str) – an optional postfix that will be added to each variable name in the pre_var_list.

  • options["post_var_postfix"] (str) – an optional postfix that will be added to each variable name in the post_var_list.

Returns:

the lowered version of this node.

Return type:

psyclone.psyir.node.Node

Raises:

GenerationError – if the node is not inside a Routine.

property module_name

Returns the _module_name of this PSyDataNode.

Returns:

the _module_name of this PSyDataNode.

Return type:

str

property options
Returns:

the option dictionary of this class.

Return type:

Dict[str,Any]

property prefix

Returns the _prefix member of this PSyDataNode.

Returns:

the _prefix member of this PSyDataNode.

Return type:

str

property psy_data_body
Returns:

the Schedule associated with this PSyData region.

Return type:

psyclone.psyir.nodes.Schedule

Raises:

InternalError – if this PSyData node does not have a Schedule as its one and only child.

property region_identifier
Returns:

the unique region identifier, which is a tuple consisting of the module name and region name.

Return type:

Tuple[str, str]

property region_name

Returns the _region_name of this PSyDataNode.

Returns:

the _region_name of this PSyDataNode.

Return type:

str

set_region_identifier(module_name, region_name)

Defines a unique region identifier based on module- and region-name. Typically the names will be concatenated to create a file name or a region name. Since the region name is unique in the module, concatenating the strings will then result in a unique region name.

Parameters:
  • module_name (str) – name of the module.

  • region_name (str) – name of the region.

property type_name
Returns:

the name of the Fortran derived type associated with this PSyData object.

Return type:

str

property var_name

Returns the _var_name member of this PSyDataNode.

Returns:

the _var_name of this PSyDataNode.

Return type:

str