#1010 Improve tests and documentation

src/psyclone/domain/lfric/lfric_invoke.py

@@ -271,16 +271,11 @@ def field_on_space(self, func_space):
                 return field
         return None
 
-    def declare(self):
-        ''' Declare and initialise all symbols associated this Invoke.
-        Generates LFRic-specific invocation code (the subroutine
-        called by the associated Invoke call in the algorithm
-        layer). This consists of the PSy invocation subroutine and the
-        declaration of its arguments.
+    def setup_psy_layer_symbols(self):
+        ''' Declare, initialise and deallocate all symbols required by the
+        PSy-layer Invoke subroutine.
 
         '''
-        cursor = 0
-
         # Declare all quantities required by this PSy routine (Invoke)
         for entities in [self.scalar_args, self.fields, self.lma_ops,
                          self.stencil, self.meshes,
@@ -293,6 +288,7 @@ def declare(self):
                          self.run_time_checks]:
             entities.invoke_declarations()
 
+        cursor = 0
         for entities in [self.proxies, self.run_time_checks,
                          self.cell_iterators, self.meshes,
                          self.stencil, self.dofmaps,

src/psyclone/domain/lfric/lfric_kern.py

@@ -543,9 +543,8 @@ def ncolours_var(self):
                                 f"coloured loop.")
         if self.is_intergrid:
             ncols_sym = self._intergrid_ref.ncolours_var_symbol
-            if not ncols_sym:
-                return None
-            return ncols_sym.name
+            if ncols_sym is not None:
+                return ncols_sym.name
 
         return self.scope.symbol_table.lookup_with_tag("ncolour").name
 

src/psyclone/domain/lfric/lfric_psy.py

@@ -122,7 +122,7 @@ def gen(self) -> str:
 
         # Now do the declarations/initialisation on the copied tree
         for invoke in self.invokes.invoke_list:
-            invoke.declare()
+            invoke.setup_psy_layer_symbols()
 
         # Use the PSyIR Fortran backend to generate Fortran code of the
         # supplied PSyIR tree.

src/psyclone/domain/lfric/lfric_stencils.py

@@ -303,9 +303,7 @@ def _unique_extent_vars(self):
 
     def _declare_unique_extent_vars(self):
         '''
-        Declare all unique extent arguments as integers with intent 'in' and
-        add the declaration as a child of the parent argument passed
-        in.
+        Declare all unique extent arguments as integers with intent 'in'.
 
         '''
         if self._unique_extent_vars:
@@ -356,9 +354,7 @@ def _unique_direction_vars(self):
 
     def _declare_unique_direction_vars(self):
         '''
-        Declare all unique direction arguments as integers with intent 'in'
-        and add the declaration as a child of the parent argument
-        passed in.
+        Declare all unique direction arguments as integers with intent 'in'.
 
         '''
         for var in self._unique_direction_vars:

src/psyclone/dynamo0p3.py

@@ -415,7 +415,10 @@ def __init__(self, node):
                     name_lower, symbol_type=DataSymbol,
                     datatype=UnsupportedFortranType(
                         "integer(kind=i_def), pointer :: adjacent_face(:,:) "
-                        "=> null()"
+                        "=> null()",
+                        partial_datatype=ArrayType(
+                            LFRicTypes("LFRicIntegerScalarDataType")(),
+                            [ArrayType.Extent.DEFERRED]*2)
                     ),
                     tag=name_lower)
             else:
@@ -566,6 +569,7 @@ def stub_declarations(self):
         '''
         Creates the necessary declarations for the variables needed in order
         to provide properties of the mesh in a kernel stub.
+        Note that argument order is redefined later by ArgOrdering.
 
         :raises InternalError: if an unsupported mesh property is encountered.
 
@@ -935,8 +939,8 @@ def invoke_declarations(self):
     def stub_declarations(self):
         '''
         Create the necessary declarations for the variables needed in order
-        to provide properties of the reference element in a Kernel stub. Note
-        that argument order is redefined later by ArgOrdering.
+        to provide properties of the reference element in a Kernel stub.
+        Note that argument order is redefined later by ArgOrdering.
 
         '''
         super().stub_declarations()
@@ -1123,6 +1127,7 @@ def __init__(self, kern_or_invoke):
     def stub_declarations(self):
         '''
         Add function-space-related declarations to a Kernel stub.
+        Note that argument order is redefined later by ArgOrdering.
 
         '''
         super().stub_declarations()
@@ -1780,6 +1785,7 @@ def stub_declarations(self):
         '''
         Generate all necessary declarations for CMA operators being passed to
         a Kernel stub.
+        Note that argument order is redefined later by ArgOrdering.
 
         '''
         super().stub_declarations()
@@ -1838,7 +1844,7 @@ def stub_declarations(self):
             op = symtab.find_or_create(
                 op_name, symbol_type=DataSymbol,
                 datatype=ArrayType(
-                    LFRicTypes("LFRicIntegerScalarDataType")(),
+                    LFRicTypes("LFRicRealScalarDataType")(),
                     [Reference(bandwidth), Reference(nrow),
                      Reference(symtab.lookup("ncell_2d"))]))
             op.interface = ArgumentInterface(
@@ -2023,12 +2029,16 @@ def colourmap_init(self):
             carg_name = call._intergrid_ref.coarse.name
             # Colour map
             base_name = "cmap_" + carg_name
+            array_type = ArrayType(
+                LFRicTypes("LFRicRealScalarDataType")(),
+                [ArrayType.Extent.DEFERRED]*2)
             colour_map = self.symtab.find_or_create(
                 base_name,
                 symbol_type=DataSymbol,
                 datatype=UnsupportedFortranType(
                     f"integer(kind=i_def), pointer, dimension(:,:) :: "
-                    f"{base_name} => null()"),
+                    f"{base_name} => null()",
+                    partial_datatype=array_type),
                 tag=base_name)
             # No. of colours
             base_name = "ncolour_" + carg_name
@@ -2338,8 +2348,9 @@ def initialise(self, cursor: int) -> int:
                             coarse_mesh, [name])))
                 self._invoke.schedule.addchild(assignment, cursor)
                 cursor += 1
-        self._invoke.schedule[comment_cursor].preceding_comment = (
-            "Look-up mesh objects and loop limits for inter-grid kernels")
+        if cursor != comment_cursor:
+            self._invoke.schedule[comment_cursor].preceding_comment = (
+                "Look-up mesh objects and loop limits for inter-grid kernels")
 
         return cursor
 
@@ -2409,12 +2420,19 @@ def __init__(self, fine_arg, coarse_arg):
         ).name
         # Name for cell map
         base_name = "cell_map_" + coarse_arg.name
+        ArrayType(
+            LFRicTypes("LFRicRealScalarDataType")(),
+            [ArrayType.Extent.DEFERRED]*2)
         sym = symtab.find_or_create(
                 base_name,
                 symbol_type=DataSymbol,
                 datatype=UnsupportedFortranType(
                     f"integer(kind=i_def), pointer :: {base_name}"
-                    f"(:,:,:) => null()"))
+                    f"(:,:,:) => null()",
+                    partial_datatype=ArrayType(
+                        LFRicTypes("LFRicRealScalarDataType")(),
+                        [ArrayType.Extent.DEFERRED]*3)
+                ))
 
         self.cell_map = sym.name
 
@@ -2713,6 +2731,7 @@ def stub_declarations(self):
         '''
         Insert the variable declarations required by the basis functions into
         the Kernel stub.
+        Note that argument order is redefined later by ArgOrdering.
 
         :raises InternalError: if an unsupported quadrature shape is found.
 
@@ -2736,6 +2755,8 @@ def stub_declarations(self):
                 arg.interface = ArgumentInterface(
                                         ArgumentInterface.Access.READ)
                 self.symtab.append_argument(arg)
+
+        # Allocate basis arrays
         for basis in basis_arrays:
             dims = []
             for value in basis_arrays[basis]:
@@ -3263,12 +3284,16 @@ def _initialise_face_or_edge_qr(self, cursor, qr_type):
                     symbol_type=DataSymbol,
                     datatype=LFRicTypes("LFRicIntegerScalarDataType")())
 
+            array_type = ArrayType(
+                LFRicTypes("LFRicRealScalarDataType")(),
+                [ArrayType.Extent.DEFERRED]*2)
             for name in self.qr_weight_vars[qr_type]:
                 self.symtab.find_or_create(
                     f"{name}_{qr_arg_name}", symbol_type=DataSymbol,
                     datatype=UnsupportedFortranType(
                         f"real(kind=r_def), pointer, dimension(:,:) :: "
-                        f"{name}_{qr_arg_name} => null()\n"
+                        f"{name}_{qr_arg_name} => null()\n",
+                        partial_datatype=array_type
                     ),
                     tag=f"{name}_{qr_arg_name}")
             const = LFRicConstants()
@@ -3553,7 +3578,11 @@ def invoke_declarations(self):
             kind = api_config.default_kind["integer"]
             dtype = UnsupportedFortranType(
                 f"integer(kind={kind}), pointer "
-                f":: {name}(:,:) => null()")
+                f":: {name}(:,:) => null()",
+                partial_datatype=ArrayType(
+                    LFRicTypes("LFRicIntegerScalarDataType")(),
+                    [ArrayType.Extent.DEFERRED]*2)
+                )
             self.symtab.new_symbol(
                 name,
                 symbol_type=DataSymbol,
@@ -3562,6 +3591,7 @@ def invoke_declarations(self):
     def stub_declarations(self):
         '''
         Add declarations for any boundary-dofs arrays required by a kernel.
+        Note that argument order is redefined later by ArgOrdering.
 
         '''
         super().stub_declarations()
@@ -4353,6 +4383,8 @@ class HaloDepth():
                    access that is represented.
     :type parent: :py:class:`psyclone.psyir.nodes.Node`
 
+    :raises TypeError: if the parent argument is not a Node.
+
     '''
     def __init__(self, parent):
         # var_depth is used to store the PSyIR of the expression holding
@@ -5420,9 +5452,10 @@ def generate_method_call(self, method, function_space=None,
         '''
         Generate a PSyIR call to the given method of this object.
 
-        :param str method: name of the method to generate.
+        :param str method: name of the method to generate a call to.
         :param Optional[str] function_space: name of the function space.
-        :param bool: if we generate the call by using the proxy as the base.
+        :param bool use_proxy: if we generate the call by using the proxy
+            as the base.
 
         :returns: the generated call.
         :rtype: :py:class:`psyclone.psyir.nodes.Call`
@@ -5437,16 +5470,17 @@ def generate_method_call(self, method, function_space=None,
             symbol = symtab.lookup(self.name)
 
         if self._vector_size > 1:
+            # For a field vector, just call the specified method on the first
+            # element
             return Call.create(ArrayOfStructuresReference.create(
                 symbol, [Literal('1', INTEGER_TYPE)],
                 [self.ref_name(function_space), method]))
-        else:
-            return Call.create(StructureReference.create(
-                symbol, [self.ref_name(function_space), method]))
+        return Call.create(StructureReference.create(
+            symbol, [self.ref_name(function_space), method]))
 
     def generate_accessor(self, function_space=None):
         '''
-        Generate a Reference accessing this object data.
+        Generate a Reference accessing this object's data.
 
         :param Optional[str] function_space: name of the function space.
 
@@ -5460,12 +5494,12 @@ def generate_accessor(self, function_space=None):
         symbol = symtab.lookup(self.proxy_name)
 
         if self._vector_size > 1:
+            # For a field vector, access the first element
             return ArrayOfStructuresReference.create(
                 symbol, [Literal('1', INTEGER_TYPE)],
                 [self.ref_name(function_space)])
-        else:
-            return StructureReference.create(
-                symbol, [self.ref_name(function_space)])
+        return StructureReference.create(
+            symbol, [self.ref_name(function_space)])
 
     def ref_name(self, function_space=None):
         '''

src/psyclone/gen_kernel_stub.py

@@ -61,12 +61,12 @@ def generate(filename, api=""):
     Kernel Metadata must be presented in the standard Kernel
     format.
 
-    :param str filename: the name of the file for which to create a \
-                         kernel stub for.
-    :param str api: the name of the API for which to create a kernel \
-                    stub. Must be one of the supported stub APIs.
+    :param str filename: the name of the file for which to create a
+        kernel stub for.
+    :param str api: the name of the API for which to create a kernel
+        stub. Must be one of the supported stub APIs.
 
-    :returns: the kernel stub of the given kernel file.
+    :returns: the kernel stub of the metadata in the given kernel file.
     :rtype: str
 
     :raises GenerationError: if an invalid stub API is specified.

src/psyclone/gocean1p0.py

@@ -914,18 +914,18 @@ def _validate_loop(self):
                                       f" '{kernel.index_offset}' which does "
                                       f"not match '{index_offset}'.")
 
-    def gen_code(self, parent):
-        ''' Create the f2pygen AST for this loop (and update the PSyIR
-        representing the loop bounds if necessary).
+    # def gen_code(self, parent):
+    #     ''' Create the f2pygen AST for this loop (and update the PSyIR
+    #     representing the loop bounds if necessary).
 
-        :param parent: the node in the f2pygen AST to which to add content.
-        :type parent: :py:class:`psyclone.f2pygen.SubroutineGen`
+    #     :param parent: the node in the f2pygen AST to which to add content.
+    #     :type parent: :py:class:`psyclone.f2pygen.SubroutineGen`
 
-        '''
-        # Check that it is a properly formed GOLoop
-        self._validate_loop()
+    #     '''
+    #     # Check that it is a properly formed GOLoop
+    #     self._validate_loop()
 
-        super().gen_code(parent)
+    #     super().gen_code(parent)
 
 
 # pylint: disable=too-few-public-methods