Modules

This section describes the functionality of the various Python modules that make up PSyclone.

Module: f2pygen

Warning

The f2pygen functionality has been superseded by the development of the PSyIR and will be removed entirely in a future release.

f2pygen provides functionality for generating Fortran code from scratch and supports the addition of a use statement to an existing parse tree.

Variable Declarations

Three different classes are provided to support the creation of variable declarations (for intrinsic, character and derived-type variables). An example of their use might be:

>>> from psyclone.f2pygen import (ModuleGen, SubroutineGen, DeclGen,
... CharDeclGen, TypeDeclGen)
>>> module = ModuleGen(name="testmodule")
>>> sub = SubroutineGen(module, name="testsubroutine")
>>> module.add(sub)
>>> sub.add(DeclGen(sub, datatype="integer", entity_decls=["my_int"]))
>>> sub.add(CharDeclGen(sub, length="10", entity_decls=["my_char"]))
>>> sub.add(TypeDeclGen(sub, datatype="field_type", entity_decls=["ufld"]))
>>> gen = str(module.root)
>>> print(gen)
  MODULE testmodule
    IMPLICIT NONE
    CONTAINS
    SUBROUTINE testsubroutine()
      TYPE(field_type) ufld
      CHARACTER(LEN=10) my_char
      INTEGER my_int
    END SUBROUTINE testsubroutine
  END MODULE testmodule

The full interface to each of these classes is detailed below:

class psyclone.f2pygen.DeclGen(parent, datatype='', entity_decls=None, intent='', pointer=False, kind='', dimension='', allocatable=False, save=False, target=False, initial_values=None, private=False)[source]

Generates a Fortran declaration for variables of various intrinsic types (integer, real and logical). For character variables CharDeclGen should be used.

Parameters:
  • parent (psyclone.f2pygen.BaseGen) – node to which to add this declaration as a child.

  • datatype (str) – the (intrinsic) type for this declaration.

  • entity_decls (list) – list of variable names to declare.

  • intent (str) – the INTENT attribute of this declaration.

  • pointer (bool) – whether or not this is a pointer declaration.

  • kind (str) – the KIND attribute to use for this declaration.

  • dimension (str) – the DIMENSION specifier (i.e. the xx in DIMENSION(xx)).

  • allocatable (bool) – whether this declaration is for an ALLOCATABLE quantity.

  • save (bool) – whether this declaration has the SAVE attribute.

  • target (bool) – whether this declaration has the TARGET attribute.

  • initial_values (list of str with same no. of elements as entity_decls) – initial value to give each variable.

  • private (bool) – whether this declaration has the PRIVATE attribute (default is False).

Raises:

RuntimeError – if datatype is not one of DeclGen.SUPPORTED_TYPES.

class psyclone.f2pygen.CharDeclGen(parent, entity_decls=None, intent='', pointer=False, kind='', dimension='', allocatable=False, save=False, target=False, length='', initial_values=None, private=False)[source]

Generates a Fortran declaration for character variables.

Parameters:
  • parent (psyclone.f2pygen.BaseGen.) – node to which to add this declaration as a child.

  • entity_decls (list) – list of variable names to declare.

  • intent (str) – the INTENT attribute of this declaration.

  • pointer (bool) – whether or not this is a pointer declaration.

  • kind (str) – the KIND attribute to use for this declaration.

  • dimension (str) – the DIMENSION specifier (i.e. the xx in DIMENSION(xx)).

  • allocatable (bool) – whether this declaration is for an ALLOCATABLE quantity.

  • save (bool) – whether this declaration has the SAVE attribute.

  • target (bool) – whether this declaration has the TARGET attribute.

  • length (str) – expression to use for the (len=xx) selector.

  • initial_values (list of str with same no. of elements as entity_decls) – list of initial values, one for each variable. Each of these can be either a variable name or a literal, quoted string (e.g. “‘hello’”). Default is None.

  • private (bool) – whether this declaration has the PRIVATE attribute.

class psyclone.f2pygen.TypeDeclGen(parent, datatype='', entity_decls=None, intent='', pointer=False, dimension='', allocatable=False, save=False, target=False, is_class=False, private=False)[source]

Generates a Fortran declaration for variables of a derived type.

Parameters:
  • parent (psyclone.f2pygen.BaseGen) – node to which to add this declaration as a child.

  • datatype (str) – the type for this declaration.

  • entity_decls (list) – list of variable names to declare.

  • intent (str) – the INTENT attribute of this declaration.

  • pointer (bool) – whether or not this is a pointer declaration.

  • dimension (str) – the DIMENSION specifier (i.e. the xx in DIMENSION(xx)).

  • allocatable (bool) – whether this declaration is for an ALLOCATABLE quantity.

  • save (bool) – whether this declaration has the SAVE attribute.

  • target (bool) – whether this declaration has the TARGET attribute.

  • is_class (bool) – whether this is a class rather than type declaration.

  • private (bool) – whether or not this declaration has the PRIVATE attribute. (Defaults to False.)

Adding code

f2pygen supports the addition of use statements to an existing fparser1 parse tree:

psyclone.f2pygen.adduse(name, parent, only=False, funcnames=None)[source]

Adds a use statement with the specified name to the supplied object. This routine is required when modifying an existing AST (e.g. when modifying a kernel). The classes are used when creating an AST from scratch (for the PSy layer).

Parameters:
  • name (str) – name of module to USE

  • parent (fparser.one.block_statements.*) – node in fparser1 AST to which to add this USE as a child

  • only (bool) – whether this USE has an “ONLY” clause

  • funcnames (list) – list of quantities to follow the “ONLY” clause

Returns:

an fparser1 Use object

Return type:

fparser.one.block_statements.Use

Module: configuration

PSyclone uses the Python ConfigParser class (https://docs.python.org/3/library/configparser.html) for reading the configuration file. This is managed by the psyclone.configuration module which provides a Config class. This class is a singleton, which can be (created and) accessed using Config.get(). Only one such instance will ever exist:

class psyclone.configuration.Config[source]

Handles all configuration management. It is implemented as a singleton using a class _instance variable and a get() function.

property api

Getter for the API selected by the user.

Returns:

The name of the selected API.

Return type:

str

api_conf(api=None)[source]

Getter for the object holding API-specific configuration options.

Parameters:

api (str) – Optional, the API for which configuration details are required. If none is specified, returns the config for the default API.

Returns:

object containing API-specific configuration

Return type:

One of psyclone.configuration.LFRicConfig, psyclone.configuration.GOceanConfig or None.

Raises:
  • ConfigurationError – if api is not in the list of supported APIs.

  • ConfigurationError – if the config file did not contain a section for the requested API.

property backend_checks_enabled
Returns:

whether the validity checks in the PSyIR backend should be disabled.

Return type:

bool

property default_api

Getter for the default API used by PSyclone.

Returns:

default PSyclone API

Return type:

str

property default_stub_api

Getter for the default API used by the stub generator.

Returns:

default API for the stub generator

Return type:

str

property distributed_memory

Getter for whether or not distributed memory is enabled

Returns:

True if DM is enabled, False otherwise

Return type:

bool

property filename

Getter for the full path and name of the configuration file used to initialise this configuration object.

Returns:

full path and name of configuration file

Return type:

str

static find_file()[source]

Static method that searches various locations for a configuration file. If the full path to an existing file has been provided in the PSYCLONE_CONFIG environment variable then that is returned. Otherwise, we search the following locations, in order:

  • ${PWD}/.psyclone/

  • if inside-a-virtual-environment:

    <base-dir-of-virtual-env>/share/psyclone/

  • ${HOME}/.local/share/psyclone/

  • <system-install-prefix>/share/psyclone/

  • <psyclone-installation-base>/share/psyclone/

Returns:

the fully-qualified path to the configuration file

Return type:

str

Raises:

ConfigurationError – if no config file is found

static get(do_not_load_file=False)[source]

Static function that if necessary creates and returns the singleton config instance.

Parameters:

do_not_load_file (bool) – If set it will not load the default config file. This is used when handling the command line so that the user can specify the file to load.

get_constants()[source]
Returns:

the constants instance of the current API.

Return type:

either psyclone.domain.lfric.LFRicConstants, psyclone.domain.gocean.GOceanConstants, or psyclone.domain.nemo.NemoConstants

get_default_keys()[source]

Returns all keys from the default section. :returns list: List of all keys of the default section as strings.

static get_repository_config_file()[source]

This function returns the absolute path to the config file included in the PSyclone repository. It is used by the testing framework to make sure all tests get the same config file (see tests/config_tests for the only exception). :return str: Absolute path to the config file included in the PSyclone repository.

static has_config_been_initialised()[source]
Returns:

if the config class has loaded a (potential custom) config file.

property include_paths
Returns:

the list of paths to search for Fortran include files.

Return type:

list of str.

property kernel_naming
Returns:

what naming scheme to use when writing transformed kernels to file.

Return type:

str

property kernel_output_dir
Returns:

the directory to which to write transformed kernels.

Return type:

str

load(config_file=None)[source]

Loads a configuration file.

Parameters:

config_file (str) – Override default configuration file to read.

Raises:

ConfigurationError – if there are errors or inconsistencies in the specified config file.

property ocl_devices_per_node
Returns:

The number of OpenCL devices per node.

Return type:

int

property psyir_root_name

Getter for the root name to use when creating PSyIR names.

Returns:

the PSyIR root name.

Return type:

str

property reprod_pad_size

Getter for the amount of padding to use for the array required for reproducible OpenMP reductions

Returns:

padding size (no. of array elements)

Return type:

int

property reproducible_reductions

Getter for whether reproducible reductions are enabled.

Returns:

True if reproducible reductions are enabled, False otherwise.

Return type:

bool

property supported_apis

Getter for the list of APIs supported by PSyclone.

Returns:

list of supported APIs

Return type:

list of str

property supported_stub_apis

Getter for the list of APIs supported by the stub generator.

Returns:

list of supported APIs.

Return type:

list of str

property valid_psy_data_prefixes
Returns:

The list of all valid class prefixes.

Return type:

list of str

The Config class is responsible for finding the configuration file (if no filename is passed to the constructor), parsing it and then storing the various configuration options. If PSyclone is started via pytest, the environment variable PSYCLONE_CONFIG is set to <PSYCLONEHOME/config>. This will guarantee that all tests use the config file provided in the PSyclone repository, and not a (potentially modified) user installed version.

The Config class also stores the list of supported APIs (Config._supported_api_list) and the default API to use if none is specified in either a config file or the command line (Config._default_api). Additionally, it performs some basic consistency checks on the values it obtains from the configuration file.

Since the PSyclone API to use can be read from the configuration file, it is not possible to have API-specific sub-classes of Config as we don’t know which API is in use before we read the file. However, the configuration file can contain API-specific settings. These are placed in separate sections, named for the API to which they apply, e.g.:

[dynamo0.3]
COMPUTE_ANNEXED_DOFS = false

Having parsed and stored the options from the default section of the configuration file, the Config constructor then creates a dictionary using the list of supported APIs to provide the keys. The configuration file is then checked for API-specific sections (again using the API names from the default section) and, if any are found, an API-specific sub-class is created using the parsed entries from the corresponding section. The resulting object is stored in the dictionary under the appropriate key. The API-specific values may then be accessed as, e.g.:

Config.get().api_conf("dynamo0.3").compute_annexed_dofs

The API-specific sub-classes exist to provide validation/type-checking and encapsulation for API-specific options. They do not sub-class Config directly but store a reference back to the Config object to which they belong.

Constants Objects

Each API provides a specific object that stores required constants. Most of these constants are hard-coded in the object, but some are taken from a section of the configuration file. The constants are provided as class variables, but an instance of it needs to be created (at least once) in order to make sure all class variables are initialised. It is therefore recommended to always use an instance of the corresponding constant class to access these constants. The constant objects make sure that this initialisation only happens the very first time - creating an instance is therefore very cheap.

There three constant objects can be imported as follows:

  • from psyclone.domain.gocean import GOceanConstants

  • from psyclone.domain.lfric import LFRicConstants

  • from psyclone.domain.nemo import NemoConstants

These objects can be used in two different ways:

  1. If the API is known, e.g. because the constant is used in an API-specific file, an instance can simply be created and used, e.g.:

    from psyclone.domain.lfric import LFRicConstants
    
    const = LFRicConstants()
    
    if var is in const.VALID_LOOP_BOUNDS_NAMES:
        ...
    

    This usage pattern can be seen in many API-specific files.

  2. In some cases a value of an API-specific constant is required in a generic function. In this case the API-specific constant object can be accessed using the config file as follows:

    from psyclone.configuration import Config
    
    const = Config.get().api_conf().get_constants()
    
    if some_variable is in const.VALID_INTRINSIC_TYPES:
        ...
    

    This pattern is used in some functions that can be called with different APIs. The following constants are used this way:

    • VALID_ARG_TYPE_NAMES

    • VALID_INTRINSIC_TYPES

    • VALID_SCALAR_NAMES

    • VALID_LOOP_TYPES

    These are the only variables that are defined across all constant objects.

Module: transformations

As one might expect, the transformations module holds the various transformation classes that may be used to modify the Schedule of an Invoke and/or the kernels called from within it.

Note

The directory layout of PSyclone is currently being restructured. As a result of this some transformations are already in the new locations, while others have not been moved yet.

The base class for any transformation must be the class Transformation:

class psyclone.psyGen.Transformation[source]

Abstract baseclass for a transformation. Uses the abc module so it can not be instantiated.

abstract apply(node, options=None)[source]

Abstract method that applies the transformation. This function must be implemented by each transform. As a minimum each apply function must take a node to which the transform is applied, and a dictionary of additional options, which will also be passed on to the validate functions. This dictionary is used to provide optional parameters, and also to modify the behaviour of validation of transformations: for example, if the user knows that a transformation can correctly be applied in a specific case, but the more generic code validation would not allow this. Validation functions should check for a key in the options dictionary to disable certain tests. Those keys will be documented in each apply() and validate() function.

Note that some apply() functions might take a slightly different set of parameters.

Parameters:
  • node (depends on actual transformation) – The node (or list of nodes) for the transformation - specific to the actual transform used.

  • options (Optional[Dict[str, Any]]) – a dictionary with options for transformations.

property name
Returns:

the transformation’s class name.

Return type:

str

validate(node, options=None)[source]

Method that validates that the input data is correct. It will raise exceptions if the input data is incorrect. This function needs to be implemented by each transformation.

The validate function can be called by the user independent of the apply() function, but it will automatically be executed as part of an apply() call.

As minimum each validate function must take a node to which the transform is applied and a dictionary of additional options. This dictionary is used to provide optional parameters and also to modify the behaviour of validation: for example, if the user knows that a transformation can correctly be applied in a specific case but the more generic code validation would not allow this. Validation functions should check for particular keys in the options dict in order to disable certain tests. Those keys will be documented in each apply() and validate() function as ‘options[“option-name”]’.

Note that some validate functions might take a slightly different set of parameters.

Parameters:
  • node (depends on actual transformation) – The node (or list of nodes) for the transformation - specific to the actual transform used.

  • options (Optional[Dict[str, Any]]) – a dictionary with options for transformations.

Those transformations that work on a region of code (e.g. enclosing multiple kernel calls within an OpenMP region) must sub-class the RegionTrans class:

class psyclone.psyir.transformations.RegionTrans[source]

This abstract class is a base class for all transformations that act on a list of nodes. It gives access to a validate function that makes sure that the nodes in the list are in the same order as in the original AST, no node is duplicated, and that all nodes have the same parent. We also check that all nodes to be enclosed are valid for this transformation - this requires that the sub-class populate the excluded_node_types tuple.

get_node_list(nodes)[source]

This is a helper function for region based transformations. The parameter for any of those transformations is either a single node, a schedule, or a list of nodes. This function converts this into a list of nodes according to the parameter type. This function will always return a copy, to avoid issues e.g. if a child list of a node should be provided, and a transformation changes the order in this list (which would then also change the order of the nodes in the tree).

Parameters:
  • nodes (Union[psyclone.psyir.nodes.Node, psyclone.psyir.nodes.Schedule, List[psyclone.psyir.nodes.Node]) – can be a single node, a schedule or a list of nodes.

  • options (Optional[Dict[str,Any]]) – a dictionary with options for transformations.

Returns:

a list of nodes.

Return type:

List[psyclone.psyir.nodes.Node]

Raises:

TransformationError – if the supplied parameter is neither a single Node, nor a Schedule, nor a list of Nodes.

validate(nodes, options=None)[source]

Checks that the nodes in node_list are valid for a region transformation.

Parameters:
  • nodes (Union[psyclone.psyir.nodes.Node, psyclone.psyir.nodes.Schedule, List[psyclone.psyir.nodes.Node]) – can be a single node, a schedule or a list of nodes.

  • options (Optional[Dict[str,Any]]) – a dictionary with options for transformations.

  • options["node-type-check"] (bool) – this flag controls if the type of the nodes enclosed in the region should be tested to avoid using unsupported nodes inside a region.

Raises:
  • TransformationError – if the nodes in the list are not in the original order in which they are in the AST, a node is duplicated or the nodes have different parents.

  • TransformationError – if any of the nodes to be enclosed in the region are of an unsupported type.

  • TransformationError – if the parent of the supplied Nodes is not a Schedule or a Directive.

  • TransformationError – if the nodes are in a NEMO Schedule and the transformation acts on the child of a single-line If or Where statment.

  • TransformationError – if the supplied options are not a dictionary.

In all cases, the apply method of any sub-class must ensure that the validate method of the parent class is called.

Module: psyGen

Provides the base classes for PSy-layer code generation.

Module: dynamo0p3

Specialises various classes from the psyclone.psyGen module in order to support the Dynamo 0.3 API.

When constructing the Fortran subroutine for either an Invoke or Kernel stub (see Kernel-stub Generator), there are various groups of related quantities for which variables must be declared and (for Invokes) initialised. Each of these groupings is managed by a distinct sub-class of the LFRicCollection abstract class:

class psyclone.domain.lfric.LFRicCollection(node)[source]

Base class for managing the declaration and initialisation of a group of related entities within an Invoke or Kernel stub

Parameters:

node (psyclone.domain.lfric.LFRicInvoke or psyclone.domain.lfric.LFRicKern) – the Kernel or Invoke for which to manage variable declarations and initialisation.

Raises:

InternalError – if the supplied node is not an LFRicInvoke or an LFRicKern.

abstract _invoke_declarations(parent)[source]

Add all necessary declarations for an Invoke.

Parameters:

parent (psyclone.f2pygen.SubroutineGen) – node in the f2pygen AST representing the Invoke to which to add declarations.

_stub_declarations(parent)[source]

Add all necessary declarations for a Kernel stub. Not abstract because not all entities need representing within a Kernel.

Parameters:

parent (psyclone.f2pygen.SubroutineGen) – node in the f2pygen AST representing the Kernel stub to which to add declarations.

declarations(parent)[source]

Insert declarations for all necessary variables into the AST of the generated code. Simply calls either ‘_invoke_declarations()’ or ‘_stub_declarations()’ depending on whether we’re handling an Invoke or a Kernel stub.

Parameters:

parent (psyclone.f2pygen.SubroutineGen) – the node in the f2pygen AST representing the routine in which to insert the declarations.

Raises:

InternalError – if neither ‘self._invoke’ nor ‘self._kernel’ are set.

initialise(parent)[source]

Add code to initialise the entities being managed by this class. We do nothing by default - it is up to the sub-class to override this method if initialisation is required.

Parameters:

parent (psyclone.f2pygen.SubroutineGen) – the node in the f2pygen AST to which to add initialisation code.

(A single base class is used for both Invokes and Kernel stubs since it allows the code dealing with variable declarations to be shared.) A concrete sub-class of LFRicCollection must provide an implementation of the _invoke_declarations method. If the quantities associated with the collection require initialisation within the PSy layer then the initialise method must also be implemented. If stub-generation is to be supported for kernels that make use of the collection type then an implementation must also be provided for _stub_declarations.

Although instances of (sub-classes of) LFRicCollection handle all declarations and initialisation, there remains the problem of constructing the list of arguments for a kernel (or kernel stub). The psyclone.domain.lfric.ArgOrdering base class provides support for this:

class psyclone.domain.lfric.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.

_mesh_ncell2d(var_accesses=None)[source]

Add the number of columns in the mesh (including halos) to the argument list and stores this access in var_accesses (if supplied).

Parameters:

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

_mesh_ncell2d_no_halos(var_accesses=None)[source]

Add the number of columns in the mesh (excluding halos) to the argument list and stores this access in var_accesses (if supplied).

Parameters:

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

property _symtab

Provide a reference to the associate Invoke SymbolTable, usually following the self._kernel.ancestor(InvokeSchedule)._symbol_table path unless a _forced_symtab has been provided.

If no symbol table is available it creates a temporary symbol table for the operation to suceed but it will not be preserved.

Note: This could be improved by TODO #2503

Returns:

the associate invoke symbol table.

Return type:

psyclone.psyir.symbols.SymbolTable

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.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)[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 (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:

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

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)[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.VariablesAccessInfo) – optional VariablesAccessInfo instance to store the information about variable accesses.

cell_position(var_accesses=None)[source]

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

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

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)[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.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)[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:
  • 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)[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.VariablesAccessInfo) – optional VariablesAccessInfo instance to store the information about variable accesses.

abstract 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:
  • 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)[source]

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

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

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 arguments

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

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.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)[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 (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:

psyclone.psyir.nodes.Reference

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

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)[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.VariablesAccessInfo) – optional VariablesAccessInfo 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

abstract 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:
  • 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)[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:
  • 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)[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.

abstract 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.VariablesAccessInfo) – optional VariablesAccessInfo 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.VariablesAccessInfo) – optional VariablesAccessInfo 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:
  • 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)[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:
  • 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)[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:
  • 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)[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:
  • 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)[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:
  • 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)[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:
  • 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)[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:
  • 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.

This class is then sub-classed in order to support the generation of argument lists when calling kernels (KernCallArgList) and when creating kernel stubs (KernStubArgList). KernStubArgList is only used in LFRicKern.gen_stub(). These classes make use of LFRicCollection sub-classes in order to ensure that argument naming is consistent.