HPC/Submitting and Managing Jobs

Processing flow of a job on Carbon.

Introduction

To accept and run jobs, Carbon uses the Torque Resource Manager, which is a variant of PBS. The determination of nodes and start time for jobs is performed by a separate software component called a scheduler, which for Carbon is the Moab Workload Manager. Further, the resources used by each job (primarily the CPU time) are managed by the Gold Allocation Manager.

The adjacent figure shows schematically how a job is processed. Unless otherwise told, Torque will execute the job on your behalf on the first node allocated by Moab, in your $HOME directory, and typically using your login shell. It is the job's responsibility to:

• change to a suitable working directory,
• recognize and use the other nodes of the job.

  This is overwhelmingly done by starting an MPI program on the nodes listed in the job's $PBS_NODEFILE.

  A job is perfectly free to run more than one program, such as several MPI programs in sequence.

To help locate programs on each compute node configure modules and $PATH in your $HOME/.bashrc file. Otherwise, mpirun will fail, typically as soon as more than one node is involved.

See also: directory layout.

Submitting and managing jobs

Job File

A job is described to Torque by a job script, which in most cases is a shell script to be executed by your login shell (bash).

• Example Job Script.

Advanced usage

The job script can be written in any scripting language, such as Perl or Python. Specify the interpreter in the first script line in Unix hash-bang syntax #!/usr/bin/perl, or use the qsub -S path_list option.

Submission

 qsub [-A accountname] [options] jobfile

For details on options:

 man qsub
 qsub --help

More details are at the Torque Manual, in particular the qsub man page.

The single main queue is batch and need not be specified. All job routing decisions are handled by the scheduler. In particular, short jobs are accommodated by a daily reserved node and by backfill scheduling, i.e. "waving forward" while a big job waits for full resources to become available.

Using the debug queue

For testing job processing and your job environment, use qsub -q debug on the command line, or the follwing in a job script:

#PBS -q debug

The debug queue accepts jobs under the following conditions

nodes ≤ 2
ppn ≤ 4
walltime ≤ 1:00:00

Checking job status

Query your jobs using commands similar to those on other HPC clusters. You can use either PBS/Torque commands or Moab commands. Both access the same information, but through different routes, and offer different display styles.

To get the regular output format:

qstat [-u $USER]
showq [-u $USER]

To get an alternate format (e.g. showing job names):

qstat -a [-u $USER]
showq -n [-u $USER]

You can always use -u $USER to show only your jobs.

Getting extra information

Show the nodes where a job runs:

qstat -n [-1] jobnum

Give full information such as submit arguments and run directories, and do not wrap long lines ("-1" is the digit "one"):

qstat -f [jobnum] [-1]

To diagnose problems with "stuck" jobs, use Moab's checkjob command. The last few lines of output give past events of the job and its current status.

checkjob -v jobnum

Changing jobs after submission

You can use qalter to modify the attributes of a job before it starts. Specify the attributes to be modified on the command line. All others will not be changed. If any of the specified attributes cannot be modified for any reason, none of that job's attributes will be modified.

qalter [-l resource] […] jobnumber …
qalter -A accountspec jobnumber …

You cannot modify the job script itself after submission. You will have to remove and resubmit the job. For exceptional situations, contact me (stern) to arrange for a manual intervention.

Removing jobs

To retract a queued job or terminate an already running job:

 qdel jobnumber

Interactive node access

There are two ways to interactively access nodes:

• Requesting an interactive job

qsub -I [-l nodes=…]

This is a special Torque job submission that will wait for the requested nodes to become available, and then you will be dropped into a login shell on the first core of the first node. $PBS_NODEFILE is set as in regular (non-interactive) jobs.

• Side-access a node that already runs a job, such as to debug or inspect running processes or node-local files.

You can use ssh to interactively access any compute node on which a job of yours is running (use qsub -n jobnum to find out the node names). As soon as a node no longer runs at least one of your jobs, your ssh session to that node will be terminated. You may find the following commands helpful:

/usr/sbin/lsof -u $USER
/usr/sbin/lsof -c command_name
/usr/sbin/lsof -p pid

- list open files; man page.

ps -fu $USER

- list your own processes.

psuser

- a Carbon-specific wrapper for ps to list user-only processes (yours and other regular users', excluding system processes).