psyclone.gocean1p0
This module implements the PSyclone GOcean 1.0 API by specialising the required base classes for both code generation (PSy, Invokes, Invoke, InvokeSchedule, Loop, Kern, Arguments and KernelArgument) and parsing (Descriptor and KernelType). It adds a GOKernelGridArgument class to capture information on kernel arguments that supply properties of the grid (and are generated in the PSy layer).
Classes
GOPSy
: The GOcean 1.0 specific PSy class. This creates a GOcean specificGOInvokes
: The GOcean specific invokes class. This passes the GOcean specificGOInvoke
: The GOcean specific invoke class. This passes the GOcean specificGOInvokeSchedule
: The GOcean specific InvokeSchedule sub-class. We call the base classGOLoop
: The GOcean specific PSyLoop class. This passes the GOcean specificGOBuiltInCallFactory
: A GOcean-specific built-in call factory. No built-insGOKernCallFactory
: A GOcean-specific kernel-call factory. A standard kernel call inGOKern
: Stores information about GOcean Kernels as specified by the KernelGOKernelArguments
: Provides information about GOcean kernel-call argumentsGOKernelArgument
: Provides information about individual GOcean kernel call argumentsGOKernelGridArgument
: Describes arguments that supply grid properties to a kernel.GOStencil
: GOcean 1.0 stencil information for a kernel argument as obtained byGO1p0Descriptor
: Description of a GOcean 1.0 kernel argument, as obtained byGOKernelType1p0
: Description of a kernel including the grid index-offset itGOACCEnterDataDirective
: Sub-classes ACCEnterDataDirective to provide the dl_esm_inf infrastructure-GOKernelSchedule
: Sub-classes KernelSchedule to provide a GOcean-specific implementation.GOHaloExchange
: GOcean specific halo exchange class which can be added to and
- class psyclone.gocean1p0.GOPSy(invoke_info)
The GOcean 1.0 specific PSy class. This creates a GOcean specific invokes object (which controls all the required invocation calls). Also overrides the PSy gen method so that we generate GOcean- specific PSy module code.
- Parameters:
invoke_info (
psyclone.parse.FileInfo
) – An object containing the required invocation information for code optimisation and generation.
Inheritance
- property gen
Generate PSy code for the GOcean api v.1.0.
- Return type:
ast
- class psyclone.gocean1p0.GOInvokes(alg_calls, psy)
The GOcean specific invokes class. This passes the GOcean specific invoke class to the base class so it creates the one we require.
- Parameters:
alg_calls (OrderedDict of
psyclone.parse.InvokeCall
objects.) – The Invoke calls discovered in the Algorithm layer.psy (
psyclone.gocean1p0.GOPSy
) – the PSy object containing this GOInvokes object.
Inheritance
- gen_code(parent)
GOcean redefines the Invokes.gen_code() to start using the PSyIR backend when possible. In cases where the backend can not be used yet (e.g. OpenCL and PSyDataNodes) the parent class will be called. This is a temporary workaround to avoid modifying the generator file while other APIs still use the f2pygen module for code generation. Once the PSyIR backend has generated an output, this is added into a f2pygen PSyIRGen block in the f2pygen AST for each Invoke in the PSy layer.
- Parameters:
parent (psyclone.f2pygen.ModuleGen) – the parent node in the f2pygen AST to which to add content.
- class psyclone.gocean1p0.GOInvoke(alg_invocation, idx, invokes)
The GOcean specific invoke class. This passes the GOcean specific schedule class to the base class so it creates the one we require. A set of GOcean infrastructure reserved names are also passed to ensure that there are no name clashes. Also overrides the gen_code method so that we generate GOcean specific invocation code and provides three methods which separate arguments that are arrays from arguments that are {integer, real} scalars.
- Parameters:
alg_invocation (
psyclone.parse.InvokeCall
) – Node in the AST describing the invoke call.idx (int) – The position of the invoke in the list of invokes contained in the Algorithm.
invokes (
psyclone.gocean1p0.GOInvokes
) – the Invokes object containing this GOInvoke object.
Inheritance
- gen_code(parent)
Generates GOcean specific invocation code (the subroutine called by the associated invoke call in the algorithm layer). This consists of the PSy invocation subroutine and the declaration of its arguments.
- Parameters:
parent (
psyclone.f2pygen.ModuleGen
) – the node in the generated AST to which to add content.
- property unique_args_arrays
find unique arguments that are arrays (defined as those that are field objects as opposed to scalars or properties of the grid).
- property unique_args_iscalars
- Returns:
the unique arguments that are scalars of type integer (defined as those that are i_scalar ‘space’).
- Return type:
list of str.
- class psyclone.gocean1p0.GOInvokeSchedule(name, alg_calls, reserved_names=None, parent=None)
The GOcean specific InvokeSchedule sub-class. We call the base class constructor and pass it factories to create GO-specific calls to both user-supplied kernels and built-ins.
- Parameters:
name (str) – name of the Invoke.
alg_calls (list of
psyclone.parse.algorithm.KernelCall
) – list of KernelCalls parsed from the algorithm layer.reserved_names (list of str) – optional list of names that are not allowed in the new InvokeSchedule SymbolTable.
parent (
psyclone.psyir.nodes.Node
) – the parent of this node in the PSyIR.
Inheritance
- class psyclone.gocean1p0.GOLoop(parent, loop_type='', field_name='', field_space='', iteration_space='', index_offset='')
The GOcean specific PSyLoop class. This passes the GOcean specific single loop information to the base class so it creates the one we require. Adds a GOcean specific setBounds method which tells the loop what to iterate over. Need to harmonise with the topology_name method in the Dynamo api.
- Parameters:
parent (
psyclone.psyir.nodes.Node
) – optional parent node (default None).loop_type (str) – loop type - must be ‘inner’ or ‘outer’.
field_name (str) – name of the field this loop iterates on.
field_space (str) – space of the field this loop iterates on.
iteration_space (str) – iteration space of the loop.
- Raises:
GenerationError – if the loop is not inserted inside a GOInvokeSchedule region.
Inheritance
- static add_bounds(bound_info)
Adds a new iteration space to PSyclone. An iteration space in the gocean1.0 API is for a certain offset type and field type. It defines the loop boundaries for the outer and inner loop. The format is a “:” separated tuple:
>>> bound_info = offset-type:field-type:iteration-space:outer-start: outer-stop:inner-start:inner-stop
Example:
>>> bound_info = go_offset_ne:go_ct:go_all_pts: {start}-1:{stop}+1:{start}:{stop}
The expressions {start} and {stop} will be replaced with the loop indices that correspond to the inner points (i.e. non-halo or boundary points) of the field. So the index {start}-1 is actually on the halo / boundary.
- Parameters:
bound_info (str) – A string that contains a “:” separated tuple with the iteration space definition.
- Raises:
ValueError – if bound_info is not a string.
ConfigurationError – if bound_info is not formatted correctly.
- property bounds_lookup
- Returns:
the GOcean loop bounds lookup table. This is a 5-dimensional dictionary with index-offset, field-space, iteration-space, loop-type, and boundary-side lookup keys which provides information about how to construct the loop boundaries for a kernel with such parameters.
- Return type:
dict
- static create(parent, loop_type, field_name='', field_space='', iteration_space='', index_offset='')
Create a new instance of a GOLoop with the expected children to represent the bounds given by the loop properties.
- Parameters:
parent (
psyclone.psyir.nodes.Node
) – parent node of this GOLoop.loop_type (str) – loop type - must be ‘inner’ or ‘outer’.
field_name (str) – name of the field this loop iterates on.
field_space (str) – space of the field this loop iterates on.
iteration_space (str) – iteration space of the loop.
index_offset (str) – the grid index offset used by the kernel(s) within this loop.
- Returns:
a new GOLoop node (with appropriate child nodes).
- Return type:
- create_halo_exchanges()
Add halo exchanges before this loop as required by fields within this loop. The PSyIR insertion logic is coded in the _add_halo_exchange helper method.
- property field_space
- Returns:
the loop’s field space (e.g. CU, CV…).
- Return type:
str
- gen_code(parent)
Create the f2pygen AST for this loop (and update the PSyIR representing the loop bounds if necessary).
- Parameters:
parent (
psyclone.f2pygen.SubroutineGen
) – the node in the f2pygen AST to which to add content.
- get_custom_bound_string(side)
Get the string that represents a customized custom bound for this GOLoop (provided by the add_bounds() method). It can provide the ‘start’ or ‘stop’ side of the bounds.
- Parameters:
side (str) – ‘start’ or ‘stop’ side of the bound.
- Returns:
the string that represents the loop bound.
- Return type:
str
- Raises:
GenerationError – if this node can not find a field in the Invoke to be the base of the infrastructure call.
GenerationError – if no expression is known to obtain the boundaries for a loop of this characteristics, because they are not in the GOcean lookup table or the loop type is not inner or outer.
- independent_iterations(test_all_variables=False, signatures_to_ignore=None, dep_tools=None)
This function is a GOcean-specific override of the default method in the Loop class. It allows domain-specific rules to be applied when determining whether or not loop 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 iteration_space
- Returns:
the loop’s iteration space (e.g. ‘go_internal_pts’, ‘go_all_pts’, …).
- Return type:
str
- lower_bound()
Returns the lower bound of this loop as a string.
- Returns:
root of PSyIR sub-tree describing this lower bound.
- Return type:
- static setup_bounds()
Populates the GOLoop._bounds_lookup dictionary. This is used by PSyclone to look up the loop boundaries for each loop it creates.
- upper_bound()
Creates the PSyIR of the upper bound of this loop.
- Returns:
the PSyIR for the upper bound of this loop.
- Return type:
- class psyclone.gocean1p0.GOBuiltInCallFactory
A GOcean-specific built-in call factory. No built-ins are supported in GOcean at the moment.
Inheritance
- static create()
Placeholder to create a GOocean-specific built-in call. This will require us to create a doubly-nested loop and then create the body of the particular built-in operation.
- class psyclone.gocean1p0.GOKernCallFactory
A GOcean-specific kernel-call factory. A standard kernel call in GOcean consists of a doubly-nested loop (over i and j) and a call to the user-supplied kernel routine.
Inheritance
- static create(call, parent=None)
Create a new instance of a call to a GO kernel. Includes the looping structure as well as the call to the kernel itself.
- Parameters:
parent (
psyclone.psyir.nodes.Node
) – node where the kernel call structure will be inserted.- Returns:
new PSyIR tree representing the kernel call loop.
- Return type:
- class psyclone.gocean1p0.GOKern(call, parent=None)
Stores information about GOcean Kernels as specified by the Kernel metadata. Uses this information to generate appropriate PSy layer code for the Kernel instance. Specialises the gen_code method to create the appropriate GOcean specific kernel call.
- Parameters:
call (
psyclone.parse.algorithm.KernelCall
) – information on the way in which this kernel is called from the Algorithm layer.parent (
psyclone.psyir.nodes.Node
) – optional node where the kernel call will be inserted.
Inheritance
- get_kernel_schedule()
- Returns:
a schedule representing the GOcean kernel code.
- Return type:
- Raises:
GenerationError – if there is a problem raising the language- level PSyIR of this kernel to GOcean PSyIR.
- property index_offset
The grid index-offset convention that this kernel expects
- local_vars()
Return a list of the variable (names) that are local to this loop (and must therefore be e.g. threadprivate if doing OpenMP)
- reference_accesses(var_accesses)
Get all variable access information. All accesses are marked according to the kernel metadata.
- Parameters:
var_accesses (
psyclone.core.VariablesAccessInfo
) – VariablesAccessInfo instance that stores the information about variable accesses.
- class psyclone.gocean1p0.GOKernelArguments(call, parent_call, check=True)
Provides information about GOcean kernel-call arguments collectively, as specified by the kernel argument metadata. This class ensures that initialisation is performed correctly. It also overrides the iteration_space_arg method to supply a GOcean-specific dictionary for the mapping of argument-access types.
- Parameters:
call (
psyclone.parse.KernelCall
) – the kernel meta-data for which to extract argument info.parent_call (
psyclone.gocean1p0.GOKern
) – the kernel-call object.check (bool) – whether to check for consistency between the kernel metadata and the algorithm layer. Defaults to True. Currently does nothing in this API.
Inheritance
- property acc_args
Provide the list of references (both objects and arrays) that must be present on an OpenACC device before the kernel associated with this Arguments object may be launched.
- Returns:
list of (Fortran) quantities
- Return type:
list of str
- append(name, argument_type)
Create and append a GOKernelArgument to the Argument list.
- Parameters:
name (str) – name of the appended argument.
argument_type (str) – type of the appended argument.
- Raises:
TypeError – if the given name is not a string.
- property dofs
Currently required for invoke base class although this makes no sense for GOcean. Need to refactor the Invoke base class and remove the need for this property (#279).
- property fields
Provides the list of names of field objects that are required by the kernel associated with this Arguments object.
- Returns:
List of names of (Fortran) field objects.
- Return type:
list of str
- find_grid_access()
Determine the best kernel argument from which to get properties of the grid. For this, an argument must be a field (i.e. not a scalar) and must be supplied by the algorithm layer (i.e. not a grid property). If possible it should also be a field that is read-only as otherwise compilers can get confused about data dependencies and refuse to SIMD vectorise. :returns: the argument object from which to get grid properties. :rtype:
psyclone.gocean1p0.GOKernelArgument
or None
- psyir_expressions()
- Returns:
the PSyIR expressions representing this Argument list.
- Return type:
list of
psyclone.psyir.nodes.Node
- property scalars
Provides the list of names of scalar arguments required by the kernel associated with this Arguments object. If there are none then the returned list is empty.
- Returns:
A list of the names of scalar arguments in this object.
- Return type:
list of str
- class psyclone.gocean1p0.GOKernelArgument(arg, arg_info, call)
Provides information about individual GOcean kernel call arguments as specified by the kernel argument metadata.
Inheritance
- property argument_type
Return the type of this kernel argument - whether it is a field, a scalar or a grid_property (to be supplied by the PSy layer). If it has no type it defaults to scalar.
- Returns:
the type of the argument.
- Return type:
str
- property function_space
Returns the expected finite difference space for this argument as specified by the kernel argument metadata.
- infer_datatype()
Infer the datatype of this argument using the API rules.
- Returns:
the datatype of this argument.
- Return type:
:py:class::psyclone.psyir.symbols.DataType
- Raises:
InternalError – if this Argument type is not “field” or “scalar”.
InternalError – if this argument is scalar but its space property is not ‘go_r_scalar’ or ‘go_i_scalar’.
- property intrinsic_type
- Returns:
the intrinsic type of this argument. If it’s not a scalar integer or real it will return an empty string.
- Return type:
str
- property is_scalar
- Returns:
whether this variable is a scalar variable or not.
- Return type:
bool
- psyir_expression()
- Returns:
the PSyIR expression represented by this Argument.
- Return type:
- Raises:
InternalError – if this Argument type is not “field” or “scalar”.
- class psyclone.gocean1p0.GOKernelGridArgument(arg, kernel_call)
Describes arguments that supply grid properties to a kernel. These arguments are provided by the PSy layer rather than in the Algorithm layer.
- Parameters:
arg (
psyclone.gocean1p0.GO1p0Descriptor
) – the meta-data entry describing the required grid property.kernel_call (
psyclone.gocean1p0.GOKern
) – the kernel call node that this Argument belongs to.
- Raises:
GenerationError – if the grid property is not recognised.
Inheritance
- property argument_type
The type of this argument. We have this for compatibility with GOKernelArgument objects since, for this class, it will always be “grid_property”.
- backward_dependence()
A grid-property argument is read-only and supplied by the PSy layer so has no dependencies
- Returns:
None to indicate no dependencies
- Return type:
NoneType
- dereference(fld_name)
Returns a Fortran string to dereference a grid property of the specified field. It queries the current config file settings for getting the proper dereference string, which is a format string where {0} represents the field name.
- Parameters:
fld_name (str) – The name of the field which is used to dereference a grid property.
- Returns:
the dereference string required to access a grid property in a dl_esm field (e.g. “subdomain%internal%xstart”). The name must contains a “{0}” which is replaced by the field name.
- Return type:
str
- forward_dependence()
A grid-property argument is read-only and supplied by the PSy layer so has no dependencies
- Returns:
None to indicate no dependencies
- Return type:
NoneType
- property intrinsic_type
- Returns:
the intrinsic_type of this argument.
- Return type:
str
- property is_scalar
- Returns:
if this variable is a scalar variable or not.
- Return type:
bool
- property name
Returns the Fortran name of the grid property, which is used in error messages etc.
- psyir_expression()
- Returns:
the PSyIR expression represented by this Argument.
- Return type:
- property text
The raw text used to pass data from the algorithm layer for this argument. Grid properties are not passed from the algorithm layer so None is returned.
- class psyclone.gocean1p0.GOStencil
GOcean 1.0 stencil information for a kernel argument as obtained by parsing the kernel meta-data. The expected structure of the metadata and its meaning is provided in the description of the load method
Inheritance
- depth(index0, index1)
Provides the depth of the stencil in the 8 possible stencil directions in a 2d regular grid (see the description in the load class for more information). Values must be between -1 and 1 as they are considered to be relative to the centre of the stencil For example:
- stencil(234,
915, 876)
returns
depth(-1,0) = 9 depth(1,1) = 4
- Parameters:
index0 (int) – the relative stencil offset for the first index of the associated array. This value must be between -1 and 1.
index1 (int) – the relative stencil offset for the second index of the associated array. This value must be between -1 and 1
- Returns:
the depth of the stencil in the specified direction.
- Return type:
int
- Raises:
GenerationError – if the indices are out-of-bounds.
- property has_stencil
Specifies whether this argument has stencil information or not. The only case when this is False is when the stencil information specifies ‘pointwise’ as this indicates that there is no stencil access.
- Returns:
True if this argument has stencil information and False if not.
- Return type:
bool
- load(stencil_info, kernel_name)
Take parsed stencil metadata information, check it is valid and store it in a convenient form. The kernel_name argument is only used to provide the location if there is an error.
The stencil information should either be a name which indicates a particular type of stencil or in the form stencil(xxx,yyy,zzz) which explicitly specifies a stencil shape where xxx, yyy and zzz are triplets of integers indicating whether there is a stencil access in a particular direction and the depth of that access. For example:
- go_stencil(010, ! N
212, ! W E 010) ! S
indicates that there is a stencil access of depth 1 in the “North” and “South” directions and stencil access of depth 2 in the “East” and “West” directions. The value at the centre of the stencil will not be used by PSyclone but can be 0 or 1 and indicates whether the local field value is accessed.
The convention is for the associated arrays to be 2-dimensional. If we denote the first dimension as “i” and the second dimension as “j” then the following directions are assumed:
> j > ^ > | > | > —->i
For example a stencil access like:
a(i,j) + a(i+1,j) + a(i,j-1)
would be stored as:
- go_stencil(000,
011, 010)
- Parameters:
stencil_info (
psyclone.expression.FunctionVar
) – contains the appropriate part of the parser ASTkernel_name (string) – the name of the kernel from where this stencil information came from.
- Raises:
ParseError – if the supplied stencil information is invalid.
- property name
Provides the stencil name if one is provided
- Returns:
the name of the type of stencil if this is provided and ‘None’ if not.
- Return type:
str
- class psyclone.gocean1p0.GO1p0Descriptor(kernel_name, kernel_arg, metadata_index)
Description of a GOcean 1.0 kernel argument, as obtained by parsing the kernel metadata.
- Parameters:
kernel_name (str) – the name of the kernel metadata type that contains this metadata.
kernel_arg (
psyclone.expression.FunctionVar
) – the relevant part of the parser’s AST.metadata_index (int) – the postion of this argument in the list of arguments specified in the metadata.
- Raises:
ParseError – if a kernel argument has an invalid grid-point type.
ParseError – for an unrecognised grid property.
ParseError – for an invalid number of arguments.
ParseError – for an invalid access argument.
Inheritance
- property grid_prop
- Returns:
the name of the grid-property that this argument is to supply to the kernel.
- Return type:
str
- class psyclone.gocean1p0.GOKernelType1p0(ast, name=None)
Description of a kernel including the grid index-offset it expects and the region of the grid that it expects to operate upon
Inheritance
- property index_offset
Return the grid index-offset that this kernel expects
- property nargs
Count and return the number of arguments that this kernel expects the Algorithm layer to provide
- class psyclone.gocean1p0.GOACCEnterDataDirective(children=None, parent=None)
Sub-classes ACCEnterDataDirective to provide the dl_esm_inf infrastructure- specific interfaces to flag and update when data is on a device.
Inheritance
- lower_to_language_level()
In-place replacement of DSL or high-level concepts into generic PSyIR constructs. In addition to calling this method in the base class, the GOACCEnterDataDirective sets up the ‘data_on_device’ flag for each of the fields accessed.
- Returns:
the lowered version of this node.
- Return type:
psyclone.psyir.node.Node
- class psyclone.gocean1p0.GOKernelSchedule(name, is_program=False, **kwargs)
Sub-classes KernelSchedule to provide a GOcean-specific implementation.
- Parameters:
name (str) – Kernel subroutine name
Inheritance
- class psyclone.gocean1p0.GOHaloExchange(field, check_dirty=False, parent=None)
GOcean specific halo exchange class which can be added to and manipulated in a schedule.
- Parameters:
field (
psyclone.gocean1p0.GOKernelArgument
) – the field that this halo exchange will act on.check_dirty (bool) – optional argument default False (contrary to its generic class - revisit in #856) indicating whether this halo exchange should be subject to a run-time check for clean/dirty halos.
parent (
psyclone.psyir.nodes.Node
) – optional PSyIR parent node (default None) of this object.
Inheritance
- lower_to_language_level()
In-place replacement of DSL or high-level concepts into generic PSyIR constructs. A GOHaloExchange is replaced by a call to the appropriate library method.
- Returns:
the lowered version of this node.
- Return type:
psyclone.psyir.node.Node