Skip Navigation
Oklahoma State University
High Performance Computing Center

A unit in the Division of the Vice President for Research

New User Tutorial

 

Welcome to the OSU HPCC New User Tutorial. This online tutorial is divided into two parts.

 

Download a PDF copy of the New User Tutorial HERE.

To schedule one-on-one training or ask a question email hpcc@okstate.edu.

 

 

 

 

 

 

 

 

 

Logging In
 
Before proceeding further into the tutorial, learn how to log in using Windows, Linux and Mac operating systems. 
 
After you log in, you will be on one of Cowboy's two login nodes. "Node" means server or computer. 
 
Cowboy also has 254 compute nodes. All these nodes are connected by a very fast private network. The cluster consists of these nodes, the network and a filesystem.
 
 
Using a mouse in a terminal
  • In Putty or in the linux xterm terminal: highlighting (with mouse) = copy
    • Right clicking (Putty) or Middle Clicking (xterm) = paste
  • In the Mac terminal, highlight (with mouse) + [Command]-C = copy
    • [Command]-V = paste
  • ​In the linux GNOME terminal, [CTRL][Shift]C = copy
    • ​[CTRL][Shift]V = paste
Other than the functions listed above, your mouse has no other function.  To move the cursor around, you use arrow keys on the keyboard.
 

 

Changing Password
 
The first time you log in, you should change your password from the default password assigned when your account was created to a more secure (and easier to remember) password of your choosing. Type the following in the command line and hit enter:
 
passwd
 
You will be prompted for your old password, new password and then your new password again. 
NOTE: Your passwords will not show up on the screen as you type it 
 
Please use a STRONG password 
**Suggestion** this should be at least eight characters long and include numbers, letters and other characters
 
 
Logging Out
 
To log out type:  exit
(**You can also use the key combination Ctrl-D)
 

 

Command Line
 
When you use a command-line interface (CLI), commands are usually short, cryptic and produce output consisting of lines of text. This might be confusing at first, but CLI allows us to automate and repeat tasks with a few commands and keystrokes. 
 
Below are some commonly used linux commands:
  • “pwd” - prints working (current) directory to the screen
  • “ls” - lists content of a directory
  • “cd” - changes to a different directory
  • “cp” - copies a file to another name or location
  • “mv” - moves or renames a file
  • "rm" - removes/deletes files permanently
  • “grep” - searches for specific words or strings
  • “nano ” - opens the nano text editor
  • “diff” - compares two files to show differences
  • “tar” - archive and unarchive source files
  • “man” - help/usage for all system commands
  • “exit” - terminate ssh session
Also, some important keyboard shortcuts:
  • TAB - autocompletes filenames as you're typing them
  • The up arrow will cycle through your previously typed commands
  • CTRL-D exits a terminal (same as typing `exit`)
  • CTRL-C breaks/cancels an ongoing operation (similar to using ESC)
More tutorials HERE.  
 
Some of them are reference guides, but here's a beginner tutorial for linux: UNIX/linux Tutorial for Beginners
 

 

File Systems
 
Each user will have two basic directories: the home and the scratch.  
  • When you first log in, your current working directory is /home/<username> (where <username> would be your Cowboy username)
    • /home/<username> has a quota of 25GB. Your source code and executables will be stored here. This filesystem is NOT BACKED UP, but it does have snapshots. To check your current usage type du -sh from your home directory. 
    • /scratch/<username> is a shared directory for large files and large collections of files. This filesystem is NOT BACKED UP.
  • The /opt folder is shared and contains applications needed by users. To request that an application be installed, please email hpcc@okstate.edu.
 
 
NOTE: The first / in a file system path represents the root - or the first or top-most directory in your file system. When you log in to Cowboy, you are automatically in your home folder, which stems from the root. Your current working directory would look like /home/<username>, with the first / representing the root. All proceeding / in a file path simply serve as dividers between any subsequent directories and files.

 

 

 

 

 

 

 

 

 

 

 

 

In part 2 of the OSU HPCC New User Tutorial, you will learn how to schedule and submit jobs on Cowboy using an example file you already have access to in the /opt directory.

Batch Scheduler on Cowboy

Imagine you are wanting to eat at a restaurant that operates on a reservation-based system. You call the restaurant and tell them how many people will be in your party and that you are open to taking whatever time they can fit you in. The restaurant looks at its open reservations and based on its table availability for your party of 10, they make a reservation for you to come in at that time. Similar to the restaurant's reservation staff, Cowboy uses a batch scheduler to manage job submissions. 
 
If you remember, when you first log in to Cowboy, you'll be on one of its login nodes. However, on Cowboy (or any HPC cluster) you won't run your job on the login node. You can edit files here, but when it's time to run a job, you will need to use the batch scheduler command to move you to a compute node. The job scheduler takes some information from you, finds the best compute node(s) to use and runs your job there.
 
This is the most efficient way to use the cluster. 
  • Login
  • Set up jobs with submit scripts
  • Submit them 
  • Log out. 
  • You can even have the scheduler email you when your jobs are finished.


 

Submission Script Example
Below is an exercise you can complete to practice creating a submission script. Remember your username will be used in place of pete
 
1. From the login node, change to the scratch directory (cd /scratch/pete). Then make a new directory (mkdir) called 'sample' and change to this new directory (cd). 
 
[pete@login2 ~]$ cd /scratch/pete
[pete@login2 pete]$ mkdir sample
[pete@login2 pete]$ cd sample
[
pete@login2 sample]$ pwd
/scratch/pete/sample
 
The pwd command shows you what directory you are in, which is why the output at the bottom shows /scratch/pete/sample. At any point, you can use pwd to confirm where you are.
 
2. Now copy (cp) a sample submit script from our shared directory (/opt) to your newly created sample directory: 
 
**Note the first command has a space after python followed by a period. The period is a shortcut representing your current directory (/scratch/pete/sample) and the command should copy the file into it
 
[pete@login2 sample]$ cp -r /opt/example_submission_scripts/python .
[pete@login2 sample]$ cd python
[pete@login2 sample]$ ls
elephant.pbs   elephant.py   README.md
 
The ls command lists the contents of the directory, which is why the output below it will now show the file elephant.pbs, elephant.py and README.md. This means you have successfully copied the contents of the python directory to your sample directory. At any point, you can use ls to see the contents of your current directory.
 
LINUX TIP: To reduce typing errors, remember your friends, the TAB (autocomplete) and up arrow (previous commands) functions! 
 
3. After typing the cat elephant.pbs command, the content of your sample submission script should display like the one below:
 
[pete@login2 sample]$ cat elephant.pbs
#!/bin/bash
#PBS -q express
#   specify the queue batch, express or bigmem
#PBS -l nodes=1:ppn=1
#   request 1 processor on 1 node
#PBS -l walltime=10:00
#   choose a walltime slightly longer than your job will take
#PBS -j oe
cd $PBS_O_WORKDIR

module load python/3.5.0
 
python elephant.py
 
NOTE: The following three lines should be checked when using a submission script:
  • #PBS -q express   - This line determines what queue your job will run. 'Express' is one of four job queues. 
  • #PBS -l nodes=1:ppn=1  - This line determines how many nodes and processors per node (ppn) your job will need.
  • #PBS -l walltime=10:00  - ​This line determines your job's time limit. Please try to accurately predict how long your job will take.
    • Learn more about walltime here.
    • Entering too long of a walltime may delay the start of your job as it waits for an open node.
    • If your job is taking longer than originally expected, please email hpcc@okstate.edu to request a walltime extension. 
  • ​Include the lines #PBS -j oe and cd $PBS_O_WORKDIR in your script.
  • module load <module name> will direct what module (or application/program) you'd like to run your job with.
    • Type module avail to see what modules (and their versions) are available on Cowboy.

If you have any questions about job queues, nodes and processors, walltime or modules, please email hpcc@okstate.edu

 


Editing with Nano
 
Nano is a very small text editor. It is good for editing small files. If you are going to edit larger, more complex files, you'll want to learn vi or emacs. Beware that many people have very strong opinions on which one of those is better!
 
Let's edit this script:
 
 [pete@login2 sample]$ nano  elephant.pbs
 
Within nano, you will use the arrow keys to move around. At the bottom of the screen you should see options. For example, to exit nano, it says ^X which means hold down the Ctrl button and press x, or "Ctrl-X".
 
If you have not made any edits, you will be returned to the command line.
 
Making edits:
Use the arrow keys to go down to this line:
  cd $PBS_O_WORKDIR
 
and press enter to add a blank line.  On that line type the following to make the scheduler email you when your job begins, ends or aborts:
 #PBS -m abe -M <youremailaddress>
 
Now, when you press Ctrl-X to exit, you'll see at the bottom the question:
 
Save modified buffer (ANSWERING "No" WILL DESTROY CHANGES) ?
Y Yes
N No           ^C Cancel
 
Press 'y' to save. Then just press 'Enter' to accept the filename helloworld.pbs If desired, you can name the file something else if you would like to keep the original version. You should then be returned to the command line.
 

 

Submitting a Job
 
Now that you've added in your email to receive alerts about your job, you can submit the job type using the qsub command:
 
[pete@login2 sample]$ qsub elephant.pbs
414.mgmt1
 
This command submits the job to the batch scheduler, and returns a jobIDnumber (in this example, it is 414, but will be a different number when you run it).
 
 
To see all the running jobs type:  $ showq
NOTE: It can take several seconds for your job to launch, so if you don't see it at first, please wait a bit and try again.  The qstat command.
 
To view only your jobs, add the grep command and subsitute your username for pete:
 
[pete@login2 sample]$ showq | grep pete
414 pete  Running  1  00:59:28  Tue Sep 18 11:02:23
 
To see the output of your job while it is running use the qpeek command and your job number:
 
[pete@login2 sample]$ qpeek 414
Hello pete I am running on node n245.cluster
 
 
You can stop (kill) your job using this command:  $ qdel 414
 
 
Once your job finishes, you can look at the output files created by the scheduler. Their name will be of the form jobname.ojobidnumber
 
[pete@login2 sample]$ ls
elephant.pbs.o414  elephant.pbs
[pete@login2 sample]$ cat elephant.pbs.o414
Hello pete I am running on node n245.cluster
waiting for 10 seconds
successfully finished!

 
Later, when you look at much bigger output files, use the less command:
 $less elephant.pbs.o414
 
NOTE: Type q to exit the less viewer. Use arrow keys to move around, use '/' and a word to search.
 
For a more interesting example with less, try this:
 $less /opt/examples/pg2701.txt
 
Within the less viewer, you can search for text.  First type the "/" character, then type 'Ahab' without the quotes and press enter. 
 

 

Moving Files - from your computer to Cowboy and back
 
Once you're done running your job, how do you get those files from Cowboy to your own computer?
 
There are several file transfer applications you can use to move files from your computer system to your directories on Cowboy and vice versa.
 
After the "python elephant" job in this tutorial has successfully completed, you will be left with a .png file. As with many output files you'll be working with, this .png file will need to be transferred off of Cowboy in order to view its contents.
 
Before you go further in the tutorial please VISIT THIS PAGE to learn about recommended file transfer applications and how to use them with the Cowboy cluster.
 
According to the instructions for the file transfer application you chose to download, try moving the elephant.png file to your computer's Desktop so you can open and view the file. Then you can return to this section to finish the tutorial.
 
 

Cleaning Up

After your job runs successfully, and you've transfered your files where they need to be, you can clean up your scratch directory by moving the files out of the scratch directory and then deleting those unneeded files. 
 
1. To move your file from your sample folder into your home directory:
 
[pete@login2 sample]$ mv elephant.pbs.o414 /home/<your username here>
 
You can confirm it is there by typing:
 
[pete@login2 sample]$ ls /home/<your username here>
elephant.pbs.o414
 
 
 
2. Now that you've moved your file to your home directory, you can delete the file(s) in your scratch directory that you no longer need:
     NOTE: There is no way to "undelete" a file in linux, so be absolutely sure you do not need a file before removing it!
 
In the example from above, you will have at least one output file from running the job, possibly more.
 
[pete@login2 sample]$ ls
elephant.pbs.o414  elephant.pbs
 
To delete FOREVER the file helloworld.pbs.o414, use the "rm" command:
 
[pete@login2 sample]$ rm elephant.pbs.o414 
[pete@login2 sample]$ ls
elephant.pbs
 
The ls command shows that all you are left with in the sample directory is the helloworld.pbs file you started with.
 
 

 

Download a PDF copy of the New User Tutorial HERE.

To schedule one-on-one training or ask a question email hpcc@okstate.edu.


NEED HELP?  hpcc@okstate.edu