qsub

Submit a script with default settings (depends on TORQUE settings)

$ qsub [script.sh]

$ qsub -l walltime=[1]:[2]:[3] [script.sh]

$ qsub -l nodes=[2]:ppn=[4] [script.sh]

$ qsub -q [queue_name] [script.sh]

qsub [options] script_file
qsub [options] -

-a date_time
    Specifies a future time for the job to be eligible for execution. Format typically [[[[CC]YY]MM]DD]hhmm[.SS].

-b option
    Specifies that the job is not a script. For example, -b n treats the command line arguments as the executable and its arguments.

-e path
    Sets the path for the job's standard error output. By default, it's typically job_name.eJOBID in the submission directory.

-I
    Submits an interactive job. This requests resources and then provides a shell prompt on the allocated compute node(s).

-k type
    Specifies which files (output/error) to keep on the execution host after the job completes (e.g., k oe for both).

-l resource_list
    A crucial option to request specific resources for the job. Common requests include nodes=X:ppn=Y (X nodes, Y processors per node), walltime=HH:MM:SS, and mem=Xgb.

-M email_address
    Specifies an email address to send job notifications to.

-m type
    Controls when email notifications are sent (e.g., a for abort, b for begin, e for end of job; abe for all).

-N job_name
    Assigns a descriptive name to the job, which appears in qstat output and filenames.

-o path
    Sets the path for the job's standard output. By default, it's typically job_name.oJOBID in the submission directory.

-P project_name
    Specifies the project name associated with the job, often used for accounting or resource allocation.

-q queue
    Submits the job to a specific queue (e.g., debug, batch, long). Different queues may have different resource limits or priorities.

-V
    Exports all current environment variables from the submission environment to the job's execution environment.

-v variable_list
    Exports specific environment variables (comma-separated) from the submission environment to the job.

-W attribute_list
    Allows specifying advanced job attributes, such as dependencies (e.g., depend=afterok:JOBID) or group lists (group_list=group_name).

-X
    Enables X11 forwarding for interactive jobs, allowing GUI applications to run on compute nodes and display on the user's local machine.

The qsub command is a fundamental utility in High-Performance Computing (HPC) environments that utilize the Portable Batch System (PBS), including its open-source derivatives like Torque Resource Manager and commercial versions such as Altair PBS Pro.

It serves as the primary interface for users to submit batch scripts (typically shell scripts) to a central job scheduler. Instead of executing computationally intensive tasks directly on login nodes, qsub allows users to queue these jobs, offloading computation and managing resources effectively.

The scheduler then intelligently manages resource allocation (such as CPUs, memory, wall time, and GPUs) across available compute nodes, ensuring efficient utilization and fair access for all users. Once a job is successfully submitted, qsub returns a unique job ID, which can be used with other q commands (like qstat or qdel) to monitor or manage the job's lifecycle.

A typical workflow involves creating a script containing both executable commands and PBS directives (e.g., #PBS -l nodes=1:ppn=2,walltime=01:00:00), then executing qsub script_name.sh. This process enables complex scientific simulations, data processing, and parallel computations to run unattended in a managed, optimized environment.

The exact syntax and available options for qsub can vary slightly depending on the specific PBS/Torque/PBS Pro version and the system's configuration. It is always recommended to consult the system's specific man page or documentation.

Incorrect or insufficient resource requests (e.g., via -l) can lead to long wait times, job failure, or resource contention. Users must be aware of their cluster's resource policies.

qsub is specific to PBS-compatible systems. Other popular schedulers like SLURM (which uses sbatch) or LSF (which uses bsub) have different command sets, even though they fulfill a similar purpose.

While qsub can submit a single executable, it most commonly takes a shell script as its argument. This script often contains special PBS directives (lines starting with #PBS), which are interpreted by qsub and the scheduler before the script itself is executed. These directives define job parameters like resource requests (e.g., #PBS -l nodes=1:ppn=2), output file paths (#PBS -o), and job names (#PBS -N). They provide a convenient way to encapsulate all job requirements within a single file.

By default, the standard output (stdout) and standard error (stderr) streams generated by a job are redirected to files in the directory from which qsub was invoked. The default filenames are typically in the format job_name.oJOBID for standard output and job_name.eJOBID for standard error. Users can override these default paths and filenames using the -o and -e options, respectively, either on the command line or within the job script as #PBS directives.

qsub is an integral part of the Portable Batch System (PBS), which was originally developed by NASA Ames Research Center in the early 1990s to manage computationally intensive tasks on supercomputers and clusters. PBS quickly became a de facto standard for batch job management in High-Performance Computing (HPC) environments.

Over time, the rights to PBS were acquired by Altair Engineering, leading to the development of the commercial product PBS Professional (PBS Pro). Concurrently, an open-source version, OpenPBS, continued to evolve, giving rise to projects like the Torque Resource Manager (now often referred to as OpenPBS or PBS Open Source).

The core functionality and command-line interface of qsub have remained remarkably consistent across these various implementations, providing a stable and familiar method for users to submit jobs to PBS-compatible batch systems, underscoring its enduring utility in research and industrial computing.

qstat(1), qdel(1), qhold(1), qrls(1), qalter(1), qmove(1), qmgr(8), pbsnodes(8), sbatch(1), bsub(1)