WIP

docs/sections/user_guide/yaml/execution.rst

@@ -25,7 +25,6 @@ Example block:
        stderr: /path/to/runscript.err
        stdout: /path/to/runscript.out
        tasks_per_node: 40
-       threads: 8
        walltime: 00:02:00
      envcmds:
        - module use /path/to/modulefiles
@@ -44,9 +43,11 @@ These entries map to job-scheduler directives sent to e.g. Slurm when a batch jo
 
 Shorthand names are provided for certain directives for each scheduler, and can be specified as-so along with appropriate values. Recognized names for each scheduler are:
 
-* LSF: ``jobname``, ``memory``, ``nodes``, ``queue``, ``shell``, ``stdout``, ``tasks_per_node``, ``threads``, ``walltime``
-* PBS: ``debug``, ``jobname``, ``memory``, ``nodes``, ``queue``, ``shell``, ``stdout``, ``tasks_per_node``, ``threads``, ``walltime``
-* Slurm: ``cores``, ``exclusive``, ``export``, ``jobname``, ``memory``, ``nodes``, ``partition``, ``queue``, ``rundir``, ``stderr``, ``stdout``, ``tasks_per_node``, ``threads``, ``walltime``
+* LSF: ``jobname``, ``memory``, ``nodes``, ``queue``, ``shell``, ``stdout``, ``tasks_per_node``, ``walltime``
+* PBS: ``debug``, ``jobname``, ``memory``, ``nodes``, ``queue``, ``shell``, ``stdout``, ``tasks_per_node``, ``walltime``
+* Slurm: ``cores``, ``exclusive``, ``export``, ``jobname``, ``memory``, ``nodes``, ``partition``, ``queue``, ``rundir``, ``stderr``, ``stdout``, ``tasks_per_node``, ``walltime``
+
+**NB** To arrange for the ``OMP_NUM_THREADS`` environment variable to be set in the execution environment of components compiled with OpenMP support, set the ``execution:`` block's  ``threads:`` child item. Drivers with appropriate support will set ``OMP_NUM_THREADS`` as well as the corresponding scheduler flag when making a batch-resource request.
 
 Other, arbitrary directive key-value pairs can be provided exactly as they should appear in the batch runscript. For example
 

src/uwtools/drivers/driver.py

@@ -456,9 +456,13 @@ def _write_runscript(self, path: Path, envvars: Optional[dict[str, str]] = None)
         Write the runscript.
         """
         path.parent.mkdir(parents=True, exist_ok=True)
+        envvars = envvars or {}
+        threads = self._driver_config.get("execution", {}).get("threads")
+        if threads and "OMP_NUM_THREADS" not in envvars:
+            raise UWConfigError("Config specified threads but driver does not set OMP_NUM_THREADS")
         rs = self._runscript(
             envcmds=self._driver_config.get("execution", {}).get("envcmds", []),
-            envvars=envvars or {},
+            envvars=envvars,
             execution=[
                 "time %s" % self._runcmd,
                 "test $? -eq 0 && touch %s" % self._runscript_done_file,

src/uwtools/tests/drivers/test_driver.py

@@ -545,6 +545,14 @@ def test_Driver__write_runscript(driverobj):
     assert actual.strip() == dedent(expected).strip()
 
 
+def test_Driver__write_runscript_threads_fail(driverobj):
+    path = Path(driverobj._driver_config["rundir"]) / "runscript"
+    driverobj._driver_config["execution"]["threads"] = 4
+    with raises(UWConfigError) as e:
+        driverobj._write_runscript(path=path)
+    assert str(e.value) == "Config specified threads but driver does not set OMP_NUM_THREADS"
+
+
 def test__add_docstring():
     class C:
         pass