Job arrays

This article is a draft

This is not a complete article: This is a draft, a work in progress that is intended to be published into an article, which may or may not be ready for inclusion in the main wiki. It should not necessarily be considered factual or authoritative.

A large number of tasks which differ only in some parameter can be conveniently submitted as a job array, also known as a task array or an array job. The individual tasks in the array are distinguished by an environment variable, $SLURM_ARRAY_TASK_ID, which Slurm sets to different values according to the range you supply with the --array parameter.

sbatch --array=0-7 ...      # $SLURM_ARRAY_TASK_ID will take values from 0 to 7 inclusive
sbatch --array=1,3,5,7 ...  # $SLURM_ARRAY_TASK_ID will take the listed values
sbatch --array=1-7:2 ...    # Step-size of 2, does the same as the previous example
sbatch --array=1-100%10 ... # Allow no more than 10 of the jobs to run simultaneously

See Job Array Support at SchedMD.com for detailed documentation.

A simple example

$ sbatch --array=1-10 runme
Submitted batch job 54321

Job 54321 will be scheduled as 10 independent tasks which may start at different times on different hosts. Each task has a different value of an environment variable $SLURM_ARRAY_TASK_ID. The script can reference $SLURM_ARRAY_TASK_ID to select an input file, for example, or to set a command-line argument for the application code:

my_app <input.$SLURM_ARRAY_TASK_ID
my_app $SLURM_ARRAY_TASK_ID some_arg another_arg

Using a job array instead of a large number of separate serial jobs has advantages for you and other users. A waiting job array only produces one line of output in squeue, making it easier for you to read its output. The scheduler does not have to analyze job requirements for each array task separately, so it can run more efficiently too.

Running the same script in multiple directories

This example assumes that you have multiple directories, each with the same structure and you want to run the same script in each directory. If the directories can be named with sequential numbers then the example above can be easily adapted. If they are not so systematic, then create a file with the names of the directories, like so:

$ cat case_list
pacific2016
pacific2017
atlantic2016
atlantic2017

File : directories_array.sh

#!/bin/bash
#SBATCH --time=0:15:00
#SBATCH --array=1-4

echo "Starting task $SLURM_ARRAY_TASK_ID at $(date)"
DIR=$(sed -n "${SLURM_ARRAY_TASK_ID}p" case_list)
cd $DIR

# Place the code to execute here
pwd
ls

Cautions:

• You should take care that the number of tasks you request matches the number of entries in the file.
• The file case_list should not be changed until all the tasks in the array have run, since it will be read each time a new task starts.