inter_grid_vector_arg_metadata.py

# -----------------------------------------------------------------------------
# BSD 3-Clause License
#
# Copyright (c) 2022-2024, Science and Technology Facilities Council
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# * Redistributions of source code must retain the above copyright notice, this
#   list of conditions and the following disclaimer.
#
# * Redistributions in binary form must reproduce the above copyright notice,
#   this list of conditions and the following disclaimer in the documentation
#   and/or other materials provided with the distribution.
#
# * Neither the name of the copyright holder nor the names of its
#   contributors may be used to endorse or promote products derived from
#   this software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
# COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
# ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.
# -----------------------------------------------------------------------------
# Author R. W. Ford, STFC Daresbury Lab
 
'''Module containing the InterGridVectorArgMetadata class which captures the
metadata associated with a intergrid vector argument. Supports the
creation, modification and Fortran output of an InterGridVector
argument.
 
'''
from psyclone.domain.lfric.kernel.inter_grid_arg_metadata import \
    InterGridArgMetadata
 
 
class InterGridVectorArgMetadata(InterGridArgMetadata):
    '''Class to capture LFRic kernel metadata information for an
    InterGridVector argument.
 
    :param str datatype: the datatype of this InterGridVector argument \
        (GH_INTEGER, ...).
    :param str access: the way the kernel accesses this InterGridVector \
        argument (GH_WRITE, ...).
    :param str function_space: the function space that this \
        InterGridVector argument is on (W0, ...).
    :param str mesh_arg: the type of mesh that this InterGrid arg \
        is on (coarse or fine).
    :param str vector_length: the size of the vector.
    :param Optional[str] stencil: the type of stencil used by the \
        kernel when accessing this InterGrid arg.
 
    '''
    # The relative position of LFRic vector length metadata. Metadata
    # for an inter-grid vector argument is provided in the following
    # format 'arg_type(form*vector_length, datatype, access,
    # function_space, [stencil], mesh)'. Therefore, the index of the
    # vector_length argument (vector_length_arg_index) is 0. Index
    # values not provided here are common to the parent classes and
    # are inherited from them.
    vector_length_arg_index = 0
    # The name to use for any exceptions.
    check_name = "inter-grid-vector"
    # Whether the class captures vector metadata.
    vector = True
 
    def __init__(self, datatype, access, function_space, mesh_arg,
                 vector_length, stencil=None):
        super().__init__(
            datatype, access, function_space, mesh_arg, stencil=stencil)
        self.vector_lengthvector_lengthvector_lengthvector_length = vector_length
 
    @classmethod
    def _get_metadata(cls, fparser2_tree):
        '''Extract the required metadata from the fparser2 tree and return it
        as strings. Also check that the metadata is in the expected
        form (but do not check the metadata values as that is done
        separately).
 
        :param fparser2_tree: fparser2 tree containing the metadata \
            for this argument.
        :type fparser2_tree: \
            :py:class:`fparser.two.Fortran2003.Structure_Constructor`
 
        :returns: a tuple containing the datatype, access, function \
            space, mesh, vector-length and stencil metadata.
        :rtype: Tuple[str, str, str, str, str, Optional[str]]
 
        '''
        datatype, access, function_space, mesh_arg, stencil = \
            super()._get_metadata(fparser2_tree)
        vector_length = cls.get_vector_lengthget_vector_length(fparser2_tree)
        return (datatype, access, function_space, mesh_arg, vector_length,
                stencil)
 
    def fortran_string(self):
        '''
        :returns: the metadata represented by this class as Fortran.
        :rtype: str
        '''
        if self.stencilstencilstencilstencil:
            return (f"arg_type({self.form}*{self.vector_length}, "
                    f"{self.datatype}, {self.access}, {self.function_space}, "
                    f"stencil({self.stencil}), mesh_arg={self.mesh_arg})")
        return (f"arg_type({self.form}*{self.vector_length}, "
                f"{self.datatype}, {self.access}, {self.function_space}, "
                f"mesh_arg={self.mesh_arg})")
 
    @property
    def vector_length(self):
        '''
        :returns: the vector length of this intergrid vector \
            argument.
        :rtype: str
        '''
        return self._vector_length_vector_length
 
    @vector_length.setter
    def vector_length(self, value):
        '''
        :param str value: set the intergrid vector length to the specified \
            value.
 
        :raises TypeError: if the provided value is not of type str.
        :raises ValueError: if the provided value is not a string \
            containing an integer.
        :raises ValueError: if the provided value is not greater than 1.
 
        '''
        if not isinstance(value, str):
            raise TypeError(f"The vector size should be a string but found "
                            f"{type(value).__name__}.")
        try:
            int_value = int(value)
        except ValueError as info:
            raise ValueError(
                f"The vector size should be a string containing an integer, "
                f"but found '{value}'.") from info
 
        if int_value <= 1:
            raise ValueError(f"The vector size should be an integer greater "
                             f"than 1 but found {value}.")
        self._vector_length_vector_length = value
 
 
__all__ = ["InterGridVectorArgMetadata"]