command-line tutorial
Divvy also provides a command-line interface that gives you the same power as the python API. You can use --help to get a list of the command-line options:
divvy --help
version: 0.5.0
usage: divvy [-h] [--version] [--verbosity V] [--silent] [--logdev]
{write,init,list,submit} ...
divvy - write compute job scripts that can be submitted to any computing
resource
positional arguments:
{write,init,list,submit}
write Write a job script
init Initialize a new divvy config file
list List available compute packages
submit Write and then submit a job script
optional arguments:
-h, --help show this help message and exit
--version show program's version number and exit
--verbosity V Set logging level (1-5 or logging module level name)
--silent Silence logging. Overrides verbosity.
--logdev Expand content of logging message format.
https://divvy.databio.org
The list command
Let's first use divvy list to show us our available computing packages:
divvy list
Using default config. No config found in env var: ['DIVCFG', 'PEPENV']
Using divvy config: /home/nsheff/.local/lib/python2.7/site-packages/divvy/default_config/divvy_config.yaml
Available compute packages:
default
slurm
singularity_slurm
singularity
local
docker
The write command
Use divvy write to actually write a new script using a template. To do this, you'll need to provide 3 things: a template (which comes from your compute package), a settings file with variables, and an outfile.
The settings file
The settings argument is where you can pass an existing yaml file with key-value pairs. Here's a simple example:
cat settings.yaml
time: 4-0-0
logfile: results.log
cores: 6
partition: large_mem
mem: 16G
Now let's take a look at the template we are going to use by activating the slurm package
cat ../divvy/default_config/divvy_templates/slurm_template.sub
#!/bin/bash
#SBATCH --job-name='{JOBNAME}'
#SBATCH --output='{LOGFILE}'
#SBATCH --mem='{MEM}'
#SBATCH --cpus-per-task='{CORES}'
#SBATCH --time='{TIME}'
#SBATCH --partition='{PARTITION}'
#SBATCH -m block
#SBATCH --ntasks=1
echo 'Compute node:' `hostname`
echo 'Start time:' `date +'%Y-%m-%d %T'`
{CODE}
We use divvy to populate that template with our list of variables above, like this:
divvy write -p slurm -s settings.yaml -o test.sub
Using default config. No config found in env var: ['DIVCFG', 'PEPENV']
Using divvy config: /home/nsheff/.local/lib/python2.7/site-packages/divvy/default_config/divvy_config.yaml
Activating compute package 'slurm'
Loading settings file: settings.yaml
Writing script to /home/nsheff/code/divvy/docs_jupyter/test.sub
Now we can take a look at what our sbumission scripts looks like.
cat test.sub
#!/bin/bash
#SBATCH --job-name='{JOBNAME}'
#SBATCH --output='results.log'
#SBATCH --mem='16G'
#SBATCH --cpus-per-task='6'
#SBATCH --time='4-0-0'
#SBATCH --partition='large_mem'
#SBATCH -m block
#SBATCH --ntasks=1
echo 'Compute node:' `hostname`
echo 'Start time:' `date +'%Y-%m-%d %T'`
{CODE}
We populated several variables, like {LOGFILE} and {TIME}, from the settings.yaml file. However, the {CODE} and {JOBNAME} variables are still unpopulated, so this submission script is incomplete. To remedy this, we'll use divvy's command-line variable passing: any non-interpreted arguments passed to divvy are assumed to be variables to populate the template. These command-line variables are considered highest priority and so will override any values in the more distant locations. For example:
divvy write -p slurm -s settings.yaml -o test.sub -c code=run-this-cmd jobname=12345 time=6-0-0
Using default config. No config found in env var: ['DIVCFG', 'PEPENV']
Using divvy config: /home/nsheff/.local/lib/python2.7/site-packages/divvy/default_config/divvy_config.yaml
Activating compute package 'slurm'
Loading settings file: settings.yaml
Writing script to /home/nsheff/code/divvy/docs_jupyter/test.sub
cat test.sub
#!/bin/bash
#SBATCH --job-name='12345'
#SBATCH --output='results.log'
#SBATCH --mem='16G'
#SBATCH --cpus-per-task='6'
#SBATCH --time='6-0-0'
#SBATCH --partition='large_mem'
#SBATCH -m block
#SBATCH --ntasks=1
echo 'Compute node:' `hostname`
echo 'Start time:' `date +'%Y-%m-%d %T'`
run-this-cmd
Now we have a complete script, which we can run with sbatch test.sub. Notice also that the time variable uses the one provided on the CLI rather than the one provided in the settings.yaml file, because the CLI has a higher priority.
Variables can come from these 3 sources, in order of increasing priority: 1) compute package (defined in the divvy configuration file and selected with the -p or --package argument); 2) settings.yaml file, passed with -s or --settings; 3) any additional variables passed on the command line as key-value pairs to -c.
Submitting jobs
Let's try actually submitting these jobs with divvy submit:
divvy submit -p slurm -s settings.yaml -o test.sub -c code=run-this-cmd jobname=12345 time=6-0-0
Using default config. No config found in env var: ['DIVCFG', 'PEPENV']
Using divvy config: /home/nsheff/.local/lib/python2.7/site-packages/divvy/default_config/divvy_config.yaml
Activating compute package 'slurm'
Loading settings file: settings.yaml
Writing script to /home/nsheff/code/divvy/docs_jupyter/test.sub
sbatch test.sub
sh: 1: sbatch: not found
The slurm package uses sbatch as its submission_command, but since I'm running this locally, it won't run as I have no sbatch command available. Let's try local instead:
divvy submit -p local -s settings.yaml -o test.sub -c code=ls
Using default config. No config found in env var: ['DIVCFG', 'PEPENV']
Using divvy config: /home/nsheff/.local/lib/python2.7/site-packages/divvy/default_config/divvy_config.yaml
Activating compute package 'local'
Loading settings file: settings.yaml
Writing script to /home/nsheff/code/divvy/docs_jupyter/test.sub
sh test.sub
Compute node: zither
Start time: 2020-05-19 07:46:03
build
cli.ipynb
debug.ipynb
results.log
settings.yaml
test_local.sub
test_script.sub
test.sub
tutorial.ipynb
There I switched the command to ls, which shows you a result of everything on this computer.