A program for submitting computational jobs to cluster

500 Words | Approximately 3 Minutes Read | Last Modified on August 12, 2014

Latest Version

Why Use It

With this program one could

avoid messing with PBS scripts
automatically submit numerous jobs at a single command (the system administrator will hate this …)
parallel independent jobs via GNU parallel program

Usage

To see basic usage, type

gw-qsub -h
	  usage: gw-qsub [-h] [-s N] [-n N] [-p N] [-m MEM] [-w WALLTIME] [-q QUEUE]
	                 [-d DIR] [-e EMAILS [EMAILS ...]] [-a OPT [OPT ...]]
	                 [--parallel] [--save] [--dry_run]
	                 name
	  
	  This is a program for submitting commands to cluster. Input commands are from
	  standard input stream.
	  
	  positional arguments:
	    name                  job name
	  
	  optional arguments:
	    -h, --help            show this help message and exit
	    -s N, --size N        number of commands per job, default to submitting all
	                          commands as one job
	    -n N, --nodes N       number of nodes reserved per job, default to 1
	    -p N, --ppn N         number of cpus reserved per node, default to 1
	    -m MEM, --mem MEM     reserved memory with units be b (bytes), w (words),
	                          kb, kw, mb, mw, gb or gw
	    -w WALLTIME, --walltime WALLTIME
	                          reserved computation time (hh:mm:ss), default to
	                          24:00:00
	    -q QUEUE, --queue QUEUE
	                          name of the queue for the job
	    -d DIR, --dir DIR     directory in which the jobs will be executed, default
	                          to current directory
	    -e EMAILS [EMAILS ...], --emails EMAILS [EMAILS ...]
	                          email notification addresses
	    -a OPT [OPT ...], --additional_attributes OPT [OPT ...]
	                          additional qsub attributes, e.g., -a
	                          "group_list=bigmem"
	    --parallel            parallel mode, powered by GNU parallel
	    --save                save pbs scripts to disk
	    --dry_run             perform a trial run which saves pbs scripts to disk
	                          without submitting any job

Note that to use the parallel mode the [[http://www.gnu.org/software/parallel/|GNU parallel]] program has to be installed and executable from $PATH.

Example

cat myjobs.sh | gw-qsub MYJOBS -p 16 -q bigtmp -w 480:00:00 > MYJOBS.id

which submits every command in myjobs.sh as one job to one computation node on queue “bigtmp” using 16 cores from that node for a reserved time of 480 hours.

cat myjobs.sh | gw-qsub MYJOBS -p 16 -a "-W x=FLAGS:ADVRES:bigtmp.0.0" -w 480:00:00 > MYJOBS.id

which passes an additional PBS option “#PBS -W x=FLAGS:ADVRES:bigtmp.0.0” to the job schedular.

Tips

As a quick reference, here is a list of commands commonly used to manage cluster jobs

showq: view the entire queue on the cluster. This reflects the current usage and available resource from the cluster. One should always check this before submitting any jobs.
qstat: view your job status, after submission
qdel: delete a job

The output of qsub command is the job ID, which is also written to screen by gw-qsub as standard output. I recommend to pipe them to a file for a record. Particularly it will be useful when you want to delete all jobs. For example if the job IDs are stored in a file called jname.id:

gw-qsub ... > jname.id

then to delete all jobs:

jobs=`cat jname.id`; for i in $jobs; do qdel $i; done

Comments & Bug Reports

gaow [at] bcm [dot] edu