The `execution:` Block

Component drivers require an execution: block to provide details about how to configure a component’s run-time environment, and how to run it.

Example block:

execution:
  batchargs:
    cores: 40
    debug: True
    exclusive: True
    export: false
    jobname: my-job
    memory: 4GB
    nodes: 1
    partition: p1
    queue: q1
    rundir: /path/to/rundir
    shell: /bin/bash
    stderr: /path/to/runscript.err
    stdout: /path/to/runscript.out
    tasks_per_node: 40
    walltime: 00:02:00
  envcmds:
    - module use /path/to/modulefiles
    - module load some_module
  executable: /path/to/sfc_climo_gen
  mpiargs:
    - "--export=ALL"
    - "--ntasks $SLURM_CPUS_ON_NODE"
  mpicmd: srun
  stacksize: 100M
  threads: 8

batchargs:

These entries map to job-scheduler directives sent to e.g. Slurm when a batch job is submitted via the --batch CLI switch or the batch=True API argument. The only required entry is walltime.

Shorthand names are provided for certain directives for each scheduler, and can be specified as-so along with appropriate values. Except where noted below, values provided for shorthand names should be strings. Supported shorthand names for each scheduler are:

Shorthand	Slurm	PBS	LSF
`account`	`--account`	`-A`	`-P`
`clusters`	`--clusters`
`cores`	`--ntasks`
`debug`	`--verbose`	`-l debug`
`exclusive`	`--exclusive`
`export`	`--export`	`-V`
`jobname`	`--job-name`	`-N`	`-J`
`memory`	`--mem`	`-l mem`	`-R rusage[mem]`
`nodes`	`--nodes`	`-l select`	`-n`
`partition`	`--partition`
`queue`	`--qos`	`-q`	`-q`
`rundir`	`--chdir`
`shell`		`-S`	`-L`
`stderr`	`--error`
`stdout`	`--output`	`-o`	`-o`
`tasks_per_node`	`--ntasks-per-node`	`mpiprocs`	`-R span[ptile]`
`threads`			`-R affinity[core()]`
`walltime`	`--time`	`-l walltime`	`-W`

export: Values should be YAML booleans. A true value means that all environment variables from the head-node shell will be propagated to the batch environment; false means that none will.
memory: Values should be strings in a form acceptable by the underlying scheduler (consult your scheduler’s documentation).
tasks_per_node: Values should be integers.
walltime: Values should be strings in hours:minutes:seconds form, e.g. 01:30:00 for one and a half hours.

Other, arbitrary directive key-value pairs can be provided exactly as they should appear in the batch runscript. For example

--nice: 100

could be specified to have the Slurm directive

#SBATCH --nice=100

included in the batch runscript.

NB To enable threading when running components compiled with OpenMP support, set the execution: block’s threads: item (see below). Then uwtools will set the appropriate scheduler flag when making a batch request, and will set the OMP_NUM_THREADS environment variable in the execution environment.

envcmds:

An array (YAML sequence) of commands to execute in the run-time shell before the component executable is run.

executable:

The name of or path to the component’s executable.

mpiargs:

An array (YAML sequence) of string arguments that should follow the MPI launch program (mpiexec, srun, et al.) on the command line. This entry is only used when configuring parallel components.

mpicmd:

The MPI launch program (mpiexec, srun, et al.). This entry is only used when configuring parallel components.

stacksize:

For drivers implementing support, exports the OMP_STACKSIZE environment variable to the execution environment, specifying the size of the stack for threads created by OpenMP. The value takes the form: size | sizeB | sizeK | sizeM | sizeG. When only size is provided, the unit is assumed to be kilobytes.

threads:

For drivers implementing support, exports the OMP_NUM_THREADS environment variable to the execution environment, specifying the number of OpenMP threads to use when running the component. This entry is only used when configuring parallel components.

The execution: Block