To illustrate the features related to SGE, we will use the following blast command as an example:

blastn -db subject.fasta -query query.fasta -out out.blast

The user which submits the job is stage01.


Submit a job

qsub command

The qsub command is used for submitting a job to a cluster node using SGE.

The basic way to submit is:

[stage01@migale ~]$ qsub -cwd -V -N myblast -b y "blastn -db subject.fasta -query query.fasta -out out.blast"
Your job 1995189 ("myblast") has been submitted
  • -cwd run in current working directory
  • -V will pass all environment variables to the job
  • -N <jobname> name of the job. This you will see when you use qstat, to check status of your jobs.
  • -b y allow command to be a binary file instead of a script.

Other usefull options are:

  • -q <queue> set the queue. See here to choose a queue adapted to your needs.
  • -pe thread <n_slots> This specifies the parallel environment. thread runs a parallel job using shared-memory and n_processors amount of cores.
  • -R y allows to reserve resources as soon as they are free
  • -l hostname=<node> specify a specific node
  • -o <output_logfile> name of the output log file
  • -e <error_logfile> name of the error log file
  • -m ea Will send email when job ends or aborts
  • -M <emailaddress> Email address to send email to

Example with the script file called myblast.sh:

[stage01@migale ~]$ head myblast.sh
blastn -db subject.fasta -query query.fasta -out out.blast
[stage01@migale ~]$ qsub -cwd -V -N myblast myblast.sh
Your job 1995190 ("myblast") has been submitted

Example using 16 slots:

[stage01@migale ~]$ qsub -cwd -V -N myblast -pe thread 16 -R y -b y "blastn -db subject.fasta -query query.fasta -out out.blast -num_threads 16"
Your job 1995190 ("myblast") has been submitted

Monitor a job

qstat command

The qstat command shows the status of your jobs.

[stage01@migale ~]$ qstat
job-ID  prior   name       user         state submit/start at     queue                          slots ja-task-ID 
-----------------------------------------------------------------------------------------------------------------
1995192 0.00000 myblast    stage01         qw    10/04/2019 17:11:46                                    1        

The qw state indicates that the job is pending.

[stage01@migale ~]$ qstat
job-ID  prior   name       user         state submit/start at     queue                          slots ja-task-ID 
-----------------------------------------------------------------------------------------------------------------
1995192 0.50500 myblast    stage01         r     10/04/2019 17:11:59 short.q@n35                        1        

The r state indicates that the job is running.


Delete a job

qdel command

If for any reason you have to delete a job, you can use the qdel command using the job-ID.

[stage01@migale ~]$ qdel 1995192
stage01 has registered the job 1995192 for deletion

If for any reason you have to delete all your jobs, you can specify your user name to delete all your jobs at one time.

[stage01@migale ~]$ qdel -u stage01
stage01 has deleted job 1995285
stage01 has deleted job 1995286
stage01 has deleted job 1995287

Interactive session

qlogin command

You can log in a cluster node and run commands without using qsub. This mode is very usefull for testing a command line. As for qsub, you need to add options to reserve slots or log in on a specific node.

[stage01@migale ~]$ qlogin
Your job 1995211 ("QLOGIN") has been submitted
waiting for interactive job to be scheduled ...
Your interactive job 1995211 has been successfully scheduled.
Establishing /opt/sge/util/resources/wrappers/qlogin_wrapper session to host n35 ...
stage01@n35's password: 
Last login: Thu Jun 27 17:17:50 2019 from nmigale
[stage01@n35 ~]$ 

To choose a specific node:

[stage01@migale ~]$ qlogin -l hostname=n58
Your job 1995212 ("QLOGIN") has been submitted
waiting for interactive job to be scheduled ...
Your interactive job 1995212 has been successfully scheduled.
Establishing /opt/sge/util/resources/wrappers/qlogin_wrapper session to host n58 ...
stage01@n58's password: 
Last login: Tue Sep  3 10:15:24 2019 from nmigale
[stage01@n58 ~]$ 

As for a job, an interactive session has a job-ID and takes up resources

[stage01@n58 ~]$ qstat
job-ID  prior   name       user         state submit/start at     queue                          slots ja-task-ID 
-----------------------------------------------------------------------------------------------------------------
1995213 0.50500 QLOGIN     stage01         r     10/04/2019 23:28:24 short.q@n58                        1        

To quit an interactive session, just type exit

[stage01@n58 ~]$ exit
Connection to n58 closed.
/opt/sge/util/resources/wrappers/qlogin_wrapper exited with exit code 0
[stage01@migale ~]$