Public Member Functions
def	__init__ (self)

def	load (self, stencil_info, kernel_name)

def	has_stencil (self)

def	name (self)

def	depth (self, index0, index1)

Detailed Description

GOcean 1.0 stencil information for a kernel argument as obtained by
parsing the kernel meta-data. The expected structure of the
metadata and its meaning is provided in the description of the
load method

Definition at line 1699 of file gocean1p0.py.

Constructor & Destructor Documentation

◆ init()

def psyclone.gocean1p0.GOStencil.__init__ ( self )

 Set up any internal variables.

Definition at line 1706 of file gocean1p0.py.

     def __init__(self):
         ''' Set up any internal variables. '''
         self._has_stencil = None
         self._stencil = [[0 for _ in range(3)] for _ in range(3)]
         self._name = None
         self._initialised = False
  

References psyclone.gocean1p0.GOStencil._has_stencil, psyclone.gocean1p0.GOStencil._initialised, 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, psyclone.psyir.symbols.symbol.Symbol._name, psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata.FieldArg._stencil, psyclone.domain.lfric.arg_index_to_metadata_index.ArgIndexToMetadataIndex._stencil(), psyclone.domain.lfric.kernel.field_arg_metadata.FieldArgMetadata._stencil, psyclone.domain.lfric.lfric_arg_descriptor.LFRicArgDescriptor._stencil, psyclone.domain.lfric.metadata_to_arguments_rules.MetadataToArgumentsRules._stencil(), psyclone.dynamo0p3.DynKernelArgument._stencil, psyclone.gocean1p0.GOStencil._stencil, and psyclone.parse.kernel.Descriptor._stencil.

Here is the call graph for this function:

Member Function Documentation

◆ depth()

def psyclone.gocean1p0.GOStencil.depth	(	self,
		index0,
		index1
	)

Provides the depth of the stencil in the 8 possible stencil
directions in a 2d regular grid (see the description in the
load class for more information). Values must be between -1
and 1 as they are considered to be relative to the centre of
the stencil For example:

stencil(234,
        915,
        876)

returns

depth(-1,0) = 9
depth(1,1) = 4

:param int index0: the relative stencil offset for the first \
                   index of the associated array. This value \
                   must be between -1 and 1.
:param int index1: the relative stencil offset for the second \
                   index of the associated array. This value \
                   must be between -1 and 1

:returns: the depth of the stencil in the specified direction.
:rtype: int

:raises GenerationError: if the indices are out-of-bounds.

Definition at line 1900 of file gocean1p0.py.

     def depth(self, index0, index1):
         '''Provides the depth of the stencil in the 8 possible stencil
         directions in a 2d regular grid (see the description in the
         load class for more information). Values must be between -1
         and 1 as they are considered to be relative to the centre of
         the stencil For example:
  
         stencil(234,
                 915,
                 876)
  
         returns
  
         depth(-1,0) = 9
         depth(1,1) = 4
  
         :param int index0: the relative stencil offset for the first \
                            index of the associated array. This value \
                            must be between -1 and 1.
         :param int index1: the relative stencil offset for the second \
                            index of the associated array. This value \
                            must be between -1 and 1
  
         :returns: the depth of the stencil in the specified direction.
         :rtype: int
  
         :raises GenerationError: if the indices are out-of-bounds.
  
         '''
         self._check_init()
         if index0 < -1 or index0 > 1 or index1 < -1 or index1 > 1:
             raise GenerationError(
                 f"The indices arguments to the depth method in the GOStencil "
                 f"object must be between -1 and 1 but found "
                 f"({index0},{index1})")
         return self._stencil[index0+1][index1+1]
  
  

References psyclone.gocean1p0.GOStencil._check_init(), psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata.FieldArg._stencil, psyclone.domain.lfric.arg_index_to_metadata_index.ArgIndexToMetadataIndex._stencil(), psyclone.domain.lfric.kernel.field_arg_metadata.FieldArgMetadata._stencil, psyclone.domain.lfric.lfric_arg_descriptor.LFRicArgDescriptor._stencil, psyclone.domain.lfric.metadata_to_arguments_rules.MetadataToArgumentsRules._stencil(), psyclone.dynamo0p3.DynKernelArgument._stencil, psyclone.gocean1p0.GOStencil._stencil, and psyclone.parse.kernel.Descriptor._stencil.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ has_stencil()

def psyclone.gocean1p0.GOStencil.has_stencil ( self )

Specifies whether this argument has stencil information or not. The
only case when this is False is when the stencil information
specifies 'pointwise' as this indicates that there is no
stencil access.

:returns: True if this argument has stencil information and False \
          if not.
:rtype: bool

Definition at line 1874 of file gocean1p0.py.

     def has_stencil(self):
         '''Specifies whether this argument has stencil information or not. The
         only case when this is False is when the stencil information
         specifies 'pointwise' as this indicates that there is no
         stencil access.
  
         :returns: True if this argument has stencil information and False \
                   if not.
         :rtype: bool
  
         '''
         self._check_init()
         return self._has_stencil
  

References psyclone.gocean1p0.GOStencil._check_init(), and psyclone.gocean1p0.GOStencil._has_stencil.

Here is the call graph for this function:

◆ load()

def psyclone.gocean1p0.GOStencil.load	(	self,
		stencil_info,
		kernel_name
	)

Take parsed stencil metadata information, check it is valid and
store it in a convenient form. The kernel_name argument is
only used to provide the location if there is an error.

The stencil information should either be a name which
indicates a particular type of stencil or in the form
stencil(xxx,yyy,zzz) which explicitly specifies a stencil
shape where xxx, yyy and zzz are triplets of integers
indicating whether there is a stencil access in a particular
direction and the depth of that access. For example:

go_stencil(010,  !   N
           212,  !  W E
           010)  !   S

indicates that there is a stencil access of depth 1 in the
"North" and "South" directions and stencil access of depth 2
in the "East" and "West" directions. The value at the centre
of the stencil will not be used by PSyclone but can be 0 or 1
and indicates whether the local field value is accessed.

The convention is for the associated arrays to be
2-dimensional. If we denote the first dimension as "i" and the
second dimension as "j" then the following directions are
assumed:


> j
> ^
> |
> |
> ---->i

For example a stencil access like:

a(i,j) + a(i+1,j) + a(i,j-1)

would be stored as:

go_stencil(000,
           011,
           010)

:param stencil_info: contains the appropriate part of the parser AST
:type stencil_info: :py:class:`psyclone.expression.FunctionVar`
:param string kernel_name: the name of the kernel from where this \
                           stencil information came from.

:raises ParseError: if the supplied stencil information is invalid.

Definition at line 1714 of file gocean1p0.py.

     def load(self, stencil_info, kernel_name):
         '''Take parsed stencil metadata information, check it is valid and
         store it in a convenient form. The kernel_name argument is
         only used to provide the location if there is an error.
  
         The stencil information should either be a name which
         indicates a particular type of stencil or in the form
         stencil(xxx,yyy,zzz) which explicitly specifies a stencil
         shape where xxx, yyy and zzz are triplets of integers
         indicating whether there is a stencil access in a particular
         direction and the depth of that access. For example:
  
         go_stencil(010,  !   N
                    212,  !  W E
                    010)  !   S
  
         indicates that there is a stencil access of depth 1 in the
         "North" and "South" directions and stencil access of depth 2
         in the "East" and "West" directions. The value at the centre
         of the stencil will not be used by PSyclone but can be 0 or 1
         and indicates whether the local field value is accessed.
  
         The convention is for the associated arrays to be
         2-dimensional. If we denote the first dimension as "i" and the
         second dimension as "j" then the following directions are
         assumed:
  
  
         > j
         > ^
         > |
         > |
         > ---->i
  
         For example a stencil access like:
  
         a(i,j) + a(i+1,j) + a(i,j-1)
  
         would be stored as:
  
         go_stencil(000,
                    011,
                    010)
  
         :param stencil_info: contains the appropriate part of the parser AST
         :type stencil_info: :py:class:`psyclone.expression.FunctionVar`
         :param string kernel_name: the name of the kernel from where this \
                                    stencil information came from.
  
         :raises ParseError: if the supplied stencil information is invalid.
  
         '''
         self._initialised = True
  
         if not isinstance(stencil_info, expr.FunctionVar):
             # the stencil information is not in the expected format
             raise ParseError(
                 f"Meta-data error in kernel '{kernel_name}': 3rd descriptor "
                 f"(stencil) of field argument is '{stencil_info}' but "
                 f"expected either a name or the format 'go_stencil(...)'")
  
         # Get the name
         name = stencil_info.name.lower()
         const = GOceanConstants()
  
         if stencil_info.args:
             # The stencil info is of the form 'name(a,b,...), so the
             # name should be 'stencil' and there should be 3
             # arguments'
             self._has_stencil = True
             args = stencil_info.args
             if name != "go_stencil":
                 raise ParseError(
                     f"Meta-data error in kernel '{kernel_name}': 3rd "
                     f"descriptor (stencil) of field argument is '{name}' but "
                     f"must be 'go_stencil(...)")
             if len(args) != 3:
                 raise ParseError(
                     f"Meta-data error in kernel '{kernel_name}': 3rd "
                     f"descriptor (stencil) of field argument with format "
                     f"'go_stencil(...)', has {len(args)} arguments but should "
                     f"have 3")
             # Each of the 3 args should be of length 3 and each
             # character should be a digit from 0-9. Whilst we are
             # expecting numbers, the parser represents these numbers
             # as strings so we have to perform string manipulation to
             # check and that extract them
             for arg_idx in range(3):
                 arg = args[arg_idx]
                 if not isinstance(arg, str):
                     raise ParseError(
                         f"Meta-data error in kernel '{kernel_name}': 3rd "
                         f"descriptor (stencil) of field argument with format "
                         f"'go_stencil(...)'. Argument index {arg_idx} should "
                         f"be a number but found '{arg}'.")
                 if len(arg) != 3:
                     raise ParseError(
                         f"Meta-data error in kernel '{kernel_name}': 3rd "
                         f"descriptor (stencil) of field argument with format "
                         f"'go_stencil(...)'. Argument index {arg_idx} should "
                         f"consist of 3 digits but found {len(arg)}.")
             # The central value is constrained to be 0 or 1
             if args[1][1] not in ["0", "1"]:
                 raise ParseError(
                     f"Meta-data error in kernel '{kernel_name}': 3rd "
                     f"descriptor (stencil) of field argument with format "
                     f"'go_stencil(...)'. Argument index 1 position 1 "
                     f"should be a number from 0-1 but found {args[1][1]}.")
             # It is not valid to specify a zero stencil. This is
             # indicated by the 'pointwise' name
             if args[0] == "000" and \
                (args[1] == "000" or args[1] == "010") and \
                args[2] == "000":
                 raise ParseError(
                     f"Meta-data error in kernel '{kernel_name}': 3rd "
                     f"descriptor (stencil) of field argument with format "
                     f"'go_stencil(...)'. A zero sized stencil has been "
                     f"specified. This should be specified with the "
                     f"'go_pointwise' keyword.")
             # store the values in an internal array as integers in i,j
             # order
             for idx0 in range(3):
                 for idx1 in range(3):
                     # The j coordinate needs to be 'reversed': the first
                     # row (index 0 in args) is 'top', which should be
                     # accessed using '+1', and the last row (index 2 in args)
                     # needs to be accessed using '-1' (see depth()). Using
                     # 2-idx1 mirrors the rows appropriately.
                     self._stencil[idx0][2-idx1] = int(args[idx1][idx0])
         else:
             # stencil info is of the form 'name' so should be one of
             # our valid names
             if name not in const.VALID_STENCIL_NAMES:
                 raise ParseError(
                     f"Meta-data error in kernel '{kernel_name}': 3rd "
                     f"descriptor (stencil) of field argument is '{name}' "
                     f"but must be one of {const.VALID_STENCIL_NAMES} or "
                     f"go_stencil(...)")
             self._name = name
             # We currently only support one valid name ('pointwise')
             # which indicates that there is no stencil
             self._has_stencil = False
             # Define a 'stencil' for pointwise so that depth() can be used for
             # pointwise kernels without handling pointwise as special case
             self._stencil = [[0, 0, 0], [0, 1, 0], [0, 0, 0]]
  

References psyclone.gocean1p0.GOStencil._has_stencil, psyclone.gocean1p0.GOStencil._initialised, 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, psyclone.psyir.symbols.symbol.Symbol._name, psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata.FieldArg._stencil, psyclone.domain.lfric.arg_index_to_metadata_index.ArgIndexToMetadataIndex._stencil(), psyclone.domain.lfric.kernel.field_arg_metadata.FieldArgMetadata._stencil, psyclone.domain.lfric.lfric_arg_descriptor.LFRicArgDescriptor._stencil, psyclone.domain.lfric.metadata_to_arguments_rules.MetadataToArgumentsRules._stencil(), psyclone.dynamo0p3.DynKernelArgument._stencil, psyclone.gocean1p0.GOStencil._stencil, and psyclone.parse.kernel.Descriptor._stencil.

Here is the call graph for this function:

◆ name()

def psyclone.gocean1p0.GOStencil.name ( self )

Provides the stencil name if one is provided

:returns: the name of the type of stencil if this is provided \
          and 'None' if not.
:rtype: str

Definition at line 1889 of file gocean1p0.py.

     def name(self):
         '''Provides the stencil name if one is provided
  
         :returns: the name of the type of stencil if this is provided \
                   and 'None' if not.
         :rtype: str
  
         '''
         self._check_init()
         return self._name
  

References psyclone.gocean1p0.GOStencil._check_init(), 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 call graph for this function:

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/gocean1p0.py

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ __init__()

Member Function Documentation

◆ depth()

◆ has_stencil()

◆ load()

◆ name()

◆ init()