`psyclone.psyir.nodes`

PSyIR nodes package module

Functions 

colored(): Returns the supplied text argument unchanged. This is a swap-in

psyclone.psyir.nodes.colored(text, _)

Returns the supplied text argument unchanged. This is a swap-in replacement for when termcolor.colored is not available.

Parameters:

text (str) – text to return.
_ – fake argument, only required to match interface provided by termcolor.colored.

Returns:

the supplied text, unchanged.

Return type:

str

Classes 

ArrayMember: Node representing an access to the element(s) of an array that is a
ArrayReference: Node representing a reference to an element or elements of an Array.
ArrayOfStructuresMember: Node representing a membership expression of a parent structure where the
ArrayOfStructuresReference: Node representing an access to a member of one or more elements of an
Assignment: Node representing an Assignment statement. As such it has a LHS and RHS
BinaryOperation: Node representing a BinaryOperation expression. As such it has two operands
Call: Node representing a Call. This can be found as a standalone statement
Clause: Base abstract class for all clauses.
CodeBlock: Node representing some generic Fortran code that PSyclone does not
Container: Node representing a set of Routine and/or Container nodes, as well
DataNode: Abstract node representing a general PSyIR expression that represents a
FileContainer: PSyIR node to encapsulate the scope of a source file. In the
IfBlock: Node representing an if-block within the PSyIR. It has two mandatory
IntrinsicCall: Node representing a call to an intrinsic routine (function or
Literal: Node representing a Literal. The value and datatype properties of
Loop: Node representing a loop within the PSyIR. It has 4 mandatory children:
Member: Node representing a membership expression of a structure.
Node: Base class for a PSyIR node.
OperandClause: Base abstract class for all clauses that have an operand.
Operation: Abstract base class for PSyIR nodes representing operators.
Range: The Range node is used to capture a range of integers via
Reference: Node representing a Reference Expression.
Return: Node representing a Return statement (subroutine break without return
Routine: A sub-class of a Schedule that represents a subroutine, function or
Schedule: Stores schedule information for a sequence of statements (supplied
Statement: Abstract node representing a general PSyIR Statement.
StructureMember: Node representing a membership expression of the parent’s Reference that
StructureReference: Node representing a reference to a component of a structure. As such
UnaryOperation: Node representing a UnaryOperation expression. As such it has one operand
ScopingNode: Abstract node that has an associated Symbol Table to keep track of
WhileLoop: Node representing a while loop within the PSyIR. It has two mandatory
KernelSchedule: A KernelSchedule is the parent node of the PSyIR for Kernel source code.
PSyDataNode: This class can be inserted into a schedule to instrument a set of nodes.
ExtractNode: This class can be inserted into a Schedule to mark Nodes for code extraction using the ExtractRegionTrans transformation. By applying the transformation the Nodes marked for extraction become children of (the Schedule of) an ExtractNode.
ProfileNode: This class can be inserted into a schedule to create profiling code.
NanTestNode: This class can be inserted into a Schedule to mark Nodes for
ReadOnlyVerifyNode: This class can be inserted into a Schedule to mark Nodes for
Directive: Abstract base class for all Directive statements.
RegionDirective: Base class for all Directive nodes that have an associated
StandaloneDirective: Base class for all StandaloneDirective statements. This class is
ACCAtomicDirective: OpenACC directive to represent that the memory accesses in the associated
ACCDirective: Base mixin class for all OpenACC directive statements.
ACCRegionDirective: Base class for all OpenACC region directive statements.
ACCStandaloneDirective: Base class for all standalone OpenACC directive statements.
ACCDataDirective: Class representing the !$ACC DATA … !$ACC END DATA directive
ACCEnterDataDirective: Class representing a “!$ACC enter data” OpenACC directive in
ACCParallelDirective: Class representing the !$ACC PARALLEL directive of OpenACC
ACCLoopDirective: Class managing the creation of a ‘!$acc loop’ OpenACC directive.
ACCKernelsDirective: Class representing the !$ACC KERNELS directive in the PSyIR.
ACCUpdateDirective: Class representing the OpenACC update directive in the PSyIR. It has
ACCRoutineDirective: Class representing a “!$ACC routine” OpenACC directive in PSyIR.
ACCCopyClause: OpenACC copy clause. Specifies a list of variables that are to be copied
ACCCopyInClause: OpenACC copy clause. Specifies a list of variables that are to be copied
ACCCopyOutClause: OpenACC copy clause. Specifies a list of variables that are to be copied
OMPAtomicDirective: OpenMP directive to represent that the memory accesses in the associated
OMPDirective: Base mixin class for all OpenMP-related directives.
OMPRegionDirective: Base class for all OpenMP region-related directives.
OMPStandaloneDirective: Base class for all OpenMP-related standalone directives.
OMPParallelDirective: Class representing an OpenMP Parallel directive.
OMPSerialDirective: Abstract class representing OpenMP serial regions, e.g.
OMPSingleDirective: Class representing an OpenMP SINGLE directive in the PSyIR.
OMPMasterDirective: Class representing an OpenMP MASTER directive in the PSyclone AST.
OMPTaskloopDirective: Class representing an OpenMP TASKLOOP directive in the PSyIR.
OMPTaskDirective: Class representing an OpenMP TASK directive in the PSyIR after lowering.
DynamicOMPTaskDirective: Class representing an OpenMP TASK directive in the PSyIR.
OMPDoDirective: Class representing an OpenMP DO directive in the PSyIR.
OMPParallelDoDirective: Class for the !$OMP PARALLEL DO directive. This inherits from
OMPTaskwaitDirective: Class representing an OpenMP TASKWAIT directive in the PSyIR.
OMPTargetDirective: Class for the !$OMP TARGET directive that offloads the code contained
OMPLoopDirective: Class for the !$OMP LOOP directive that specifies that the iterations
OMPDeclareTargetDirective: Class representing an OpenMP Declare Target directive in the PSyIR.
OMPSimdDirective: OpenMP directive to inform that the associated loop can be vectorised.
OMPTeamsDistributeParallelDoDirective: Class representing the OMP teams distribute parallel do directive.
OMPGrainsizeClause: OpenMP grainsize clause, used by OMPTaskloopDirective. Controls the
OMPNogroupClause: OpenMP nogroup clause, used by OMPTaskloopDirective to disable the
OMPNowaitClause: OpenMP nowait clause. Disable the implicit barrier at the end of the
OMPNumTasksClause: OpenMP numtasks clause, used by OMPTaskloopDirective. Controls the number
OMPPrivateClause: OpenMP private clause. This is used to declare variables as private
OMPDefaultClause: OpenMP Default clause. Used to determine the default declaration for
OMPReductionClause: OpenMP Reduction clause.
OMPScheduleClause: OpenMP Schedule clause used for OMP Do Directives.
OMPFirstprivateClause: OpenMP firstprivate clause. This is used to declare variables as
OMPSharedClause: OpenMP shared clause. This is used to declare variables as shared in an
OMPDependClause: OpenMP Depend clause used for OpenMP Task directives.

class psyclone.psyir.nodes.ArrayMember(member_name, parent=None)

Node representing an access to the element(s) of an array that is a member of a structure. Must have one or more children which give the array-index expressions for the array access.

Inheritance

static create(member_name, indices)

Construct an ArrayMember instance describing an array access to a member of a structure.

e.g. for the Fortran grid%subdomains(1,2), subdomains must be an array and we are accessing element (1,2) of it. We would therefore create the ArrayMember for this access by calling:

>>> amem = ArrayMember.create("subdomains",
                              [Literal("1", INTEGER_TYPE),
                               Literal("2", INTEGER_TYPE)])

Parameters:

member_name (str) – the name of the member of the structure that is being accessed.
indices (list of psyclone.psyir.nodes.DataNode or psyclone.psyir.nodes.Range) – the array-index expressions.

Raises:

GenerationError – if the supplied indices argument is not a list.

class psyclone.psyir.nodes.ArrayReference(symbol, **kwargs)

Node representing a reference to an element or elements of an Array. The array-index expressions are stored as the children of this node.

Inheritance

static create(symbol, indices)

Create an ArrayReference instance given a symbol and a list of Node array indices. The special value “:” can be used as an index to create the corresponding PSyIR Range that represents “:”.

Parameters:

symbol (psyclone.psyir.symbols.DataSymbol) – the symbol that this array is associated with.
indices (List[Union[psyclone.psyir.nodes.Node,”:”]]) – a list of Nodes or “:” describing the array indices.

Returns:

an ArrayReference instance.

Return type:

psyclone.psyir.nodes.ArrayReference

Raises:

GenerationError – if the arguments to the create method are not of the expected type.

property datatype

Returns:: the datatype of the accessed array element(s).
Return type:: psyclone.psyir.symbols.DataType

class psyclone.psyir.nodes.ArrayOfStructuresMember(member_name, parent=None)

Node representing a membership expression of a parent structure where the expression resolves to the component of one or more elements of an array of structures. As such, its first child must be a member of that structure. Subsequent children give the array-index expressions.

Inheritance

static create(member_name, indices, inner_member)

Create an access to a member of one or more elements of an array of structures that is itself a member of a structure.

e.g. if we had the Fortran grid%subdomains(1)%xstart then subdomains must be an array of structure (derived) type. We would construct an ArrayOfStructuresMember for this access by calling:

>>> aosmem = ArrayOfStructuresMember.create(
        "subdomains", [Literal("1", INTEGER_TYPE)], Member("xstart"))

Parameters:

member_name (str) – the name of the array member of the structure that is being accessed.
indices (list of psyclone.psyir.nodes.DataNode) – the array-index expressions.
inner_member (psyclone.psyir.nodes.Member) – the member of the member_name structure that is being accessed.

Returns:

a new ArrayOfStructuresMember object.

Return type:

psyclone.psyir.nodes.ArrayOfStructuresMember

class psyclone.psyir.nodes.ArrayOfStructuresReference(symbol, **kwargs)

Node representing an access to a member of one or more elements of an array of structures. Since this access is to a member of the structure, its first child will be a subclass of Member. All subsequent children give the array-index expressions.

Inheritance

static create(symbol, indices, members, parent=None, overwrite_datatype=None)

Create a reference to a member of one or more elements of an array of structures.

The symbol to be referred to must be of UnresolvedType, UnsupportedType or ArrayType. If the latter then the ‘intrinsic’ type of the array must be specified with a DataTypeSymbol. The member of the structure that is accessed is specified using the ‘members’ argument. e.g. for a reference to “field(idx)%bundle(2)%flag” this argument would be [(“bundle”, [Literal(“2”, INTEGER4_TYPE)]), “flag”]. The ‘indices’ argument specifies the DataNodes describing the indexing into the array of structures. For the example given previously, this would be [Reference(idx_symbol)] where idx_symbol is the Symbol representing the idx variable in the Fortran code snippet.

Parameters:

symbol (psyclone.psyir.symbols.DataSymbol) – the symbol that this reference is to.
indices (list of psyclone.psyir.nodes.Node) – a list of Nodes describing the array indices.
members (list of str or 2-tuples containing (str, list of nodes describing array access)) – one or more component(s) of the structure(s) that make up the full access. Any components that are array references must provide the name of the array and a list of DataNodes describing which part of it is accessed.
parent (sub-class of psyclone.psyir.nodes.Node) – the parent of this node in the PSyIR.
overwrite_datatype (Optional[psyclone.psyir.symbols.DataType]) – the datatype for the reference, which will overwrite the value determined by analysing the corresponding user defined type. This is useful when e.g. the module that declares the structure cannot be accessed.

Returns:

an ArrayOfStructuresReference instance.

Return type:

psyclone.psyir.nodes.ArrayOfStructuresReference

Raises:

TypeError – if the arguments to the create method are not of the expected type.

class psyclone.psyir.nodes.Assignment(ast=None, children=None, parent=None, annotations=None)

Node representing an Assignment statement. As such it has a LHS and RHS as children 0 and 1 respectively.

Inheritance

static create(lhs, rhs)

Create an Assignment instance given lhs and rhs child instances.

Parameters:

lhs (psyclone.psyir.nodes.Node) – the PSyIR node containing the left hand side of the assignment.
rhs (psyclone.psyir.nodes.Node) – the PSyIR node containing the right hand side of the assignment.

Returns:

an Assignment instance.

Return type:

psyclone.psyir.nodes.Assignment

gen_code(parent)

F2pygen code generation of an Assignment.

Parameters:: parent (psyclone.psyir.nodes.Node) – the parent of this Node in the PSyIR.

property is_array_assignment: returns: True if the lhs of the assignment is an array access with at least one of its dimensions being a range and False otherwise. rtype: bool

property lhs

Returns:: the child node representing the Left-Hand Side of the assignment.
Return type:: psyclone.psyir.nodes.Node
Raises:: InternalError – Node has fewer children than expected.

reference_accesses(var_accesses)

Get all variable access information from this node. The assigned-to variable will be set to ‘WRITE’.

Parameters:: var_accesses (psyclone.core.VariablesAccessInfo) – VariablesAccessInfo instance that stores the information about variable accesses.

property rhs

Returns:: the child node representing the Right-Hand Side of the assignment.
Return type:: psyclone.psyir.nodes.Node
Raises:: InternalError – Node has fewer children than expected.

class psyclone.psyir.nodes.BinaryOperation(operator, parent=None)

Node representing a BinaryOperation expression. As such it has two operands as children 0 and 1, and an attribute with the operator type.

Inheritance

class Operator(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

static create(operator, lhs, rhs)

Create a BinaryOperator instance given an operator and lhs and rhs child instances with optional names.

Parameters:

operator (psyclone.psyir.nodes.BinaryOperation.Operator) – the operator used in the operation.
lhs (Union[psyclone.psyir.nodes.Node, Tuple[str, psyclone.psyir.nodes.Node]]) – the PSyIR node containing the left hand side of the assignment, or a tuple containing the name of the argument and the PSyIR node.
rhs (Union[psyclone.psyir.nodes.Node, Tuple[str, psyclone.psyir.nodes.Node]]) – the PSyIR node containing the right hand side of the assignment, or a tuple containing the name of the argument and the PSyIR node.

Returns:

a BinaryOperator instance.

Return type:

psyclone.psyir.nodes.BinaryOperation

Raises:

GenerationError – if the arguments to the create method are not of the expected type.

property datatype

Determines the datatype of this operation. If it cannot be determined for any reason then an instance of UnresolvedType is returned.

Returns:: the datatype of the result of this BinaryOperation.
Return type:: psyclone.psyir.symbols.DataType
Raises:: InternalError – if the operands are both arrays but are of different shapes.

class psyclone.psyir.nodes.Call(routine, **kwargs)

Node representing a Call. This can be found as a standalone statement or an expression.

TODO #1437: The combined Statement and Expression implementation is simple but it has some shortcomings that may need to be addressed.

Parameters:

routine (py:class:psyclone.psyir.symbols.RoutineSymbol) – the routine that this call calls.
kwargs (unwrapped dict.) – additional keyword arguments provided to the PSyIR node.

Raises:

TypeError – if the routine argument is not a RoutineSymbol.

Inheritance

append_named_arg(name, arg)

Append a named argument to this call.

Parameters:

name (Optional[str]) – the argument name.
arg (psyclone.psyir.nodes.DataNode) – the argument expression.

Raises:

ValueError – if the name argument is already used for an existing argument.

property argument_names

Returns:: a list with the name of each argument. If the entry is None then the argument is a positional argument.
Return type:: List[Optional[str]]

copy()

Return a copy of this node. This is a bespoke implementation for a Call node that ensures that any internal id’s are consistent before and after copying.

Returns:: a copy of this node and its children.
Return type:: psyclone.psyir.node.Node

classmethod create(routine, arguments)

Create an instance of class cls given valid instances of a routine symbol, and a list of child nodes (or name and node tuple) for its arguments.

Parameters:

routine (py:class:psyclone.psyir.symbols.RoutineSymbol) – the routine that class cls calls.
arguments (List[ Union[:py:class:psyclone.psyir.nodes.DataNode, Tuple[str, :py:class:psyclone.psyir.nodes.DataNode]]]) – the arguments to this routine, and/or 2-tuples containing an argument name and the argument. Arguments are added as child nodes.

Returns:

an instance of cls.

Return type:

psyclone.psyir.nodes.Call or a subclass thereof.

Raises:

GenerationError – if the routine argument is not a RoutineSymbol.
GenerationError – if the arguments argument is not a list.

insert_named_arg(name, arg, index)

Insert a named argument to the call.

Parameters:

name (Optional[str]) – the argument name.
arg (psyclone.psyir.nodes.DataNode) – the argument expression.
index (int) – where in the argument list to insert the named argument.

Raises:

ValueError – if the name argument is already used for an existing argument.
TypeError – if the index argument is the wrong type.

is_available_on_device()

Returns:: whether this intrinsic is available on an accelerated device.
Return type:: bool

property is_elemental

Returns:: whether the routine being called is elemental (provided with an input array it will apply the operation individually to each of the array elements and return an array with the results). If this information is not known then it returns None.
Return type:: NoneType | bool

property is_pure

Returns:: whether the routine being called is pure (guaranteed to return the same result when provided with the same argument values). If this information is not known then it returns None.
Return type:: NoneType | bool

node_str(colour=True)

Construct a text representation of this node, optionally containing colour control codes.

Parameters:: colour (bool) – whether or not to include colour control codes.
Returns:: description of this PSyIR node.
Return type:: str

reference_accesses(var_accesses)

Updates the supplied var_accesses object with information on the arguments passed to this call.

TODO #446 - all arguments that are passed by reference are currently marked as having READWRITE access (unless we know that the routine is PURE). We could do better than this if we have the PSyIR of the called Routine.

Parameters:: var_accesses (psyclone.core.VariablesAccessInfo) – VariablesAccessInfo instance that stores the information about variable accesses.

replace_named_arg(existing_name, arg)

Replace one named argument node with another node keeping the same name.

param str existing_name:

the argument name.

param arg:

the argument expression.

type arg:

psyclone.psyir.nodes.DataNode

raises TypeError:

if the name argument is the wrong type.

raises ValueError:

if the name argument is already used for an existing argument.

raises TypeError:

if the index argument is the wrong type.

property routine

Returns:: the routine symbol that this call calls.
Return type:: py:class:psyclone.psyir.symbols.RoutineSymbol

class psyclone.psyir.nodes.Clause(ast=None, children=None, parent=None, annotations=None)

Base abstract class for all clauses.

Inheritance

property clause_string

Returns:: the base clause string for this Clause.
Return type:: str

class psyclone.psyir.nodes.CodeBlock(fp2_nodes, structure, parent=None, annotations=None)

Node representing some generic Fortran code that PSyclone does not attempt to manipulate. As such it is a leaf in the PSyIR and therefore has no children.

Parameters:

fp2_nodes (list of fparser.two.utils.Base) – list of fparser2 AST nodes representing the Fortran code constituting the code block.
structure (psyclone.psyir.nodes.CodeBlock.Structure) – argument indicating whether this code block is a statement or an expression.
parent (psyclone.psyir.nodes.Node) – the parent node of this code block in the PSyIR.
annotations (list of str or NoneType) – tags that provide additional information about the node. The node should still be functionally correct when ignoring these tags.

Inheritance

class Structure(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None): Enumeration that captures the structure of the code block which may be required when processing.

property get_ast_nodes

Returns:: the list of nodes associated with this code block in the original AST.
Return type:: list of subclass of :py:classfparser.two.Fortran2003.Base

get_symbol_names()

Returns:: the list of symbol names used inside the CodeBock.
Return type:: list of str

node_str(colour=True)

Create a text description of this node in the schedule, optionally including control codes for colour.

Parameters:: colour (bool) – whether or not to include control codes for colour.
Returns:: text description of this node.
Return type:: str

property structure

Returns:: whether this code block is a statement or an expression.
Return type:: psyclone.psyir.nodes.CodeBlock.Structure

valid_annotations = 'psy-data-start': The annotations that are supported by this node. psy-data-start - this node has replaced a PSyDataNode during the lowering of the PSyIR to language level.

class psyclone.psyir.nodes.Container(name, **kwargs)

Node representing a set of Routine and/or Container nodes, as well as a name and a SymbolTable. This construct can be used to scope symbols of variables, Routine names and Container names. In Fortran a container would naturally represent a module or a submodule.

Parameters:

name (str) – the name of the container.
parent (psyclone.psyir.nodes.Node) – optional parent node of this Container in the PSyIR.
symbol_table (psyclone.psyir.symbols.SymbolTable or NoneType) – initialise the node with a given symbol table.

Inheritance

classmethod create(name, symbol_table, children)

Create a Container instance given a name, a symbol table and a list of child nodes.

Parameters:

name (str) – the name of the Container.
symbol_table (psyclone.psyir.symbols.SymbolTable) – the symbol table associated with this Container.
children (list of psyclone.psyir.nodes.Container or psyclone.psyir.nodes.Routine) – a list of PSyIR nodes contained in the Container. These must be Containers or Routines.

Returns:

an instance of cls.

Return type:

psyclone.psyir.nodes.Container or subclass thereof

Raises:

GenerationError – if the arguments to the create method are not of the expected type.

get_routine_psyir(name)

Returns the PSyIR for the routine with the given name, or None if a routine with this name does not exist.

Parameters:: name (str) – name of the routine to find.
Returns:: the PSyIR Routine instance of the subroutine, or None if there is no routine with that name in this container.
Return type:: Union[None, psyclone.psyir.nodes.Routine]

property name

Returns:: name of the container.
Return type:: str

node_str(colour=True)

Returns the name of this node with appropriate control codes to generate coloured output in a terminal that supports it.

Parameters:: colour (bool) – whether or not to include colour control codes.
Returns:: description of this node, possibly coloured.
Return type:: str

class psyclone.psyir.nodes.DataNode(ast=None, children=None, parent=None, annotations=None)

Abstract node representing a general PSyIR expression that represents a value, which has a datatype.

Inheritance

property datatype

Returns:: the data-type of this Node. Currently this base implementation just returns UnresolvedType(). If a sub-class can do better then it must override this method.
Return type:: psyclone.psyir.symbols.UnresolvedType

class psyclone.psyir.nodes.FileContainer(name, **kwargs)

PSyIR node to encapsulate the scope of a source file. In the PSyIR, a FileContainer is identical to a Container. However, it is useful to distinguish this type of container for the backends, which can have different constraints/syntax for general Containers and a FileContainer. For example, a FileContainer can not have any symbol table entries in Fortran.

Inheritance

node_str(colour=True)

Returns the name of this node with appropriate control codes to generate coloured output in a terminal that supports it.

Parameters:: colour (bool) – whether or not to include colour control codes.
Returns:: description of this node, possibly coloured.
Return type:: str

class psyclone.psyir.nodes.IfBlock(ast=None, children=None, parent=None, annotations=None)

Node representing an if-block within the PSyIR. It has two mandatory children: the first one represents the if-condition and the second one the if-body; and an optional third child representing the else-body.

Inheritance

property condition

Return the PSyIR Node representing the conditional expression of this IfBlock.

Returns:: IfBlock conditional expression.
Return type:: psyclone.psyir.nodes.Node
Raises:: InternalError – If the IfBlock node does not have the correct number of children.

static create(if_condition, if_body, else_body=None)

Create an IfBlock instance given valid instances of an if_condition, an if_body and an optional else_body.

Parameters:

if_condition (psyclone.psyir.nodes.Node) – the PSyIR node containing the if condition of the if block.
if_body (List[psyclone.psyir.nodes.Node]) – the PSyIR nodes representing the if body of the if block.
else_body (Optional[List[psyclone.psyir.nodes.Node]]) – PSyIR nodes representing the else body of the if block or None if there is no else body (defaults to None).

Returns:

an IfBlock instance.

Return type:

psyclone.psyir.nodes.IfBlock

Raises:

GenerationError – if the arguments to the create method are not of the expected type.

property else_body

If available return the Schedule executed when the IfBlock evaluates to False, otherwise return None.

Returns:: Schedule to be executed when IfBlock evaluates to False, if it doesn’t exist returns None.
Return type:: psyclone.psyir.nodes.Schedule or NoneType

property if_body

Return the Schedule executed when the IfBlock evaluates to True.

Returns:: Schedule to be executed when IfBlock evaluates to True.
Return type:: psyclone.psyir.nodes.Schedule
Raises:: InternalError – If the IfBlock node does not have the correct number of children.

reference_accesses(var_accesses)

Get all variable access information. It combines the data from the condition, if-body and (if available) else-body. This could later be extended to handle cases where a variable is only written in one of the two branches.

Parameters:: var_accesses (psyclone.core.VariablesAccessInfo) – VariablesAccessInfo instance that stores the information about variable accesses.

class psyclone.psyir.nodes.IntrinsicCall(routine, **kwargs)

Node representing a call to an intrinsic routine (function or subroutine). This can be found as a standalone statement or an expression.

Parameters:

routine (py:class:psyclone.psyir.IntrinsicCall.Intrinsic) – the type of Intrinsic being created.
kwargs (unwrapped dict.) – additional keyword arguments provided to the PSyIR node.

Raises:

TypeError – if the routine argument is not an Intrinsic type.

Inheritance

class Intrinsic(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Enum of all intrinsics with their attributes as values using the IAttr namedtuple format:

NAME = IAttr(name, is_pure, is_elemental, is_inquiry,
required_args, optional_args)

Note that name is duplicated inside IAttr because each item in the Enum must have a different value, and without the name that would not be guaranteed.

classmethod create(routine, arguments)

Create an instance of this class given the type of routine and a list of nodes (or name-and-node tuples) for its arguments. Any named arguments must come after any required arguments.

Parameters:

routine (py:class:psyclone.psyir.IntrinsicCall.Intrinsic) – the Intrinsic being called.
arguments (List[ Union[psyclone.psyir.nodes.DataNode, Tuple[str, psyclone.psyir.nodes.DataNode]]]) – the arguments to this routine, and/or 2-tuples containing an argument name and the argument. Arguments are added as child nodes.

Returns:

an instance of this class.

Return type:

psyclone.psyir.nodes.IntrinsicCall

Raises:

TypeError – if any of the arguments are of the wrong type.
ValueError – if any optional arguments have incorrect names or if a positional argument is listed after a named argument.
ValueError – if the number of supplied arguments is not valid for the specified intrinsic routine.

property intrinsic

Return the type of intrinsic.

Returns:: enumerated type capturing the type of intrinsic.
Return type:: psyclone.psyir.nodes.IntrinsicCall.Intrinsic

is_available_on_device()

Returns:: whether this intrinsic is available on an accelerated device.
Return type:: bool

property is_elemental

Returns:: whether the routine being called is elemental (provided with an input array it will apply the operation individually to each of the array elements and return an array with the results). If this information is not known then it returns None.
Return type:: NoneType | bool

property is_inquiry

Returns:: whether the routine being called is a query function (i.e. returns information about its argument rather than accessing any data referenced by the argument). If this information is not known then it returns None.
Return type:: NoneType | bool

property is_pure

Returns:: whether the routine being called is pure (guaranteed to return the same result when provided with the same argument values). If this information is not known then it returns None.
Return type:: NoneType | bool

reference_accesses(var_accesses)

Get all reference access information from this node. If the ‘COLLECT-ARRAY-SHAPE-READS’ options is set, it will report array accesses used as first parameter in ‘inquiry intrinsics’ like lbound, ubound, or size as ‘read’ accesses.

Parameters:: var_accesses (psyclone.core.VariablesAccessInfo) – VariablesAccessInfo instance that stores the information about variable accesses.

class psyclone.psyir.nodes.Literal(value, datatype, parent=None)

Node representing a Literal. The value and datatype properties of this node are immutable.

If the node represents “real” data and the value is expressed with an exponent (e.g. 3.2e4 or 0.1E-3) then the stored value always uses a lower case “e”.

Parameters:

value (str) – the value of the literal.
datatype (psyclone.psyir.symbols.DataType) – the datatype of this literal.
parent (psyclone.psyir.nodes.Node) – the parent node of this Literal in the PSyIR.

Raises:

TypeError – if the datatype is not an instance of psyclone.psyir.symbols.DataType.
ValueError – if the datatype is not one of self.VALID_DATA_TYPES.
TypeError – if the supplied value is not a string.
ValueError – if the supplied value is an empty string and the Literal is not a CHARACTER.
ValueError – if the Literal is a BOOLEAN and the value is not ‘true’ or ‘false’.
ValueError – if the Literal is a REAL but does not conform to the supported format defined by the _real_value property.
ValueError – if the Literal is an INTEGER but does not conform to the supported format defined by the _int_value property.

Inheritance

property datatype

Returns:: the type of this Literal.
Return type:: psyclone.psyir.symbols.DataType

node_str(colour=True)

Construct a text representation of this node, optionally containing colour control codes.

Parameters:: colour (bool) – whether or not to include colour control codes.
Returns:: description of this PSyIR node.
Return type:: str

property value

Returns:: String representing the literal value.
Return type:: str

class psyclone.psyir.nodes.Loop(variable=None, annotations=None, **kwargs)

Node representing a loop within the PSyIR. It has 4 mandatory children: the first one represents the loop lower bound, the second one represents the loop upper bound, the third one represents the step value and the fourth one is always a PSyIR Schedule node containing the statements inside the loop body.

(Note: Loop only represents the equivalent to Fortran counted do loops. This means the loop is bounded by start/stop/step expressions evaluated before the loop starts. See WhileLoop for while loops, including the Fortran do while and do loop with no condition.)

Parameters:

variable (Optional[psyclone.psyir.symbols.DataSymbol]) – optional reference to the loop iterator variable. Defaults to None.
annotations (Optional[List[str]]) – One or more labels that provide additional information about the node (primarily relating to the input code that it was created from).
kwargs (unwrapped dict.) – additional keyword arguments provided to the PSyIR node.

Raises:

InternalError – if the ‘was_single_stmt’ annotation is supplied without the ‘was_where’ annotation.

Inheritance

classmethod create(variable, start, stop, step, children)

Create a Loop instance given valid instances of a variable, start, stop and step nodes, and a list of child nodes for the loop body.

Parameters:

variable (psyclone.psyir.symbols.DataSymbol) – the PSyIR node containing the variable of the loop iterator.
start (psyclone.psyir.nodes.Node) – the PSyIR node determining the value for the start of the loop.
end (psyclone.psyir.nodes.Node) – the PSyIR node determining the value for the end of the loop.
step (psyclone.psyir.nodes.Node) – the PSyIR node determining the value for the loop step.
children (list of psyclone.psyir.nodes.Node) – a list of PSyIR nodes contained in the loop.

Returns:

a Loop instance.

Return type:

psyclone.psyir.nodes.Loop

Raises:

GenerationError – if the arguments to the create method are not of the expected type.

property dag_name

Return the name to use in a dag for this node

Returns:: Return the dag name for this loop
Return type:: string
Raises:: InternalError – if this Loop has no ancestor Routine.

gen_code(parent)

Generate the Fortran Loop and any associated code.

Parameters:: parent (psyclone.f2pygen.SubroutineGen) – the node in the f2pygen AST to which to add content.

independent_iterations(test_all_variables=False, signatures_to_ignore=None, dep_tools=None)

This function analyses a loop in the PSyIR to see whether its iterations are independent.

Parameters:

test_all_variables (bool) – if True, it will test if all variable accesses are independent, otherwise it will stop after the first variable access is found that isn’t.
signatures_to_ignore (Optional[ List[psyclone.core.Signature]]) – list of signatures for which to skip the access checks.
dep_tools (Optional[ psyclone.psyir.tools.DependencyTools]) – an optional instance of DependencyTools so that the caller can access any diagnostic messages detailing why the loop iterations are not independent.

Returns:

True if the loop iterations are independent, False otherwise.

Return type:

bool

property loop_body

Returns:: the PSyIR Schedule with the loop body statements.
Return type:: psyclone.psyir.nodes.Schedule

node_str(colour=True)

Returns the name of this node with (optional) control codes to generate coloured output in a terminal that supports it.

Parameters:: colour (bool) – whether or not to include colour control codes.
Returns:: description of this node, possibly coloured.
Return type:: str

reference_accesses(var_accesses)

Get all variable access information. It combines the data from the loop bounds (start, stop and step), as well as the loop body. The loop variable is marked as ‘READ+WRITE’ and references in start, stop and step are marked as ‘READ’.

Parameters:: var_accesses (psyclone.core.VariablesAccessInfo) – VariablesAccessInfo instance that stores the information about variable accesses.

property start_expr

Returns:: the PSyIR Node representing the Loop start expression.
Return type:: psyclone.psyir.nodes.Node

property step_expr

Returns:: the PSyIR Node representing the Loop step expression.
Return type:: psyclone.psyir.nodes.Node

property stop_expr

Returns:: the PSyIR Node representing the Loop stop expression.
Return type:: psyclone.psyir.nodes.Node

property variable

Returns:: the control variable for this loop.
Return type:: psyclone.psyir.symbols.DataSymbol

class psyclone.psyir.nodes.Member(member_name, parent=None)

Node representing a membership expression of a structure. As such it is a leaf in the PSyIR tree.

Parameters:

member_name (str) – the name of the member of the structure that is being referenced.
parent (psyclone.psyir.nodes.StructureReference or psyclone.psyir.nodes.Member) – the parent of this node in the PSyIR tree.

Raises:

TypeError – if the supplied parent is of the wrong type.

Inheritance

get_signature_and_indices()

Returns:: the Signature of this member access, and a list of list of the indices used for each component, which is empty in this case since it is not an array access.
Return type:: tuple(psyclone.core.Signature, list of lists of indices)

property is_array

Returns:: whether this member is an array.
Return type:: bool

property name

Returns:: the name of this member.
Return type:: str

node_str(colour=True)

Create a text description of this node in the schedule, optionally including control codes for colour.

Parameters:: colour (bool) – whether or not to include colour control codes.
Returns:: text description of this node.
Return type:: str

class psyclone.psyir.nodes.Node(ast=None, children=None, parent=None, annotations=None)

Base class for a PSyIR node.

Parameters:

ast (sub-class of fparser.two.Fortran2003.Base) – reference into the fparser2 AST corresponding to this node.
children (list of psyclone.psyir.nodes.Node) – the PSyIR nodes that are children of this node.
parent (psyclone.psyir.nodes.Node) – that parent of this node in the PSyIR tree.
annotations (list of str) – Tags that provide additional information about the node. The node should still be functionally correct when ignoring these tags.

Raises:

TypeError – if a parent is supplied that is not an instance of Node.
InternalError – if an invalid annotation tag is supplied.

Inheritance

property abs_position

Find a Node’s absolute position in the tree (starting with 0 if it is the root). Needs to be computed dynamically from the starting position (0) as its position may change.

Returns:: absolute position of a Node in the tree.
Return type:: int
Raises:: InternalError – if the absolute position cannot be found.

addchild(child, index=None)

Adds the supplied node as a child of this node (at position index if supplied). The supplied node must not have an existing parent.

Parameters:

child (psyclone.psyir.nodes.Node) – the node to add as a child of this one.
index (Optional[int]) – optional position at which to insert new child. Default is to append new child to the list of existing children.

ancestor(my_type, excluding=None, include_self=False, limit=None, shared_with=None)

Search back up the tree and check whether this node has an ancestor that is an instance of the supplied type. If it does then we return it otherwise we return None. An individual (or tuple of) (sub-) class(es) to ignore may be provided via the excluding argument. If include_self is True then the current node is included in the search. If limit is provided then the search ceases if/when the supplied node is encountered. If shared_with is provided, then the ancestor search will find an ancestor of both this node and the node provided as shared_with if such an ancestor exists.

Parameters:

my_type (type | Tuple[type, ...]) – class(es) to search for.
excluding (Optional[type | Tuple[type, ...]]) – (sub-)class(es) to ignore or None.
include_self (bool) – whether or not to include this node in the search.
limit (Optional[psyclone.psyir.nodes.Node]) – an optional node at which to stop the search.
shared_with (Optional[psyclone.psyir.nodes.Node]) – an optional node which must also have the found node as an ancestor.

Returns:

First ancestor Node that is an instance of any of the requested classes or None if not found.

Return type:

Optional[psyclone.psyir.nodes.Node]

Raises:

TypeError – if excluding is provided but is not a type or tuple of types.
TypeError – if limit is provided but is not an instance of Node.

property annotations

Return the list of annotations attached to this Node.

Returns:: List of anotations
Return type:: list of str

property args: Return the list of arguments associated with this Node. The default implementation assumes the Node has no directly associated arguments (i.e. is not a Kern class or subclass). Arguments of any of this nodes descendants are considered to be associated.

property ast

Returns:: a reference to that part of the fparser2 parse tree that this node represents or None.
Return type:: sub-class of fparser.two.utils.Base

property ast_end

Returns:: a reference to the last node in the fparser2 parse tree that represents a child of this PSyIR node or None.
Return type:: sub-class of fparser.two.utils.Base

backward_dependence(): Returns the closest preceding Node that this Node has a direct dependence with or None if there is not one. Only Nodes with the same parent as self are returned. Nodes inherit their descendants’ dependencies. The reason for this is that for correctness a node must maintain its parent if it is moved. For example a halo exchange and a kernel call may have a dependence between them but it is the loop body containing the kernel call that the halo exchange must not move beyond i.e. the loop body inherits the dependencies of the routines within it.

property children

Returns:: the immediate children of this Node.
Return type:: List[psyclone.psyir.nodes.Node]

coded_kernels()

Returns a list of all of the user-supplied kernels (as opposed to builtins) that are beneath this node in the PSyIR.

Returns:: all user-supplied kernel calls below this node.
Return type:: List[psyclone.psyGen.CodedKern]

coloured_name(colour=True)

Returns the display name of this Node, optionally with colour control codes (requires that the termcolor package be installed).

Parameters:: colour (bool) – whether or not to include colour control codes in the result.
Returns:: the name of this node, optionally with colour control codes.
Return type:: str

copy()

Return a copy of this node. This is a bespoke implementation for PSyIR nodes that will deepcopy some of its recursive data-structure (e.g. the children tree), while not copying other attributes (e.g. top-level parent reference).

Returns:: a copy of this node and its children.
Return type:: psyclone.psyir.node.Node

dag(file_name='dag', file_format='svg')

Create a dag of this node and its children, write it to file and return the graph object.

Parameters:

file_name (str) – name of the file to create.
file_format (str) – format of the file to create. (Must be one recognised by Graphviz.)

Returns:

the graph object or None (if the graphviz bindings are not installed).

Return type:

graphviz.Digraph or NoneType

Raises:

GenerationError – if the specified file format is not recognised by Graphviz.

dag_gen(graph): Output my node’s graph (dag) information and call any children. Nodes with children are represented as two vertices, a start and an end. Forward dependencies are represented as green edges, backward dependencies are represented as red edges (but their direction is reversed so the layout looks reasonable) and parent child dependencies are represented as blue edges.

property dag_name

Return the dag name for this node. This includes the name of the class and the index of its relative position to the parent Routine. If no parent Routine is found, the index used is the absolute position in the tree.

Returns:: the dag name for this node.
Return type:: str

debug_string()

Generates a Fortran-like output representation but without lowering high-level nodes. This is fast to generate because it doesn’t deepcopy the tree like the Language backends and its output, although not compilable, is readable for error messages.

Returns:: a Fortran-like output representation of the tree.
Return type:: str

property depth: Returns this Node’s depth in the tree: 1 for the Schedule and increasing for its descendants at each level. :returns: depth of the Node in the tree :rtype: int

detach()

Detach this node from the tree it belongs to. This is necessary as a precursor to inserting it as the child of another node.

Returns:: this node detached from its parent.
Return type:: psyclone.psyir.node.Node

following(routine=True)

Return all psyclone.psyir.nodes.Node nodes after this node. Ordering is depth first. If the routine argument is set to True then nodes are only returned if they are descendents of this node’s closest ancestor routine if one exists.

Parameters:: routine (bool) – an optional (default True) argument that only returns nodes that are within this node’s closest ancestor Routine node if one exists.
Returns:: a list of nodes.
Return type:: list() of psyclone.psyir.nodes.Node

forward_dependence(): Returns the closest following Node that this Node has a direct dependence with or None if there is not one. Only Nodes with the same parent as self are returned. Nodes inherit their descendants’ dependencies. The reason for this is that for correctness a node must maintain its parent if it is moved. For example a halo exchange and a kernel call may have a dependence between them but it is the loop body containing the kernel call that the halo exchange must not move beyond i.e. the loop body inherits the dependencies of the routines within it.

get_sibling_lists(my_type, stop_type=None)

Recurse through the PSyIR tree and return lists of Nodes that are instances of ‘my_type’ and are immediate siblings. Here ‘my_type’ is either a single class or a tuple of classes. In the latter case all nodes are returned that are instances of any classes in the tuple. The recursion into the tree is stopped if an instance of ‘stop_type’ (which is either a single class or a tuple of classes) is found.

Parameters:

my_type (type | Tuple[type, ...]) – the class(es) for which the instances are collected.
stop_type (Optional[type | Tuple[type, ...]]) – class(es) at which recursion is halted (optional).

Returns:

list of lists, each of which containing nodes that are instances of my_type and are immediate siblings, starting at and including this node.

Return type:

List[List[psyclone.psyir.nodes.Node]]

property has_constructor_parent

Returns:: whether the constructor has predefined a parent connection but the parent’s children list doesn’t include this node yet.
Return type:: bool

immediately_follows(node_1)

Returns:: True if this node immediately follows node_1, False otherwise
Return type:: bool

immediately_precedes(node_2)

Returns:: True if this node immediately precedes node_2, False otherwise
Return type:: bool

is_openmp_parallel()

Returns:: True if this Node is within an OpenMP parallel region, False otherwise.
Return type:: bool

is_valid_location(new_node, position='before')

If this Node can be moved to the new_node (where position determines whether it is before of after the new_node) without breaking any data dependencies then return True, otherwise return False.

Parameters:

new_node (psyclone.psyir.nodes.Node) – Node to which this node should be moved.
position (str) – either ‘before’ or ‘after’.

Raises:

GenerationError – if new_node is not an instance of psyclone.psyir.nodes.Node.
GenerationError – if position is not ‘before’ or ‘after’.
GenerationError – if self and new_node do not have the same parent.
GenerationError – self and new_node are the same Node.

Returns:

whether or not the specified location is valid for this node.

Return type:

bool

kernels()

Returns:: all kernels that are descendants of this node in the PSyIR.
Return type:: List[psyclone.psyGen.Kern]

loops()

Returns:: all loops currently in this schedule.
Return type:: List[psyclone.psyir.nodes.Loop]

lower_to_language_level()

In-place replacement of high-level concepts into generic language PSyIR constructs. This generic implementation only recurses down to its children, but this method must be re-implemented by Nodes that represent high-level concepts.

Returns:: the lowered version of this node.
Return type:: psyclone.psyir.node.Node

node_str(colour=True)

Parameters:: colour (bool) – whether or not to include control codes for coloured text.
Returns:: a text description of this node. Will typically be overridden by sub-class.
Return type:: str

origin_string()

Generates a string with the available information about where this node has been created. It currently only works with Fortran Statements or subchildren of them.

Returns:: a string specifing the origin of this node.
Return type:: str

property parent

Returns:: the parent node.
Return type:: psyclone.psyir.nodes.Node or NoneType

path_from(ancestor)

Find the path in the psyir tree between ancestor and node and returns a list containing the path.

The result of this method can be used to find the node from its ancestor for example by:

>>> index_list = node.path_from(ancestor)
>>> cursor = ancestor
>>> for index in index_list:
>>>    cursor = cursor.children[index]
>>> assert cursor is node

Parameters:: ancestor (psyclone.psyir.nodes.Node) – an ancestor node of self to find the path from.
Raises:: ValueError – if ancestor is not an ancestor of self.
Returns:: a list of child indices representing the path between ancestor and self.
Return type:: List[int]

pop_all_children()

Remove all children of this node and return them as a list.

Returns:: all the children of this node as orphan nodes.
Return type:: list of psyclone.psyir.node.Node

property position

Find a Node’s position relative to its parent Node (starting with 0 if it does not have a parent).

Returns:: relative position of a Node to its parent
Return type:: int

preceding(reverse=False, routine=True)

Return all psyclone.psyir.nodes.Node nodes before this node. Ordering is depth first. If the reverse argument is set to True then the node ordering is reversed i.e. returning the nodes closest to this node first. if the routine argument is set to True then nodes are only returned if they are descendents of this node’s closest ancestor routine if one exists.

Parameters:

reverse (bool) – an optional (default False) argument that reverses the order of any returned nodes (i.e. makes them ‘closest first’ if set to true.
routine (bool) – an optional (default True) argument that only returns nodes that are within this node’s closest ancestor Routine node if one exists.

Returns:

a list of nodes.

Return type:

list() of psyclone.psyir.nodes.Node

reductions(reprod=None)

Return all kernels that have reductions and are decendents of this node. If reprod is not provided, all reductions are returned. If reprod is False, all builtin reductions that are not set to reproducible are returned. If reprod is True, all builtins that are set to reproducible are returned.

Parameters:: reprod (Optional[bool]) – if provided, filter reductions by whether or not they are set to be reproducible.
Returns:: all kernels involving reductions that are descendants of this node.
Return type:: List[psyclone.psyir.nodes.Kern]

reference_accesses(var_accesses)

Get all variable access information. The default implementation just recurses down to all children.

Parameters:: var_accesses (psyclone.core.VariablesAccessInfo) – Stores the output results.

replace_with(node, keep_name_in_context=True)

Removes self, and its descendants, from the PSyIR tree to which it is connected, and replaces it with the supplied node (and its descendants).

Parameters:

node (psyclone.psyir.nodes.node) – the node that will replace self in the PSyIR tree.
keep_name_in_context (bool) – whether to conserve the name referencing this node.

Raises:

TypeError – if the argument ‘node’ is not a Node.
TypeError – if the argument ‘keep_name_in_context’ is not bool.
GenerationError – if this node does not have a parent.
GenerationError – if the argument ‘node’ has a parent.

property root

Returns:: the root node of the PSyIR tree.
Return type:: psyclone.psyir.nodes.Node

sameParent(node_2)

Returns:: True if node_2 has the same parent as this node, False otherwise.
Return type:: bool

property scope

Some nodes (e.g. Schedule and Container) allow symbols to be scoped via an attached symbol table. This property returns the closest ScopingNode node including self.

Returns:: the closest ancestor ScopingNode node.
Return type:: psyclone.psyir.node.ScopingNode
Raises:: SymbolError – if there is no ScopingNode ancestor.

property siblings

Returns:: list of sibling nodes, including self.
Return type:: List[psyclone.psyir.nodes.Node]

update_signal(): Called whenever there is a change in the PSyIR tree below this node. It is responsible for ensuring that this method does not get called recursively and then calls the _update_node() method of the current node (which is the only part that subclasses should specialise). Finally, it propagates the update signal up to the parent node (if any).

validate_global_constraints()

Validates this Node in the context of the whole PSyIR tree. Although there are validation checks for the parent<->child relationships, there are other constraints that can only be checked once the tree is complete and all transformations have been applied. (One example is that an OMP Do directive must be within the scope of an OMP Parallel directive.)

By default, this routine does nothing. It must be overridden appropriately in any sub-classes to which constraints apply. If an error is found then a GenerationError should be raised.

view(depth=0, colour=True, indent=' ', _index=None)

Output a human readable description of the current node and all of its descendents as a string.

Parameters:

depth (int) – depth of the tree hierarchy for output text. Defaults to 0.
colour (bool) – whether to include colour coding in the output. Defaults to True.
indent (str) – the indent to apply as the depth increases. Defaults to 4 spaces.
_index (int) – the position of this node wrt its siblings or None. Defaults to None.

Returns:

a representation of this node and its descendents.

Return type:

str

Raises:

TypeError – if one of the arguments is the wrong type.
ValueError – if the depth argument is negative.

walk(my_type, stop_type=None, depth=None)

Recurse through the PSyIR tree and return all objects that are an instance of ‘my_type’, which is either a single class or a tuple of classes. In the latter case all nodes are returned that are instances of any classes in the tuple. The recursion into the tree is stopped if an instance of ‘stop_type’ (which is either a single class or a tuple of classes) is found. This can be used to avoid analysing e.g. inlined kernels, or as performance optimisation to reduce the number of recursive calls. The recursion into the tree is also stopped if the (optional) ‘depth’ level is reached.

Parameters:

my_type (type | Tuple[type, ...]) – the class(es) for which the instances are collected.
stop_type (Optional[type | Tuple[type, ...]]) – class(es) at which recursion is halted (optional).
depth (Optional[int]) – the depth value the instances must have (optional).

Returns:

list with all nodes that are instances of my_type starting at and including this node.

Return type:

List[psyclone.psyir.nodes.Node]

class psyclone.psyir.nodes.OperandClause(ast=None, children=None, parent=None, annotations=None)

Base abstract class for all clauses that have an operand.

Inheritance

property operand

Returns the operand string for this Clause.

Return type:: str

class psyclone.psyir.nodes.Operation(operator, parent=None)

Abstract base class for PSyIR nodes representing operators.

Parameters:

operator (psyclone.psyir.nodes.UnaryOperation.Operator or psyclone.psyir.nodes.BinaryOperation.Operator or psyclone.psyir.nodes.NaryOperation.Operator) – the operator used in the operation.
parent (psyclone.psyir.nodes.Node) – the parent node of this Operation in the PSyIR.

Raises:

TypeError – if the supplied operator is not an instance of self.Operator.

Inheritance

Operator: alias of object

node_str(colour=True)

Construct a text representation of this node, optionally with control codes for coloured display in a suitable terminal.

Parameters:: colour (bool) – whether or not to include colour control codes.
Returns:: description of this PSyIR node.
Return type:: str

property operator

Return the operator.

Returns:: Enumerated type capturing the operator.
Return type:: psyclone.psyir.nodes.UnaryOperation.Operator or psyclone.psyir.nodes.BinaryOperation.Operator or psyclone.psyir.nodes.NaryOperation.Operator

class psyclone.psyir.nodes.Range(ast=None, children=None, parent=None, annotations=None)

The Range node is used to capture a range of integers via start, stop and step expressions. For example, start=2, stop=6 and step=2 indicates the values 2, 4 and 6.

At the moment the only valid use of Range in the PSyIR is to describe a set of accesses to an Array dimension (so-called array notation in Fortran). Therefore, the parent of a Range node should only be an Array node.

The Range node has three children nodes, the first child captures the start of the range, the second child captures the end of the range and the third captures the step within the range.

The nodes for each of the children must return an integer. Potentially valid nodes are therefore Literal, Reference, Operation and CodeBlock.

A common use case is to want to specify all the elements of a given array dimension without knowing the extent of that dimension. In the PSyIR this is achieved by using the LBOUND, and UBOUND intrinsics:

>>> one = Literal("1", INTEGER_TYPE)
>>> # Declare a 1D real array called 'a' with 10 elements
>>> symbol = DataSymbol("a", ArrayType(REAL_TYPE, [10]))
>>> # Return the lower bound of the first dimension of array 'a'
>>> lbound = IntrinsicCall.create(
        IntrinsicCall.Intrinsic.LBOUND,
        [Reference(symbol), one.copy()])
>>> # Return the upper bound of the first dimension of array 'a'
>>> ubound = IntrinsicCall.create(
        IntrinsicCall.Intrinsic.UBOUND,
        [Reference(symbol), one.copy()])
>>> # Step defaults to 1 so no need to include it when creating range
>>> my_range = Range.create(lbound, ubound)
>>> # Create an access to all elements in the 1st dimension of array 'a'
>>> array_access = ArrayReference.create(symbol, [my_range])

In Fortran the above access array_access can be represented by a(:). The Fortran front-ends and back-ends are aware of array notation. Therefore the Fortran frontend is able to convert array notation to PSyIR and the Fortran backend is able to convert PSyIR back to array notation.

Inheritance

static create(start, stop, step=None)

Create an internally-consistent Range object. If no step is provided then it defaults to an integer Literal with value 1.

Parameters:

start (psyclone.psyir.nodes.Node) – the PSyIR for the start value.
stop (psyclone.psyir.nodes.Node) – the PSyIR for the stop value.
step (psyclone.psyir.nodes.Node or NoneType) – the PSyIR for the increment/step or None.
parent (psyclone.psyir.nodes.Node or NoneType) – the parent node of this Range in the PSyIR.

Returns:

a fully-populated Range object.

Return type:

psyclone.psyir.nodes.ranges.Range

property start

Checks that this Range is valid and then returns the PSyIR for the starting value of the range.

Returns:: the starting value of this range.
Return type:: psyclone.psyir.nodes.Node

property step

Checks that this Range is valid and then returns the step (increment) value/expression.

Returns:: the increment used in this range.
Return type:: psyclone.psyir.nodes.Node

property stop

Checks that this Range is valid and then returns the end value/expression.

Returns:: the end value of this range.
Return type:: psyclone.psyir.nodes.Node

class psyclone.psyir.nodes.Reference(symbol, **kwargs)

Node representing a Reference Expression.

Parameters:

symbol (psyclone.psyir.symbols.Symbol) – the symbol being referenced.
kwargs (unwrapped dict.) – additional keyword arguments provided to the super class.

Inheritance

property datatype

Returns:: the datatype of this reference.
Return type:: psyclone.psyir.symbols.DataType

get_signature_and_indices()

Returns:: the Signature of this reference, and an empty list of lists as ‘indices’ since this reference does not represent an array access.
Return type:: tuple(psyclone.core.Signature, list of list of indices)

property is_array

Returns:: whether this reference is an array, False if it can not be determined.
Return type:: bool

property name

Return the name of the referenced symbol.

Returns:: Name of the referenced symbol.
Return type:: str

node_str(colour=True)

Create a text description of this node in the schedule, optionally including control codes for colour.

Parameters:: colour (bool) – whether or not to include colour control codes.
Returns:: text description of this node.
Return type:: str

reference_accesses(var_accesses)

Get all variable access information from this node, i.e. it sets this variable to be read. It relies on get_signature_and_indices and will correctly handle array expressions.

Parameters:: var_accesses (psyclone.core.VariablesAccessInfo) – VariablesAccessInfo instance that stores the information about variable accesses.

property symbol

Return the referenced symbol.

Returns:: the referenced symbol.
Return type:: psyclone.psyir.symbols.Symbol

class psyclone.psyir.nodes.Return(ast=None, children=None, parent=None, annotations=None)

Node representing a Return statement (subroutine break without return value).

Inheritance

class psyclone.psyir.nodes.Routine(name, is_program=False, **kwargs)

A sub-class of a Schedule that represents a subroutine, function or program unit.

Parameters:

name (str) – the name of this routine.
is_program (bool) – whether this Routine represents the entry point into a program (e.g. Fortran Program or C main()).
kwargs (unwrapped dict.) – additional keyword arguments provided to the super class.

Raises:

TypeError – if any of the supplied arguments are of the wrong type.

Inheritance

classmethod create(name, symbol_table, children, is_program=False, return_symbol_name=None)

Create an instance of the supplied class given a name, a symbol table and a list of child nodes. This is implemented as a classmethod so that it is able to act as a Factory for subclasses - e.g. it will create a KernelSchedule if called from KernelSchedule.create().

Parameters:

name (str) – the name of the Routine (or subclass).
symbol_table (psyclone.psyGen.SymbolTable) – the symbol table associated with this Routine.
children (list of psyclone.psyir.nodes.Node) – a list of PSyIR nodes contained in the Routine.
is_program (bool) – whether this Routine represents the entry point into a program (i.e. Fortran Program or C main()).
return_symbol_name (str) – name of the symbol that holds the return value of this routine (if any). Must be present in the supplied symbol table.

Returns:

an instance of cls.

Return type:

psyclone.psyGen.Routine or subclass

Raises:

TypeError – if the arguments to the create method are not of the expected type.

property dag_name

Returns:: the name of this node in the dag.
Return type:: str

property is_program

Returns:: whether this Routine represents the entry point into a program (e.g. is a Fortran Program or a C main()).
Return type:: bool

property name

Returns:: the name of this Routine.
Return type:: str

node_str(colour=True)

Returns the name of this node with (optional) control codes to generate coloured output in a terminal that supports it.

Parameters:: colour (bool) – whether or not to include colour control codes.
Returns:: description of this node, possibly coloured.
Return type:: str

property return_symbol

Returns:: the symbol which will hold the return value of this Routine or None if the Routine is not a function.
Return type:: psyclone.psyir.symbols.DataSymbol or NoneType

class psyclone.psyir.nodes.Schedule(children=None, parent=None, symbol_table=None)

Stores schedule information for a sequence of statements (supplied as a list of children).

Inheritance

gen_code(parent)

A Schedule does not have any direct Fortran representation. We just call gen_code() for all of its children.

Parameters:: parent (psyclone.f2pygen.BaseGen) – node in the f2pygen AST to which to add content.

class psyclone.psyir.nodes.Statement(ast=None, children=None, parent=None, annotations=None)

Abstract node representing a general PSyIR Statement.

Inheritance

class psyclone.psyir.nodes.StructureMember(member_name, parent=None)

Node representing a membership expression of the parent’s Reference that resolves into another structure.

Inheritance

static create(member_name, inner_member)

Given the name of a structure member of a structure and a Member node describing the access to a component of it, construct a StructureMember.

e.g. if we had the following Fortran access: grid%subdomain%xstart then ‘subdomain’ must itself be of structure type and we are accessing the ‘xstart’ component of it. We would therefore create the StructureMember for this by calling:

>>> smem = StructureMember.create("subdomain", Member("xstart"))

Parameters:

member_name (str) – name of the structure member.
inner_member (sub-class of psyclone.psyir.nodes.Member) – a Member describing the access to a component of the named structure member.

get_signature_and_indices()

Returns:: the Signature of this structure member, and a list of the indices used for each component (empty list for this component, since the access is not an array - but other components might have indices).
Return type:: tuple(psyclone.core.Signature, list of list of indices)

property member

Returns:: the member of the structure that is being accessed.
Return type:: (sub-class of) psyclone.psyir.nodes.Member
Raises:: InternalError – if the first child of this node is not an instance of Member.

class psyclone.psyir.nodes.StructureReference(symbol, **kwargs)

Node representing a reference to a component of a structure. As such it must have a single child representing the component being accessed.

Parameters:

symbol (psyclone.psyir.symbols.Symbol) – the symbol being referenced.
kwargs (unwrapped dict.) – additional keyword arguments provided to the super class.

Inheritance

static create(symbol, members, parent=None, overwrite_datatype=None)

Create a StructureReference instance given a symbol and a list of components. e.g. for “field%bundle(2)%flag” this list would be [(“bundle”, [Literal(“2”, INTEGER4_TYPE)]), “flag”].

Parameters:

symbol (psyclone.psyir.symbols.DataSymbol) – the symbol that this reference is to.
members (list of str or 2-tuples containing (str, list of nodes describing array access)) – the component(s) of the structure that make up the full access. Any components that are array accesses must provide the name of the array and a list of DataNodes describing which part of it is accessed.
parent (sub-class of psyclone.psyir.nodes.Node) – the parent of this node in the PSyIR.
overwrite_datatype (Optional[psyclone.psyir.symbols.DataType]) – the datatype for the reference, which will overwrite the value determined by analysing the corresponding user defined type. This is useful when e.g. the module that declares the structure cannot be accessed.

Returns:

a StructureReference instance.

Return type:

psyclone.psyir.nodes.StructureReference

Raises:

TypeError – if the supplied symbol is not a DataSymbol.

property datatype

Walks down the list of members making up this reference to determine the type that it refers to. If an overwrite datatype was given to this reference, this datatype will be returned instead of determining the type.

In order to minimise code duplication, this method also supports ArrayOfStructuresReference by simply allowing for the case where the starting reference is to an Array.

Returns:: the datatype of this reference.
Return type:: psyclone.psyir.symbols.DataType
Raises:: NotImplementedError – if the structure reference represents an array of arrays.

get_signature_and_indices()

Returns:: the Signature of this structure reference, and a list of the indices used for each component (empty list if an access is not an array).
Return type:: Tuple[psyclone.core.Signature, List[List[psyclone.psyir.nodes.Node]]]

property member

Returns:: the member of the structure that this reference is to.
Return type:: psyclone.psyir.nodes.Member
Raises:: InternalError – if the first child of this node is not an instance of Member.

class psyclone.psyir.nodes.UnaryOperation(operator, parent=None)

Node representing a UnaryOperation expression. As such it has one operand as child 0, and an attribute with the operator type.

Inheritance

class Operator(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

static create(operator, operand)

Create a UnaryOperation instance given an operator and operand.

Parameters:

operator (psyclone.psyir.nodes.UnaryOperation.Operator) – the specified operator.
operand (Union[psyclone.psyir.nodes.Node | Tuple[str, :py:class:psyclone.psyir.nodes.Node]]) – the PSyIR node that oper operates on, or a tuple containing the name of the argument and the PSyIR node.

Returns:

a UnaryOperation instance.

Return type:

psyclone.psyir.nodes.UnaryOperation

Raises:

GenerationError – if the arguments to the create method are not of the expected type.

property datatype

Returns:: the datatype of the result of this UnaryOperation.
Return type:: psyclone.psyir.symbols.DataType

class psyclone.psyir.nodes.ScopingNode(children=None, parent=None, symbol_table=None)

Abstract node that has an associated Symbol Table to keep track of symbols declared in its scope (symbols that can be accessed by this node and any of its descendants). If a pre-existing symbol table is provided, it will be attached to the node (raising an error if the symbol table is already attached to another scope), otherwise a new empty Symbol Table will be created.

Parameters:

children (List[psyclone.psyir.nodes.Node]) – the PSyIR nodes that are children of this node.
parent (Optional[psyclone.psyir.nodes.Node]) – the parent node of this node in the PSyIR.
symbol_table (Optional[psyclone.psyir.symbols.SymbolTable]) – attach the given symbol table to the new node.

Inheritance

property symbol_table

Returns:: table containing symbol information for this scope.
Return type:: psyclone.psyGen.SymbolTable

class psyclone.psyir.nodes.WhileLoop(ast=None, children=None, parent=None, annotations=None)

Node representing a while loop within the PSyIR. It has two mandatory children: the first one represents the loop condition and the second one the loop body.

Inheritance

property condition

Return the PSyIR Node representing the conditional expression of this WhileLoop.

Returns:: WhileLoop conditional expression.
Return type:: psyclone.psyir.nodes.Node
Raises:: InternalError – If the WhileLoop node does not have the correct number of children.

static create(loop_condition, loop_body)

Create a WhileLoop instance given valid instances of a loop_condition and a loop_body.

Parameters:

loop_condition (psyclone.psyir.nodes.Node) – the PSyIR node containing the loop condition of the while loop statement.
loop_body (List[psyclone.psyir.nodes.Node]) – the PSyIR nodes representing the loop body of the loop statement.

Returns:

a WhileLoop instance.

Return type:

psyclone.psyir.nodes.WhileLoop

Raises:

GenerationError – if the arguments to the create method are not of the expected type.

property loop_body

Return the Schedule executed when the WhileLoop condition is True.

Returns:: Schedule to be executed when WhileLoop condition is True.
Return type:: psyclone.psyir.nodes.Schedule
Raises:: InternalError – If the WhileLoop node does not have the correct number of children.

reference_accesses(var_accesses)

Get all variable access information. It combines the data from the loop condition and the loop body.

Parameters:: var_accesses (psyclone.core.VariablesAccessInfo) – VariablesAccessInfo instance that stores the information about variable accesses.

class psyclone.psyir.nodes.KernelSchedule(name, is_program=False, **kwargs)

A KernelSchedule is the parent node of the PSyIR for Kernel source code.

Inheritance

class psyclone.psyir.nodes.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

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

class psyclone.psyir.nodes.ExtractNode(ast=None, children=None, parent=None, options=None)

This class can be inserted into a Schedule to mark Nodes for code extraction using the ExtractRegionTrans transformation. By applying the transformation the Nodes marked for extraction become children of (the Schedule of) an ExtractNode.

Parameters:

ast (sub-class of fparser.two.Fortran2003.Base) – reference into the fparser2 parse tree corresponding to this node.
children (list of psyclone.psyir.nodes.Node) – the PSyIR nodes that are children of this node.
parent (psyclone.psyir.nodes.Node) – the parent of this node in the PSyIR tree.
options (Optional[Dict[str, Any]]) – a dictionary with options provided via 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 “extract”, which means the module name used will be extract_psy_data_mode, and the data type extract_PSyDataType.
options["post_var_postfix"] (str) – a postfix to be used when creating names to store values of output variable. A variable ‘a’ would store its value as ‘a’, and its output values as ‘a_post’ with the default post_var_postfix of ‘_post’.

Inheritance

property extract_body

Returns:: the Schedule associated with this ExtractNode.
Return type:: psyclone.psyir.nodes.Schedule

gen_code(parent)

Generates the code required for extraction of one or more Nodes. It uses the PSyData API (via the base class PSyDataNode) to create the required callbacks that will allow a library to write the kernel data to a file.

Parameters:: parent (psyclone.psyir.nodes.Node.) – the parent of this Node in the PSyIR.

lower_to_language_level()

Lowers this node (and all children) to language-level PSyIR. The PSyIR tree is modified in-place.

Returns:: the lowered version of this node.
Return type:: psyclone.psyir.node.Node

property post_name

Returns:: the _post_name member of this ExtractNode.
Return type:: str

class psyclone.psyir.nodes.ProfileNode(ast=None, children=None, parent=None, options=None)

This class can be inserted into a schedule to create profiling code.

Inheritance

class psyclone.psyir.nodes.NanTestNode(ast=None, children=None, parent=None, options=None)

This class can be inserted into a Schedule to mark Nodes for NAN-checking using the NanTestTrans transformation. The Nodes marked for checking become children of (the Schedule of) a NanTestNode.

Inheritance

lower_to_language_level()

Lowers this node (and all children) to language-level PSyIR. The PSyIR tree is modified in-place.

Returns:: the lowered version of this node.
Return type:: psyclone.psyir.node.Node

property nan_test_body

Returns:: the Schedule associated with this NanTestNode.
Return type:: psyclone.psyir.nodes.Schedule

class psyclone.psyir.nodes.ReadOnlyVerifyNode(ast=None, children=None, parent=None, options=None)

This class can be inserted into a Schedule to mark Nodes for read-only-verification. By applying the ReadOnlyVerifyTrans transformation, the Nodes marked for extraction become children of (the Schedule of) a ReadOnlyVerifyNode.

Inheritance

lower_to_language_level()

Lowers this node (and all children) to language-level PSyIR. The PSyIR tree is modified in-place.

Returns:: the lowered version of this node.
Return type:: psyclone.psyir.node.Node

property read_only_verify_body

Returns:: the Schedule associated with this ExtractNode.
Return type:: psyclone.psyir.nodes.Schedule

class psyclone.psyir.nodes.Directive(ast=None, children=None, parent=None, annotations=None)

Abstract base class for all Directive statements.

Inheritance

abstract property clauses

Returns:: the Clauses associated with this directive.
Return type:: List of psyclone.psyir.nodes.Clause

create_data_movement_deep_copy_refs()

Creates the References required to perform a deep copy (in e.g. OpenACC or OpenMP) of all of the quantities accessed in Nodes below this one in the tree. It distringuishes between those quantities that are only read, only written or are both read and written. The necessary References are added to the returned OrderedDicts in the order in which they must be copied.

Returns:: a 3-tuple containing dicts describing the quantities that are read-only, write-only and readwrite. Each dict contains References indexed by Signatures.
Return type:: Tuple[OrderedDict[psyclone.core.Signature, psyclone.psyir.nodes.Reference]]

class psyclone.psyir.nodes.RegionDirective(ast=None, children=None, parent=None)

Base class for all Directive nodes that have an associated region of code with them.

All classes that generate RegionDirective statements (e.g. OpenMP, OpenACC, compiler-specific) inherit from this class.

Parameters:

ast (Optional[fparser.two.Fortran2003.Base]) – the entry in the fparser2 parse tree representing the code contained within this directive or None.
children (Optional[List[psyclone.psyir.nodes.Node]]) – the nodes that will be children of this Directive node or None.
parent (Optional[psyclone.psyir.nodes.Node]) – PSyIR node that is the parent of this Directive or None.

Inheritance

property clauses

Returns:: the Clauses associated with this directive.
Return type:: List of psyclone.psyir.nodes.Clause

property dir_body

Returns:: the Schedule associated with this directive.
Return type:: psyclone.psyir.nodes.Schedule
Raises:: InternalError – if this node does not have a Schedule as its first child.

gen_post_region_code(parent)

Generates any code that must be executed immediately after the end of the region defined by this directive.

TODO #1648 this method is only used by the gen_code() code-generation path and should be replaced by functionality in a ‘lower_to_language_level’ method in an LFRic-specific subclass of the appropriate directive.

Parameters:: parent (psyclone.f2pygen.BaseGen) – where to add new f2pygen nodes.

class psyclone.psyir.nodes.StandaloneDirective(ast=None, children=None, parent=None, annotations=None)

Base class for all StandaloneDirective statements. This class is designed for directives which do not have code associated with them, e.g. OpenMP’s taskwait.

All classes that generate StandaloneDirective statements (e.g. OpenMP, OpenACC, compiler-specific) inherit from this class.

Inheritance

property clauses

Returns:: the Clauses associated with this directive.
Return type:: List of psyclone.psyir.nodes.Clause

class psyclone.psyir.nodes.ACCAtomicDirective(ast=None, children=None, parent=None)

OpenACC directive to represent that the memory accesses in the associated assignment must be performed atomically. Note that the standard supports blocks with 2 assignments but this is currently unsupported in the PSyIR.

Inheritance

begin_string()

Returns:: the opening string statement of this directive.
Return type:: str

end_string()

Returns:: the ending string statement of this directive.
Return type:: str

static is_valid_atomic_statement(stmt)

Check if a given statement is a valid OpenACC atomic expression.

Parameters:: stmt (psyclone.psyir.nodes.Node) – a node to be validated.
Returns:: whether a given statement is compliant with the OpenACC atomic expression.
Return type:: bool

validate_global_constraints()

Perform validation of those global constraints that can only be done at code-generation time.

Raises:: GenerationError – if the ACCAtomicDirective associated statement does not conform to a valid OpenACC atomic operation.

class psyclone.psyir.nodes.ACCDirective

Base mixin class for all OpenACC directive statements.

This class is useful to provide a unique common ancestor to all the OpenACC directives, for instance when traversing the tree with node.walk(ACCDirective)

Note that classes inheriting from it must place the ACCDirective in front of the other Directive node sub-class, so that the Python MRO gives preference to this class’s attributes.

Inheritance

class psyclone.psyir.nodes.ACCRegionDirective(ast=None, children=None, parent=None)

Base class for all OpenACC region directive statements.

Inheritance

property signatures

Returns a 1-tuple or a 2-tuple of sets depending on the working API. If a 1-tuple, the set includes both input and output signatures (whether to arrays or objects) required by the Kernel call(s) that are children of this directive. If a 2-tuple, the first entry is the set of input signatures and the second entry is the set of output signatures. The set(s) describe the quantities that must be available on the remote device (probably a GPU) before the parallel region can be begun.

Returns:: 1-tuple or 2-tuple of input and output sets of variable names
Return type:: Union[Tuple[Set[psyclone.core.Signature]], Tuple[Set[psyclone.core.Signature], Set[psyclone.core.Signature]]]

validate_global_constraints()

Perform validation checks for any global constraints. This can only be done at code-generation time.

Raises:: GenerationError – if this ACCRegionDirective encloses any form of PSyData node since calls to PSyData routines within OpenACC regions are not supported.

class psyclone.psyir.nodes.ACCStandaloneDirective(ast=None, children=None, parent=None, annotations=None)

Base class for all standalone OpenACC directive statements.

Inheritance

class psyclone.psyir.nodes.ACCDataDirective(ast=None, children=None, parent=None)

Class representing the !$ACC DATA … !$ACC END DATA directive in the PSyIR.

Inheritance

begin_string()

Returns:: the beginning of the opening statement of this directive.
Return type:: str

end_string()

Returns:: the text for the end of this directive region.
Return type:: str

gen_code(_)

Raises:: InternalError – the ACC data directive is currently only supported for the NEMO API and that uses the PSyIR backend to generate code. fparser2 parse tree.

class psyclone.psyir.nodes.ACCEnterDataDirective(children=None, parent=None)

Class representing a “!$ACC enter data” OpenACC directive in an InvokeSchedule. Must be sub-classed for a particular API because the way in which fields are marked as being on the remote device is API-dependent.

Parameters:

children (List[psyclone.psyir.nodes.Node]) – list of nodes which the directive should have as children.
parent (psyclone.psyir.nodes.Node) – the node in the InvokeSchedule to which to add this directive as a child.

Inheritance

begin_string()

Returns the beginning statement of this directive. The visitor is responsible for adding the correct directive beginning (e.g. “!$”).

Returns:: the opening statement of this directive.
Return type:: str
Raises:: GenerationError – if there are no variables to copy to the device.

data_on_device(parent)

Adds nodes into an InvokeSchedule to flag that the data required by the kernels in the data region is now on the device. The generic implementation doesn’t add any node but this can be redefined in the APIs if any infrastructure call is needed.

Parameters:: parent (psyclone.psyir.nodes.Node) – the node in the InvokeSchedule to which to add nodes

gen_code(parent)

Generate the elements of the f2pygen AST for this Node in the Schedule.

Parameters:: parent (psyclone.f2pygen.BaseGen) – node in the f2pygen AST to which to add node(s).
Raises:: GenerationError – if no data is found to copy in.

lower_to_language_level()

In-place replacement of this directive concept into language level PSyIR constructs.

Returns:: the lowered version of this node.
Return type:: psyclone.psyir.node.Node

class psyclone.psyir.nodes.ACCParallelDirective(default_present=True, **kwargs)

Class representing the !$ACC PARALLEL directive of OpenACC in the PSyIR. By default it includes the ‘DEFAULT(PRESENT)’ clause which means this node must either come after an EnterDataDirective or within a DataDirective.

Parameters:: default_present (bool) – whether this directive includes the ‘DEFAULT(PRESENT)’ clause.

Inheritance

begin_string()

Returns the beginning statement of this directive, i.e. “acc parallel” plus any qualifiers. The backend is responsible for adding the correct characters to mark this as a directive (e.g. “!$”).

Returns:: the opening statement of this directive.
Return type:: str

property default_present

Returns:: whether the directive includes the ‘default(present)’ clause.
Return type:: bool

end_string()

Returns:: the closing statement for this directive.
Return type:: str

property fields

Returns a list of the names of field objects required by the Kernel call(s) that are children of this directive.

Returns:: list of names of field arguments.
Return type:: List[str]

gen_code(parent)

Generate the elements of the f2pygen AST for this Node in the Schedule.

Parameters:: parent (psyclone.f2pygen.BaseGen) – node in the f2pygen AST to which to add node(s).

class psyclone.psyir.nodes.ACCLoopDirective(collapse=None, independent=True, sequential=False, gang=False, vector=False, **kwargs)

Class managing the creation of a ‘!$acc loop’ OpenACC directive.

Parameters:

collapse (int) – Number of nested loops to collapse into a single iteration space or None.
independent (bool) – Whether or not to add the independent clause to the loop directive.
sequential (bool) – whether or not to add the seq clause to the loop directive.
gang (bool) – whether or not to add the gang clause to the loop directive.
vector (bool) – whether or not to add the vector clause to the loop directive.
kwargs (unwrapped dict.) – additional keyword arguments provided to the super class.

Inheritance

begin_string(leading_acc=True)

Returns the opening statement of this directive, i.e. “acc loop” plus any qualifiers. If leading_acc is False then the leading “acc loop” text is not included.

Parameters:: leading_acc (bool) – whether or not to include the leading “acc loop” in the text that is returned.
Returns:: the opening statement of this directive.
Return type:: str

property collapse

Returns:: the number of nested loops to collapse into a single iteration space for this node.
Return type:: int or None

end_string()

Would return the end string for this directive but “acc loop” doesn’t have a closing directive.

Returns:: empty string.
Return type:: str

property gang

Returns:: whether or not the gang clause is added to this loop directive.
Return type:: bool

gen_code(parent)

Generate the f2pygen AST entries in the Schedule for this OpenACC loop directive.

Parameters:: parent (sub-class of psyclone.f2pygen.BaseGen) – the parent Node in the Schedule to which to add our content.
Raises:: GenerationError – if this “!$acc loop” is not enclosed within an ACC Parallel region.

property independent

Returns whether the independent clause will be added to this loop directive.

Returns:: whether the independent clause will be added to this loop directive.
Return type:: bool

node_str(colour=True)

Returns the name of this node with (optional) control codes to generate coloured output in a terminal that supports it.

Parameters:: colour (bool) – whether or not to include colour control codes.
Returns:: description of this node, possibly coloured.
Return type:: str

property sequential

Returns:: whether or not the seq clause is added to this loop directive.
Return type:: bool

validate_global_constraints()

Perform validation of those global constraints that can only be done at code-generation time.

Raises:: GenerationError – if this ACCLoopDirective is not enclosed within some OpenACC parallel or kernels region and is not in a Routine that has been marked up with an ‘ACC Routine’ directive.

property vector

Returns:: whether or not the vector clause is added to this loop directive.
Return type:: bool

class psyclone.psyir.nodes.ACCKernelsDirective(children=None, parent=None, default_present=True)

Class representing the !$ACC KERNELS directive in the PSyIR.

Parameters:

children (List[psyclone.psyir.nodes.Node]) – the PSyIR nodes to be enclosed in the Kernels region and which are therefore children of this node.
parent (sub-class of psyclone.psyir.nodes.Node) – the parent of this node in the PSyIR.
default_present (bool) – whether or not to add the “default(present)” clause to the kernels directive.

Inheritance

begin_string()

Returns the beginning statement of this directive, i.e. “acc kernels …”. The backend is responsible for adding the correct directive beginning (e.g. “!$”).

Returns:: the beginning statement for this directive.
Return type:: str

property default_present

Returns:: whether the “default(present)” clause is added to the kernels directive.
Return type:: bool

end_string()

Returns the ending statement for this directive. The backend is responsible for adding the language-specific syntax that marks this as a directive.

Returns:: the closing statement for this directive.
Return type:: str

gen_code(parent)

Generate the f2pygen AST entries in the Schedule for this OpenACC Kernels directive.

Parameters:: parent (sub-class of psyclone.f2pygen.BaseGen) – the parent Node in the Schedule to which to add this content.

class psyclone.psyir.nodes.ACCUpdateDirective(signatures, direction, children=None, parent=None, if_present=True)

Class representing the OpenACC update directive in the PSyIR. It has a direction attribute that can be set to ‘self’, ‘host’ or ‘device’, the set of symbols being updated and an optional if_present clause.

Parameters:

signatures (Set[psyclone.core.Signature]) – the access signature(s) that need to be synchronised with the device.
direction (str) – the direction of the synchronisation.
children (List[psyclone.psyir.nodes.Node]) – list of nodes which the directive should have as children.
parent (psyclone.psyir.nodes.Node) – the node in the InvokeSchedule to which to add this directive as a child.
if_present (Optional[bool]) – whether or not to include the ‘if_present’ clause on the update directive (this instructs the directive to silently ignore any variables that are not on the device).

Inheritance

begin_string()

Returns the beginning statement of this directive, i.e. “acc update host(symbol)”. The backend is responsible for adding the correct characters to mark this as a directive (e.g. “!$”).

Returns:: the opening statement of this directive.
Return type:: str

property direction

Returns:: the direction of the synchronisation.
Return type:: str

property if_present

Returns:: whether or not to add the ‘if_present’ clause.
Return type:: bool

property sig_set

Returns:: the set of signatures to synchronise with the device.
Return type:: Set[psyclone.core.Signature]

class psyclone.psyir.nodes.ACCRoutineDirective(ast=None, children=None, parent=None, annotations=None)

Class representing a “!$ACC routine” OpenACC directive in PSyIR.

Inheritance

begin_string()

Returns the beginning statement of this directive, i.e. “acc routine”. The visitor is responsible for adding the correct directive beginning (e.g. “!$”).

Returns:: the opening statement of this directive.
Return type:: str

gen_code(parent)

Generate the fortran ACC Routine Directive and any associated code.

Parameters:: parent (sub-class of psyclone.f2pygen.BaseGen) – the parent Node in the Schedule to which to add our content.

class psyclone.psyir.nodes.ACCCopyClause(ast=None, children=None, parent=None, annotations=None)

OpenACC copy clause. Specifies a list of variables that are to be copied to the device at the start of the associated region and back to the host at the end.

Inheritance

class psyclone.psyir.nodes.ACCCopyInClause(ast=None, children=None, parent=None, annotations=None)

OpenACC copy clause. Specifies a list of variables that are to be copied to the device at the start of a region.

Inheritance

class psyclone.psyir.nodes.ACCCopyOutClause(ast=None, children=None, parent=None, annotations=None)

OpenACC copy clause. Specifies a list of variables that are to be copied from the device to the host at the end of the associated region.

Inheritance

class psyclone.psyir.nodes.OMPAtomicDirective(ast=None, children=None, parent=None)

OpenMP directive to represent that the memory accesses in the associated assignment must be performed atomically. Note that the standard supports blocks with 2 assignments but this is currently unsupported in the PSyIR.

Inheritance

begin_string()

Returns:: the opening string statement of this directive.
Return type:: str

end_string()

Returns:: the ending string statement of this directive.
Return type:: str

static is_valid_atomic_statement(stmt)

Check if a given statement is a valid OpenMP atomic expression. See: https://www.openmp.org/spec-html/5.0/openmpsu95.html

Parameters:: stmt (psyclone.psyir.nodes.Node) – a node to be validated.
Returns:: whether a given statement is compliant with the OpenMP atomic expression.
Return type:: bool

validate_global_constraints()

Perform validation of those global constraints that can only be done at code-generation time.

Raises:: GenerationError – if the OMPAtomicDirective associated statement does not conform to a valid OpenMP atomic operation.

class psyclone.psyir.nodes.OMPDirective

Base mixin class for all OpenMP-related directives.

This class is useful to provide a unique common ancestor to all the OpenMP directives, for instance when traversing the tree with node.walk(OMPDirective)

Note that classes inheriting from it must place the OMPDirective in front of the other Directive node sub-class, so that the Python MRO gives preference to this class’s attributes.

Inheritance

class psyclone.psyir.nodes.OMPRegionDirective(ast=None, children=None, parent=None)

Base class for all OpenMP region-related directives.

Inheritance

class psyclone.psyir.nodes.OMPStandaloneDirective(ast=None, children=None, parent=None, annotations=None)

Base class for all OpenMP-related standalone directives.

Inheritance

class psyclone.psyir.nodes.OMPParallelDirective(ast=None, children=None, parent=None)

Class representing an OpenMP Parallel directive.

Inheritance

begin_string()

Returns the beginning statement of this directive, i.e. “omp parallel”. The visitor is responsible for adding the correct directive beginning (e.g. “!$”).

Returns:: the opening statement of this directive.
Return type:: str

static create(children=None)

Create an OMPParallelDirective.

Parameters:: children (List of psyclone.psyir.nodes.Node) – The child nodes of the new directive.
Returns:: A new OMPParallelDirective.
Return type:: psyclone.psyir.nodes.OMPParallelDirective

property default_clause

Returns:: The OMPDefaultClause associated with this Directive.
Return type:: psyclone.psyir.nodes.OMPDefaultClause

end_string()

Returns the end (or closing) statement of this directive, i.e. “omp end parallel”. The visitor is responsible for adding the correct directive beginning (e.g. “!$”).

Returns:: the end statement for this directive.
Return type:: str

gen_code(parent)

Generate the fortran OMP Parallel Directive and any associated code.

Parameters:: parent (psyclone.f2pygen.BaseGen) – the node in the generated AST to which to add content.
Raises:: GenerationError – if the OpenMP directive needs some synchronisation mechanism to create valid code. These are not implemented yet.

infer_sharing_attributes()

The PSyIR does not specify if each symbol inside an OpenMP region is private, firstprivate, shared or shared but needs synchronisation, the attributes are inferred looking at the usage of each symbol inside the parallel region.

This method analyses the directive body and automatically classifies each symbol using the following rules: - All arrays are shared. - Scalars that are accessed only once are shared. - Scalars that are read-only or written outside a loop are shared. - Scalars written in multiple iterations of a loop are private, unless:

there is a write-after-read dependency in a loop iteration, in this case they are shared but need synchronisation;

they are read before in the same parallel region (but not inside the same loop iteration), in this case they are firstprivate.

they are only conditionally written in some iterations; in this case they are firstprivate.

This method returns the sets of private, firstprivate, and shared but needing synchronisation symbols, all symbols not in these sets are assumed shared. How to synchronise the symbols in the third set is up to the caller of this method.

Returns:: three set of symbols that classify each of the symbols in the directive body as PRIVATE, FIRSTPRIVATE or SHARED NEEDING SYNCHRONISATION.
Return type:: Tuple[Set(psyclone.psyir.symbols.Symbol), Set(psyclone.psyir.symbols.Symbol), Set(psyclone.psyir.symbols.Symbol)]
Raises:: GenerationError – if the DefaultClauseType associated with this OMPParallelDirective is not shared.

lower_to_language_level()

In-place construction of clauses as PSyIR constructs. At the higher level these clauses rely on dynamic variable dependence logic to decide what is private and what is shared, so we use this lowering step to find out which References are private, and place them explicitly in the lower-level tree to be processed by the backend visitor.

Returns:: the lowered version of this node.
Return type:: psyclone.psyir.node.Node
Raises:: GenerationError – if the OpenMP directive needs some synchronisation mechanism to create valid code. These are not implemented yet.

property private_clause

Returns:: The current OMPPrivateClause associated with this Directive.
Return type:: psyclone.psyir.nodes.OMPPrivateClause

validate_global_constraints()

Perform validation checks that can only be done at code-generation time.

Raises:: GenerationError – if this OMPDoDirective is not enclosed within some OpenMP parallel region.

class psyclone.psyir.nodes.OMPSerialDirective(ast=None, children=None, parent=None)

Abstract class representing OpenMP serial regions, e.g. OpenMP SINGLE or OpenMP Master.

Inheritance

lower_to_language_level(): Checks that any task dependencies inside this node are valid.

validate_global_constraints()

Perform validation checks that can only be done at code-generation time.

Raises:

GenerationError – if this OMPSerial is not enclosed within some OpenMP parallel region.
GenerationError – if this OMPSerial is enclosed within any OMPSerialDirective subclass region.

class psyclone.psyir.nodes.OMPSingleDirective(nowait=False, **kwargs)

Class representing an OpenMP SINGLE directive in the PSyIR.

Parameters:

nowait (bool) – argument describing whether this single should have a nowait clause applied. Default value is False.
kwargs (unwrapped dict.) – additional keyword arguments provided to the PSyIR node.

Inheritance

begin_string()

Returns the beginning statement of this directive, i.e. “omp single”. The visitor is responsible for adding the correct directive beginning (e.g. “!$”).

Returns:: the opening statement of this directive.
Return type:: str

end_string()

Returns the end (or closing) statement of this directive, i.e. “omp end single”. The visitor is responsible for adding the correct directive beginning (e.g. “!$”).

Returns:: the end statement for this directive.
Return type:: str

gen_code(parent)

Generate the fortran OMP Single Directive and any associated code

Parameters:: parent (sub-class of psyclone.f2pygen.BaseGen) – the parent Node in the Schedule to which to add our content.

property nowait

Returns:: whether the nowait clause is specified for this directive.
Return type:: bool

class psyclone.psyir.nodes.OMPMasterDirective(ast=None, children=None, parent=None)

Class representing an OpenMP MASTER directive in the PSyclone AST.

Inheritance

begin_string()

Returns the beginning statement of this directive, i.e. “omp master”. The visitor is responsible for adding the correct directive beginning (e.g. “!$”).

Returns:: the opening statement of this directive.
Return type:: str

end_string()

Returns the end (or closing) statement of this directive, i.e. “omp end master”. The visitor is responsible for adding the correct directive beginning (e.g. “!$”).

Returns:: the end statement for this directive.
Return type:: str

gen_code(parent)

Generate the Fortran OMP Master Directive and any associated code

Parameters:: parent (sub-class of psyclone.f2pygen.BaseGen) – the parent Node in the Schedule to which to add our content.

class psyclone.psyir.nodes.OMPTaskloopDirective(grainsize=None, num_tasks=None, nogroup=False, **kwargs)

Class representing an OpenMP TASKLOOP directive in the PSyIR.

Parameters:

grainsize (int or None.) – The grainsize value used to specify the grainsize clause on this OpenMP directive. If this is None the grainsize clause is not applied. Default value is None.
num_tasks (int or None.) – The num_tasks value used to specify the num_tasks clause on this OpenMP directive. If this is None the num_tasks clause is not applied. Default value is None.
nogroup (bool) – Whether the nogroup clause should be used for this node. Default value is False
kwargs (unwrapped dict.) – additional keyword arguments provided to the PSyIR node.

Raises:

GenerationError – if this OMPTaskloopDirective has both a grainsize and num_tasks value specified.

Inheritance

begin_string()

Returns the beginning statement of this directive, i.e. “omp taskloop …”. The visitor is responsible for adding the correct directive beginning (e.g. “!$”).

Returns:: the beginning statement for this directive.
Return type:: str

end_string()

Returns the end (or closing) statement of this directive, i.e. “omp end taskloop”. The visitor is responsible for adding the correct directive beginning (e.g. “!$”).

Returns:: the end statement for this directive.
Return type:: str

gen_code(parent)

Generate the f2pygen AST entries in the Schedule for this OpenMP taskloop directive.

Parameters:: parent (sub-class of psyclone.f2pygen.BaseGen) – the parent Node in the Schedule to which to add our content.
Raises:: GenerationError – if this “!$omp taskloop” is not enclosed within an OMP Parallel region and an OMP Serial region.

property nogroup

Returns:: the nogroup clause status of this node.
Return type:: bool

validate_global_constraints()

Perform validation checks that can only be done at code-generation time.

Raises:

GenerationError – if this OMPTaskloopDirective is not enclosed within an OpenMP serial region.
GenerationError – if this OMPTaskloopDirective has two Nogroup clauses as children.

class psyclone.psyir.nodes.OMPTaskDirective(children=None, parent=None, clauses=None)

Class representing an OpenMP TASK directive in the PSyIR after lowering. This node should not be created by any transformation, it is solely used to represent TASK directives after lowering a DynamicOMPTaskDirective.

Parameters:

children (List[psyclone.psyir.nodes.Node]) – list of Nodes that are children of this Node.
parent (psyclone.psyir.nodes.Node) – the Node in the AST that has this directive as a child
clauses (Optional[List[psyclone.psyir.nodes.Clause]]) – optional list of clauses to be added to this Node.

Inheritance

begin_string()

Returns the beginning statement of this directive, i.e. “omp task …”. The visitor is responsible for adding the correct directive beginning (e.g. “!$”).

Returns:: the beginning statement for this directive.
Return type:: str

end_string()

Returns the end (or closing) statement of this directive, i.e. “omp end task”. The visitor is responsible for adding the correct directive beginning (e.g. “!$”).

Returns:: the end statement for this directive.
Return type:: str

property input_depend_clause

Returns:: the OMPDependClause child of this node corresponding to input dependencies.
Return type:: psyclones.psyir.nodes.OMPDependClause

property output_depend_clause

Returns:: the OMPDependClause child of this node corresponding to output dependencies.
Return type:: psyclones.psyir.nodes.OMPDependClause

validate_global_constraints()

Perform validation checks that can only be done at code-generation time.

Raises:: GenerationError – if this OMPTaskDirective is not enclosed within an OpenMP serial region.

class psyclone.psyir.nodes.DynamicOMPTaskDirective(children=None, parent=None)

Class representing an OpenMP TASK directive in the PSyIR.

Parameters:

children (list) – list of Nodes that are children of this Node.
parent (psyclone.psyir.nodes.Node) – the Node in the AST that has this directive as a child

Inheritance

lower_to_language_level(): Lowers the structure of the PSyIR tree inside the Directive to generate the Clauses that are required for this Directive.

class psyclone.psyir.nodes.OMPDoDirective(omp_schedule='none', collapse=None, reprod=None, **kwargs)

Class representing an OpenMP DO directive in the PSyIR.

Parameters:

omp_schedule (str) – the OpenMP schedule to use (defaults to “none” which means it is implementation dependent).
collapse (Optional[int]) – optional number of nested loops to collapse into a single iteration space to parallelise. Defaults to None.
reprod (Optional[bool]) – whether or not to generate code for run-reproducible OpenMP reductions (if not specified the value is provided by the PSyclone Config file).
kwargs (unwrapped dict.) – additional keyword arguments provided to the PSyIR node.

Inheritance

begin_string()

Returns the beginning statement of this directive, i.e. “omp do …”. The visitor is responsible for adding the correct directive beginning (e.g. “!$”).

Returns:: the beginning statement for this directive.
Return type:: str

property collapse

Returns:: the value of the collapse clause.
Return type:: int or NoneType

end_string()

Returns the end (or closing) statement of this directive, i.e. “omp end do”. The visitor is responsible for adding the correct directive beginning (e.g. “!$”).

Returns:: the end statement for this directive.
Return type:: str

gen_code(parent)

Generate the f2pygen AST entries in the Schedule for this OpenMP do directive.

TODO #1648: Note that gen_code ignores the collapse clause but the generated code is still valid. Since gen_code is going to be removed and it is only used for LFRic (which does not support GPU offloading that gets improved with the collapse clause) it will not be supported.

Parameters:: parent (sub-class of psyclone.f2pygen.BaseGen) – the parent Node in the Schedule to which to add our content.
Raises:: GenerationError – if this “!$omp do” is not enclosed within an OMP Parallel region.

node_str(colour=True)

Returns the name of this node with (optional) control codes to generate coloured output in a terminal that supports it.

Parameters:: colour (bool) – whether or not to include colour control codes.
Returns:: description of this node, possibly coloured.
Return type:: str

property omp_schedule

Returns:: the omp_schedule for this object.
Return type:: str

property reprod

Returns:: whether reprod has been set for this object or not.

validate_global_constraints()

Perform validation checks that can only be done at code-generation time.

Raises:: GenerationError – if this OMPDoDirective is not enclosed within some OpenMP parallel region.

class psyclone.psyir.nodes.OMPParallelDoDirective(**kwargs)

Class for the !$OMP PARALLEL DO directive. This inherits from both OMPParallelDirective (because it creates a new OpenMP thread-parallel region) and OMPDoDirective (because it causes a loop to be parallelised).

Parameters:: kwargs (unwrapped dict.) – additional keyword arguments provided to the PSyIR node.

Inheritance

begin_string()

Returns the beginning statement of this directive, i.e. “omp parallel do …”. The visitor is responsible for adding the correct directive beginning (e.g. “!$”).

Returns:: the beginning statement for this directive.
Return type:: str

end_string()

Returns the end (or closing) statement of this directive, i.e. “omp end parallel do”. The visitor is responsible for adding the correct directive beginning (e.g. “!$”).

Returns:: the end statement for this directive.
Return type:: str

gen_code(parent)

Generate the f2pygen AST entries in the Schedule for this OpenMP directive.

TODO #1648: Note that gen_code ignores the collapse clause but the generated code is still valid. Since gen_code is going to be removed and it is only used for LFRic (which does not support GPU offloading that gets improved with the collapse clause) it will not be supported.

Parameters:: parent (sub-class of psyclone.f2pygen.BaseGen) – the parent Node in the Schedule to which to add our content.

lower_to_language_level()

In-place construction of clauses as PSyIR constructs. The clauses here may need to be updated if code has changed, or be added if not yet present.

Returns:: the lowered version of this node.
Return type:: psyclone.psyir.node.Node

validate_global_constraints(): Perform validation checks that can only be done at code-generation time.

class psyclone.psyir.nodes.OMPTaskwaitDirective(ast=None, children=None, parent=None, annotations=None)

Class representing an OpenMP TASKWAIT directive in the PSyIR.

Inheritance

begin_string()

Returns the beginning statement of this directive, i.e. “omp taskwait”. The visitor is responsible for adding the correct directive beginning (e.g. “!$”).

Returns:: the opening statement of this directive.
Return type:: str

gen_code(parent)

Generate the fortran OMP Taskwait Directive and any associated code

Parameters:: parent (sub-class of psyclone.f2pygen.BaseGen) – the parent Node in the Schedule to which to add our content.

validate_global_constraints()

Perform validation checks that can only be done at code-generation time.

Raises:: GenerationError – if this OMPTaskwait is not enclosed within some OpenMP parallel region.

class psyclone.psyir.nodes.OMPTargetDirective(ast=None, children=None, parent=None)

Class for the !$OMP TARGET directive that offloads the code contained in its region into an accelerator device.

Inheritance

begin_string()

Returns the beginning statement of this directive, i.e. “omp target”. The visitor is responsible for adding the correct directive beginning (e.g. “!$”).

Returns:: the opening statement of this directive.
Return type:: str

end_string()

Returns the end (or closing) statement of this directive, i.e. “omp end target”. The visitor is responsible for adding the correct directive beginning (e.g. “!$”).

Returns:: the end statement for this directive.
Return type:: str

class psyclone.psyir.nodes.OMPLoopDirective(collapse=None, **kwargs)

Class for the !$OMP LOOP directive that specifies that the iterations of the associated loops may execute concurrently.

Parameters:

collapse (Optional[int]) – optional number of nested loops to collapse into a single iteration space to parallelise. Defaults to None.
kwargs (unwrapped dict.) – additional keyword arguments provided to the PSyIR node.

Inheritance

begin_string()

Returns the beginning statement of this directive, i.e. “omp loop”. The visitor is responsible for adding the correct directive beginning (e.g. “!$”).

Returns:: the opening statement of this directive.
Return type:: str

property collapse

Returns:: the value of the collapse clause.
Return type:: int or NoneType

end_string()

Returns the end (or closing) statement of this directive, i.e. “omp end loop”. The visitor is responsible for adding the correct directive beginning (e.g. “!$”).

Returns:: the end statement for this directive.
Return type:: str

node_str(colour=True)

Returns the name of this node with (optional) control codes to generate coloured output in a terminal that supports it.

Parameters:: colour (bool) – whether or not to include colour control codes.
Returns:: description of this node, possibly coloured.
Return type:: str

validate_global_constraints()

Perform validation of those global constraints that can only be done at code-generation time.

Raises:

GenerationError – if this OMPLoopDirective has more than one child in its associated schedule.
GenerationError – if the schedule associated with this OMPLoopDirective does not contain a Loop.
GenerationError – this directive must be inside a omp target or parallel region.
GenerationError – if this OMPLoopDirective has a collapse clause but it doesn’t have the expected number of nested Loops.

class psyclone.psyir.nodes.OMPDeclareTargetDirective(ast=None, children=None, parent=None, annotations=None)

Class representing an OpenMP Declare Target directive in the PSyIR.

Inheritance

begin_string()

Returns the beginning statement of this directive, i.e. “omp routine”. The visitor is responsible for adding the correct directive beginning (e.g. “!$”).

Returns:: the opening statement of this directive.
Return type:: str

gen_code(parent)

Generate the fortran OMP Declare Target Directive and any associated code.

Parameters:: parent (sub-class of psyclone.f2pygen.BaseGen) – the parent Node in the Schedule to which to add our content.

validate_global_constraints()

Perform validation checks that can only be done at code-generation time.

Raises:: GenerationError – if this directive is not the first statement in a routine.

class psyclone.psyir.nodes.OMPSimdDirective(ast=None, children=None, parent=None)

OpenMP directive to inform that the associated loop can be vectorised.

Inheritance

begin_string()

Returns:: the opening string statement of this directive.
Return type:: str

end_string()

Returns:: the ending string statement of this directive.
Return type:: str

validate_global_constraints()

Perform validation of those global constraints that can only be done at code-generation time.

Raises:: GenerationError – if the OMPSimdDirective does not contain precisely one loop.

class psyclone.psyir.nodes.OMPTeamsDistributeParallelDoDirective(**kwargs)

Class representing the OMP teams distribute parallel do directive.

Inheritance

class psyclone.psyir.nodes.OMPGrainsizeClause(ast=None, children=None, parent=None, annotations=None)

OpenMP grainsize clause, used by OMPTaskloopDirective. Controls the grainsize of the associated directive.

Inheritance

class psyclone.psyir.nodes.OMPNogroupClause(ast=None, children=None, parent=None, annotations=None)

OpenMP nogroup clause, used by OMPTaskloopDirective to disable the implicit Taskgroup associated with a Taskloop.

Inheritance

class psyclone.psyir.nodes.OMPNowaitClause(ast=None, children=None, parent=None, annotations=None)

OpenMP nowait clause. Disable the implicit barrier at the end of the associated directive.

Inheritance

class psyclone.psyir.nodes.OMPNumTasksClause(ast=None, children=None, parent=None, annotations=None)

OpenMP numtasks clause, used by OMPTaskloopDirective. Controls the number of tasks created by OpenMP for the associated directive.

Inheritance

class psyclone.psyir.nodes.OMPPrivateClause(ast=None, children=None, parent=None, annotations=None)

OpenMP private clause. This is used to declare variables as private to an OpenMP region.

Inheritance

static create(symbols)

Create a OMPPrivateClause containing a Reference to each of the provided symbols as children.

Parameters:: symbols (List[psyclone.psyir.symbols.Symbol]) – List of symbols to reference in the private clause.
Returns:: A OMPPrivateClause referencing the provided symbols.
Return type:: py:class:psyclone.psyir.nodes.OMPPrivateClause
Raises:: TypeError – If the symbols argument is not a List that contains only PSyIR Symbols.

class psyclone.psyir.nodes.OMPDefaultClause(clause_type=DefaultClauseTypes.SHARED, **kwargs)

OpenMP Default clause. Used to determine the default declaration for variables used in an OpenMP region.

Parameters:

clause_type (psyclone.psyir.nodes.OMPDefaultClause.DefaultClauseTypes) – The default data-sharing attribute to be described by this clause. The default value is OMPDefaultClause.DefaultClauseTypes.SHARED.
kwargs (unwrapped dict.) – additional keyword arguments provided to the PSyIR node.

Raises:

TypeError – if the supplied clause_type is not the correct type.

Inheritance

class DefaultClauseTypes(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None): Enumeration of the different types of OMPDefaultClause supported in PSyclone.

property clause_type

Gets the clause type value of this OMPDefaultClause

Returns:: the clause type for this OMPDefaultClause.
Return type:: psyclone.psyir.nodes.OMPDefaultClause. DefaultClauseTypes

node_str(colour=True)

Parameters:: colour (bool) – whether or not to include control codes for coloured text.
Returns:: a text description of this node.
Return type:: str

class psyclone.psyir.nodes.OMPReductionClause(ast=None, children=None, parent=None, annotations=None)

OpenMP Reduction clause.

Inheritance

class psyclone.psyir.nodes.OMPScheduleClause(schedule='none', **kwargs)

OpenMP Schedule clause used for OMP Do Directives.

Parameters:

schedule (str) – The OpenMP schedule to use with this directive. The default value is “none” which means that no explicit schedule is specified.
kwargs (unwrapped dict.) – additional keyword arguments provided to the PSyIR node.

Inheritance

node_str(colour=True)

Parameters:: colour (bool) – whether or not to include control codes for coloured text.
Returns:: a text description of this node.
Return type:: str

property schedule

Returns:: the schedule for this OMPScheduleClause.
Return type:: str

class psyclone.psyir.nodes.OMPFirstprivateClause(ast=None, children=None, parent=None, annotations=None)

OpenMP firstprivate clause. This is used to declare variables as firstprivate to an OpenMP region.

Inheritance

static create(symbols)

Create an OMPFirstprivateClause containing a Reference to each of the provided symbols as children.

Parameters:: symbols (List[psyclone.psyir.symbols.Symbol]) – List of symbols to reference in the firstprivate clause.
Returns:: A OMPFirstprivateClause referencing the provided symbols.
Return type:: py:class:psyclone.psyir.nodes.OMPFirstprivateClause
Raises:: TypeError – If the symbols argument is not a List that contains only PSyIR Symbols.

class psyclone.psyir.nodes.OMPSharedClause(ast=None, children=None, parent=None, annotations=None)

OpenMP shared clause. This is used to declare variables as shared in an OpenMP region.

Inheritance

class psyclone.psyir.nodes.OMPDependClause(depend_type=DependClauseTypes.INOUT, **kwargs)

OpenMP Depend clause used for OpenMP Task directives.

Parameters:

depend_type (psyclone.psyir.nodes.OMPDependClause.DependClauseTypes) – The dependency type to use for this clause. The default value is OMPDependClause.DependClauseTypes.INOUT.
kwargs (unwrapped dict.) – additional keyword arguments provided to the PSyIR node.

Raises:

TypeError – if the supplied depend_type argument is the wrong type.

Inheritance

class DependClauseTypes(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None): Enumeration of the different types of OMPDependClause supported in PSyclone.

node_str(colour=True)

Parameters:: colour (bool) – whether or not to include control codes for coloured text.
Returns:: a text description of this node.
Return type:: str

property operand

Returns:: the string representation of the operand of this clause.
Return type:: str

psyclone.psyir.nodes

Submodules

Functions

Classes

`psyclone.psyir.nodes`

Submodules 

Functions 

Classes 