psyclone.psyir.nodes.omp_directives
This module contains the implementation of the various OpenMP Directive nodes.
Classes
OMPRegionDirective: Base class for all OpenMP region-related directives.OMPParallelDirective: Class representing an OpenMP Parallel directive.OMPSingleDirective: Class representing an OpenMP SINGLE directive in the PSyIR.OMPMasterDirective: Class representing an OpenMP MASTER directive in the PSyclone AST.OMPDoDirective: Class representing an OpenMP DO directive in the PSyIR.OMPParallelDoDirective: Class for the !$OMP PARALLEL DO directive. This inherits fromOMPSerialDirective: Abstract class representing OpenMP serial regions, e.g.OMPTaskloopDirective: Class representing an OpenMP TASKLOOP directive in the PSyIR.OMPTargetDirective: Class for the !$OMP TARGET directive that offloads the code containedOMPTaskwaitDirective: Class representing an OpenMP TASKWAIT directive in the PSyIR.OMPDirective: Base mixin class for all OpenMP-related directives.OMPStandaloneDirective: Base class for all OpenMP-related standalone directives.OMPLoopDirective: Class for the !$OMP LOOP directive that specifies that the iterationsOMPDeclareTargetDirective: Class representing an OpenMP Declare Target directive in the PSyIR.OMPAtomicDirective: OpenMP directive to represent that the memory accesses in the associatedOMPSimdDirective: OpenMP directive to inform that the associated loop can be vectorised.
- class psyclone.psyir.nodes.omp_directives.OMPRegionDirective(ast=None, children=None, parent=None)
Base class for all OpenMP region-related directives.
Inheritance
- class psyclone.psyir.nodes.omp_directives.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:
- property default_clause
- Returns:
The OMPDefaultClause associated with this Directive.
- Return type:
- 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:
- 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.omp_directives.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.omp_directives.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.omp_directives.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.omp_directives.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.omp_directives.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.omp_directives.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.omp_directives.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.omp_directives.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.omp_directives.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.omp_directives.OMPStandaloneDirective(ast=None, children=None, parent=None, annotations=None)
Base class for all OpenMP-related standalone directives.
Inheritance
- class psyclone.psyir.nodes.omp_directives.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.omp_directives.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.omp_directives.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
- 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.omp_directives.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.