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)
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 propertyarglist
checks thatgenerate
has been called and then provides a list.- Parameters:
kern (
psyclone.domain.lfric.LFRicKern
) – the kernel call object to use.
Inheritance
- append(var_name, var_accesses=None, var_access_name=None, mode=AccessType.READ, metadata_posn=None)
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.VariablesAccessInfo
) – 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, tag=None, symbol=None)
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 (
psyclone.psyir.symbols.datatypes.ScalarType.Intrinsic
) – 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:
- append_integer_reference(name, tag=None)
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:
- 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)
Add banded dofmap (required for CMA operator assembly).
- Parameters:
function_space (
psyclone.domain.lfric.FunctionSpace
) – the function space for which banded dofmap is added.var_accesses (
psyclone.core.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.
- abstract basis(function_space, var_accesses=None)
Add basis function information for this function space to the argument list and optionally to the variable access information.
- Parameters:
function_space (
psyclone.domain.lfric.FunctionSpace
) – the function space for which the basis function is required.var_accesses (
psyclone.core.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.
- cell_map(var_accesses=None)
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.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.
- cell_position(var_accesses=None)
Add cell position information.
- Parameters:
var_accesses (
psyclone.core.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.
- abstract cma_operator(arg, var_accesses=None)
Add the CMA operator and associated scalars to the argument list and optionally add them to the variable access information.
- Parameters:
arg (
psyclone.dynamo0p3.DynKernelArgument
) – the CMA operator argument.var_accesses (
psyclone.core.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.
- abstract diff_basis(function_space, var_accesses=None)
Add differential basis information for the function space to the argument list. If supplied it also stores this access in var_accesses.
- Parameters:
function_space (
psyclone.domain.lfric.FunctionSpace
) – the function space for which the differential basis functions are required.var_accesses (
psyclone.core.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.
- extend(list_var_name, var_accesses=None, mode=AccessType.READ, list_metadata_posn=None)
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.VariablesAccessInfo
) – 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.
- abstract field(arg, var_accesses=None)
Add the field array associated with the argument ‘arg’ to the argument list. If supplied it also stores this access in var_accesses.
- Parameters:
arg (
psyclone.dynamo0p3.DynKernelArgument
) – the field to be added.var_accesses (
psyclone.core.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.
- abstract field_bcs_kernel(function_space, var_accesses=None)
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.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.
- abstract field_vector(argvect, var_accesses=None)
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:
argvect (
psyclone.dynamo0p3.DynKernelArgument
) – the field vector to add.var_accesses (
psyclone.core.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.
- fs_common(function_space, var_accesses=None)
Add function-space related arguments common to LMA operators and fields. If supplied it also stores this access in var_accesses.
- Parameters:
function_space (
psyclone.domain.lfric.FunctionSpace
) – the function space for which the related arguments common to LMA operators and fields are added.var_accesses (
psyclone.core.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.
- fs_compulsory_field(function_space, var_accesses=None)
Add compulsory arguments associated with this function space to the list. If supplied it also stores this access in var_accesses.
- Parameters:
function_space (
psyclone.domain.lfric.FunctionSpace
) – the function space for which the compulsory arguments are added.var_accesses (
psyclone.core.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.
- abstract fs_intergrid(function_space, var_accesses=None)
Add function-space related arguments for an intergrid kernel. If supplied it also stores this access in var_accesses.
- Parameters:
function_space (
psyclone.domain.lfric.FunctionSpace
) – the function space for which to add argumentsvar_accesses (
psyclone.core.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.
- generate(var_accesses=None)
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.VariablesAccessInfo
) – optional VariablesAccessInfo 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, tag=None, symbol=None)
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 (
psyclone.psyir.symbols.datatypes.ScalarType.Intrinsic
) – the intrinsic type of the array.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:
- indirection_dofmap(function_space, operator=None, var_accesses=None)
Add indirection dofmap required when applying a CMA operator. If supplied it also stores this access in var_accesses.
- Parameters:
function_space (
psyclone.domain.lfric.FunctionSpace
) – the function space for which the indirect dofmap is required.operator (
psyclone.dynamo0p3.DynKernelArgument
) – the CMA operator (not used at the moment).var_accesses (
psyclone.core.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.
- mesh_height(var_accesses=None)
Add mesh height (nlayers) to the argument list and if supplied stores this access in var_accesses.
- Parameters:
var_accesses (
psyclone.core.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.
- abstract mesh_properties(var_accesses=None)
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.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.
- metadata_index_from_actual_index(idx)
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
- abstract operator(arg, var_accesses=None)
Add the operator arguments to the argument list. If supplied it also stores this access in var_accesses.
- Parameters:
arg (
psyclone.dynamo0p3.DynKernelArgument
) – the meta-data description of the operator.var_accesses (
psyclone.core.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.
- abstract operator_bcs_kernel(function_space, var_accesses=None)
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:
function_space (
psyclone.domain.lfric.FunctionSpace
) – the function space of the operator.var_accesses (
psyclone.core.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.
- psyir_append(node)
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:
- Raises:
InternalError – if the generate() method has not been called.
- abstract quad_rule(var_accesses=None)
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.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.
- ref_element_properties(var_accesses=None)
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.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.
- scalar(scalar_arg, var_accesses=None)
Add the name associated with the scalar argument to the argument list and optionally add this scalar to the variable access information.
- Parameters:
scalar_arg (
psyclone.dynamo0p3.DynKernelArgument
) – the kernel argument.var_accesses (
psyclone.core.VariablesAccessInfo
) – optional VariablesAccessInfo instance that stores information about variable accesses.
- Raises:
InternalError – if the argument is not a recognised scalar type.
- abstract stencil(arg, var_accesses=None)
Add general stencil information associated with the argument ‘arg’ to the argument list. If supplied it also stores this access in var_accesses.
- Parameters:
arg (
psyclone.dynamo0p3.DynKernelArgument
) – the meta-data description of the kernel argument with which the stencil is associated.var_accesses (
psyclone.core.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.
- abstract stencil_2d(arg, var_accesses=None)
Add 2D stencil information associated with the argument ‘arg’ to the argument list. If supplied it also stores this access in var_accesses.
- Parameters:
arg (
psyclone.dynamo0p3.DynKernelArgument
) – the meta-data description of the kernel argument with which the stencil is associated.var_accesses (
psyclone.core.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.
- abstract stencil_2d_max_extent(arg, var_accesses=None)
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:
arg (
psyclone.dynamo0p3.DynKernelArgument
) – the kernel argument with which the stencil is associated.var_accesses (
psyclone.core.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.
- abstract stencil_2d_unknown_extent(arg, var_accesses=None)
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:
arg (
psyclone.dynamo0p3.DynKernelArgument
) – the kernel argument with which the stencil is associated.var_accesses (
psyclone.core.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.
- abstract stencil_unknown_direction(arg, var_accesses=None)
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:
arg (
psyclone.dynamo0p3.DynKernelArgument
) – the kernel argument with which the stencil is associated.var_accesses (
psyclone.core.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.
- abstract stencil_unknown_extent(arg, var_accesses=None)
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:
arg (
psyclone.dynamo0p3.DynKernelArgument
) – the kernel argument with which the stencil is associated.var_accesses (
psyclone.core.VariablesAccessInfo
) – optional VariablesAccessInfo instance to store the information about variable accesses.