======CHPC Induction======

This is an introduction to the practical aspects of using the CHPC //Lengau// cluster.  This page is an abbreviated overview of the full short course.  More details will be delivered by the lecturer.

> Links to slides and videos will be added later.

=====Connecting to Lengau=====

To connect to the CHPC cluster you will need to use the //ssh// protocol.  This is most easily accomplished with the **ssh** program on Linux systems.  If you do not have Linux on your laptop and are using MS Windows, please see the appropriate section of the //[[guide:connect|Connecting to the CHPC]]// guide.

On your Linux laptop, open a text terminal and type the **ssh** command:
<code>
ssh username@lengau.chpc.ac.za
</code>
where you will need to replace ''username'' with //your// user name, of course.

> If you do not have an account on Lengau as part of a CHPC research programme then you will be provided with a temporary ''student''NN account valid for the duration of the workshop only.

For more information on **ssh** see the //[[guide:connect|Connecting to the CHPC]]// guide.

=====Linux shell=====

Once connected to Lengau you will be using the Linux shell command line interface (CLI).  To be precise, the default shell is **bash**.  When you successfully connect via **ssh** you will see a display similar to:

<code>
Last login: Mon Feb 24 12:07:46 2020 from 10.128.23.164

Welcome to LENGAU

################################################################################
#                                                                              #
# In order to receive notifications via email from the CHPC all users should   #
# be subscribed to the CHPC user distribution list. If you are not part of the #
# distribution list you can subscribe at the following link:                   #
# https://lists.chpc.ac.za/mailman/listinfo/chpc-users                         #
#                                                                              #
################################################################################ 
login2:~$ 
</code>

The first part is a welcome message.  Read it first since important announcements will be displayed here: notice of shutdowns, your quota usage, //et al.//

Please take note of the ''login2:~$'' -- this is the shell //prompt// and it contains important information about your //location// in the system.  The first part, before the colon, ''login2'' indicates that you are on the //login2// node of the cluster.  This means that the command you type and the directories and files you have access to are //not// on your computer, they are on the CHPC login node.  You are connected remotely to it over the Internet

The part after the colon, and before the ''$'', displays your current working directory.  Note, at first login this will just display ''~'' which is short hand for //your// home directory path. 

Here are a few basic Linux commands which you can use:

  pwd

This prints out the current working directory.  When you do this for the first time it should display your //home// directory, e.g.,

  /home/username

Note: ''username'' will be replaced by //your// user name.  This is the actual full absolute path to your home directory and the ''~'' short form is equivalent to this.

  ls
  
The ''ls'' command lists the files in the current working directory.

  cd dir

Change directory to ''dir''.

> The lecturer will demonstrate the most commonly used commands.

=====Work Sheet=====

The practical portion of this short course uses a {{:guide:worksheet.pdf|worksheet}}.  This includes spaces for you to fill in notes and answer questions.

=====Interactive Job=====

The login nodes are not for any substantive computation, including compiling.  Instead, request an //interactive job// through the PBSPro scheduler:

<code>
qsub -I 
</code>

You will then see (after a short delay) a display similar to:

<code>
login2:~$ qsub -I -q serial -l select=1:ncpus=12:mpiprocs=12 -P WCHPC
qsub: waiting for job 2665052.sched01 to start
qsub: job 2665052.sched01 ready

cnode0040:~$ 
</code>
Note that you are now connected to a //compute node// as indicated by the prompt: you are on ''cnode0004'' and all commands you run will execute on this compute node and **not** on the ''login2'' node.


=====First Job Script=====

<code bash>
#!/bin/bash
#PBS -N example01
#PBS -l select=1:ncpus=24:mpiprocs=24
#PBS -P Wchpc
#PBS -q smp
#PBS -l walltime=0:10:00

CWD=/mnt/lustre/users/$USER/example



cd $CWD
echo "Working directory is $CWD"
nproc=`cat $PBS_NODEFILE | wc -l`
echo "nproc is $nproc"
echo "Nodes used by this job:"
cat $PBS_NODEFILE

echo "Starting run..."
# Insert command to run here:

echo "... done."
</code>

> The lecturer will explain this script and you will be able to write notes in your {{:guide:worksheet.pdf|worksheet}}.