Merge branch 'master' into 1786_renaming_conversion_builtins

changelog

@@ -57,7 +57,7 @@
 	21) PR #2362 for #2243 and #2312. Add support for Fortran save statements.
 
 	22) PR #2379 for #2370. Adds a Node.get_sibling_lists() method.
-	
+
 	23) PR #2366 towards #342. Improve symbols and tighten-up ACCRoutineTrans
 	validation.
 
@@ -77,6 +77,15 @@
 	29) PR #2406 for #2404. Fixes bug in setop_random kernel (was only
 	filling the lowest vertical level).
 
+	30) PR #2389 toward #928. Adds support for field_bcs_kernel when
+	parsing kernels using kernel_interface.py. This is required when
+	validating LFRic kernel arguments.
+
+	31) PR #2388 for #2323. Rename the array reduction 2code transformations
+	to use the 2loop postfix and improve their implementation. 
+
+	32) PR #2400 for #1508. Add flag/config option to disable backend checks.
+
 release 2.4.0 29th of September 2023
 
 	1) PR #1758 for #1741. Splits the PSyData read functionality into a

doc/developer_guide/psyir_backends.rst

@@ -1,7 +1,7 @@
 .. -----------------------------------------------------------------------------
    BSD 3-Clause License
 
-   Copyright (c) 2017-2022, Science and Technology Facilities Council.
+   Copyright (c) 2017-2023, Science and Technology Facilities Council.
    All rights reserved.
 
    Redistribution and use in source and binary forms, with or without
@@ -34,6 +34,7 @@
    Authors: R. W. Ford, A. R. Porter, S. Siso and N. Nobre, STFC Daresbury Lab
 
 
+.. _psyir-backends:
 
 PSyIR Back-ends
 ###############

doc/user_guide/configuration.rst

@@ -1,7 +1,7 @@
 .. -----------------------------------------------------------------------------
 .. BSD 3-Clause License
 ..
-.. Copyright (c) 2018-2022, Science and Technology Facilities Council
+.. Copyright (c) 2018-2023, Science and Technology Facilities Council
 .. All rights reserved.
 ..
 .. Redistribution and use in source and binary forms, with or without
@@ -49,7 +49,7 @@ is in the ``PSyclone/config`` directory of the PSyclone
 distribution.
 
 At execution-time, the user can specify a custom configuration file to
-be used. This can either be done with the ``--config`` command line
+be used. This can either be done with the ``--config`` command-line
 option, or by specifying the (full path to the) configuration file
 to use via the ``PSYCLONE_CONFIG`` environment variable. If the specified
 configuration file is not found then PSyclone will fall back to
@@ -141,18 +141,20 @@ including "true/false", "yes/no" and "1/0". See
 https://docs.python.org/3/library/configparser.html#supported-datatypes
 for more details.
 
+.. _config-default-section:
+
 ``DEFAULT`` Section
 ^^^^^^^^^^^^^^^^^^^
 
 This section contains entries that are, in principle, applicable to all APIs
 supported by PSyclone.
 
-.. tabularcolumns:: |l|L|
+.. tabularcolumns:: |l|L|l|
 
-======================= =======================================================
-Entry                   Description
-======================= =======================================================
-DEFAULTAPI              The API that PSyclone assumes an Algorithm/Kernel
+======================= ======================================================= ===========
+Entry                   Description                                             Type
+======================= ======================================================= ===========
+DEFAULTAPI              The API that PSyclone assumes an Algorithm/Kernel       str
                         conforms to if no API is specified. Must be one of the
                         APIs supported by PSyclone ("dynamo0.3", "gocean1.0"
                         and "nemo"). If there is no
@@ -162,26 +164,30 @@ DEFAULTAPI              The API that PSyclone assumes an Algorithm/Kernel
                         line option '-api'. If there is no API entry in the
                         config file, and '-api' is not specified on the 
                         command line, "dynamo0.3" is used as default.
-DEFAULTSTUBAPI          The API that the kernel-stub generator assumes by
+DEFAULTSTUBAPI          The API that the kernel-stub generator assumes by       str
                         default. Must be one of the stub-APIs supported by
                         PSyclone ("dynamo0.3" only at this stage).
-DISTRIBUTED_MEMORY      Whether or not to generate code for distributed-memory
+DISTRIBUTED_MEMORY      Whether or not to generate code for distributed-memory  bool
                         parallelism by default.  Note that this is currently
                         only supported for the LFRic (Dynamo 0.3) API.
-REPRODUCIBLE_REDUCTIONS Whether or not to generate code for reproducible OpenMP
+REPRODUCIBLE_REDUCTIONS Whether or not to generate code for reproducible OpenMP bool
                         reductions (see :ref:`openmp-reductions`) by default.
-REPROD_PAD_SIZE         If generating code for reproducible OpenMP reductions,
+REPROD_PAD_SIZE         If generating code for reproducible OpenMP reductions,  int
                         this setting controls the amount of padding used
                         between elements of the array in which each thread
                         accumulates its local reduction. (This prevents false
                         sharing of cache lines by different threads.)
-PSYIR_ROOT_NAME         The root for generated PSyIR symbol names if one is not
+PSYIR_ROOT_NAME         The root for generated PSyIR symbol names if one is not str
                         supplied when creating a symbol. Defaults to
                         "psyir_tmp".
-VALID_PSY_DATA_PREFIXES Which class prefixes are permitted in any
+VALID_PSY_DATA_PREFIXES Which class prefixes are permitted in any               list of str
                         PSyData-related transformations. See :ref:`psy_data`
                         for details.
-======================= =======================================================
+BACKEND_CHECKS_ENABLED  Optional (defaults to True). Whether or not the PSyIR   bool
+                        backend should validate the tree that it is passed.
+                        Can be overridden by the ``--backend`` command-line
+                        flag (see :ref:`backend-options`).
+======================= ======================================================= ===========
 
 Common Sections
 ^^^^^^^^^^^^^^^

doc/user_guide/psyclone_command.rst

@@ -65,7 +65,9 @@ by the command:
   usage: psyclone [-h] [-oalg OALG] [-opsy OPSY] [-okern OKERN] [-api API]
                   [-s SCRIPT] [-d DIRECTORY] [-I INCLUDE] [-l {off,all,output}]
                   [-dm] [-nodm] [--kernel-renaming {multiple,single}]
-                  [--profile {invokes,kernels}] [--config CONFIG] [--version]
+                  [--profile {invokes,kernels}]
+		  [--backend {enable-validation,disable-validation}]
+		  [--config CONFIG] [--version]
                   filename
 
   Run the PSyclone code generator on a particular file
@@ -101,6 +103,10 @@ by the command:
                           kernels
     --profile {invokes,kernels}, -p {invokes,kernels}
                           Add profiling hooks for either 'kernels' or 'invokes'
+    --backend {dis,en}able-validation
+                          Options to control the PSyIR backend used for code
+                          generation. Use 'disable-validation' to disable the
+                          validation checks that are performed by default.
     --config CONFIG       Config file with PSyclone specific options.
     --version, -v         Display version information (\ |release|\ )
 
@@ -379,6 +385,30 @@ by the ``-I``/``--include`` flags. (Currently this search assumes that a
 module named e.g. "my_mod" will be in a file named "my_mod.*90" - see issue
 #1895.)
 
+.. _backend-options:
+
+Backend Options
+---------------
+
+The final code generated by PSyclone is created by passing the PSyIR
+tree to one of the 'backends' (see :ref:`dev_guide:psyir-backends` in
+the Developer Guide for more details). The ``--backend`` flag permits
+a user to tune the behaviour of this code generation. Currently, the
+only option is ``{en,dis}able-validation`` which turns on/off the
+validation checks performed when doing code generation. By default,
+such validation is enabled as it is only at code-generation time that
+certain constraints can be checked (since PSyclone does not mandate
+the order in which code transformations are applied).  Occasionally,
+these validation checks may raise false positives (due to incomplete
+implementations), at which point it is useful to be able to disable
+them.  The default behaviour may be changed by adding the
+``BACKEND_CHECKS_ENABLED`` entry to the
+:ref:`configuration file <config-default-section>`. Any
+command-line setting always takes precendence though. It is
+recommended that validation only be disabled as a last resort and for
+as few input source files as possible.
+
+
 C Pre-processor #include Files
 ------------------------------
 

doc/user_guide/psyir.rst

@@ -67,13 +67,12 @@ collectively as 'PSyIR nodes'.
 
 At the present time PSyIR classes can be essentially split into two
 types. PSy-layer classes and Kernel-layer classes. PSy-layer classes
-make use of a ``gen_code()`` or an ``update()`` method to create
-Fortran code whereas Kernel-layer classes make use of PSyIR backends
-to create code.
+make use of a ``gen_code()`` method to create Fortran code whereas
+Kernel-layer classes make use of PSyIR backends to create code.
 
 .. note:: This separation will be removed in the future and eventually
 	  all PSyIR classes will make use of backends with the
-	  expectation that ``gen_code()`` and ``update()`` methods
+	  expectation that ``gen_code()`` methods
 	  will be removed. Further this separation will be superseded
 	  by a separation between ``language-level PSyIR`` and
 	  ``domain-specific PSyIR``.
@@ -229,7 +228,7 @@ Following the `parent` and `children` terminology, we define a node's `siblings`
 as the children of its parent. Note that this definition implies that all nodes
 are their own siblings.
 
-.. automethod:: psyclone.psyir.nodes.Node.siblings
+.. autoproperty:: psyclone.psyir.nodes.Node.siblings
 
 We can check whether two nodes are siblings which immediately precede or follow
 one another using the following methods:

doc/user_guide/transformations.rst

@@ -282,7 +282,7 @@ can be found in the API-specific sections).
 
 ####
 
-.. autoclass:: psyclone.psyir.transformations.Maxval2CodeTrans
+.. autoclass:: psyclone.psyir.transformations.Maxval2LoopTrans
       :members: apply
       :noindex:
 
@@ -299,7 +299,7 @@ can be found in the API-specific sections).
 
 ####
 
-.. autoclass:: psyclone.psyir.transformations.Minval2CodeTrans
+.. autoclass:: psyclone.psyir.transformations.Minval2LoopTrans
       :members: apply
       :noindex:
 
@@ -412,6 +412,12 @@ can be found in the API-specific sections).
 
 ####
 
+.. autoclass:: psyclone.psyir.transformations.Product2LoopTrans
+      :members: apply
+      :noindex:
+
+####
+
 .. autoclass:: psyclone.psyir.transformations.ProfileTrans
     :members: apply
     :noindex:
@@ -449,7 +455,7 @@ can be found in the API-specific sections).
 
 ####
 
-.. autoclass:: psyclone.psyir.transformations.Sum2CodeTrans
+.. autoclass:: psyclone.psyir.transformations.Sum2LoopTrans
       :members: apply
       :noindex:
 

src/psyclone/configuration.py

@@ -223,6 +223,11 @@ def __init__(self):
         # Number of OpenCL devices per node
         self._ocl_devices_per_node = 1
 
+        # By default, a PSyIR backend performs validation checks as it
+        # traverses the tree. Setting this option to False disables those
+        # checks which can be useful in the case of unimplemented features.
+        self._backend_checks_enabled = True
+
     # -------------------------------------------------------------------------
     def load(self, config_file=None):
         '''Loads a configuration file.
@@ -358,6 +363,17 @@ def load(self, config_file=None):
                     f"prefix must be valid for use as the start of a Fortran "
                     f"variable name.", config=self)
 
+        # Whether validation is performed in the PSyIR backends.
+        if 'BACKEND_CHECKS_ENABLED' in self._config['DEFAULT']:
+            try:
+                self._backend_checks_enabled = (
+                    self._config['DEFAULT'].getboolean(
+                        'BACKEND_CHECKS_ENABLED'))
+            except ValueError as err:
+                raise ConfigurationError(
+                    f"Error while parsing BACKEND_CHECKS_ENABLED: {err}",
+                    config=self) from err
+
         # Now we deal with the API-specific sections of the config file. We
         # create a dictionary to hold the API-specific Config objects.
         self._api_conf = {}
@@ -547,6 +563,31 @@ def default_stub_api(self):
         '''
         return self._default_stub_api
 
+    @property
+    def backend_checks_enabled(self):
+        '''
+        :returns: whether the validity checks in the PSyIR backend should be
+                  disabled.
+        :rtype: bool
+        '''
+        return self._backend_checks_enabled
+
+    @backend_checks_enabled.setter
+    def backend_checks_enabled(self, value):
+        '''
+        Setter for whether or not the PSyIR backend is to perform validation
+        checks.
+
+        :param bool value: whether or not to perform validation.
+
+        :raises TypeError: if `value` is not a boolean.
+
+        '''
+        if not isinstance(value, bool):
+            raise TypeError(f"Config.backend_checks_enabled must be a boolean "
+                            f"but got '{type(value).__name__}'")
+        self._backend_checks_enabled = value
+
     @property
     def supported_stub_apis(self):
         '''

src/psyclone/domain/lfric/arg_ordering.py

@@ -47,6 +47,8 @@
 # a circular dependency.
 from psyclone.domain.lfric import LFRicConstants
 from psyclone.domain.lfric.lfric_symbol_table import LFRicSymbolTable
+from psyclone.domain.lfric.metadata_to_arguments_rules import (
+    MetadataToArgumentsRules)
 from psyclone.errors import GenerationError, InternalError
 from psyclone.psyir.nodes import ArrayReference, Reference
 from psyclone.psyir.symbols import ScalarType
@@ -472,8 +474,8 @@ def generate(self, var_accesses=None):
                     self.diff_basis(unique_fs, var_accesses=var_accesses)
             # Fix for boundary_dofs array to the boundary condition
             # kernel (enforce_bc_kernel) arguments
-            if self._kern.name.lower() == "enforce_bc_code" and \
-               unique_fs.orig_name.lower() == "any_space_1":
+            if (MetadataToArgumentsRules.bc_kern_regex.match(self._kern.name)
+                    and unique_fs.orig_name.lower() == "any_space_1"):
                 self.field_bcs_kernel(unique_fs, var_accesses=var_accesses)
 
         # Add boundary dofs array to the operator boundary condition

src/psyclone/domain/lfric/kernel_interface.py

@@ -586,20 +586,54 @@ def diff_basis(self, function_space, var_accesses=None):
                            basis_name_func, first_dim_value_func)
 
     def field_bcs_kernel(self, function_space, var_accesses=None):
-        '''Not implemented.
+        '''Create the boundary-dofs mask argument required for the
+        enforce_bc_code kernel. Adds it to the symbol table and the argument
+        list.
 
         :param function_space: the function space for this boundary condition.
         :type function_space: :py:class:`psyclone.domain.lfric.FunctionSpace`
-        :param var_accesses: an unused optional argument that stores \
+        :param var_accesses: an unused optional argument that stores
             information about variable accesses.
-        :type var_accesses: :\
-            py:class:`psyclone.core.VariablesAccessInfo`
+        :type var_accesses: :py:class:`psyclone.core.VariablesAccessInfo`
 
-        :raises NotImplementedError: as this method is not implemented.
+        :raises InternalError: if the kernel does not have a single field as
+                               argument.
+        :raises InternalError: if the field argument is not on the
+                               'ANY_SPACE_1' function space.
 
         '''
-        raise NotImplementedError(
-            "TODO #928: field_bcs_kernel not implemented")
+        # Sanity check - expect the enforce_bc_code to have a single argument
+        # that is a field.
+        if (len(self._kern.arguments.args) != 1 or
+                not self._kern.arguments.args[0].is_field):
+            const = LFRicConstants()
+            raise InternalError(
+                f"Kernel '{self._kern.name}' applies boundary conditions to a "
+                f"field and therefore should have a single, field argument "
+                f"(one of {const.VALID_FIELD_NAMES}) but got "
+                f"{[arg.argument_type for arg in self._kern.arguments.args]}")
+        farg = self._kern.arguments.args[0]
+        fspace = farg.function_space
+        # Sanity check - expect the field argument to the enforce_bc_code
+        # kernel to be on the ANY_SPACE_1 space.
+        if fspace.orig_name != "any_space_1":
+            raise InternalError(
+                f"Kernel '{self._kern.name}' applies boundary conditions to a "
+                f"field but the supplied argument, '{farg.name}', is on "
+                f"'{fspace.orig_name}' rather than the expected 'ANY_SPACE_1'")
+
+        ndf_symbol = self._symtab.find_or_create_tag(
+            f"ndf_{fspace.orig_name}", fs=fspace.orig_name,
+            symbol_type=LFRicTypes("NumberOfDofsDataSymbol"),
+            interface=self._read_access)
+
+        # Add the boundary-dofs array argument.
+        sym = self._symtab.find_or_create_tag(
+            f"boundary_dofs_{farg.name}",
+            interface=self._read_access,
+            symbol_type=LFRicTypes("VerticalBoundaryDofMaskDataSymbol"),
+            dims=[Reference(ndf_symbol), 2])
+        self._arglist.append(sym)
 
     def operator_bcs_kernel(self, function_space, var_accesses=None):
         '''Not implemented.