Allowing file-specific transformation scripts for PSyclone (#308)

Changed the transformation_script parameter of function `psyclone` to accept a call-back function that can return file-specific transformation scripts.

docs/source/writing_config.rst

@@ -64,7 +64,7 @@ A grab step will copy files from a folder or remote repo into a folder called
 
     if __name__ == '__main__':
 
-        with BuildConfig(project_label='<project label') as state:
+        with BuildConfig(project_label='<project label>') as state:
             grab_folder(state, src='<path to source folder>')
             find_source_files(state)
 
@@ -122,7 +122,7 @@ The Fortran preprocessor will read the :ref:`FPP<env_vars>` environment variable
 
     if __name__ == '__main__':
 
-        with BuildConfig(project_label='<project label') as state:
+        with BuildConfig(project_label='<project label>') as state:
             grab_folder(state, src='<path to source folder>')
             find_source_files(state)
             preprocess_fortran(state)
@@ -132,6 +132,56 @@ Preprocessed files are created in the `'build_output'` folder, inside the projec
 After the fortran_preprocessor step, there will be a collection called ``"preprocessed_fortran"``, in the artefact store.
 
 
+PSyclone
+========
+
+If you want to use PSyclone to do code transformation and pre-processing (see https://github.com/stfc/PSyclone),
+you must run :func:`~fab.steps.psyclone.preprocess_x90` and :func:`~fab.steps.psyclone.psyclone`,
+before you run the :func:`~fab.steps.analyse.analyse` step below.
+
+* For :func:`~fab.steps.psyclone.preprocess_x90`:
+            You can pass in `common_flags` list as an argument.
+* For :func:`~fab.steps.psyclone.psyclone`:
+            You can pass in:
+
+            * kernel file roots to `kernel_roots`, 
+            * a function to get transformation script to `transformation_script` 
+              (see examples in ``~fab.run_configs.lfric.gungho.py`` and ``~fab.run_configs.lfric.atm.py``),
+            * command-line arguments to `cli_args`,
+            * override for input files to `source_getter`, 
+            * folders containing override files to `overrides_folder`.
+
+
+.. code-block::
+    :linenos:
+    :caption: build_it.py
+    :emphasize-lines: 8,18,19
+
+    #!/usr/bin/env python3
+    from logging import getLogger
+
+    from fab.build_config import BuildConfig
+    from fab.steps.find_source_files import find_source_files
+    from fab.steps.grab.folder import grab_folder
+    from fab.steps.preprocess import preprocess_fortran
+    from fab.steps.psyclone import psyclone, preprocess_x90
+
+    logger = getLogger('fab')
+
+    if __name__ == '__main__':
+
+        with BuildConfig(project_label='<project label>') as state:
+            grab_folder(state, src='<path to source folder>')
+            find_source_files(state)
+            preprocess_fortran(state)
+            preprocess_x90(state)
+            psyclone(state)
+
+
+After the psyclone step, two new source files will be created for each .x90 file in the `'build_output'` folder.
+These two output files will be added under ``"psyclone_output"`` collection to the artefact store.
+
+
 .. _Analyse Overview:
 
 Analyse
@@ -149,7 +199,7 @@ The Analyse step looks for source to analyse in several collections:
 .. code-block::
     :linenos:
     :caption: build_it.py
-    :emphasize-lines: 4,18
+    :emphasize-lines: 4,21
 
     #!/usr/bin/env python3
     from logging import getLogger
@@ -159,15 +209,18 @@ The Analyse step looks for source to analyse in several collections:
     from fab.steps.find_source_files import find_source_files
     from fab.steps.grab.folder import grab_folder
     from fab.steps.preprocess import preprocess_fortran
+    from fab.steps.psyclone import psyclone, preprocess_x90
 
     logger = getLogger('fab')
 
     if __name__ == '__main__':
 
-        with BuildConfig(project_label='<project label') as state:
+        with BuildConfig(project_label='<project label>') as state:
             grab_folder(state, src='<path to source folder>')
             find_source_files(state)
             preprocess_fortran(state)
+            preprocess_x90(state)
+            psyclone(state)
             analyse(state, root_symbol='<program>')
 
 
@@ -187,7 +240,7 @@ then creates the executable.
 .. code-block::
     :linenos:
     :caption: build_it.py
-    :emphasize-lines: 6,9,21,22
+    :emphasize-lines: 6,9,24,25
 
     #!/usr/bin/env python3
     from logging import getLogger
@@ -199,15 +252,18 @@ then creates the executable.
     from fab.steps.grab.folder import grab_folder
     from fab.steps.link import link_exe
     from fab.steps.preprocess import preprocess_fortran
+    from fab.steps.psyclone import psyclone, preprocess_x90
 
     logger = getLogger('fab')
 
     if __name__ == '__main__':
 
-        with BuildConfig(project_label='<project label') as state:
+        with BuildConfig(project_label='<project label>') as state:
             grab_folder(state, src='<path to source folder>')
             find_source_files(state)
             preprocess_fortran(state)
+            preprocess_x90(state)
+            psyclone(state)
             analyse(state, root_symbol='<program>')
             compile_fortran(state)
             link_exe(state)

run_configs/lfric/atm.py

@@ -19,8 +19,6 @@
 
 logger = logging.getLogger('fab')
 
-# todo: optimisation path stuff
-
 
 def file_filtering(config):
     """Based on lfric_atm/fcm-make/extract.cfg"""
@@ -163,6 +161,21 @@ def file_filtering(config):
     ]
 
 
+def get_transformation_script(fpath, config):
+    ''':returns: the transformation script to be used by PSyclone.
+    :rtype: Path
+
+    '''
+    optimisation_path = config.source_root / 'lfric' / 'lfric_atm' / 'optimisation' / 'meto-spice'
+    local_transformation_script = optimisation_path / (fpath.relative_to(config.source_root).with_suffix('.py'))
+    if local_transformation_script.exists():
+        return local_transformation_script
+    global_transformation_script = optimisation_path / 'global.py'
+    if global_transformation_script.exists():
+        return global_transformation_script
+    return ""
+
+
 if __name__ == '__main__':
     lfric_source = lfric_source_config.source_root / 'lfric'
     gpl_utils_source = gpl_utils_source_config.source_root / 'gpl_utils'
@@ -239,7 +252,7 @@ def file_filtering(config):
         psyclone(
             state,
             kernel_roots=[state.build_output / 'lfric' / 'kernel'],
-            transformation_script=lfric_source / 'lfric_atm/optimisation/meto-spice/global.py',
+            transformation_script=get_transformation_script,
             cli_args=[],
         )
 

run_configs/lfric/gungho.py

@@ -22,7 +22,19 @@
 logger = logging.getLogger('fab')
 
 
-# todo: optimisation path stuff
+def get_transformation_script(fpath, config):
+    ''':returns: the transformation script to be used by PSyclone.
+    :rtype: Path
+
+    '''
+    optimisation_path = config.source_root / 'lfric' / 'miniapps' / 'gungho_model' / 'optimisation' / 'meto-spice'
+    local_transformation_script = optimisation_path / (fpath.relative_to(config.source_root).with_suffix('.py'))
+    if local_transformation_script.exists():
+        return local_transformation_script
+    global_transformation_script = optimisation_path / 'global.py'
+    if global_transformation_script.exists():
+        return global_transformation_script
+    return ""
 
 
 if __name__ == '__main__':
@@ -65,7 +77,7 @@
         psyclone(
             state,
             kernel_roots=[state.build_output],
-            transformation_script=lfric_source / 'miniapps/gungho_model/optimisation/meto-spice/global.py',
+            transformation_script=get_transformation_script,
             cli_args=[],
         )