Merge remote-tracking branch 'origin/master' into 2778_removed_old_todos

.github/workflows/compilation.yml

@@ -130,5 +130,5 @@ jobs:
         module load nvidia-hpcsdk/${NVFORTRAN_VERSION}
         module load hdf5/${HDF5_VERSION} netcdf_c/${NETCDF_C_VERSION} netcdf_fortran/${NETCDF_FORTRAN_VERSION}
         F90=nvfortran F90FLAGS="-acc -Minfo=all" make -C tutorial/practicals/LFRic compile
-        F90=nvfortran F90FLAGS="-acc -Minfo=all -Mnofma -O2" make -C tutorial/practicals/nemo run
-        make -C tutorial/practicals/nemo/4_nemo_openacc acc_test
+        F90=nvfortran F90FLAGS="-acc -Minfo=all -Mnofma -O2" make -C tutorial/practicals/generic run
+        make -C tutorial/practicals/generic/4_openacc acc_test

.github/workflows/python-package.yml

@@ -76,7 +76,7 @@ jobs:
     # Now we can check for warnings and broken links
     - run: cd doc/user_guide; make html SPHINXOPTS="-W --keep-going"
     - run: cd doc/developer_guide; make html SPHINXOPTS="-W --keep-going"
-    # TODO #1280: - run: cd doc/reference_guide; make html SPHINXOPTS="-W --keep-going"
+    - run: cd doc/reference_guide; make html SPHINXOPTS="-W --keep-going"
     - run: cd doc/psyad/user_guide; make html SPHINXOPTS="-W --keep-going"
     - run: cd doc/user_guide; make linkcheck
     - run: cd doc/developer_guide; make linkcheck

changelog

@@ -279,6 +279,8 @@
 
 	106) PR #2770 towards #2543. Improve UG introduction.
 
+	107) PR #2776 for #1280. Fixes ref_guide warnings.
+
 release 2.5.0 14th of February 2024
 
 	1) PR #2199 for #2189. Fix bugs with missing maps in enter data

doc/reference_guide/source/conf.py

@@ -16,8 +16,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-import subprocess
+import enum
 import os
+import subprocess
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
@@ -204,9 +205,36 @@
 epub_exclude_files = ['search.html']
 
 
-# -- Extension configuration -------------------------------------------------
+# -- Autodoc configuration ---------------------------------------------------
+
+
+def remove_op_enum_attrib_docstring(app, what, name, obj, skip, options):
+    '''
+    A handler that ensures any EnumType objects named 'Operator' are *not*
+    documented. This is required to avoid warnings of the form:
+
+        psyclone/psyir/nodes/operation.py:docstring of
+        psyclone.psyir.nodes.operation.Operator:1: WARNING: duplicate object
+        description of psyclone.psyir.nodes.operation.Operator, other instance
+        in autogenerated/psyclone.psyir.nodes, use :no-index: for one of them
+
+    '''
+    # EnumMeta is used for compatibility with Python < 3.11.
+    if name.endswith("Operator") and isinstance(obj, enum.EnumMeta):
+        return True
+    return skip
+
+
+def setup(app):
+    '''
+    Add in our custom handler to avoid documentation warnings for the various
+    Operator members of psyir.nodes.*Operation.
+
+    '''
+    app.connect('autodoc-skip-member', remove_op_enum_attrib_docstring)
+
 
-# Generate the Doxygen documentation
+# -- Generate the Doxygen documentation --------------------------------------
 subprocess.call('cd ..; doxygen doxygen.config', shell=True)
 # If we want to completely replace the Sphinx-generated documentation
 # with that constructed by Doxygen then we uncomment the line below.

examples/nemo/eg5/Makefile

@@ -62,13 +62,13 @@ GENERATED_FILES += psy.f90 psy.o traadv-$(TYPE).exe output.dat
 # Pick up the right extraction library:
 PSYROOT=../../..
 ifeq ($(TYPE), netcdf)
-	EXTRACT_DIR ?= $(PSYROOT)/lib/extract/netcdf/nemo
+	EXTRACT_DIR ?= $(PSYROOT)/lib/extract/netcdf/generic
 	READ_DIR ?= $(PSYROOT)/lib/extract/netcdf
 	F90FLAGS += $$(nf-config --fflags)
 	LDFLAGS += $$(nf-config --flibs) $$(nc-config --libs)
 	GENERATED_FILES += tra_adv-r?.nc
 else
-	EXTRACT_DIR ?= $(PSYROOT)/lib/extract/standalone/nemo
+	EXTRACT_DIR ?= $(PSYROOT)/lib/extract/standalone/generic
 	READ_DIR ?= $(PSYROOT)/lib/extract/standalone
 	GENERATED_FILES += tra_adv-r?.binary
 endif

examples/nemo/eg5/README.md

@@ -20,7 +20,7 @@ by supplying the `-l all` flag to PSyclone (as is done in the Makefile).
 
 
 The stand-alone extraction library in
-``../../../lib/extract/standalone/nemo`` is used as default, and
+``../../../lib/extract/standalone/generic`` is used as default, and
 will also be automatically compiled. You can also use the NetCDF based
 extraction library by setting the environment variable `TYPE` to `netcdf`
 when calling `make`, e.g.:
@@ -29,7 +29,7 @@ when calling `make`, e.g.:
 
 This requires NetCDF to be available (including ``nf-config`` to detect
 installation-specific paths). The NetCDF-based extraction library in
-``../../../../lib/extract/netcdf/nemo``
+``../../../../lib/extract/netcdf/generic``
 will also be automatically compiled.
 
 The binary  instrumented for extraction will either be called

src/psyclone/domain/lfric/algorithm/psyir/__init__.py

@@ -46,11 +46,3 @@
     LFRicKernelFunctor)
 from psyclone.domain.lfric.algorithm.psyir.lfric_kernel_functor import (
     LFRicBuiltinFunctorFactory)
-
-
-# For Sphinx AutoAPI
-__all__ = [
-    'LFRicAlgorithmInvokeCall',
-    'LFRicKernelFunctor',
-    'LFRicBuiltinFunctor',
-    'LFRicBuiltinFunctorFactory']

src/psyclone/domain/lfric/kern_call_arg_list.py

@@ -42,7 +42,7 @@
 should be removed as we migrate to use PSyIR in LFRic.
 '''
 
-from collections import namedtuple
+from dataclasses import dataclass
 
 from psyclone import psyGen
 from psyclone.core import AccessType, Signature
@@ -75,7 +75,16 @@ class KernCallArgList(ArgOrdering):
     :type kern: :py:class:`psyclone.domain.lfric.LFRicKern`
 
     '''
-    NdfInfo = namedtuple("NdfInfo", ["position", "function_space"])
+    @dataclass(frozen=True)
+    class NdfInfo:
+        '''
+        Holds information relating to the number-of-dofs kernel argument.
+
+        :param position: the position of this argument in the argument list.
+        :param function_space: the function space that this argument is for.
+        '''
+        position: int = None
+        function_space: str = None
 
     def __init__(self, kern):
         super().__init__(kern)

src/psyclone/domain/lfric/lfric_kern.py

@@ -39,8 +39,9 @@
 ''' This module implements the PSyclone LFRic API by specialising the required
     base class Kern in psyGen.py '''
 
-# Imports
-from collections import OrderedDict, namedtuple
+from collections import OrderedDict
+from dataclasses import dataclass
+from typing import List
 
 from psyclone.configuration import Config
 from psyclone.core import AccessType
@@ -69,16 +70,22 @@ class LFRicKern(CodedKern):
 
     '''
     # pylint: disable=too-many-instance-attributes
-    # An instance of this `namedtuple` is used to store information on each of
-    # the quadrature rules required by a kernel.
-    #
-    # alg_name: The actual argument text specifying the QR object in the
-    #           Alg. layer.
-    # psy_name: The PSy-layer variable name for the QR object.
-    # kernel_args: List of kernel arguments associated with this QR rule.
 
-    QRRule = namedtuple("QRRule",
-                        ["alg_name", "psy_name", "kernel_args"])
+    @dataclass(frozen=True)
+    class QRRule:
+        '''
+        Used to store information on a quadrature rule required by
+        a kernel.
+
+        :param alg_name: The actual argument text specifying the QR object in
+                         the Alg. layer.
+        :param psy_name: The PSy-layer variable name for the QR object.
+        :param kernel_args: Kernel arguments associated with this QR rule.
+
+        '''
+        alg_name: str
+        psy_name: str
+        kernel_args: List[str]
 
     def __init__(self):
         # The super-init is called from the _setup() method which in turn
@@ -635,8 +642,8 @@ def gen_stub(self):
         :rtype: :py:class:`fparser.one.block_statements.Module`
 
         :raises GenerationError: if the supplied kernel stub does not operate
-            on a supported subset of the domain (currently only
-            "*cell_column").
+            on a supported subset of the domain (currently only those that
+            end with "cell_column").
 
         '''
         # The operates-on/iterates-over values supported by the stub generator.

src/psyclone/psyad/adjoint_visitor.py

@@ -451,10 +451,10 @@ def _copy_and_process(self, node):
             if isinstance(symbol_obj,
                           GenericInterfaceSymbol):
                 new_routines = []
-                for rsym, mod_pro in symbol_obj.routines:
+                for rinfo in symbol_obj.routines:
                     new_routines.append((
-                            sym_tab.lookup(rsym.name),
-                            mod_pro
+                            sym_tab.lookup(rinfo.symbol.name),
+                            rinfo.from_container
                     ))
                 symbol_obj.routines = new_routines
 

src/psyclone/psyir/frontend/fparser2.py

@@ -396,9 +396,9 @@ def _find_or_create_psyclone_internal_cmp(node):
             routine_symbol3 = container.symbol_table.lookup(name_f_char)
             symbol = GenericInterfaceSymbol(
                     sym.name,
-                    [(routine_symbol1, sym.routines[0][1]),
-                     (routine_symbol2, sym.routines[1][1]),
-                     (routine_symbol3, sym.routines[2][1])],
+                    [(routine_symbol1, sym.routines[0].from_container),
+                     (routine_symbol2, sym.routines[1].from_container),
+                     (routine_symbol3, sym.routines[2].from_container)],
                     visibility=sym.visibility
                     )
             container.symbol_table.add(symbol)

src/psyclone/psyir/nodes/container.py

@@ -307,7 +307,7 @@ def resolve_routine(self, name):
         except KeyError:
             return []
         if isinstance(rsym, GenericInterfaceSymbol):
-            return [rt[0].name.lower() for rt in rsym.routines]
+            return [rt.symbol.name.lower() for rt in rsym.routines]
         if isinstance(rsym, RoutineSymbol):
             return [name]
         if type(rsym) is Symbol and rsym.is_import:

src/psyclone/psyir/nodes/operation.py

@@ -64,10 +64,10 @@ class Operation(DataNode, metaclass=ABCMeta):
                        self.Operator.
 
     '''
-    # Must be overridden in sub-class to hold an Enumeration of the Operators
-    # that it can represent.
+    #: Must be overridden in sub-class to hold an Enumeration of the Operators
+    #: that it can represent.
     Operator = object
-    # Colour of the node in a view tree.
+    #: Colour of the node in a view tree.
     _colour = "blue"
 
     def __init__(self, operator, parent=None):
@@ -140,6 +140,7 @@ class UnaryOperation(Operation):
     # Textual description of the node.
     _children_valid_format = "DataNode"
 
+    #: The Operators that a UnaryOperation can represent.
     Operator = Enum('Operator', [
         # Arithmetic Operators
         'MINUS', 'PLUS',
@@ -209,6 +210,7 @@ class BinaryOperation(Operation):
     as children 0 and 1, and an attribute with the operator type.
 
     '''
+    #: The Operators that a BinaryOperation can represent.
     Operator = Enum('Operator', [
         # Arithmetic Operators. ('REM' is remainder AKA 'MOD' in Fortran.)
         'ADD', 'SUB', 'MUL', 'DIV', 'REM', 'POW',

src/psyclone/psyir/symbols/__init__.py

@@ -56,7 +56,7 @@
      ArrayType, BOOLEAN_TYPE, CHARACTER_TYPE, DataType, INTEGER4_TYPE,
      INTEGER8_TYPE, INTEGER_DOUBLE_TYPE, INTEGER_SINGLE_TYPE, INTEGER_TYPE,
      NoType, REAL4_TYPE, REAL8_TYPE, REAL_DOUBLE_TYPE, REAL_SINGLE_TYPE,
-     REAL_TYPE, ScalarType, StructureType, TYPE_MAP_TO_PYTHON, UnresolvedType,
+     REAL_TYPE, ScalarType, StructureType, UnresolvedType,
      UnsupportedType, UnsupportedFortranType)
 
 # For auto documentation generation.
@@ -93,7 +93,6 @@
            'Symbol',
            'SymbolError',
            'SymbolTable',
-           'TYPE_MAP_TO_PYTHON',
            'TypedSymbol',
            'UnsupportedFortranType',
            'UnknownInterface',

src/psyclone/psyir/symbols/datasymbol.py

@@ -243,11 +243,10 @@ def initial_value(self, new_value):
                             f"{node}")
                 new_initial_value = new_value
             else:
-                from psyclone.psyir.symbols.datatypes import TYPE_MAP_TO_PYTHON
                 # No need to check that self.datatype has an intrinsic
                 # attribute as we know it is a ScalarType or ArrayType
                 # due to an earlier test.
-                lookup = TYPE_MAP_TO_PYTHON[self.datatype.intrinsic]
+                lookup = ScalarType.TYPE_MAP_TO_PYTHON[self.datatype.intrinsic]
                 if not isinstance(new_value, lookup):
                     raise ValueError(
                         f"Error setting initial value for symbol "