`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 specific
GOInvokes: The GOcean specific invokes class. This passes the GOcean specific
GOInvoke: The GOcean specific invoke class. This passes the GOcean specific
GOInvokeSchedule: The GOcean specific InvokeSchedule sub-class. We call the base class
GOLoop: The GOcean specific PSyLoop class. This passes the GOcean specific
GOBuiltInCallFactory: A GOcean-specific built-in call factory. No built-ins
GOKernCallFactory: A GOcean-specific kernel-call factory. A standard kernel call in
GOKern: Stores information about GOcean Kernels as specified by the Kernel
GOKernelArguments: Provides information about GOcean kernel-call arguments
GOKernelArgument: Provides information about individual GOcean kernel call arguments
GOKernelGridArgument: Describes arguments that supply grid properties to a kernel.
GOStencil: GOcean 1.0 stencil information for a kernel argument as obtained by
GO1p0Descriptor: Description of a GOcean 1.0 kernel argument, as obtained by
GOKernelType1p0: Description of a kernel including the grid index-offset it
GOACCEnterDataDirective: 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)[source]#

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

class psyclone.gocean1p0.GOInvokes(alg_calls, psy)[source]#

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

class psyclone.gocean1p0.GOInvoke(alg_invocation, idx, invokes)[source]#

The GOcean specific invoke class. This passes the GOcean specific schedule class to the base class so it creates the one we require.

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

class psyclone.gocean1p0.GOInvokeSchedule(symbol, alg_calls=None, parent=None, **kwargs)[source]#

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:

symbol (psyclone.psyir.symbols.RoutineSymbol) – RoutineSymbol representing the Invoke.
alg_calls (Optional[list of psyclone.parse.algorithm.KernelCall]) – optional list of KernelCalls parsed from the algorithm layer.
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='')[source]#

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 LFRic 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)[source]#

Adds a new iteration space to PSyclone. An iteration space in the gocean 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='')[source]#

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:

psyclone.gocean1p0.GOLoop

create_halo_exchanges()[source]#: 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

get_custom_bound_string(side)[source]#

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)[source]#

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()[source]#

Returns the lower bound of this loop as a string.

Returns:: root of PSyIR sub-tree describing this lower bound.
Return type:: psyclone.psyir.nodes.Node

static setup_bounds()[source]#: Populates the GOLoop._bounds_lookup dictionary. This is used by PSyclone to look up the loop boundaries for each loop it creates.

upper_bound()[source]#

Creates the PSyIR of the upper bound of this loop.

Returns:: the PSyIR for the upper bound of this loop.
Return type:: psyclone.psyir.nodes.Node

class psyclone.gocean1p0.GOBuiltInCallFactory[source]#

A GOcean-specific built-in call factory. No built-ins are supported in GOcean at the moment.

Inheritance

static create()[source]#: 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[source]#

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)[source]#

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:: psyclone.gocean1p0.GOLoop

class psyclone.gocean1p0.GOKern(call, parent=None)[source]#

Stores information about GOcean Kernels as specified by the Kernel metadata. Uses this information to generate appropriate PSy layer code for the Kernel instance.

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_callees()[source]#

Obtains and returns the PSyIR Schedule representing the kernel code.

For consistency with LFRic kernels (which may be polymorphic), this method actually returns a list comprising just one Schedule.

Returns:: a schedule representing the GOcean kernel code.
Return type:: list[psyclone.gocean1p0.GOKernelSchedule]
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

reference_accesses()[source]#

Return type:: VariablesAccessMap
Returns:: a map of all the symbol accessed inside this node, the keys are Signatures (unique identifiers to a symbol and its structure acccessors) and the values are AccessSequence (a sequence of AccessTypes).

class psyclone.gocean1p0.GOKernelArguments(call, parent_call, check=True)[source]#

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)[source]#

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()[source]#: 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()[source]#

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)[source]#

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()[source]#

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()[source]#

Returns:: the PSyIR expression represented by this Argument.
Return type:: psyclone.psyir.nodes.Node
Raises:: InternalError – if this Argument type is not “field” or “scalar”.

class psyclone.gocean1p0.GOKernelGridArgument(arg, kernel_call)[source]#

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()[source]#

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)[source]#

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()[source]#

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()[source]#

Returns:: the PSyIR expression represented by this Argument.
Return type:: psyclone.psyir.nodes.Node

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[source]#

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)[source]#

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)[source]#

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 AST
kernel_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)[source]#

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)[source]#

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, async_queue=False)[source]#

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()[source]#

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(symbol, is_program=False, **kwargs)[source]#

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)[source]#

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()[source]#

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

psyclone.gocean1p0#

Classes#

`psyclone.gocean1p0`#

Classes #