diff --git a/docs/config_reference.rst b/docs/config_reference.rst index d03e882f53..de39df008c 100644 --- a/docs/config_reference.rst +++ b/docs/config_reference.rst @@ -323,6 +323,14 @@ System Partition Configuration - ``upcrun``: Parallel programs will be launched using the `UPC `__ ``upcrun`` command. - ``upcxx-run``: Parallel programs will be launched using the `UPC++ `__ ``upcxx-run`` command. + .. tip:: + + .. versionadded:: 4.0.0 + + ReFrame also allows you to register your own custom launchers simply by defining them in the configuration. + You can follow a small tutorial `here `__. + + .. js:attribute:: .systems[].partitions[].access :required: No diff --git a/docs/tutorial_advanced.rst b/docs/tutorial_advanced.rst index f23c7fd143..f56e5cacc9 100644 --- a/docs/tutorial_advanced.rst +++ b/docs/tutorial_advanced.rst @@ -576,8 +576,6 @@ The trick here is to replace the parallel launcher with the local one, which pra The :func:`~reframe.core.backends.getlauncher` function takes the `registered `__ name of a launcher and returns the class that implements it. You then instantiate the launcher and assign to the :attr:`~reframe.core.schedulers.Job.launcher` attribute of the job descriptor. -An alternative to this approach would be to define your own custom parallel launcher and register it with the framework. -You could then use it as the scheduler of a system partition in the configuration, but this approach is less test-specific. Adding more parallel launch commands ==================================== @@ -628,6 +626,65 @@ Let's see how the generated job script looks like: The first three ``srun`` commands are emitted through the :attr:`prerun_cmds` whereas the last one comes from the test's :attr:`executable` attribute. +Adding a custom launcher to a partition +======================================= + +.. versionadded:: 4.0.0 + +An alternative to the approaches above would be to define your own custom parallel launcher and register it with the framework. +You could then use it as the launcher of a system partition in the configuration and use it in multiple tests. + +Each `launcher `__ needs to implement the :func:`~reframe.core.launchers.JobLauncher.command` method and can optionally change the default :func:`~reframe.core.launchers.JobLauncher.run_command` method. + +As an example of how easy it is to define a new parallel launcher backend, here is the actual implementation of the ``mpirun`` launcher: + +.. code:: python + + from reframe.core.backends import register_launcher + from reframe.core.launchers import JobLauncher + + + @register_launcher('mpirun') + class MpirunLauncher(JobLauncher): + def command(self, job): + return ['mpirun', '-np', str(job.num_tasks)] + + +The :func:`~reframe.core.launchers.JobLauncher.command` returns a list of command tokens that will be combined with any user-supplied `options `__ by the :func:`~reframe.core.launchers.JobLauncher.run_command` method to generate the actual launcher command line. +Notice you can use the ``job`` argument to get job-specific information that will allow you to construct the correct launcher invocation. + +If you use a Python-based configuration file, you can define your custom launcher directly inside your config as follows: + +.. code:: python + + from reframe.core.backends import register_launcher + from reframe.core.launchers import JobLaucher + + + @register_launcher('slrun') + class MySmartLauncher(JobLauncher): + def command(self, job): + return ['slrun', ...] + + site_configuration = { + 'systems': [ + { + 'name': 'my_system', + 'partitions': [ + { + 'name': 'my_partition', + 'launcher': 'slrun' + ... + } + ], + ... + }, + ... + ], + ... + } + + Flexible Regression Tests ------------------------- diff --git a/reframe/core/launchers/__init__.py b/reframe/core/launchers/__init__.py index d187c9a74f..f59a1ed362 100644 --- a/reframe/core/launchers/__init__.py +++ b/reframe/core/launchers/__init__.py @@ -15,11 +15,11 @@ class JobLauncher(abc.ABC): A job launcher is the executable that actually launches a distributed program to multiple nodes, e.g., ``mpirun``, ``srun`` etc. - .. warning:: - - Users may not create job launchers directly. .. note:: + .. versionchanged:: 4.0.0 + Users may create job launchers directly. + .. versionchanged:: 2.8 Job launchers do not get a reference to a job during their initialization. diff --git a/reframe/schemas/config.json b/reframe/schemas/config.json index b8e1561f9e..5490b55280 100644 --- a/reframe/schemas/config.json +++ b/reframe/schemas/config.json @@ -251,12 +251,7 @@ ] }, "launcher": { - "type": "string", - "enum": [ - "alps", "ibrun", "local", "mpirun", - "mpiexec", "srun", "srunalloc", "ssh", - "upcrun", "upcxx-run", "lrun", "lrun-gpu" - ] + "type": "string" }, "access": { "type": "array",