2444 use dash instead of colon

changelog

@@ -153,6 +153,9 @@
 	Pointer *declarations* will still result in symbols of
 	UnsupportedFortranType.
 
+	55) PR #2445 for #2444. Changes the kernel-extraction tooling so
+	that filenames are construction using dashes instead of colons.
+
 release 2.5.0 14th of February 2024
 
 	1) PR #2199 for #2189. Fix bugs with missing maps in enter data

doc/user_guide/examples.rst

@@ -512,11 +512,11 @@ of the kernel launches and data transfers:
    > NV_ACC_NOTIFY=3 ./example_openacc
    ...
      Step             5 : chksm =    2.1098315506694516E-004
-     PreStart called for module 'main_psy' region 'invoke_2:setval_c:r2'
+     PreStart called for module 'main_psy' region 'invoke_2-setval_c-r2'
     upload CUDA data  file=PSyclone/examples/lfric/eg14/main_psy.f90 function=invoke_2 line=183 device=0 threadid=1 variable=.attach. bytes=144
     upload CUDA data  file=PSyclone/examples/lfric/eg14/main_psy.f90 function=invoke_2 line=183 device=0 threadid=1 variable=.attach. bytes=144
     launch CUDA kernel  file=PSyclone/examples/lfric/eg14/main_psy.f90 function=invoke_2 line=186 device=0 threadid=1 num_gangs=5 num_workers=1 vector_length=128 grid=5 block=128
-     PostEnd called for module 'main_psy' region 'invoke_2:setval_c:r2'
+     PostEnd called for module 'main_psy' region 'invoke_2-setval_c-r2'
     download CUDA data  file=PSyclone/src/psyclone/tests/test_files/dynamo0p3/infrastructure//field/field_r64_mod.f90 function=log_minmax line=756 device=0 threadid=1 variable=self%data(:) bytes=4312
     20230807214504.374+0100:INFO : Min/max minmax of field1 =   0.30084014E+00  0.17067212E+01
    ...

doc/user_guide/profiling.rst

@@ -169,11 +169,15 @@ profile_PSyDataInit()
 This method needs to be called once to initialise the profiling tool.
 At this stage this call is not automatically inserted by PSyclone, so
 it is the responsibility of the user to add the call to an appropriate
-location in the application::
+location in the application:
 
-   use profile_psy_data_mod, only : profile_PSyDataInit
-   ...
-   call profile_PSyDataInit()
+.. code-block::
+    :caption: Adding profile_PSyDataInit.
+    :emphasize-lines: 3
+
+    use profile_psy_data_mod, only : profile_PSyDataInit
+    ...
+    call profile_PSyDataInit()
 
 The "appropriate" location might depend on the profiling library used.
 For example, it might be necessary to invoke this before or after
@@ -187,7 +191,11 @@ must be called.
 It will make sure that the measurements are printed, files are flushed,
 and that the profiling tool is closed correctly. Again at
 this stage it is necessary to manually insert the call at an appropriate
-location::
+location:
+
+.. code-block::
+    :caption: Adding profile_PSyDataShutdown.
+    :emphasize-lines: 3
 
     use profile_psy_data_mod, only : profile_PSyDataShutdown
     ...
@@ -218,8 +226,9 @@ around every routine that it processes.)
 
 The option ``--profile kernels`` will surround each outer loop
 created by PSyclone with start and end profiling calls. Note that this
-option is not available for the 'nemo' API as it does not have the
-concept of explicit Kernels.
+option is only available if PSyclone was invoked with a ``-api``
+parameter. If you are only transforming existing code, this option
+cannot be used as there is no concept of `kernels`.
 
 .. note:: In some APIs (for example :ref:`LFRic <lfric-api>`
           when using distributed memory) additional minor code might
@@ -243,7 +252,11 @@ profiling regions. Below we show an example of a schedule created
 when instrumenting invokes - all children of a Profile-Node will
 be part of the profiling region, including all loops created by
 PSyclone and all kernel calls (note that for brevity, the nodes
-holding the loop bounds have been omitted for all but the first loop)::
+holding the loop bounds have been omitted for all but the first loop):
+
+.. code-block::
+    :caption: Instrumenting invokes.
+    :emphasize-lines: 2
 
     GOInvokeSchedule[invoke='invoke_1']
         0: [Profile]
@@ -278,7 +291,11 @@ holding the loop bounds have been omitted for all but the first loop)::
 
 And now the same schedule when instrumenting kernels. In this case
 each loop nest and kernel call will be contained in a separate
-region::
+region:
+
+.. code-block::
+    :caption: Instrumenting kernels.
+    :emphasize-lines: 2,13,24
 
     GOInvokeSchedule[invoke='invoke_1']
         0: [Profile]
@@ -315,7 +332,11 @@ region::
                                 0: CodedKern compute_pnew_code(pnew_fld,pold_fld,
                                         cu_fld,cv_fld,tdt,dx,dy) [module_inline=False]
 
-Both options can be specified at the same time::
+Both options can be specified at the same time:
+
+.. code-block::
+    :caption: Instrumenting kernels and invokes.
+    :emphasize-lines: 2,4,16,28
 
     GOInvokeSchedule[invoke='invoke_1']
         0: [Profile]
@@ -366,7 +387,11 @@ takes either a single PSyIR Node or a list of PSyIR Nodes as argument,
 and will insert a Profile Node into the PSyIR, with the 
 specified nodes as children. At code creation time the
 listed children will all be enclosed in one profile region.
-As an example::
+As an example:
+
+.. code-block::
+    :caption: Explicitly adding profiling regions.
+    :emphasize-lines: 3,8
 
     from psyclone.psyir.transformations import ProfileTrans
 
@@ -383,12 +408,16 @@ explicitly, rather than being automatically created (see
 :ref:`profile_names` for details). This allows for potentially
 more intuitive names or finer grain control over profiling
 (as particular regions could be provided with the same profile
-names). For example::
+names). For example:
+
+.. code-block::
+    :caption: Setting profile region names.
+    :emphasize-lines: 5,8
 
     invoke = psy.invokes.invoke_list[0]
     schedule = invoke.schedule
     profile_trans = ProfileTrans()
-    # Use the actual psy-layer module and subroutine names.
+    # Use the actual PSy-layer module and subroutine names.
     options = {"region_name": (psy.name, invoke.name)}
     profile_trans.apply(schedule.children, options=options)
     # Use own names and repeat for different regions to aggregate profile.
@@ -414,12 +443,13 @@ Naming Profiling Regions
 ------------------------
 A profile region derives its name from two components:
 
-`module_name`
-    A string identifying the psy-layer containing this 
-    profile node.
-`region_name`
-    A string identifying the invoke containing 
-    this profile node and its location within the invoke
+``module_name``
+    A string identifying the PSy-layer (PSyKAl DSL) or module (existing code)
+    containing this profile node.
+
+``region_name``
+    A string identifying the invoke (PSyKAl DSL) or routine (existing code)
+    containing this profile node and its location within the invoke/routine
     (where necessary).
 
 By default PSyclone will generate appropriate names to uniquely
@@ -428,34 +458,37 @@ somewhat cryptic, alternative names can be specified by the user
 when adding profiling via a transformation script, see
 :ref:`dev_guide:psy_data_parameters_to_constructor`.
 
-The automatic name generation depends on the API according
-to the following rules:
+The automatic name generation depends on whether you are using a
+PSyKAl DSL or only the transformation capabilities of PSyclone. If
+you are transforming existing code:
 
-For the :ref:`NEMO API <nemo-api>`,
-
-* the `module_name` string is set to the name of the parent
+* the ``module_name`` string is set to the name of the parent
   function/subroutine/program. This name is unique as Fortran requires
   these names to be unique within a program.
 
-* the `region_name` is set to an `r` (standing for region) followed by
+* the ``region_name`` is set to an ``r`` (standing for region) followed by
   an integer which uniquely identifies the profile within the parent
   function/subroutine/program (based on the profile node's position in
   the PSyIR representation relative to any other profile nodes).
 
 For the :ref:`LFRic <lfric-api>` and
-:ref:`GOcean <gocean-api>` APIs,
+:ref:`GOcean <gocean-api>` APIs:
 
-* the `module_name` string is set to the module name of the generated
+* the ``module_name`` string is set to the module name of the generated
   PSy-layer. This name should be unique by design (otherwise module
   names would clash when compiling).
 
-* the `region_name` is set to the name of the invoke in which it
-  resides, followed by a `:` and a kernel name if the
-  profile region contains a single kernel, and is completed by `:r`
+* the ``region_name`` is set to the name of the invoke in which it
+  resides, followed by a ``-`` and a kernel name if the
+  profile region contains a single kernel, and is completed by ``-r``
   (standing for region) followed by an integer which uniquely
   identifies the profile within the invoke (based on the profile
   node's position in the PSyIR representation relative to any other
-  profile nodes). For example::
+  profile nodes). For example:
+
+.. code-block::
+    :caption: PSyIR with profiling nodes.
+    :emphasize-lines: 2
 
     InvokeSchedule[invoke='invoke_0', dm=True]
       0: Profile[]
@@ -500,15 +533,19 @@ For the :ref:`LFRic <lfric-api>` and
                       0: CodedKern testkern_qr_code(f1,f2,m1,a,m2,istp)
                          [module_inline=False]
 
-This is the code created for this example::
+This is the code created for this example:
+
+.. code-block::
+    :caption: Created Fortran source code with profiling regions.
+    :emphasize-lines: 5,6,7,18,19,24,25
 
      MODULE container
       CONTAINS
       SUBROUTINE invoke_0(a, f1, f2, m1, m2, istp, qr)
         ...
-        CALL psy_data_3%PreStart("multi_functions_multi_invokes_psy", "invoke_0:r0", &
+        CALL psy_data_3%PreStart("multi_functions_multi_invokes_psy", "invoke_0-r0", &
                                      0, 0)
-        CALL psy_data%PreStart("multi_functions_multi_invokes_psy", "invoke_0:r1", 0, 0)
+        CALL psy_data%PreStart("multi_functions_multi_invokes_psy", "invoke_0-r1", 0, 0)
         IF (f2_proxy%is_dirty(depth=1)) THEN
           CALL f2_proxy%halo_exchange(depth=1)
         END IF 
@@ -519,14 +556,14 @@ This is the code created for this example::
           CALL m2_proxy%halo_exchange(depth=1)
         END IF 
         CALL psy_data%PreEnd()
-        CALL psy_data_1%PreStart("multi_functions_multi_invokes_psy", "invoke_0:r2", &
+        CALL psy_data_1%PreStart("multi_functions_multi_invokes_psy", "invoke_0-r2", &
                                      0, 0)
         DO cell=1,mesh%get_last_halo_cell(1)
           CALL testkern_code(...)
         END DO 
         ...
         CALL psy_data_2%PreStart("multi_functions_multi_invokes_psy", &
-                          "invoke_0:testkern_code:r3", 0, 0)
+                          "invoke_0-testkern_code-r3", 0, 0)
         DO cell=1,mesh%get_last_halo_cell(1)
           CALL testkern_code(...)
         END DO 

examples/gocean/eg5/profile/README.md

@@ -89,10 +89,10 @@ library, you should see:
  ...
  profile_PSyDataInit called
  ...
- PreStart called for module 'psy_test' region 'invoke_0:r0'
- PostEnd called for module 'psy_test' region 'invoke_0:r0'
- PreStart called for module 'psy_test' region 'invoke_1_update_field:update_field_code:r0'
- PostEnd called for module 'psy_test' region 'invoke_1_update_field:update_field_code:r0'
+ PreStart called for module 'invoke_0' region 'r0'
+ PostEnd called for module 'invoke_0' region 'r0'
+ PreStart called for module 'invoke_1_update_field' region 'r0'
+ PostEnd called for module 'invoke_1_update_field' region 'r0'
  ...  
  profile_PSyDataShutdown called
 ```

examples/lfric/eg14/README.md

@@ -31,12 +31,12 @@ The binary can be executed using ``example_openacc`` without additional paramete
 ./example_openacc
  Mesh has           5 layers.
  profile_PSyDataInit called
- PreStart called for module 'main_psy' region 'invoke_initialise_fields:r0'
- PostEnd called for module 'main_psy' region 'invoke_initialise_fields:r0'
+ PreStart called for module 'main_psy' region 'invoke_initialise_fields-r0'
+ PostEnd called for module 'main_psy' region 'invoke_initialise_fields-r0'
  PreStart called for module 'main_psy' region '
- invoke_testkern_w0:testkern_w0_code:r1'
+ invoke_testkern_w0-testkern_w0_code-r1'
  PostEnd called for module 'main_psy' region '
- invoke_testkern_w0:testkern_w0_code:r1'
+ invoke_testkern_w0-testkern_w0_code-r1'
  ...
 20230807214504.374+0100:INFO : Min/max minmax of field1 =   0.30084014E+00  0.17067212E+01
 20230807214504.374+0100:INFO : Min/max minmax of field2 =   0.21098316E-03  0.21098316E-03

src/psyclone/psyir/nodes/psy_data_node.py

@@ -559,7 +559,7 @@ def gen_code(self, parent, options=None):
             if len(kerns) == 1:
                 # This PSyData region only has one kernel within it,
                 # so append the kernel name.
-                region_name += f":{kerns[0].name}"
+                region_name += f"-{kerns[0].name}"
             # Add a region index to ensure uniqueness when there are
             # multiple regions in an invoke.
             psy_data_nodes = self.root.walk(PSyDataNode)
@@ -570,7 +570,7 @@ def gen_code(self, parent, options=None):
                 if node is self:
                     idx = index
                     break
-            region_name += f":r{idx}"
+            region_name += f"-r{idx}"
 
         if not options:
             options = {}

src/psyclone/psyir/transformations/psy_data_trans.py

@@ -190,14 +190,14 @@ def get_unique_region_name(self, nodes, options):
         if len(kerns) == 1:
             # This PSyData region only has one kernel within it,
             # so append the kernel name.
-            region_name += f":{kerns[0].name}"
+            region_name += f"-{kerns[0].name}"
 
         # Add a region index to ensure uniqueness when there are
         # multiple regions in an invoke.
         key = module_name + "|" + region_name
         idx = PSyDataTrans._used_kernel_names.get(key, 0)
         PSyDataTrans._used_kernel_names[key] = idx + 1
-        region_name += f":r{idx}"
+        region_name += f"-r{idx}"
         return (module_name, region_name)
 
     # ------------------------------------------------------------------------

src/psyclone/tests/domain/common/extract_driver_creator_test.py

@@ -98,7 +98,7 @@ def test_driver_creation1():
 
     driver = Path("driver-psy_extract_example_with_various_"
                   "variable_access_patterns-invoke_0_compute_"
-                  "kernel:compute_kernel_code:r0.f90")
+                  "kernel-compute_kernel_code-r0.f90")
     assert driver.is_file()
 
     with driver.open("r", encoding="utf-8") as driver_file:
@@ -122,7 +122,7 @@ def test_driver_creation1():
   real*8, allocatable, dimension(:,:) :: in_out_fld_post
   type(ReadKernelDataType) :: extract_psy_data
   call extract_psy_data%OpenRead('psy_extract_example_with_various_variable_''' \
-  '''access_patterns', 'invoke_0_compute_kernel:compute_kernel_code:r0')
+  '''access_patterns', 'invoke_0_compute_kernel-compute_kernel_code-r0')
   call extract_psy_data%ReadVariable('out_fld_post', out_fld_post)
   ALLOCATE(out_fld, mold=out_fld_post)
   out_fld = 0

src/psyclone/tests/domain/gocean/transformations/gocean1p0_transformations_test.py

@@ -32,7 +32,7 @@
 # POSSIBILITY OF SUCH DAMAGE.
 # ----------------------------------------------------------------------------
 # Authors R. W. Ford, A. R. Porter, S. Siso and N. Nobre, STFC Daresbury Lab
-# Modified work Copyright (c) 2017-2024 by J. Henrichs, Bureau of Meteorology
+# Modified J. Henrichs, Bureau of Meteorology
 # Modified I. Kavcic, Met Office
 
 ''' Module containing tests of Transformations when using the GOcean API '''