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)

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

Inheritance diagram of GOPSy
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

Inheritance diagram of GOInvokes
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

Inheritance diagram of GOInvoke
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

Inheritance diagram of GOInvokeSchedule
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

Inheritance diagram of GOLoop
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:

psyclone.gocean1p0.GOLoop

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:

psyclone.psyir.nodes.Node

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:

psyclone.psyir.nodes.Node

class psyclone.gocean1p0.GOBuiltInCallFactory

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

Inheritance

Inheritance diagram of GOBuiltInCallFactory
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

Inheritance diagram of GOKernCallFactory
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:

psyclone.gocean1p0.GOLoop

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:

Inheritance

Inheritance diagram of GOKern
get_kernel_schedule()
Returns:

a schedule representing the GOcean kernel code.

Return type:

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

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

Inheritance diagram of GOKernelArguments
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

Inheritance diagram of GOKernelArgument
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:

psyclone.psyir.nodes.Node

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:
Raises:

GenerationError – if the grid property is not recognised.

Inheritance

Inheritance diagram of GOKernelGridArgument
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:

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

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

Inheritance diagram of GOStencil
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 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)

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

Inheritance diagram of GO1p0Descriptor
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

Inheritance diagram of GOKernelType1p0
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

Inheritance diagram of GOACCEnterDataDirective
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

Inheritance diagram of GOKernelSchedule
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

Inheritance diagram of GOHaloExchange
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