Classes
class	FieldArg

class	GridArg

class	ScalarArg

Public Member Functions
def	__init__ (self, iterates_over=None, index_offset=None, meta_args=None, procedure_name=None, name=None)

def	lower_to_psyir (self)

def	fortran_string (self)

def	name (self)

def	name (self, value)

def	iterates_over (self)

def	iterates_over (self, value)

def	index_offset (self)

def	index_offset (self, value)

def	meta_args (self)

def	procedure_name (self)

def	procedure_name (self, value)

Static Public Member Functions
def	create_from_psyir (symbol)

def	create_from_fortran_string (fortran_string)

Public Attributes
	iterates_over

	index_offset

	procedure_name

	name

Detailed Description

Contains GOcean kernel metadata. This class supports kernel
metadata creation, modification, loading from a fortran string,
writing to a fortran string, raising from existing language-level
PSyIR and lowering to language-level psyir.

:param iterates_over: the name of the quantity that this kernel is \
    intended to iterate over.
:type iterates_over: Optional[str]
:param index_offset: the name of the quantity that specifies the \
    index offset (how different field indices relate to each \
    other).
:type index_offset: Optional[str]
:param meta_args: a list of 'meta_arg' objects which capture the \
    metadata values of the kernel arguments.
:type meta_args: Optional[List[:py:class:`GridArg` | :py:class:`FieldArg` \
    | :py:class:`ScalarArg`]]
:param procedure_name: the name of the kernel procedure to call.
:type procedure_name: Optional[str]
:param name: the name of the symbol to use for the metadata in \
    language-level PSyIR.
:type name: Optional[str]

Definition at line 133 of file psyir.py.

Member Function Documentation

◆ create_from_fortran_string()

def psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata.create_from_fortran_string ( fortran_string )

static

Create a new instance of GOceanKernelMetadata populated with
metadata stored in a fortran string.

:param str fortran_string: the metadata stored as Fortran.

:returns: an instance of GOceanKernelMetadata.
:rtype: :py:class:`psyclone.domain.gocean.kernel.psyir.\
    GOceanKernelMetadata`

:raises ValueError: if the string does not contain a fortran \
    derived type.
:raises ParseError: if the metadata has an unexpected format.

Definition at line 237 of file psyir.py.

     def create_from_fortran_string(fortran_string):
         '''Create a new instance of GOceanKernelMetadata populated with
         metadata stored in a fortran string.
  
         :param str fortran_string: the metadata stored as Fortran.
  
         :returns: an instance of GOceanKernelMetadata.
         :rtype: :py:class:`psyclone.domain.gocean.kernel.psyir.\
             GOceanKernelMetadata`
  
         :raises ValueError: if the string does not contain a fortran \
             derived type.
         :raises ParseError: if the metadata has an unexpected format.
  
         '''
         kernel_metadata = GOceanKernelMetadata()
  
         # Ensure the Fortran2003 parser is initialised.
         _ = ParserFactory().create(std="f2003")
         reader = FortranStringReader(fortran_string)
         try:
             spec_part = Fortran2003.Derived_Type_Def(reader)
         except Fortran2003.NoMatchError:
             # pylint: disable=raise-missing-from
             raise ValueError(
                 f"Expected kernel metadata to be a Fortran derived type, but "
                 f"found '{fortran_string}'.")
  
         kernel_metadata.name = spec_part.children[0].children[1].tostr()
  
         const = GOceanConstants()
         # Extract and store the required 'iterates_over',
         # 'index_offset' and 'code' properties from the parse tree
  
         # the value of iterates over (go_all_pts, ...)
         value = GOceanKernelMetadata._get_property(
             spec_part, "iterates_over").string
         kernel_metadata.iterates_over = value
  
         # the value of index offset (NE, ...)
         value = GOceanKernelMetadata._get_property(
             spec_part, "index_offset").string
         kernel_metadata.index_offset = value
  
         # the name of the procedure that this metadata refers to.
         kernel_metadata.procedure_name = GOceanKernelMetadata._get_property(
             spec_part, "code").string
  
         # meta_args contains arguments which have
         # properties. Therefore create appropriate (GridArg, ScalarArg
         # or FieldArg) instances to capture this information.
         meta_args = GOceanKernelMetadata._get_property(
             spec_part, "meta_args")
         args = walk(meta_args, Fortran2003.Ac_Value_List)
         if not args:
             raise ParseError(
                 f"meta_args should be a list, but found "
                 f"'{str(meta_args)}' in '{spec_part}'.")
  
         for meta_arg in args[0].children:
             if len(meta_arg.children[1].children) == 2:
                 # Grid args have 2 arguments
                 kernel_metadata.meta_args.append(
                     GOceanKernelMetadata.GridArg(meta_arg, kernel_metadata))
             elif len(meta_arg.children[1].children) == 3:
                 # scalar and field args have 3 arguments
                 arg2 = meta_arg.children[1].children[1].string.lower()
                 if arg2 in const.VALID_FIELD_GRID_TYPES:
                     kernel_metadata.meta_args.append(
                         GOceanKernelMetadata.FieldArg(
                             meta_arg, kernel_metadata))
                 elif arg2 in const.VALID_SCALAR_TYPES:
                     kernel_metadata.meta_args.append(
                         GOceanKernelMetadata.ScalarArg(
                             meta_arg, kernel_metadata))
                 else:
                     raise ParseError(
                         f"Expected a 'meta_arg' entry with 3 arguments to "
                         f"either be a field or a scalar, but found '{arg2}' "
                         f"as the second argument instead of "
                         f"'{const.VALID_FIELD_GRID_TYPES}' (fields) or "
                         f"'{const.VALID_SCALAR_TYPES}' (scalars).")
             else:
                 raise ParseError(
                     f"'meta_args' should have either 2 or 3 arguments, but "
                     f"found {len(meta_arg.children[1].children)} in "
                     f"{str(meta_arg)}.")
  
         return kernel_metadata
  

◆ create_from_psyir()

def psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata.create_from_psyir ( symbol )

static

Create a new instance of GOceanKernelMetadata populated with
metadata from a kernel in language-level PSyIR.

:param symbol: the symbol in which the metadata is stored \
    in language-level PSyIR.
:type symbol: :py:class:`psyclone.psyir.symbols.DataTypeSymbol`

:returns: an instance of GOceanKernelMetadata.
:rtype: :py:class:`psyclone.domain.gocean.kernel.psyir.\
    GOceanKernelMetadata`

:raises TypeError: if the symbol argument is not the expected \
    type.
:raises InternalError: if the datatype of the provided symbol \
    is not the expected type.

Definition at line 200 of file psyir.py.

     def create_from_psyir(symbol):
         '''Create a new instance of GOceanKernelMetadata populated with
         metadata from a kernel in language-level PSyIR.
  
         :param symbol: the symbol in which the metadata is stored \
             in language-level PSyIR.
         :type symbol: :py:class:`psyclone.psyir.symbols.DataTypeSymbol`
  
         :returns: an instance of GOceanKernelMetadata.
         :rtype: :py:class:`psyclone.domain.gocean.kernel.psyir.\
             GOceanKernelMetadata`
  
         :raises TypeError: if the symbol argument is not the expected \
             type.
         :raises InternalError: if the datatype of the provided symbol \
             is not the expected type.
  
         '''
         if not isinstance(symbol, DataTypeSymbol):
             raise TypeError(
                 f"Expected a DataTypeSymbol but found a "
                 f"{type(symbol).__name__}.")
  
         datatype = symbol.datatype
  
         if not isinstance(datatype, UnsupportedFortranType):
             raise InternalError(
                 f"Expected kernel metadata to be stored in the PSyIR as "
                 f"an UnsupportedFortranType, but found "
                 f"{type(datatype).__name__}.")
  
         # In an UnsupportedFortranType, the declaration is stored as a
         # string, so use create_from_fortran_string()
         return GOceanKernelMetadata.create_from_fortran_string(
             datatype.declaration)
  

◆ fortran_string()

def psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata.fortran_string ( self )

:returns: the metadata represented by this instance as Fortran.
:rtype: str

Definition at line 402 of file psyir.py.

     def fortran_string(self):
         '''
         :returns: the metadata represented by this instance as Fortran.
         :rtype: str
         '''
         go_args = []
         for go_arg in self.meta_args:
             go_args.append(go_arg.fortran_string())
         go_args_str = ", &\n".join(go_args)
         result = (
             f"TYPE, EXTENDS(kernel_type) :: {self.name}\n"
             f"  TYPE(go_arg), DIMENSION({len(self.meta_args)}) :: "
             f"meta_args = (/ &\n{go_args_str}/)\n"
             f"  INTEGER :: ITERATES_OVER = {self.iterates_over}\n"
             f"  INTEGER :: INDEX_OFFSET = {self.index_offset}\n"
             f"  CONTAINS\n"
             f"    PROCEDURE, NOPASS :: code => {self.procedure_name}\n"
             f"END TYPE {self.name}\n")
         return result
  

References psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata.meta_args(), and psyclone.domain.lfric.kernel.lfric_kernel_metadata.LFRicKernelMetadata.meta_args().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ index_offset() [1/2]

def psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata.index_offset ( self )

:returns: the name of the quantity that specifies the index \
    offset (how different field indices relate to each other).
:rtype: str

Definition at line 495 of file psyir.py.

     def index_offset(self):
         '''
         :returns: the name of the quantity that specifies the index \
             offset (how different field indices relate to each other).
         :rtype: str
         '''
         return self._index_offset
  

References psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata._index_offset, psyclone.gocean1p0.GOKern._index_offset, and psyclone.gocean1p0.GOKernelType1p0._index_offset.

Here is the caller graph for this function:

◆ index_offset() [2/2]

def psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata.index_offset	(	self,
		value
	)

:param str value: set the index_offset metadata to the \
  specified value.

Definition at line 504 of file psyir.py.

     def index_offset(self, value):
         '''
         :param str value: set the index_offset metadata to the \
           specified value.
         '''
         self._validate_index_offset(value)
         self._index_offset = value
  

References psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata._index_offset, psyclone.gocean1p0.GOKern._index_offset, psyclone.gocean1p0.GOKernelType1p0._index_offset, and psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata._validate_index_offset().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ iterates_over() [1/2]

def psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata.iterates_over ( self )

:returns: the name of the quantity that this kernel is intended to \
    iterate over.
:rtype: str

Definition at line 461 of file psyir.py.

     def iterates_over(self):
         '''
         :returns: the name of the quantity that this kernel is intended to \
             iterate over.
         :rtype: str
         '''
         return self._iterates_over
  

References psyclone.domain.common.psylayer.psyloop.PSyLoop._iterates_over, psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata._iterates_over, psyclone.parse.kernel.KernelType._iterates_over, and psyclone.psyGen.Kern._iterates_over.

Here is the caller graph for this function:

◆ iterates_over() [2/2]

def psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata.iterates_over	(	self,
		value
	)

:param str value: set the iterates_over metadata to the \
    specified value.

Definition at line 470 of file psyir.py.

     def iterates_over(self, value):
         '''
         :param str value: set the iterates_over metadata to the \
             specified value.
         '''
         self._validate_iterates_over(value)
         self._iterates_over = value
  

References psyclone.domain.common.psylayer.psyloop.PSyLoop._iterates_over, psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata._iterates_over, psyclone.parse.kernel.KernelType._iterates_over, psyclone.psyGen.Kern._iterates_over, and psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata._validate_iterates_over().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ lower_to_psyir()

def psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata.lower_to_psyir ( self )

 Lower the metadata to language-level PSyIR.

:returns: metadata as stored in language-level PSyIR.
:rtype: :py:class:`psyclone.psyir.symbols.DataTypeSymbol`

Definition at line 189 of file psyir.py.

     def lower_to_psyir(self):
         ''' Lower the metadata to language-level PSyIR.
  
         :returns: metadata as stored in language-level PSyIR.
         :rtype: :py:class:`psyclone.psyir.symbols.DataTypeSymbol`
  
         '''
         return DataTypeSymbol(
             str(self.name), UnsupportedFortranType(self.fortran_string()))
  

Here is the call graph for this function:

◆ meta_args()

def psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata.meta_args ( self )

:returns: a list of 'meta_arg' objects which capture the \
    metadata values of the kernel arguments.
:rtype: List[:py:class:`psyclone.psyir.common.kernel.\
    KernelMetadataSymbol.KernelMetadataArg`]

Definition at line 513 of file psyir.py.

     def meta_args(self):
         '''
         :returns: a list of 'meta_arg' objects which capture the \
             metadata values of the kernel arguments.
         :rtype: List[:py:class:`psyclone.psyir.common.kernel.\
             KernelMetadataSymbol.KernelMetadataArg`]
         '''
         return self._meta_args
  

References psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata._meta_args, and psyclone.domain.lfric.kernel.lfric_kernel_metadata.LFRicKernelMetadata._meta_args.

Here is the caller graph for this function:

◆ name() [1/2]

def psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata.name ( self )

:returns: the name of the symbol that will contain the \
    metadata when lowering.
:rtype: str

Definition at line 439 of file psyir.py.

     def name(self):
         '''
         :returns: the name of the symbol that will contain the \
             metadata when lowering.
         :rtype: str
  
         '''
         return self._name
  

References psyclone.domain.common.algorithm.psyir.AlgorithmInvokeCall._name, psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata._name, psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata.GridArg._name, psyclone.domain.lfric.kernel.lfric_kernel_metadata.LFRicKernelMetadata._name, psyclone.dynamo0p3.DynFuncDescriptor03._name, psyclone.expression.NamedArg._name, psyclone.gocean1p0.GOKernelGridArgument._name, psyclone.gocean1p0.GOStencil._name, psyclone.nemo.NemoInvoke._name, psyclone.nemo.NemoPSy._name, psyclone.parse.algorithm.FileInfo._name, psyclone.parse.algorithm.InvokeCall._name, psyclone.parse.kernel.KernelProcedure._name, psyclone.parse.kernel.KernelType._name, psyclone.parse.module_info.ModuleInfo._name, psyclone.psyGen.PSy._name, psyclone.psyGen.Invoke._name, psyclone.psyGen.Kern._name, psyclone.psyGen.Argument._name, psyclone.psyir.nodes.container.Container._name, psyclone.psyir.nodes.routine.Routine._name, and psyclone.psyir.symbols.symbol.Symbol._name.

Here is the caller graph for this function:

◆ name() [2/2]

def psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata.name	(	self,
		value
	)

:param str value: set the name of the symbol that will contain \
    the metadata when lowering.

:raises ValueError: if the name is not valid.

Definition at line 449 of file psyir.py.

     def name(self, value):
         '''
         :param str value: set the name of the symbol that will contain \
             the metadata when lowering.
  
         :raises ValueError: if the name is not valid.
  
         '''
         FortranReader.validate_name(value)
         self._name = value
  

References psyclone.domain.common.algorithm.psyir.AlgorithmInvokeCall._name, psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata._name, psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata.GridArg._name, psyclone.domain.lfric.kernel.lfric_kernel_metadata.LFRicKernelMetadata._name, psyclone.dynamo0p3.DynFuncDescriptor03._name, psyclone.expression.NamedArg._name, psyclone.gocean1p0.GOKernelGridArgument._name, psyclone.gocean1p0.GOStencil._name, psyclone.nemo.NemoInvoke._name, psyclone.nemo.NemoPSy._name, psyclone.parse.algorithm.FileInfo._name, psyclone.parse.algorithm.InvokeCall._name, psyclone.parse.kernel.KernelProcedure._name, psyclone.parse.kernel.KernelType._name, psyclone.parse.module_info.ModuleInfo._name, psyclone.psyGen.PSy._name, psyclone.psyGen.Invoke._name, psyclone.psyGen.Kern._name, psyclone.psyGen.Argument._name, psyclone.psyir.nodes.container.Container._name, psyclone.psyir.nodes.routine.Routine._name, and psyclone.psyir.symbols.symbol.Symbol._name.

Here is the caller graph for this function:

◆ procedure_name() [1/2]

def psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata.procedure_name ( self )

:returns: the kernel procedure name specified by the metadata.
:rtype: str

Definition at line 523 of file psyir.py.

     def procedure_name(self):
         '''
         :returns: the kernel procedure name specified by the metadata.
         :rtype: str
         '''
         return self._procedure_name
  

References psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata._procedure_name, and psyclone.domain.lfric.kernel.lfric_kernel_metadata.LFRicKernelMetadata._procedure_name.

Here is the caller graph for this function:

◆ procedure_name() [2/2]

def psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata.procedure_name	(	self,
		value
	)

:param str value: set the procedure name specified in the
    metadata to the specified value.

:raises ValueError: if the supplied procedure name is invalid.

Definition at line 531 of file psyir.py.

     def procedure_name(self, value):
         '''
         :param str value: set the procedure name specified in the
             metadata to the specified value.
  
         :raises ValueError: if the supplied procedure name is invalid.
  
         '''
         try:
             FortranReader.validate_name(value)
         except (TypeError, ValueError) as err:
             raise ValueError(
                 f"Expected procedure_name to be a valid value but found "
                 f"'{value}'.") from err
         self._procedure_name = value
  

References psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata._procedure_name, and psyclone.domain.lfric.kernel.lfric_kernel_metadata.LFRicKernelMetadata._procedure_name.

Here is the caller graph for this function:

The documentation for this class was generated from the following file:

/home/docs/checkouts/readthedocs.org/user_builds/psyclone-ref/checkouts/latest/src/psyclone/domain/gocean/kernel/psyir.py

Classes

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ create_from_fortran_string()

◆ create_from_psyir()

◆ fortran_string()

◆ index_offset() [1/2]

◆ index_offset() [2/2]

◆ iterates_over() [1/2]

◆ iterates_over() [2/2]

◆ lower_to_psyir()

◆ meta_args()

◆ name() [1/2]

◆ name() [2/2]

◆ procedure_name() [1/2]

◆ procedure_name() [2/2]