(closes #1010, #1910, #719, #798, #1648) Generate PSy-layers and Kernel Subs using PSyIR lowering (instead of gen_code/f2pygen)

doc/developer_guide/APIs.rst

@@ -141,27 +141,6 @@ TBD
 .. classname being provided. This allow them to instantiate the
 .. appropriate objects without knowing what they are.
 ..
-.. gen_code()
-.. ++++++++++
-..
-.. All of the above classes (with the exception of PSy which supports a
-.. gen() method) have the gen_code() method. This method passes the
-.. parent of the generation tree and expect the object to add the code
-.. associated with the object as a child of the parent. The object is
-.. then expected to call any children. This approach is powerful as it
-.. lets each object concentrate on the code that it is responsible for.
-..
-.. Adding code in gen_code()
-.. +++++++++++++++++++++++++
-..
-.. The f2pygen classes have been developed to help create appropriate
-.. fortran code in the gen_code() method.
-..
-.. When writing a gen_code() method for a particular object and API it is
-.. natural to add code as a child of the parent provided by the callee of
-.. the method. However, in some cases we do not want code to appear at
-.. the current position in the hierarchy.
-..
 .. The add() method
 .. ++++++++++++++++
 ..
@@ -633,8 +612,7 @@ operator are computed redundantly in the halo up to depth-1 (see the
 requires a check that any loop which includes a kernel that reads from
 an operator is limited to iterating in the halo up to
 depth-1. PSyclone will raise an exception if an optimisation attempts
-to increase the iteration space beyond this (see the ``gen_code()``
-method in the ``LFRicKern`` class).
+to increase the iteration space beyond this point.
 
 To alleviate the above restriction one could add a configurable depth with
 which to compute operators e.g. operators are always computed up to
@@ -1201,50 +1179,6 @@ the `w0` function space then at least one of the the `meta_arg`
 arguments must be on the `w0` function space. However, this is not
 checked in the current implementation.
 
-GOcean1.0
-=========
-
-TBD
-
-.. OpenMP Support
-.. --------------
-..
-.. Loop directives are treated as first class entities in the psyGen
-.. package. Therefore they can be added to psyGen's high level
-.. representation of the fortran code structure in the same way as calls
-.. and loops. Obviously it is only valid to add a loop directive outside
-.. of a loop.
-..
-.. When adding a call inside a loop the placement of any additional calls
-.. or declarations must be specified correctly to ensure that they are
-.. placed at the correct location in the hierarchy. To avoid accidentally
-.. splitting the loop directive from its loop the start_parent_loop()
-.. method can be used. This is available as a method in all fortran
-.. generation calls. *We could have placed it in psyGen instead of
-.. f2pygen*.  This method returns the location at the top of any loop
-.. hierarchy and before any comments immediately before the top level
-.. loop.
-..
-.. The OpenMPLoopDirective object needs to know which variables are
-.. shared and which are private. In the current implementation default
-.. shared is used and private variables are listed. To determine the
-.. objects private variables the OpenMP implementation uses its internal
-.. xxx_get_private_list() method. This method first finds all loops
-.. contained within the directive and adds each loops variable name as a
-.. private variable. this method then finds all calls contained within
-.. the directive and adds each calls list of private variables, returned
-.. with the local_vars() method. Therefore the OpenMPLoopDirective object
-.. relies on calls specifying which variables they require being local.
-..
-.. Next ...
-..
-.. Update transformation for colours
-..
-.. OpenMPLoop transformation in transformations.py.
-..
-.. Create third transformation which goes over all loops in a schedule and
-.. applies the OpenMP loop transformation.
-
 NEMO
 ====
 

doc/developer_guide/modules.rst

@@ -40,67 +40,6 @@ Modules
 This section describes the functionality of the various Python modules
 that make up PSyclone.
 
-Module: f2pygen
-===============
-
-.. warning::
-   The f2pygen functionality has been superseded by the development of
-   the PSyIR and will be removed entirely in a future release.
-
-`f2pygen` provides functionality for generating Fortran code from
-scratch and supports the addition of a use statement to an existing
-parse tree.
-
-Variable Declarations
----------------------
-
-Three different classes are provided to support the creation of
-variable declarations (for intrinsic, character and derived-type
-variables). An example of their use might be:
-
->>> from psyclone.f2pygen import (ModuleGen, SubroutineGen, DeclGen,
-... CharDeclGen, TypeDeclGen)
->>> module = ModuleGen(name="testmodule")
->>> sub = SubroutineGen(module, name="testsubroutine")
->>> module.add(sub)
->>> sub.add(DeclGen(sub, datatype="integer", entity_decls=["my_int"]))
->>> sub.add(CharDeclGen(sub, length="10", entity_decls=["my_char"]))
->>> sub.add(TypeDeclGen(sub, datatype="field_type", entity_decls=["ufld"]))
->>> gen = str(module.root)
->>> print(gen)
-  MODULE testmodule
-    IMPLICIT NONE
-    CONTAINS
-    SUBROUTINE testsubroutine()
-      TYPE(field_type) ufld
-      CHARACTER(LEN=10) my_char
-      INTEGER my_int
-    END SUBROUTINE testsubroutine
-  END MODULE testmodule
-
-The full interface to each of these classes is detailed below:
-
-.. autoclass:: psyclone.f2pygen.DeclGen
-    :members:
-    :noindex:
-
-.. autoclass:: psyclone.f2pygen.CharDeclGen
-    :members:
-    :noindex:
-
-.. autoclass:: psyclone.f2pygen.TypeDeclGen
-    :members:
-    :noindex:
-
-Adding code
------------
-
-`f2pygen` supports the addition of use statements to an existing
-`fparser1` parse tree:
-
-.. autofunction:: psyclone.f2pygen.adduse
-
-
 .. _dev_configuration:
 
 Module: configuration
@@ -252,7 +191,7 @@ Module: dynamo0p3
 =================
 
 Specialises various classes from the ``psyclone.psyGen`` module
-in order to support the Dynamo 0.3 API.
+in order to support the LFRic API.
 
 When constructing the Fortran subroutine for either an Invoke or
 Kernel stub (see :ref:`stub-generation`), there are various groups of
@@ -265,15 +204,15 @@ sub-class of the ``LFRicCollection`` abstract class:
    :private-members:
    :noindex:
 
-(A single base class is used for both Invokes and Kernel stubs since it
-allows the code dealing with variable declarations to be shared.)
+A single ``LFRicCollection`` class is used for both Invokes and Kernel stubs
+since it allows the code dealing with variable declarations to be shared.
 A concrete sub-class of ``LFRicCollection`` must provide an
-implementation of the ``_invoke_declarations`` method. If the
+implementation of the ``invoke_declarations`` method. If the
 quantities associated with the collection require initialisation
 within the PSy layer then the ``initialise`` method must also be
 implemented. If stub-generation is to be supported for kernels that
 make use of the collection type then an implementation must also be
-provided for ``_stub_declarations.``
+provided for ``stub_declarations``.
 
 Although instances of (sub-classes of) ``LFRicCollection`` handle all
 declarations and initialisation, there remains the problem of

doc/developer_guide/psy_data.rst

@@ -461,7 +461,7 @@ The derived classes will typically control the behaviour
 of ``PSyDataNode`` by providing additional parameters.
 
 .. autoclass:: psyclone.psyir.nodes.PSyDataNode
-    :members: gen_code
+    :members:
 
 There are two ways of passing options to the
 ``PSyDataNode``. The first one is used to pass
@@ -488,8 +488,8 @@ can be somewhat cryptic due to the need to be unique).
 The region name is validated by ``PSyDataTrans``, and
 then passed to the node constructor. The ``PSyDataNode``
 stores the name as an instance attribute, so that they can
-be used at code creation time (when ``gen_code`` is being
-called). Below is the list of all options that the PSyData
+be used at code creation time (PSyIR lowering).
+Below is the list of all options that the PSyData
 node supports in the option dictionary:
 
 .. table::
@@ -516,15 +516,15 @@ node supports in the option dictionary:
 
 Passing Parameter From a Derived Node to the ``PSyDataNode``
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-The ``PSyDataTrans.gen_code`` function also accepts
-an option dictionary, which is used by derived nodes
-to control code creation. The ``gen_code`` function
-is called internally, not directly by the user. If
-the ``gen_code`` function of a node derived from
-``PSyDataNode`` is called, it can define this
+The ``PSyDataNode.lower_to_language_level`` function also accepts
+an option dictionary, which is used by derived nodes to control code
+creation.
+The ``lower_to_language_level`` function is called internally, not
+directly by the user. If the ``lower_to_language_level`` function of a
+node derived from ``PSyDataNode`` is called, it can define this
 option directory to pass the parameters to the ``PSyDataNode``'s
-``gen_code`` function. Here are the options that are currently
-supported by ``PSyDataNode``:
+``lower_to_language_level`` function. Here are the options that are
+currently supported by ``PSyDataNode``:
 
 ================ =========================================
 Parameter Name   Description
@@ -554,9 +554,9 @@ for more details.
 
 The kernel extraction node ``ExtractNode`` uses the dependency
 module to determine which variables are input- and output-parameters,
-and provides these two lists to the ``gen_code()`` function of its base class,
-a ``PSyDataNode`` node. It also uses the ``post_var_postfix`` option
-as described under ``gen_code()`` above (see also
+and provides these two lists to the ````lower_to_language_level``()`` function
+of its base class, a ``PSyDataNode`` node. It also uses the ``post_var_postfix``
+option as described under ``lower_to_language_level``()`` above (see also
 :ref:`user_guide:extraction_libraries`).
 
 .. _psydata_base_class:

doc/developer_guide/psyir.rst

@@ -700,8 +700,7 @@ psyclone.psyir.nodes.html#psyclone.psyir.nodes.Directive`.
 .. warning::
     Some parts of some Clauses are still under development, and not all clauses
     are encoded in Clauses classes yet (for example OpenACC clauses). These
-    clause strings are instead generated inside the ``begin_string`` or
-    ``gen_code`` methods during code generation.
+    clause strings are instead generated inside the ``begin_string``.
 
 .. _named_arguments-label:
 
@@ -991,9 +990,7 @@ The Kernel-layer subclasses will be used to:
    translated into LFRic PSyIR using the expected datatypes as
    specified by the kernel metadata and associated LFRic rules.
 
-3) replace the existing kernel stub generation implementation so that
-   the PSyIR back ends can be used and PSyclone will rely less on
-   ``f2pygen`` and ``fparser1``. At the moment ``kernel_interface``
+3) At the moment ``kernel_interface``
    provides the same functionality as ``kern_stub_arg_list``, except
    that it uses the symbol table (which keeps datatypes and their
    declarations together).
@@ -1087,9 +1084,8 @@ correspond to and how the arguments relate to each other (they just
 output strings).
 
 The logic and declaration of kernel variables is handled separately by
-the ``gen_stub`` method in ``LFRicKern`` and the ``gen_code`` method in
-``LFRicInvoke``. In both cases these methods make use of the subclasses
-of ``LFRicCollection`` to declare variables.
+the ``stub_declarations`` and ``invoke_declarations`` methods in the
+appropriate ``LFRicCollection``.
 
 When using the symbol table in the LFRic PSyIR we naturally capture
 arguments and datatypes together. The ``KernelInterface`` class is

doc/user_guide/dynamo0p3_topclasses.dot

@@ -2,14 +2,14 @@ digraph "classes_dynamo0p3" {
 charset="utf-8"
 rankdir=BT
 
-"20" [label="{LFRicInvoke|\l|arg_for_funcspace()\lfield_on_space()\lgen_code()\lis_coloured()\lunique_fss()\lunique_proxy_declarations()\l}", shape="record"];
+"20" [label="{LFRicInvoke|\l|arg_for_funcspace()\lfield_on_space()\lis_coloured()\lunique_fss()\lunique_proxy_declarations()\l}", shape="record"];
 "21" [label="{LFRicInvokeSchedule|\l|view()\l}", shape="record"];
 "35" [label="{DynamoInvokes|\l|}", shape="record"];
 "36" [label="{LFRicPSy|\l|}", shape="record"];
-"45" [label="{Invoke|\l|first_access()\lgen()\lgen_code()\lunique_declarations()\lunique_declns_by_intent()\l}", shape="record", style=filled, fillcolor="antiquewhite"];
-"46" [label="{InvokeSchedule|\l|gen_code()\lview()\l}", shape="record"];
-"47" [label="{Invokes|\l|gen_code()\lgen_ocl_init()\lget()\l}", shape="record", style=filled, fillcolor="antiquewhite"];
-"54" [label="{Node|\l|addchild()\lancestor()\lbackward_dependence()\lcalls()\ldag()\ldag_gen()\lfollowing()\lforward_dependence()\lgen_c_code()\lgen_code()\lindent()\lis_openmp_parallel()\lis_valid_location()\lkern_calls()\llist()\llist_to_string()\lloops()\lpreceding()\lreductions()\lsameParent()\lsameRoot()\lupdate()\lview()\lwalk()\l}", shape="record"];
+"45" [label="{Invoke|\l|first_access()\lgen()\lunique_declarations()\lunique_declns_by_intent()\l}", shape="record", style=filled, fillcolor="antiquewhite"];
+"46" [label="{InvokeSchedule|\l|view()\l}", shape="record"];
+"47" [label="{Invokes|\l|gen_ocl_init()\lget()\l}", shape="record", style=filled, fillcolor="antiquewhite"];
+"54" [label="{Node|\l|addchild()\lancestor()\lbackward_dependence()\lcalls()\ldag()\ldag_gen()\lfollowing()\lforward_dependence()\lgen_c_code()\lindent()\lis_openmp_parallel()\lis_valid_location()\lkern_calls()\llist()\llist_to_string()\lloops()\lpreceding()\lreductions()\lsameParent()\lsameRoot()\lupdate()\lview()\lwalk()\l}", shape="record"];
 "55" [label="{PSy|\l|inline()\l}", shape="record", style=filled, fillcolor="antiquewhite"];
 "56" [label="{Schedule|\l|view()\l}", shape="record", style=filled, fillcolor="antiquewhite"];
 

doc/user_guide/gocean1p0.rst

@@ -650,9 +650,7 @@ Rules
 #####
 
 Kernel arguments follow a set of rules which have been specified for
-the GOcean 1.0 API. These rules are encoded in the ``gen_code()``
-method of the ``GOKern`` class in the ``gocean1p0.py`` file. The
-rules, along with PSyclone's naming conventions, are:
+the GOcean 1.0 API. The rules, along with PSyclone's naming conventions, are:
 
 1) Every kernel has the indices of the current grid point as the first two arguments, ``i`` and ``j``. These are integers and have intent ``in``.
 

doc/user_guide/psyke.rst

@@ -224,8 +224,8 @@ PSyclone modifies the Schedule of the selected ``invoke_0``:
   Schedule[invoke='invoke_0' dm=False]
       0: Loop[type='dofs',field_space='any_space_1',it_space='dofs',
               upper_bound='ndofs']
-          Literal[value:'NOT_INITIALISED']
-          Literal[value:'NOT_INITIALISED']
+          Reference[name:'loop0_start']
+          Reference[name:'loop0_stop']
           Literal[value:'1']
           Schedule[]
               0: BuiltIn setval_c(f5,0.0)

examples/lfric/README.md

@@ -245,14 +245,14 @@ Kernel call 'matrix_vector_code' was found in
 InvokeSchedule[invoke='invoke_0', dm=False]
     ...
     Loop[type='', field_space='any_space_1', it_space='cells', upper_bound='ncells']
-        Literal[value:'NOT_INITIALISED']
-        Literal[value:'NOT_INITIALISED']
+        Reference[name:'loop0_start']
+        Reference[name:'loop0_stop']
         Literal[value:'1']
         Schedule[]
             CodedKern matrix_vector_kernel_code(m_lumped,ones,mb) [module_inline=False]
     Loop[type='dofs', field_space='any_space_1', it_space='dofs', upper_bound='ndofs']
-        Literal[value:'NOT_INITIALISED']
-        Literal[value:'NOT_INITIALISED']
+        Reference[name:'loop1_start']
+        Reference[name:'loop1_stop']
         Literal[value:'1']
         Schedule[]
             BuiltIn x_divideby_y(self_mb_lumped_inv,ones,m_lumped)

src/psyclone/alg_gen.py

@@ -227,10 +227,6 @@ def _adduse(location, name, only=None, funcnames=None):
     tree. This will be added at the first valid location before the
     current location.
 
-    This function should be part of the fparser2 replacement for
-    f2pygen (which uses fparser1) but is kept here until this is
-    developed, see issue #240.
-
     :param location: the current location (node) in the parse tree to which \
                      to add a USE.
     :type location: :py:class:`fparser.two.utils.Base`

src/psyclone/core/component_indices.py

@@ -36,8 +36,6 @@
 
 '''This module provides a class to manage indices in variable accesses.'''
 
-from __future__ import print_function, absolute_import
-
 
 from psyclone.errors import InternalError