Add usage_filter support to executable modifiers

This commit allows executable_modifiers defined within modifiers to
define usage filters. These can currently be set to only apply
once, to apply once but only on the first MPI executable, to be applied
to only MPI executables (but all of them), or to have no usage
filters.

Filters will constrain the number of times an executable modifier will
be applied within a given experiment.

Author: douglasjacobsen

lib/ramble/ramble/language/modifier_language.py

@@ -131,7 +131,7 @@ def _execute_variable_modification(mod):
 
 
 @modifier_directive("executable_modifiers")
-def executable_modifier(name, when=None, **kwargs):
+def executable_modifier(name, usage_filter=None, when=None, **kwargs):
     """Register an executable modifier
 
     Executable modifiers can modify various aspects of non-builtin application
@@ -166,6 +166,9 @@ def write_exec_name(self, executable_name, executable, app_inst=None):
     Args:
         name (str): Name of executable modifier to use. Should be the name of a
                     class method.
+        usage_filter (str): Filters the application of this executable modifier.
+                            Modifiers can register filters to select how to apply this.
+                            Valid default options include: None, "once", "first_mpi", "all_mpi"
         when (list | None): List of when conditions this executable modifier should apply in
 
     Each executable modifier needs to return:
@@ -185,6 +188,7 @@ def _executable_modifier(mod):
             mod.executable_modifiers[when_set] = {}
 
         mod.executable_modifiers[when_set][name] = {
+            "usage_filter": usage_filter,
             "when": when_list,
         }
 

var/ramble/repos/builtin/base_classes/modifier-base/base_class.py

@@ -70,6 +70,7 @@ def __init__(self, file_path):
         self.expander = None
         self._usage_mode = None
         self.app_inst = None
+        self._executable_modification_applied = set()
 
         self._mod_regex = re.compile(
             self._mod_prefix_builtin + f"{self.name}{NS_SEPARATOR}"
@@ -375,22 +376,130 @@ def applies_to_executable(self, executable):
 
         return bool(self._mod_regex.match(executable))
 
+    def executable_modifier_applied(self, exec_mod):
+        """Check if an executable modifier has been applies alerady
+
+
+        Returns:
+            (bool): True if the executable modifier has been applied. False otherwise
+        """
+        if exec_mod in self._executable_modification_applied:
+            return True
+        return False
+
+    def executable_modifier_usage_filter(filter_name: str):
+        """Decorator for registering a usage filter for executable modifiers"""
+
+        def _decorator(decorated_function):
+            if not hasattr(decorated_function, "_ramble_attributes"):
+                decorated_function._ramble_attributes = {}
+            decorated_function._ramble_attributes["filter_name"] = filter_name
+            return decorated_function
+
+        return _decorator
+
+    @executable_modifier_usage_filter("once")
+    def filter_once(self, exec_mod, executable) -> bool:
+        """Usage filter for only allowing an executable modifier to be applied
+        once in an experiment"""
+        return not self.executable_modifier_applied(exec_mod)
+
+    @executable_modifier_usage_filter("first_mpi")
+    def filter_first_mpi(self, exec_mod, executable) -> bool:
+        """Usage filter for only applying executable modifier to the first MPI
+        executable in an experiment"""
+        return executable.mpi and not self.executable_modifier_applied(
+            exec_mod
+        )
+
+    @executable_modifier_usage_filter("all_mpi")
+    def filter_all_mpi(self, exec_mod, executable) -> bool:
+        """Usage filter for applying an executalbe modifier to only MPI
+        executables in an experiment"""
+        return executable.mpi
+
+    def get_executable_modifier_filter(self, filter_name):
+        """Get the filter function for a usage filter (by name)
+
+        Args:
+            filter_name (str): Name of usage filter to extract for filtering executable modifier
+
+        Returns:
+            Reference to function, if found. None otherwise"""
+
+        filter_names = set()
+        for attr in dir(self):
+            method = getattr(self, attr)
+
+            if callable(method):
+                method_attributes = getattr(method, "_ramble_attributes", {})
+                test_filter_name = None
+                if "filter_name" in method_attributes:
+                    test_filter_name = method_attributes["filter_name"]
+                filter_names.add(test_filter_name)
+                if filter_name == test_filter_name:
+                    return method
+
+        if filter_name is not None and filter_name != "None":
+            logger.die(
+                f"When extracting a usage_filter for an executable_modifier "
+                f"on modifier {self.name} "
+                f"the filter {filter_name} does not exist. Registered filters are: \n"
+                f"{filter_names}"
+            )
+        return None
+
+    def executable_modification_applies(
+        self, exec_mod, filter_name, executable
+    ):
+        """Determine if an executable modifier applies to an executable or not
+
+        Args:
+            exec_mod (str): Name of executable modifier
+            filter_name (str): Name of usage filter to apply
+            executable: CommandExecutable object to check if exec_mod applies to
+
+        """
+        apply = True
+
+        filter_func = self.get_executable_modifier_filter(filter_name)
+
+        if filter_func is not None:
+            apply = filter_func(exec_mod, executable)
+
+        return apply
+
     def apply_executable_modifiers(
         self, executable_name, executable, app_inst=None
     ):
+        """Apply all executable modifiers to an executable
+
+        Args:
+            executable_name (str): Name of executable
+            executable: CommandExecutable object
+            app_inst: Instance of application object
+
+        Returns
+            (list, list): List of CommandExecutable objects that occur before
+                          and after (respectively) to the input executable.
+        """
         pre_execs = []
         post_execs = []
         for when_set, exec_mods in self.executable_modifiers.items():
             if self.expander.satisfies(when_set, self.experiment_variants()):
-                for exec_mod in exec_mods:
-                    mod_func = getattr(self, exec_mod)
-
-                    pre_exec, post_exec = mod_func(
-                        executable_name, executable, app_inst=app_inst
-                    )
+                for exec_mod, mod_conf in exec_mods.items():
+                    if self.executable_modification_applies(
+                        exec_mod, mod_conf["usage_filter"], executable
+                    ):
+                        self._executable_modification_applied.add(exec_mod)
+                        mod_func = getattr(self, exec_mod)
+
+                        pre_exec, post_exec = mod_func(
+                            executable_name, executable, app_inst=app_inst
+                        )
 
-                    pre_execs.extend(pre_exec)
-                    post_execs.extend(post_exec)
+                        pre_execs.extend(pre_exec)
+                        post_execs.extend(post_exec)
 
         return pre_execs, post_execs
 

var/ramble/repos/builtin/modifiers/intel-aps/modifier.py

@@ -80,7 +80,7 @@ class IntelAps(BasicModifier):
 
     modifier_variable(
         "apply_aps_exe_regex",
-        default="",
+        default=".*",
         description="apply aps to executables that match with the regex",
         mode="mpi",
     )
@@ -115,7 +115,7 @@ class IntelAps(BasicModifier):
 
         required_package("intel-oneapi-vtune")
 
-    executable_modifier("aps_summary")
+    executable_modifier("aps_summary", usage_filter="all_mpi")
 
     def aps_summary(self, executable_name, executable, app_inst=None):
         from ramble.util.executable import CommandExecutable
@@ -125,7 +125,7 @@ def aps_summary(self, executable_name, executable, app_inst=None):
 
         exe_regex = self.expander.expand_var_name("apply_aps_exe_regex")
         applicable = exe_regex and re.match(exe_regex, executable_name)
-        if applicable or executable.mpi:
+        if applicable:
             env_var_name = self.expander.expand_var_name(
                 "external_aps_env_var"
             )