HPC-novice

Submit first job

Learning Objectives

Submit the hello world example
First exposure to some linux commands
Explain concepts involved

The typical workflow on an HPC system involves the following steps:

Login
Transfer any files or data needed on the system (we’ll get to this later)
Prepare job submission script and submit the job
Monitor job progress (if desired)
Log out (and potentially wait for an email saying your job finished)

Doing these things in a linux terminal requires several (but not that many) commands to move files around, edit files and work with the scheduler.

In this lesson, we walk through an entire example explaining as we go. In order to have our example job finish quickly, we’ll submit a prepared script and discuss its contents while the job runs.

To get started, log in to your HPC system. You should have a terminal window open waiting for your input.

Next, let’s create a new directory (also called folders) for this lesson material. The name of the folder is up to you, but you’ll want to remember it.

$ mkdir submit_lesson

We can list the contents of our current directory with the ls command (you may have other things in your directory, but make sure the new directory we just created is there:

$ ls

submit_lesson

Next, we change into the new directory with the cd command:

$ cd submit_lesson

Next, we’ll download the example submission files. Don’t worry much about these commands yet. wget is a tool to download files from the internet and tar is a tool much like unzip that unpacks a collection of files. To facilitate copying and pasting the url, here is the link to examples.tar https://github.com/dbrunson/hpc-novice/raw/gh-pages/examples.tar (Right-click on the link and choose ‘copy link location’ or something similar.

$ wget  https://github.com/dbrunson/hpc-novice/raw/gh-pages/examples.tar

The wget command will have many lines of output showing its progress. When you get a command prompt $ back, use tar as below to extract the files:

$ tar xvf examples.tar

Let’s check to see if that worked by using ls -F. The -F is a ‘flag’ or command line option to the ls command and it causes subdirectories to have a / at the end of their name.

$ ls -F

examples/  examples.tar

Let’s navigate into the examples subdirectory and see what’s there:

$ cd examples
$ ls

helloworld.pbs  helloworld.sh

Since a scheduled job make take some time to complete, we’ll go ahead and submit this hello world job now so it can be working while we learn about the files.

$ qsub helloworld.pbs

The output from this command will include your job id number.

The file helloworld.pbs is called a submission script.

Let’s look at the jobs running on the cluster. (Cluster is another word for HPC system.)

$ showq

NOTE: The showq -u and qpeek commands are not much use for this extremely short hello world example. If you do a longer example later, postpone these unil then.

If you just want to see your jobs (if any):

$ showq -u yourusername

If you have a long job running (which we don’t) you can check on the output with qpeek, but you’ll need to know your job id number. If you forgot, use showq -u yourusername to see it. Suppose your job id number is 412343, just type:

$ qpeek 412343

Let’s take a look at the contents of the submission script helloworld.pbs. The three most common ways to do this are with one of these commands: cat, more,and less. You could also open it in a text editor, such as nano, vim, or emacs.

$ cat helloworld.pbs

#!/bin/bash

# This is a comment that is just for humans to read
# Lines starting with #PBS are instructions to the scheduler

# Select the queue you want:
#PBS -q express

# Request the number of nodes and the number of
# processors per node
#PBS -l nodes=1:ppn=1

# Request the maximum time that your job could possibly need
#PBS -l walltime=10:00

#  This line puts all the output that would have gone to the screen
#  into a single file.  Some schedulers do this by default.
#PBS -j oe

#  This makes sure your job starts in the same directory as
#  where you submitted the job.
cd $PBS_O_WORKDIR

# This is the command to run a job 
./helloworld.sh