Quick Start Guide

This guide runs through the process of getting an ARCHER account, logging in, compiling a simple program and running your first job.

Request an account on ARCHER

• Login to SAFE using your email address that you registered with and your SAFE password: https://www.archer.ac.uk/safe/
• Under "Login accounts" select "Request login account"
• Choose your ARCHER project in the drop-down box.
• Select machine "ARCHER"
• Type in your selected username.

The PI or project manager of project will be asked to approve your request. After your request has been approved, the systems team will create the account, and when this has been done, you will receive an email. You can then come back to SAFE and pick up the password of your new account.

Collect your ARCHER password

• Login to SAFE using your email address that you registered with and your SAFE password: https://www.archer.ac.uk/safe/
• Go to section "Login accounts".
• Choose the relevant account. This will display details of your account.
• Click "View Login Account Password" button near the bottom of the screen.

This password is generated randomly by the software. It's best to copy-and-paste it across when you log in to the service machine. After you login, you will be prompted to change it. You should enter this password again, and then you will be prompted for your new, easy-to-remember password. Note that when you change your password on the service machine in this way, this is not reflected on the SAFE.

Login to ARCHER

To log into ARCHER you should use the "login.archer.ac.uk" address:

ssh [userID]@login.archer.ac.uk

More information on connecting to ARCHER is available in the User Guide.

Write your first program on ARCHER

Open a text file on the system using your favourite text editor called "hello_world.f90". For example, using vi:

auser@eslogin01:~> vi hello_world.f90

Now copy and paste the source code below into the file and save it.

! Example Hello World program
program hello_world
use mpi
implicit none

! Set up the variables
integer :: irank, nrank
integer :: iout, ierr
character(len=5) :: cirank
character(len=30) :: filename

! Initialize MPI and get my rank and total
call mpi_init(ierr)
call mpi_comm_rank(MPI_COMM_WORLD, irank, ierr)
call mpi_comm_size(MPI_COMM_WORLD, nrank, ierr)

! Set the filename from this process and open for writing
write(cirank, "(I0.5)") irank
filename = "output"//cirank//".out"
iout = 10 + irank
open(unit=iout, file=filename, form="FORMATTED")

! Write the output
write(iout,'(A,I5,A,I5)') "Hello from ", irank, " of ", nrank

! Close the output file and finalize MPI
close(iout)
call mpi_finalize(ierr)

end program hello_world

Compile your first program

Now use the Fortran compiler wrapper command "ftn" to compile the code:

auser@eslogin01:~> ftn -o hello_world.x hello_world.f90

For C programs you would use the "cc" command and for C++ programs you would use the "CC" command.

More information on compilers on ARCHER is available in the User Guide.

Create a job submission script

To run a program on the ARCHER compute nodes you need to write a job submission script that tells the system how many compute nodes you want to reserve and for how long. You also need to use the "aprun" command to tell ARCHER how to place the parallel processes and threads onto the processors you have reserved.

More information on job submission and process/thread placement on ARCHER is available in the User Guide.

Parallel jobs on ARCHER should be run from the /work filesystem to have good IO performance. Create a job submission script called "submit.pbs" in your space on the work filesystem using your favourite text editor. For example, using vi:

auser@eslogin01:~> cd /work/z01/z01/auser
auser@eslogin01:/work/z01/z01/auser> vi submit.pbs

(You will need to use your project code and username to get to the correct directory. i.e. replace the "z01" above with your project code and replace the username "auser" with your ARCHER username.

Paste the following text into your job submission script, replacing ENTER_YOUR_BUDGET_CODE_HERE with your budget code e.g. e99-ham.

#!/bin/bash --login

#PBS -N hello_world
#PBS -l select=1
#PBS -l walltime=0:5:0
#PBS -A ENTER_YOUR_BUDGET_CODE_HERE

cd $PBS_O_WORKDIR

aprun -n 24 $HOME/hello_world.x

cat output*.out > helloworld.out

Submit your job to the queue

You submit your job to the job submission using the "qsub" command:

auser@eslogin01:/work/z01/z01/auser> qsub submit.pbs
72136.sdb

The value retuned is your job ID.

Monitoring your job

You use the "qstat" command to examine jobs in the queue. Use:

auser@eslogin01:/work/z01/z01/auser> qstat -u $USER

To list all the jobs you have in the queue. PBS will also provide an estimate of the start time for any queued jobs by adding the "-T" option:

auser@eslogin01:/work/z01/z01/auser> qstat -Tu $USER

To see more details about the queued job, Use:

auser@eslogin01:/work/z01/z01/auser> qstat -f $JOBID

If your job does not enter a running state in the queues, this option may be useful as it contains a comment field which may explain the reason why.

Checking the output from the job

The job submission script above should write the output to a file called "helloworld.out", you can check this with the "cat" command. If the job was successful you should see output that looks something like:

auser@eslogin01:/work/z01/z01/auser> cat helloworld.out
Hello from     0 of    24
Hello from     1 of    24
Hello from     2 of    24
Hello from     3 of    24
Hello from     4 of    24
Hello from     5 of    24
Hello from     6 of    24
Hello from     7 of    24
Hello from     8 of    24
Hello from     9 of    24
Hello from    10 of    24
Hello from    11 of    24
Hello from    12 of    24
Hello from    13 of    24
Hello from    14 of    24
Hello from    15 of    24
Hello from    16 of    24
Hello from    17 of    24
Hello from    18 of    24
Hello from    19 of    24
Hello from    20 of    24
Hello from    21 of    24
Hello from    22 of    24
Hello from    23 of    24

If something has gone wrong, you will find any error messages in the file "hello_world.e[jobID]".