(Towards #2381 #2674) add min max access types and new LFRic builtins

config/psyclone.cfg

@@ -64,7 +64,7 @@ FORTRAN_STANDARD = f2008
 # ==================================
 [lfric]
 access_mapping = gh_read: read, gh_write: write, gh_readwrite: readwrite,
-                 gh_inc: inc, gh_readinc: readinc, gh_sum: sum
+                 gh_inc: inc, gh_readinc: readinc, gh_reduction: reduction
 
 # Specify whether we compute annexed dofs when a kernel is written so
 # that it iterates over dofs. This is currently only the case for

doc/user_guide/lfric.rst

@@ -793,7 +793,7 @@ intents there are always ``intent(in)``.
 The Fortran intent of :ref:`scalars <lfric-scalar>` is still defined
 by their :ref:`access metadata <lfric-kernel-valid-access>` as they are
 actual data. This means ``intent(in)`` for ``GH_READ`` and ``intent(out)``
-for ``GH_SUM`` (more details in :ref:`meta_args <lfric-api-meta-args>`
+for ``GH_REDUCTION`` (more details in :ref:`meta_args <lfric-api-meta-args>`
 section below).
 
 The intent of other data structures is mandated by the relevant
@@ -1143,7 +1143,7 @@ The third component of argument metadata describes how the Kernel
 makes use of the data being passed into it (the way it is accessed
 within a Kernel). This information is mandatory. There are currently 6
 possible values of this metadata ``GH_READ``, ``GH_WRITE``,
-``GH_READWRITE``, ``GH_INC``, ``GH_READINC`` and ``GH_SUM``. However,
+``GH_READWRITE``, ``GH_INC``, ``GH_READINC`` and ``GH_REDUCTION``. However,
 not all combinations of metadata entries are valid and PSyclone will
 raise an exception if an invalid combination is specified. Valid
 combinations are specified later in this section (see
@@ -1174,9 +1174,9 @@ combinations are specified later in this section (see
   subsequently incremented. Therefore this is equivalent to a
   ``GH_READ`` followed by a ``GH_INC``.
 
-* ``GH_SUM`` is an example of a reduction and is the only reduction
-  currently supported in PSyclone. This metadata indicates that values
-  are summed over calls to Kernel code.
+* ``GH_REDUCTION`` indicates a reduction. Only Built-ins may perform
+  reductions. The type of reduction (sum, maximum value, minimum value)
+  is a property of the particular Built-in.
 
 For example::
 
@@ -1187,7 +1187,7 @@ For example::
        arg_type(GH_FIELD,        GH_INTEGER, GH_INC,       ... ),    &
        arg_type(GH_FIELD,        GH_REAL,    GH_READINC,   ... ),    &
        arg_type(GH_SCALAR_ARRAY, GH_LOGICAL, GH_READ,      ... ),    &
-       arg_type(GH_SCALAR,       GH_REAL,    GH_SUM)                 &
+       arg_type(GH_SCALAR,       GH_REAL,    GH_REDUCTION)           &
        /)
 
 .. warning:: It is important that ``GH_INC`` is not incorrectly used
@@ -2797,7 +2797,8 @@ are listed in the table below.
 +===============+=====================+================+====================+
 | GH_SCALAR     | GH_INTEGER          | n/a            | GH_READ            |
 +---------------+---------------------+----------------+--------------------+
-| GH_SCALAR     | GH_REAL             | n/a            | GH_READ, GH_SUM    |
+| GH_SCALAR     | GH_REAL             | n/a            | GH_READ,           |
+|               |                     |                | GH_REDUCTION       |
 +---------------+---------------------+----------------+--------------------+
 | GH_FIELD      | GH_REAL, GH_INTEGER | ANY_SPACE_<n>  | GH_READ, GH_WRITE, |
 |               |                     |                | GH_READWRITE       |
@@ -3455,6 +3456,34 @@ the same field (``X = min(a, X)``)::
 
   field(:) = MIN(rscalar, field(:))
 
+Global minimum and maximum field-element values
+###############################################
+
+Built-ins which scan through all elements of a field and return its
+maximum or minimum value.
+
+.. warning::
+   Support for these built-ins is not yet complete and therefore they
+   cannot currently be used. TODO #2381.
+
+minval_X
+^^^^^^^^
+
+**minval_X** (*rscalar*, **field**)
+
+Returns the minimum value held in the field *field*::
+
+  rscalar = MINVAL(field(:))
+
+maxval_X
+^^^^^^^^
+
+**maxval_X** (*rscalar*, **field**)
+
+Returns the maximum value held in the field *field*::
+
+  rscalar = MAXVAL(field(:))
+
 Conversion of ``real`` field elements
 #####################################
 

src/psyclone/configuration.py

@@ -46,6 +46,7 @@
 from configparser import (ConfigParser, MissingSectionHeaderError,
                           ParsingError)
 from collections import namedtuple
+import logging
 import os
 import re
 import sys
@@ -811,11 +812,12 @@ class BaseConfig:
     '''
 
     def __init__(self, section):
+        logger = logging.getLogger(__name__)
         # Set a default mapping, this way the test cases all work without
         # having to specify those mappings.
         self._access_mapping = {"read": "read", "write": "write",
                                 "readwrite": "readwrite", "inc": "inc",
-                                "sum": "sum"}
+                                "reduction": "reduction", "sum": "reduction"}
         # Get the mapping if one exists and convert it into a
         # dictionary. The input is in the format: key1:value1,
         # key2=value2, ...
@@ -837,9 +839,11 @@ def __init__(self, section):
                         AccessType.from_string(access_type)
                 except ValueError as err:
                     # Raised by from_string()
-                    raise ConfigurationError(
+                    # raise ConfigurationError(
+                    logger.warn(
                         f"Unknown access type '{access_type}' found for key "
-                        f"'{api_access_name}'") from err
+                        f"'{api_access_name}'")
+                    # from err
 
         # Now create the reverse lookup (for better error messages):
         self._reverse_access_mapping = {v: k for k, v in

src/psyclone/core/access_type.py

@@ -37,6 +37,7 @@
 
 '''This module implements the AccessType used throughout PSyclone.'''
 
+from __future__ import annotations
 from enum import Enum
 from psyclone.configuration import Config
 
@@ -57,8 +58,8 @@ class AccessType(Enum):
     #: Read before incrementing. Requires that the outermost halo be clean (see
     #: the LFRic API section of the User Guide).
     READINC = 5
-    #: Is the output of a SUM reduction.
-    SUM = 6
+    #: Is the output of a (min/max/sum) reduction.
+    REDUCTION = 6
     #: This is used internally to indicate unknown access type of
     #: a variable, e.g. when a variable is passed to a subroutine
     #: and the access type of this variable in the subroutine
@@ -132,12 +133,11 @@ def all_read_accesses():
                 AccessType.READINC]
 
     @staticmethod
-    def get_valid_reduction_modes():
+    def get_valid_reduction_modes() -> list[AccessType]:
         '''
         :returns: A list of valid reduction access modes.
-        :rtype: List of py:class:`psyclone.core.access_type.AccessType`.
         '''
-        return [AccessType.SUM]
+        return [AccessType.REDUCTION]
 
     @staticmethod
     def get_valid_reduction_names():

src/psyclone/domain/lfric/lfric_builtins.py

@@ -44,6 +44,7 @@
 
 # pylint: disable=too-many-lines
 import abc
+from typing import Optional
 
 from psyclone.configuration import Config
 from psyclone.core import AccessType, Signature, VariablesAccessMap
@@ -168,6 +169,9 @@ class LFRicBuiltIn(BuiltIn, metaclass=abc.ABCMeta):
     '''
     _case_name = None
     _datatype = None
+    #: The type of reduction performed by this kernel. By default this is
+    ## None indicating no reduction.
+    _reduction_type = None
 
     def __init__(self):
         # Builtins do not accept quadrature
@@ -311,6 +315,10 @@ def _validate(self):
         write_count = 0  # Only one argument must be written to
         field_count = 0  # We must have one or more fields as arguments
         spaces = set()   # All field arguments must be on the same space
+        # Built-ins update fields DoF by DoF and therefore can have
+        # WRITE/READWRITE access
+        write_access_modes = AccessType.get_valid_reduction_modes() + [
+            AccessType.WRITE, AccessType.READWRITE]
         # Field data types must be the same except for the conversion built-ins
         data_types = set()
         for arg in self.arg_descriptors:
@@ -328,10 +336,8 @@ def _validate(self):
                     f"must have one of {const.VALID_BUILTIN_DATA_TYPES} as "
                     f"a data type but kernel '{self.name}' has an argument "
                     f"of data type '{arg.data_type}'.")
-            # Built-ins update fields DoF by DoF and therefore can have
-            # WRITE/READWRITE access
-            if arg.access in [AccessType.WRITE, AccessType.SUM,
-                              AccessType.READWRITE]:
+            # Check for write accesses
+            if arg.access in write_access_modes:
                 write_count += 1
             if arg.argument_type in const.VALID_FIELD_NAMES:
                 field_count += 1
@@ -450,6 +456,14 @@ def fs_descriptors(self):
         '''
         return self._fs_descriptors
 
+    @property
+    def reduction_type(self) -> Optional[str]:
+        '''
+        :returns: the type of reduction operation performed by this Built-in
+            or None if it does not perform a reduction.
+        '''
+        return self._reduction_type
+
     def get_dof_loop_index_symbol(self):
         '''
         Finds or creates the symbol representing the index in any loops
@@ -2350,6 +2364,7 @@ class LFRicXInnerproductYKern(LFRicBuiltIn):
     '''
     _case_name = "X_innerproduct_Y"
     _datatype = "real"
+    _reduction_type = "sum"
 
     @classmethod
     def metadata(cls):
@@ -2361,7 +2376,7 @@ def metadata(cls):
         '''
         gh_datatype = LFRicConstants().MAPPING_INTRINSIC_TYPES[cls._datatype]
         return cls._builtin_metadata([
-            ScalarArgMetadata(gh_datatype, "gh_sum"),
+            ScalarArgMetadata(gh_datatype, "gh_reduction"),
             FieldArgMetadata(gh_datatype, "gh_read", "any_space_1"),
             FieldArgMetadata(gh_datatype, "gh_read", "any_space_1")])
 
@@ -2397,6 +2412,7 @@ class LFRicXInnerproductXKern(LFRicBuiltIn):
     '''
     _case_name = "X_innerproduct_X"
     _datatype = "real"
+    _reduction_type = "sum"
 
     @classmethod
     def metadata(cls):
@@ -2408,7 +2424,7 @@ def metadata(cls):
         '''
         gh_datatype = LFRicConstants().MAPPING_INTRINSIC_TYPES[cls._datatype]
         return cls._builtin_metadata([
-            ScalarArgMetadata(gh_datatype, "gh_sum"),
+            ScalarArgMetadata(gh_datatype, "gh_reduction"),
             FieldArgMetadata(gh_datatype, "gh_read", "any_space_1")])
 
     def lower_to_language_level(self) -> Node:
@@ -2447,6 +2463,7 @@ class LFRicSumXKern(LFRicBuiltIn):
     '''
     _case_name = "sum_X"
     _datatype = "real"
+    _reduction_type = "sum"
 
     @classmethod
     def metadata(cls):
@@ -2458,7 +2475,7 @@ def metadata(cls):
         '''
         gh_datatype = LFRicConstants().MAPPING_INTRINSIC_TYPES[cls._datatype]
         return cls._builtin_metadata([
-            ScalarArgMetadata(gh_datatype, "gh_sum"),
+            ScalarArgMetadata(gh_datatype, "gh_reduction"),
             FieldArgMetadata(gh_datatype, "gh_read", "any_space_1")])
 
     def __str__(self):
@@ -2743,6 +2760,90 @@ def lower_to_language_level(self) -> Node:
         # Create assignment and replace node
         return self._replace_with_assignment(lhs, rhs)
 
+# ------------------------------------------------------------------- #
+# ============ Minimum, maximum value of real field elements) ======= #
+# ------------------------------------------------------------------- #
+
+
+class LFRicMinvalXKern(LFRicBuiltIn):
+    '''
+    Computes the (global) minimum scalar value held in
+    the supplied field.
+    '''
+    _case_name = "minval_X"
+    _datatype = "real"
+    _reduction_type = "min"
+
+    @classmethod
+    def metadata(cls) -> LFRicKernelMetadata:
+        """
+        :returns: kernel metadata describing this built-in.
+        """
+        return cls._builtin_metadata([
+            ScalarArgMetadata("gh_real", "gh_reduction"),
+            FieldArgMetadata("gh_real", "gh_read", "any_space_1")])
+
+    def __str__(self):
+        return (f"Built-in: {self._case_name} (compute the global minimum "
+                f"value contained in a field)")
+
+    def lower_to_language_level(self) -> Node:
+        '''
+        Lowers this LFRic-specific built-in kernel to language-level PSyIR.
+        This BuiltIn node is replaced by an Assignment node.
+
+        :returns: the lowered version of this node.
+
+        '''
+        super().lower_to_language_level()
+        # Get indexed references for the field (proxy) argument.
+        arg_refs = self.get_indexed_field_argument_references()
+        # Get a reference for the kernel scalar reduction argument.
+        lhs = self._reduction_reference()
+        minval = IntrinsicCall.create(IntrinsicCall.Intrinsic.MIN,
+                                      [lhs.copy(), arg_refs[0]])
+        return self._replace_with_assignment(lhs, minval)
+
+
+class LFRicMaxvalXKern(LFRicBuiltIn):
+    '''
+    Computes the (global) maximum scalar value held in
+    the supplied field.
+    '''
+    _case_name = "maxval_X"
+    _datatype = "real"
+    _reduction_type = "max"
+
+    @classmethod
+    def metadata(cls) -> LFRicKernelMetadata:
+        """
+        :returns: kernel metadata describing this built-in.
+        """
+        return cls._builtin_metadata([
+            ScalarArgMetadata("gh_real", "gh_reduction"),
+            FieldArgMetadata("gh_real", "gh_read", "any_space_1")])
+
+    def __str__(self):
+        return (f"Built-in: {self._case_name} (compute the global maximum "
+                f"value contained in a field)")
+
+    def lower_to_language_level(self) -> Node:
+        '''
+        Lowers this LFRic-specific built-in kernel to language-level PSyIR.
+        This BuiltIn node is replaced by an Assignment node.
+
+        :returns: the lowered version of this node.
+
+        '''
+        super().lower_to_language_level()
+        # Get indexed references for the field (proxy) argument.
+        arg_refs = self.get_indexed_field_argument_references()
+        # Get a reference for the kernel scalar reduction argument.
+        lhs = self._reduction_reference()
+        minval = IntrinsicCall.create(IntrinsicCall.Intrinsic.MAX,
+                                      [lhs.copy(), arg_refs[0]])
+        return self._replace_with_assignment(lhs, minval)
+
 # ------------------------------------------------------------------- #
 # ============== Converting real to integer field elements ========== #
 # ------------------------------------------------------------------- #
@@ -3270,6 +3371,9 @@ def lower_to_language_level(self) -> Node:
     # Minimum of a real scalar value and real field elements
     "min_aX": LFRicMinAXKern,
     "inc_min_aX": LFRicIncMinAXKern,
+    # Minimum and maximum values contained in a field
+    "minval_X": LFRicMinvalXKern,
+    "maxval_X": LFRicMaxvalXKern,
     # Converting real to integer field elements
     "real_to_int_X": LFRicRealToIntXKern,
     # Converting real to real field elements

src/psyclone/domain/lfric/lfric_constants.py

@@ -114,8 +114,8 @@ def __init__(self) -> None:
         # pylint: disable=too-many-instance-attributes
 
         # Supported access types
-        # gh_sum for scalars is restricted to iterates_over == 'dof'
-        LFRicConstants.VALID_SCALAR_ACCESS_TYPES = ["gh_read", "gh_sum"]
+        # Reduction for scalars is restricted to iterates_over == 'dof'
+        LFRicConstants.VALID_SCALAR_ACCESS_TYPES = ["gh_read", "gh_reduction"]
         LFRicConstants.VALID_ARRAY_ACCESS_TYPES = ["gh_read"]
         LFRicConstants.VALID_FIELD_ACCESS_TYPES = [
             "gh_read", "gh_write", "gh_readwrite", "gh_inc", "gh_readinc"]
@@ -125,7 +125,7 @@ def __init__(self) -> None:
             "gh_read", "gh_write", "gh_readwrite", "gh_inc", "gh_readinc"]
 
         LFRicConstants.WRITE_ACCESSES = [
-            "gh_write", "gh_readwrite", "gh_inc", "gh_readinc", "gh_sum"]
+            "gh_write", "gh_readwrite", "gh_inc", "gh_readinc", "gh_reduction"]
 
         # Supported LFRic API stencil types and directions
         LFRicConstants.VALID_STENCIL_TYPES = ["x1d", "y1d", "xory1d", "cross",