Merge pull request #1745 from stfc/1731_split_loop_class

(towards #1731) Split PSyLoop node from Loop

Author: arporter

changelog

@@ -1,6 +1,9 @@
 	1) PR #1747 for #1720. Adds support for If blocks to PSyAD.
+
 	2) PR #1669 for #450. Remove set_dirty/clean from ACC regions
 
+	3) PR #1745 towards #1731. Split PSyLoop class from Loop node.
+
 release 2.3.0 9th June 2022
 
 	1) PR #1672. Fixes BOZ literal standard incompatibility in the

doc/developer_guide/psyir.rst

@@ -410,28 +410,17 @@ Annotation         Node types         Origin
 Loop Node
 ^^^^^^^^^
 
-The `Loop` node is sub-classed in all of the domains supported by
-PSyclone. This then allows the class to be configured with a
-domain-specific list of valid loop 'types'. For instance, the GOcean
-sub-class, `GOLoop`, has "inner" and "outer" while the LFRic
-(dynamo0.3) sub-class, `DynLoop`, has "dofs", "colours", "colour", ""
-and "null". The default loop type (iterating over cells) is here
-indicated by the empty string. The concept of a "null" loop type is
-currently required because the dependency analysis that determines the
-placement of halo exchanges is handled within the `Loop` class. As a
-result, every `Kernel` call must be associated with a `Loop` node.
-However, the LFRic domain has support for kernels which operate on the
-'domain' and thus do not require a loop over cells or dofs in the
-generated PSy layer. Supporting a `DynLoop` of "null" type allows us
-to retain the dependence-analysis functionality within the `Loop`
-while not actually producing a loop in the generated code. When
-`#1148 <https://github.com/stfc/PSyclone/issues/1148>`_ is tackled,
-the dependence-analysis functionality will be removed from
-the `Loop` class and this concept of a "null" loop can be dropped.
+The `Loop` node is the cannonical representation of a bounded loop, it
+has the start, stop, step and loop_body of the loop as its children. The
+node has the same semantics than the Fortran do construct: the boundary
+values are inclusive (both are part of the iteration space) and the start,
+stop and step expressions are evaluated just once at the beginning of the
+loop.
 
 For more details on the `Loop` node, see the full API in the
 :ref_guide:`reference guide psyclone.psyir.nodes.html#psyclone.psyir.nodes.Loop`.
 
+
 Ranges
 ------
 
@@ -790,11 +779,53 @@ symbols, transformations, front-ends and back-ends. None of this is
 domain specific.
 
 To obtain domain-specific concepts the language-level PSyIR can be
-specialised or extended. In LFRic there are specialisations for
+specialised or extended. All domains follow the PSyKAl separation of
+concerns with the Algorithm-layer and the PSy-layer having its own
+domain-specific concepts, this can be found in
+``psyclone.domain.common.algorithm`` and ``psyclone.domain.common.psylayer``
+respectively (some concepts are still on ``psyclone.psyGen`` for legacy
+reasons but will be moved to the new locations over time).
+
+PSy-layer concepts
+------------------
+
+* The `PSyLoop` is a `Loop` where the boundaries are given by the domain
+  specific iteration space that the kernels are applied to. In turn it is
+  sub-classed in all of the domains supported by PSyclone. This then allows
+  the class to be configured with a list of valid loop 'types'. For instance,
+  the GOcean sub-class, `GOLoop`, has "inner" and "outer" while the LFRic
+  (dynamo0.3) sub-class, `DynLoop`, has "dofs", "colours", "colour", ""
+  and "null". The default loop type (iterating over cells) is here
+  indicated by the empty string. The concept of a "null" loop type is
+  currently required because the dependency analysis that determines the
+  placement of halo exchanges is handled within the `Loop` class. As a
+  result, every `Kernel` call must be associated with a `Loop` node.
+  However, the LFRic domain has support for kernels which operate on the
+  'domain' and thus do not require a loop over cells or dofs in the
+  generated PSy layer. Supporting a `DynLoop` of "null" type allows us
+  to retain the dependence-analysis functionality within the `Loop`
+  while not actually producing a loop in the generated code. When
+  `#1148 <https://github.com/stfc/PSyclone/issues/1148>`_ is tackled,
+  the dependence-analysis functionality will be removed from
+  the `Loop` class and this concept of a "null" loop can be dropped.
+* The `Kern`, which can be of type `CodedKern`, `InlinedKern` or `BuiltIn`
+  are the singular units of computation that can be found inside a
+  `PSyLoop`.
+* The `HaloExchange` is a distributed-memory concept in the PSy-layer.
+* The `GlobalSum` is a distributed-memory concept in the PSy-layer.
+
+
+Other specializations
+---------------------
+
+In LFRic there are specialisations for
 kernel-layer datatypes and symbols. For the algorithm layer in both
 GOcean1.0 and LFRic there are specialisations for invokes and kernel
 calls. This is discussed further in the following sections.
 
+
+
+
 The LFRic PSyIR
 ===============
 

psyclone.pdf

@@ -0,0 +1,40 @@
+# -----------------------------------------------------------------------------
+# BSD 3-Clause License
+#
+# Copyright (c) 2022, 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.
+# -----------------------------------------------------------------------------
+# Authors S. Siso, STFC Daresbury Lab
+
+'''A package module for psyclone.domain.common.psylayer'''
+
+from psyclone.domain.common.psylayer.psyloop import PSyLoop
+
+__all__ = ["PSyLoop"]