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:
- 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:
- 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:
- property curated_api_list
- property distributed_memory
Getter for whether or not distributed memory is enabled
- Returns:
True if DM is enabled, False otherwise
- Return type:
- 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:
- 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:
- 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:
psyclone.domain.lfric.LFRicConstants
|psyclone.domain.gocean.GOceanConstants
- 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:
- property kernel_output_dir
- Returns:
the directory to which to write transformed kernels.
- Return type:
- 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 psyir_root_name
Getter for the root name to use when creating PSyIR names.
- Returns:
the PSyIR root name.
- Return type:
- 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:
- property reproducible_reductions
Getter for whether reproducible reductions are enabled.
- Returns:
True if reproducible reductions are enabled, False otherwise.
- Return type:
- property supported_apis
Getter for the list of APIs supported by PSyclone.
- property supported_stub_apis
Getter for the list of APIs supported by the stub generator.
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
). 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.:
[lfric]
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("lfric").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 two constant objects can be imported as follows:
from psyclone.domain.gocean import GOceanConstants
from psyclone.domain.lfric import LFRicConstants
These objects can be used in two different ways:
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.
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.
- 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
orpsyclone.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 propertyarglist
checks thatgenerate
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:
- 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:
- 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:
- 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)[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 argumentsvar_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
- 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.VariablesAccessInfo
) – optional VariablesAccessInfo 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:
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.
- property num_args
- Returns:
the current number of arguments stored in _arglist.
- Return type:
- 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.