psyclone.domain.lfric.arg_ordering#

This module implements the base class for managing arguments to kernel calls.

Classes#

  • ArgOrdering: Base class capturing the arguments, type and ordering of data in

class psyclone.domain.lfric.arg_ordering.ArgOrdering(kern)[source]#

Base class capturing the arguments, type and ordering of data in a Kernel call. This base class implements some functionality of a list (extend and append functions), but not using list as a base class. Reason is that many typical functions of a list make only sense to be used after generate is called, which would then require a large number of functions to be re-implemented. So instead the property arglist checks that generate has been called and then provides a list.

Parameters:

kern (psyclone.domain.lfric.LFRicKern) – the kernel call object to use.

Inheritance

Inheritance diagram of ArgOrdering
append(var_name, var_accesses=None, var_access_name=None, mode=AccessType.READ, metadata_posn=None)[source]#

Appends the specified variable name to the list of all arguments and stores the mapping between the position of this actual argument and the corresponding metadata entry. If var_accesses is given, it will also record the access to the variable. The name of the variable accessed can be overwritten by specifying var_access_name. By default it is assumed that access mode is READ (which can be set with mode).

Parameters:

  • var_name (str) – the name of the variable.

  • var_accesses (psyclone.core.VariablesAccessMap) – optional class to store variable access information.

  • var_access_name (str) – optional name of the variable for which access information is stored (used e.g. when the actual argument is field_proxy, but the access is to be recorded for field).

  • mode (psyclone.core.access_type.AccessType) – optional access mode (defaults to READ).

  • metadata_posn (int) – the location of the corresponding entry in the list of arguments in the kernel metadata (if any).

append_array_reference(array_name, indices, intrinsic_type=None, tag=None, symbol=None)[source]#

This function adds an array reference. If there is no symbol with the given tag, a new array symbol will be defined using the given intrinsic_type. If a symbol already exists but has no type, it will be replaced. The created reference is added to the list of PSyIR expressions, and the symbol is returned to the user.

Parameters:

  • array_name (str) – the name and tag of the array.

  • indices (List[Union[str, py:class:psyclone.psyir.nodes.Node]]) – the indices to be used in the PSyIR reference. It must either be “:”, or a PSyIR node.

  • intrinsic_type (Optional[psyclone.psyir.symbols.datatypes.ScalarType]) – the intrinsic type of the array.

  • tag (Optional[str]) – optional tag for the symbol.

  • symbol (Optional[psyclone.psyir.symbols.Symbol]) – optional the symbol to use.

Returns:

the symbol used in the added reference.

Return type:

psyclone.psyir.symbols.Symbol

append_integer_reference(name, tag=None)[source]#

This function adds a reference to an integer variable to the list of PSyIR nodes. If the symbol does not exist, it will be added to the symbol table. If no tag is specified, is uses the name as tag. It also returns the symbol.

Parameters:

  • name (str) – name of the integer variable to declare.

  • tag (Optional[str]) – optional tag of the integer variable to declare.

Returns:

the symbol to which a reference was added.

Return type:

psyclone.psyir.symbols.Symbol

property arglist#
Returns:

the kernel argument list. The generate method must be called first.

Return type:

List[str]

Raises:

InternalError – if the generate() method has not been called.

banded_dofmap(function_space, var_accesses=None)[source]#

Add banded dofmap (required for CMA operator assembly).

Parameters:
abstractmethod basis(function_space, var_accesses=None)[source]#

Add basis function information for this function space to the argument list and optionally to the variable access information.

Parameters:
cell_map(var_accesses=None)[source]#

Add cell-map and related cell counts (for inter-grid kernels) to the argument list. If supplied it also stores these accesses to the var_access object.

Parameters:

var_accesses (psyclone.core.VariablesAccessMap) – optional VariablesAccessMap instance to store the information about variable accesses.

cell_position(var_accesses=None)[source]#

Add cell position information.

Parameters:

var_accesses (psyclone.core.VariablesAccessMap) – optional VariablesAccessMap instance to store the information about variable accesses.

abstractmethod cma_operator(arg, var_accesses=None)[source]#

Add the CMA operator and associated scalars to the argument list and optionally add them to the variable access information.

Parameters:
abstractmethod diff_basis(function_space, var_accesses=None)[source]#

Add differential basis information for the function space to the argument list. If supplied it also stores this access in var_accesses.

Parameters:
extend(list_var_name, var_accesses=None, mode=AccessType.READ, list_metadata_posn=None)[source]#

Appends all variable names in the argument list to the list of all arguments. If var_accesses is given, it will also record the access to the variables. By default any access will be recorded as a read-only access, but this can be changed (for all variables included) using mode.

Parameters:

  • list_var_name (list of str.) – the list with name of the variables to append.

  • var_accesses (psyclone.core.VariablesAccessMap) – optional class to store variable access information.

  • mode (Optional[psyclone.core.access_type.AccessType]) – optional access mode (defaults to READ).

  • list_metadata_posn (Optional[List[int]]) – list of metadata argument positions.

abstractmethod field(arg, var_accesses=None)[source]#

Add the field array associated with the argument ‘arg’ to the argument list. If supplied it also stores this access in var_accesses.

Parameters:
abstractmethod field_bcs_kernel(function_space, var_accesses=None)[source]#

Implement the boundary_dofs array fix for a field. If supplied it also stores this access in var_accesses.

Parameters:

  • function_space – the function space for which boundary dofs are required.

  • var_accesses (psyclone.core.VariablesAccessMap) – optional VariablesAccessMap instance to store the information about variable accesses.

abstractmethod field_vector(argvect, var_accesses=None)[source]#

Add the field vector associated with the argument ‘argvect’ to the argument list. If supplied it also stores these accesses to the var_access object.

Parameters:
fs_common(function_space, var_accesses=None)[source]#

Add function-space related arguments common to LMA operators and fields. If supplied it also stores this access in var_accesses.

Parameters:
fs_compulsory_field(function_space, var_accesses=None)[source]#

Add compulsory arguments associated with this function space to the list. If supplied it also stores this access in var_accesses.

Parameters:
abstractmethod fs_intergrid(function_space, var_accesses=None)[source]#

Add function-space related arguments for an intergrid kernel. If supplied it also stores this access in var_accesses.

Parameters:
generate(var_accesses=None)[source]#

Specifies which arguments appear in an argument list, their type and their ordering. Calls methods for each type of argument that can be specialised by a child class for its particular need. If the optional argument var_accesses is supplied, this function will also add variable access information for each implicit argument (i.e. that is not explicitly listed in kernel metadata) that is added. These accesses will be marked as read.

Parameters:

var_accesses (psyclone.core.VariablesAccessMap) – optional VariablesAccessMap instance that stores the information about variable accesses.

Raises:

GenerationError – if the kernel arguments break the rules for the LFRic API.

get_array_reference(array_name, indices, intrinsic_type=None, tag=None, symbol=None)[source]#

This function creates an array reference. If there is no symbol with the given tag, a new array symbol will be defined using the given intrinsic_type. If a symbol already exists but has no type, it will be replaced.

Parameters:

  • array_name (str) – the name and tag of the array.

  • indices (List[Union[str, py:class:psyclone.psyir.nodes.Node]]) – the indices to be used in the PSyIR reference. It must either be “:”, or a PSyIR node.

  • intrinsic_type (Optional[psyclone.psyir.symbols.datatypes.ScalarType]) – the intrinsic type of the array. Defaults to LFRicIntegerScalarDataType.

  • tag (Optional[str]) – optional tag for the symbol.

  • symbol – optional the symbol to use.

Type:

Optional[psyclone.psyir.symbols.Symbol]

Returns:

a reference to the symbol used.

Return type:

psyclone.psyir.nodes.Reference

halo_depth(var_accesses=None)[source]#

Add a halo-depth argument to the Kernel argument list. This default implementation does nothing as halo depths are not passed to kernel subroutines (but they are passed down from the Algorithm layer to the PSy layer).

Parameters:

var_accesses (Optional[ psyclone.core.VariablesAccessMap) – optional VariablesAccessMap instance to store information about variable accesses.

indirection_dofmap(function_space, operator=None, var_accesses=None)[source]#

Add indirection dofmap required when applying a CMA operator. If supplied it also stores this access in var_accesses.

Parameters:
mesh_height(var_accesses=None)[source]#

Add mesh height (nlayers) to the argument list and if supplied stores this access in var_accesses.

Parameters:

var_accesses (psyclone.core.VariablesAccessMap) – optional VariablesAccessMap instance to store the information about variable accesses.

abstractmethod mesh_properties(var_accesses=None)[source]#

Provide the kernel arguments required for the mesh properties specified in the kernel metadata. If supplied it also stores this access in var_accesses.

Parameters:

var_accesses (psyclone.core.VariablesAccessMap) – optional VariablesAccessMap instance to store the information about variable accesses.

metadata_index_from_actual_index(idx)[source]#

Returns the index of the entry in the meta_args list from which the actual subroutine argument at idx originated.

Parameters:

idx (int) – the index of an actual argument to the kernel subroutine.

Returns:

the 0-indexed position of the corresponding metadata entry or None if there isn’t one.

Return type:

Optional[int]

property num_args#
Returns:

the current number of arguments stored in _arglist.

Return type:

int

abstractmethod operator(arg, var_accesses=None)[source]#

Add the operator arguments to the argument list. If supplied it also stores this access in var_accesses.

Parameters:
abstractmethod operator_bcs_kernel(function_space, var_accesses=None)[source]#

Supply necessary additional arguments for the kernel that applies boundary conditions to a LMA operator. If supplied it also stores this access in var_accesses.

Parameters:
psyir_append(node)[source]#

Appends a PSyIR node to the PSyIR argument list.

Parameters:

node (psyclone.psyir.nodes.Node) – the node to append.

property psyir_arglist#
Returns:

the kernel argument list as PSyIR expressions. The generate method must be called first.

Return type:

List[psyclone.psyir.nodes.Reference]

Raises:

InternalError – if the generate() method has not been called.

abstractmethod quad_rule(var_accesses=None)[source]#

Add quadrature-related information to the kernel argument list. Adds the necessary arguments to the argument list, and optionally adds variable access information to the var_accesses object.

Parameters:

var_accesses (psyclone.core.VariablesAccessMap) – optional VariablesAccessMap instance to store the information about variable accesses.

ref_element_properties(var_accesses=None)[source]#

Add kernel arguments relating to properties of the reference element. If supplied it also stores this access in var_accesses.

Parameters:

var_accesses (psyclone.core.VariablesAccessMap) – optional VariablesAccessMap instance to store the information about variable accesses.

scalar(scalar_arg, var_accesses=None)[source]#

Add the name associated with the scalar argument to the argument list and optionally add this scalar to the variable access information.

Parameters:
Raises:

InternalError – if the argument is not a recognised scalar type.

abstractmethod stencil(arg, var_accesses=None)[source]#

Add general stencil information associated with the argument ‘arg’ to the argument list. If supplied it also stores this access in var_accesses.

Parameters:
abstractmethod stencil_2d(arg, var_accesses=None)[source]#

Add 2D stencil information associated with the argument ‘arg’ to the argument list. If supplied it also stores this access in var_accesses.

Parameters:
abstractmethod stencil_2d_max_extent(arg, var_accesses=None)[source]#

Add 2D stencil information to the argument list associated with the argument ‘arg’ if the stencil extent (from which it is calculated) is passed from the Algorithm layer rather than being specified in kernel metadata. If supplied it also stores this access in var_accesses.

Parameters:
abstractmethod stencil_2d_unknown_extent(arg, var_accesses=None)[source]#

Add 2D stencil information to the argument list associated with the argument ‘arg’ if the extent is unknown. If supplied it also stores this access in var_accesses.

Parameters:
abstractmethod stencil_unknown_direction(arg, var_accesses=None)[source]#

Add stencil information to the argument list associated with the argument ‘arg’ if the direction is unknown (i.e. it’s being supplied in a variable). If supplied it also stores this access in var_accesses.

Parameters:
abstractmethod stencil_unknown_extent(arg, var_accesses=None)[source]#

Add stencil information to the argument list associated with the argument ‘arg’ if the extent is unknown. If supplied it also stores this access in var_accesses.

Parameters: