2757 script arguments

doc/user_guide/user_scripts.rst

@@ -89,6 +89,26 @@ and/or kernels) contained within the provided tree.
 The :ref:`examples section<examples>` provides a list of psyclone user scripts
 and associated usage instructions for multiple applications.
 
+.. _script_kwargs:
+
+Arguments for Scripts
+---------------------
+Scripts can take optional keyword arguments specified on the command line
+using the option `--script-kwargs`. The keyword arguments are specified
+as separate `keyword:value` pairs, separate by `,`. For example:
+
+.. code-block:: shell
+
+    psyclone -s ./optimise.py input_source.f90 \
+             --scripts-kwargs "omp: True, tiling: [4,4]"
+
+This will result in the additional keyword arguments for any transformation call:
+
+.. code-block:: python
+
+    def trans(psyir, omp: bool, tiling: list[int]):
+        # Modify psyir tree
+
 
 .. _sec_script_globals:
 
@@ -142,3 +162,8 @@ associated with the merged invoke.
 
 An example of the use of a script making use of the ``trans_alg``
 function can be found in ``examples/gocean/eg7``.
+
+Note that the ``trans_alg`` function will receive the same keyword arguments
+as the ``trans`` function if the PSyclone command line option
+``--script-kwargs`` is used (see :ref:`script_kwargs`). It is therefore
+important that both functions accept the same keyword arguments.

examples/nemo/eg8/Makefile

@@ -60,7 +60,8 @@ PSYCLONE_PROFILING_LIB ?= ${PSYCLONE_PROFILING_DIR}/libsimple_timing.a
 PSYCLONE_PROFILING_LIBS ?= -L${PSYCLONE_PROFILING_DIR} -lsimple_timing
 
 transform:
-	ENABLE_PROFILING=1 ${PSYCLONE} -s ./omp_gpu_profile_trans.py ../code/tra_adv.F90 -o traadv_instrumented.F90
+	${PSYCLONE} -s ./omp_gpu_profile_trans.py --script-kwargs "profiling: True" \
+		../code/tra_adv.F90 -o traadv_instrumented.F90
 
 compile: transform traadv.exe
 

examples/nemo/eg8/README.md

@@ -18,7 +18,8 @@ make transform
 or explicitly:
 
 ```sh
-ENABLE_PROFILING=1 ${PSYCLONE} -s ./omp_gpu_profile_trans.py ../code/tra_adv.F90 -o traadv_instrumented.F90
+${PSYCLONE} -s ./omp_gpu_profile_trans.py --script-kwargs "profiling: True"  \
+            ../code/tra_adv.F90 -o traadv_instrumented.F90
 ```
 
 This emits transformed Fortran code with PSyData profiling around OpenMP target

examples/nemo/eg8/omp_gpu_profile_trans.py

@@ -33,13 +33,12 @@
 # POSSIBILITY OF SUCH DAMAGE.
 # -----------------------------------------------------------------------------
 
-import os
 import pathlib
 import sys
 from typing import List, Union
 from psyclone.psyir.nodes import (
-    Assignment, IfBlock, Node, OMPDirective, OMPTargetDirective, ProfileNode,
-    Routine, Schedule)
+    Assignment, FileContainer, IfBlock, Node, OMPDirective,
+    OMPTargetDirective, ProfileNode, Routine, Schedule)
 from psyclone.psyir.transformations import OMPTargetTrans, ProfileTrans
 from psyclone.transformations import OMPLoopTrans, TransformationError
 
@@ -50,9 +49,6 @@
     sys.path.insert(0, str(NEMO_SCRIPTS_DIR))
 
 
-PROFILING_ENABLED = os.environ.get("ENABLE_PROFILING", False)
-
-
 def add_omp_region_profiling_markers(children: Union[List[Node], Schedule]):
     """Insert profiling markers around all top-level OpenMP directives.
 
@@ -94,8 +90,16 @@ def add_omp_region_profiling_markers(children: Union[List[Node], Schedule]):
             add_omp_region_profiling_markers(child.children)
 
 
-def trans(psyir):
-    """Apply OpenMP offloading and insert profiling around target regions."""
+def trans(psyir: FileContainer, profiling=False):
+    """
+    Apply OpenMP offloading and insert profiling around target regions.
+
+    :param psyir: the PSyIR of the file container to modify.
+    :param profiling: if set to True (using the PSyclone command line option
+        --scripts-kwargs "profiling: True"), also adds profiling
+        instrumentation to the generated code.
+    """
+
     from utils import normalise_loops, insert_explicit_loop_parallelism
 
     omp_target_trans = OMPTargetTrans()
@@ -119,5 +123,5 @@ def trans(psyir):
             collapse=True,
             enable_reductions=True
         )
-        if PROFILING_ENABLED:
+        if profiling:
             add_omp_region_profiling_markers(subroutine.children)