Niagara Quickstart

From Alliance Doc
Revision as of 17:32, 27 September 2018 by Pinto (talk | contribs)
Jump to navigation Jump to search
Other languages:

Specifications[edit]

The Niagara cluster is a large cluster of 1500 Lenovo SD350 servers each with 40 Intel "Skylake" cores at 2.4 GHz. The peak performance of the cluster is 3.02 PFlops delivered / 4.6 PFlops theoretical. It was ranked 53rd fastest supercomputer on the TOP500 list of June 2018.

Each node of the cluster has 188 GiB / 202 GB RAM per node (at least 4 GiB/core for user jobs). Being designed for large parallel workloads, it has a fast interconnect consisting of EDR InfiniBand in a Dragonfly+ topology with Adaptive Routing. The compute nodes are accessed through a queueing system that allows jobs with a minimum of 15 minutes and a maximum of 12 or 24 hours and favours large jobs.

See the "Intro to Niagara" recording

More detailed hardware characteristics of the Niagara supercomputer can be found on this page.

Getting started on Niagara[edit]

Those of you new to SciNet and belonging to a group whose primary PI does not have an allocation, as granted in the annual Compute Canada RAC, must first follow the old route of requesting a SciNet Consortium Account on the CCDB site to gain access to Niagara.

Please read this document carefully. The FAQ is also a useful resource. If at any time you require assistance, or if something is unclear, please do not hesitate to contact us

Logging in[edit]

Niagara runs CentOS 7, which is a type of Linux. You will need to be familiar with Linux systems to function on Niagara. If you are not it will be worth your time to review our Introduction to Linux Shell class.

As with all SciNet and CC (Compute Canada) compute systems, access to Niagara is done via ssh (secure shell) only. Open a terminal window (e.g. PuTTY on Windows or MobaXTerm), then ssh into the Niagara login nodes with your CC credentials: 

$ ssh -Y MYCCUSERNAME@niagara.scinet.utoronto.ca

or 

$ ssh -Y MYCCUSERNAME@niagara.computecanada.ca

The Niagara login nodes are where you develop, edit, compile, prepare and submit jobs.

These login nodes are not part of the Niagara compute cluster, but have the same architecture, operating system, and software stack.

The optional -Y is needed to open windows from the Niagara command-line onto your local X server.

To run on Niagara's compute nodes, you must submit a batch job.

If you cannot log in, be sure first to check the System Status on this site's front page.

Your various directories[edit]

By virtue of your access to Niagara you are granted storage space on the system. There are several directories available to you, each indicated by an associated environment variable

home and scratch[edit]

You have a home and scratch directory on the system, whose locations are of the form

$HOME=/home/g/groupname/myccusername

$SCRATCH=/scratch/g/groupname/myccusername

where groupname is the name of your PI's group, and myccusername is your CC username. For example: 

nia-login07:~$ pwd
/home/s/scinet/rzon
nia-login07:~$ cd $SCRATCH
nia-login07:rzon$ pwd
/scratch/s/scinet/rzon

NOTE: home is read-only on compute nodes.

project and archive[edit]

Users from groups with RAC storage allocation will also have a project and/or archive directory.

$PROJECT=/project/g/groupname/myccusername

$ARCHIVE=/archive/g/groupname/myccusername

NOTE: Currently archive space is available only via HPSS

IMPORTANT: Future-proof your scripts

When writing your scripts, use the environment variables ($HOME, $SCRATCH, $PROJECT, $ARCHIVE) instead of the actual paths! The paths may change in the future.

Storage and quotas[edit]

You should familiarize yourself with the various file systems, what purpose they serve, and how to properly use them. This table summarizes the various file systems. See the Data Management page for more details.

location quota block size expiration time backed up on login nodes on compute nodes
$HOME 100 GB per user 1 MB yes yes read-only
$SCRATCH 25 TB per user 16 MB 2 months no yes yes
50-500TB per group depending on group size
$PROJECT by group allocation 16 MB yes yes yes
$ARCHIVE by group allocation dual-copy no no
$BBUFFER 10 TB per user 1 MB very short no yes yes

Moving data to Niagara[edit]

If you need to move data to Niagara for analysis, or when you need to move data off of Niagara, use the following guidelines:

  • If your data is less than 10GB, move the data using the login nodes.
  • If your data is greater than 10GB, move the data using the datamover nodes nia-datamover1.scinet.utoronto.ca and nia-datamover2.scinet.utoronto.ca .

Details of how to use the datamover nodes can be found on the Data Management page.

Loading software modules[edit]

You have two options for running code on Niagara: use existing software, or compile your own. This section focuses on the former.

Other than essentials, all installed software is made available using module commands. These modules set environment variables (PATH, etc.), allowing multiple, conflicting versions of a given package to be available. A detailed explanation of the module system can be found on the modules page.

Common module subcommands are:

  • module load <module-name>: use particular software
  • module purge: remove currently loaded modules
  • module spider (or module spider <module-name>): list available software packages
  • module avail: list loadable software packages
  • module list: list loaded modules

    • Along with modifying common environment variables, such as PATH, and LD_LIBRARY_PATH, these modules also create a SCINET_MODULENAME_ROOT environment variable, which can be used to access commonly needed software directories, such as /include and /lib. There are handy abbreviations for the module commands. ml is the same as module list, and ml <module-name> is the same as module load <module-name>.

    Software stacks: NiaEnv and CCEnv[edit]

    On Niagara, there are two available software stacks:

    1. A Niagara software stack tuned and compiled for this machine. This stack is available by default, but if not, can be reloaded with

      module load NiaEnv

    2. The same software stack available on Compute Canada's General Purpose clusters Graham and Cedar, compiled (for now) for a previous generation of CPUs:

      module load CCEnv

      Or, if you want the same default modules loaded as on Cedar and Graham, then do

      module load CCEnv

      module load StdEnv

      Tips for loading software[edit]

      We advise against loading modules in your .bashrc.
      This could lead to very confusing behaviour under certain circumstances.

      Our guidelines for .bashrc files can be found here

      Instead, load modules by hand when needed, or by sourcing a separate script.

      Load run-specific modules inside your job submission script.

      Short names give default versions; e.g. intel → intel/2018.2. It is usually better to be explicit about the versions, for future reproducibility.

      Modules sometimes require other modules to be loaded first.

      Solve these dependencies by using module spider.

      Available compilers and interpreters[edit]

      • For most compiled software, one should use the Intel compilers (icc for C, icpc for C++, and ifort for Fortran). Loading an intel module makes these available.
      • The GNU compiler suite (gcc, g++, gfortran) is also available, if you load one of the gcc modules.
      • Open source interpreted, interactive software is also available:

      Please visit the Python or R page for details on using these tools. For information on running MATLAB applications on Niagara, visit this page.

      Running commercial software[edit]

      • You may have to provide your own license.
      • SciNet and Compute Canada have an extremely large and broad user base of thousands of users, so we cannot provide licenses for everyone's favorite software.
      • Thus, the only commercial software installed on Niagara is software that can benefit everyone: compilers, math libraries and debuggers.
      • That means no Matlab, Gaussian, IDL,
      • Open source alternatives like Octave, Python, R are available.
      • We are happy to help you to install commercial software for which you have a license.
      • In some cases, if you have a license, you can use software in the Compute Canada stack.

      Compiling on Niagara: Example[edit]

      Suppose one want to compile an application from two c source files, main.c and module.c, which use the Gnu Scientific Library (GSL). This is an example of how this would be done: 

      nia-login07:~$ module list
Currently Loaded Modules:
  1) NiaEnv/2018a (S)
  Where:
   S:  Module is Sticky, requires --force to unload or purge

nia-login07:~$ module load intel/2018.2 gsl/2.4

nia-login07:~$ ls
appl.c module.c

nia-login07:~$ icc -c -O3 -xHost -o appl.o appl.c
nia-login07:~$ icc -c -O3 -xHost -o module.o module.c
nia-login07:~$ icc  -o appl module.o appl.o -lgsl -mkl

nia-login07:~$ ./appl

      Note:

      • The optimization flags -O3 -xHost allow the Intel compiler to use instructions specific to the architecture CPU that is present (instead of for more generic x86_64 CPUs).
      • The GSL requires a cblas implementation, which is contained in the Intel Math Kernel Library (MKL). Linking with this library is easy when using the intel compiler, it just requires the -mkl flags.
      • If compiling with gcc, the optimization flags would be -O3 -march=native. For the way to link with the MKL, it is suggested to use the MKL link line advisor.

      Testing[edit]

      You really should test your code before you submit it to the cluster to know if your code is correct and what kind of resources you need.

      • Small test jobs can be run on the login nodes.

        Rule of thumb: couple of minutes, taking at most about 1-2GB of memory, couple of cores.

      • You can run the the ddt debugger on the login nodes after module load ddt.

      • Short tests that do not fit on a login node, or for which you need a dedicated node, request an
        interactive debug job with the salloc command

        nia-login07:~$ salloc -pdebug --nodes N --time=1:00:00

        where N is the number of nodes. The duration of your interactive debug session can be at most one hour, can use at most 4 nodes, and each user can only have one such session at a time.

        Alternatively, on Niagara, you can use the command 

        nia-login07:~$ debugjob N

        where N is the number of nodes, If N=1, this gives an interactive session one 1 hour, when N=4 (the maximum), it give you 30 minutes.

      Testing with Graphics: X-forwarding[edit]

      If you need to use graphics while testing your code, e.g. when using a debugger such as DDT or DDD, you have the following options:

      • You can use the debugjob command which automatically provides X-forwarding support. 
        $ ssh  niagara.scinet.utoronto.ca -X

USER@nia-login07:~$ debugjob
debugjob: Requesting 1 nodes for 60 minutes
xalloc: Granted job allocation 189857
xalloc: Waiting for resource configuration
xalloc: Nodes nia0030 are ready for job

[USER@nia1265 ~]$
      • If debugjob is not suitable for your case due to the limitations either on time or resources (see above #Testing), then you have to follow these steps: You will need two terminals in order to achieve this:
        1. In the 1st terminal
          • ssh to niagara.scinet.utoronto.ca and issue your salloc command
          • wait until your resources are allocated and you are assigned the nodes
          • take note of the node where you are logged to, ie. the head node, let's say niaWXYZ 
          $ ssh  niagara.scinet.utoronto.ca
USER@nia-login07:~$ salloc --nodes 5 --time=2:00:00

.salloc: Granted job allocation 141862
.salloc: Waiting for resource configuration
.salloc: Nodes nia1265 are ready for job

[USER@nia1265 ~]$
        2. On the second terminal:
          • ssh into niagara.scinet.utoronto.ca now using the -X flag in the ssh command
          • after that ssh -X niaWXYZ, ie. you will ssh carrying on the '-X' flag into the head node of the job
          • in the niaWXYZ you should be able to use graphics and should be redirected by x-forwarding to your local terminal 
          ssh niagara.scinet.utoronto.ca -X
USER@nia-login07:~$ ssh -X nia1265
[USER@nia1265 ~]$ xclock   ## just an example to test the graphics, a clock should pop up, close it to exit
[USER@nia1265 ~]$ module load ddt  ## load corresponding modules, eg. for DDT
[USER@nia1265 ~]$ ddt  ## launch DDT, the GUI should appear in your screen


      Observations:

      • If you are using ssh from a Windows machine, you need to have an X-server, a good option is to use MobaXterm, that already brings an X-server included.
      • If you are in Mac OS, substitute -X by -Y
      • Instead of using two terminals, you could just use screen to request the resources and then detach the session and ssh into the head node directly.

      Submitting jobs[edit]

      • Niagara uses SLURM as its job scheduler.

      • You submit jobs from a login node by passing a script to the sbatch command:

        nia-login07:~$ sbatch jobscript.sh

      • This puts the job in the queue. It will run on the compute nodes in due course.

      • Jobs will run under their group's RRG allocation, or, if the group has none, under a RAS allocation (previously called `default' allocation).

      Keep in mind:

      • Scheduling is by node, so in multiples of 40-cores.

      • Maximum walltime is 24 hours (or 12 hours for users without an allocation).

      • Jobs must write to your scratch or project directory (home is read-only on compute nodes).

      • Compute nodes have no internet access.

        Download data you need beforehand on a login node.

      SLURM nomenclature: jobs, nodes, tasks, cpus, cores, threads[edit]

      SLURM, which is the job scheduler used on Niagara, has a somewhat different way of referring to things like mpi processes and threads tasks. The SLURM nomenclature is reflected in the names of scheduler option (i.e., resource requests). SLURM strictly enforces those requests, so it is important to get this right.

      term meaning SLURM term related scheduler options
      job scheduled piece of work for which specific resources were requested. job sbatch, salloc
      node basic computing component with several cores (40 for Niagara) that share memory node --nodes -N
      mpi process one of a group of running programs using Message Passing Interface for parallel computing task --ntasks -n --ntasks-per-node
      core or physical cpu A fully functional independent physical execution unit. - -
      logical cpu An execution unit that the operating system can assign work to. Operating systems can be configured to overload physical cores with multiple logical cpus using hyperthreading. cpu --ncpus-per-task
      thread one of possibly multiple simultaneous execution paths within a program, which can share memory. - --ncpus-per-task and OMP_NUM_THREADS
      hyperthread a thread run in a collection of threads that is larger than the number of physical cores. - -

      Scheduling by node[edit]

      • All job resource requests on Niagara are scheduled as a multiple of nodes.

      • The nodes that your jobs run on are exclusively yours.
        • No other users are running anything on them.
        • You can ssh into them to see how things are going.

      • Whatever your requests to the scheduler, it will always be translated into a multiple of nodes allocated to your job.

      • Memory requests to the scheduler are of no use. Your job always gets N x 202GB of RAM, where N is the number of nodes.

      • You should try to use all the cores on the nodes allocated to your job. Since there are 40 cores per node, your job should use N x 40 cores. If this is not the case, we will be contacted you to help you optimize your workflow.

      Hyperthreading: Logical CPUs vs. cores[edit]

      Hyperthreading, a technology that leverages more of the physical hardware by pretending there are twice as many logical cores than real once, is enabled on Niagara.

      So the OS and scheduler see 80 logical cores.

      80 logical cores vs. 40 real cores typically gives about a 5-10% speedup (Your Mileage May Vary).

      Because Niagara is scheduled by node, hyperthreading is actually fairly easy to use:

      • Ask for a certain number of nodes N for your jobs.
      • You know that you get 40xN cores, so you will use (at least) a total of 40xN mpi processes or threads. (mpirun, srun, and the OS will automaticallly spread these over the real cores)
      • But you should also test if running 80xN mpi processes or threads gives you any speedup.
      • Regardless, your usage will be counted as 40xNx(walltime in years).

      Limits[edit]

      There are limits to the size and duration of your jobs, the number of jobs you can run and the number of jobs you can have queued. It matters whether a user is part of a group with a Resources for Research Group allocation or not. It also matters in which 'partition' the jobs runs. 'Partitions' are SLURM-speak for use cases. You specify the partition with the -p parameter to sbatch or salloc, but if you do not specify one, your job will run in the compute partition, which is the most common case.

      Usage Partition Running jobs Submitted jobs (incl. running) Min. size of jobs Max. size of jobs Min. walltime Max. walltime
      Compute jobs with an allocation compute 50 1000 1 node (40 cores) 1000 nodes (40000 cores) 15 minutes 24 hours
      Compute jobs without allocation ("default") compute 50 200 1 node (40 cores) 20 nodes (800 cores) 15 minutes 12 hours
      Testing or troubleshooting debug 1 1 1 node (40 cores) 4 nodes (160 cores) N/A 1 hour
      Archiving or retrieving data in HPSS archivelong 2 per user (max 5 total) 10 per user N/A N/A 15 minutes 72 hours
      Inspecting archived data, small archival actions in HPSS archiveshort 2 per user 10 per user N/A N/A 15 minutes 1 hour

      Within these limits, jobs will still have to wait in the queue. The waiting time depends on many factors such as the allocation amount, how much allocation was used in the recent past, the number of nodes and the walltime, and how many other jobs are waiting in the queue.

      SLURM Accounts[edit]

      To be able to prioritise jobs based on groups and allocations, the SLURM scheduler uses the concept of accounts. Each group that has a Resource for Research Groups (RRG) or Research Platforms and Portals (RPP) allocation (awarded through an annual competition by Compute Canada) has an account that starts with rrg- or rpp-. SLURM assigns a 'fairshare' priority to these accounts based on the size of the award in core-years. Groups without an RRG or RPP can use Niagara using a so-called Rapid Access Service (RAS), and have an account that starts with def-.

      On Niagara, most users will only ever use one account, and those users do not need to specify the account to SLURM. However, users that are part of collaborations may be able to use multiple accounts, i.e., that of their sponsor and that of their collaborator, but this mean that they need to select the right account when running jobs.

      To select the account, just add 

         #SBATCH -A [account]

      to the job scripts, or use the -A [account] to salloc or debugjob.

      To see which accounts you have access to, or what their names are, use the command 

         sshare -U

      Passing Variables to Job's submission scripts[edit]

      It is possible to pass values through environment variables into your SLURM submission scripts. For doing so with already defined variables in your shell, just add the following directive in the submission script, 

      #SBATCH --export=ALL

      and you will have access to any predefined environment variable.

      A better way is to specify explicitly which variables you want to pass into the submision script, 

      sbatch --export=i=15,j='test' jobscript.sbatch

      You can even set the job name and output files using environment variables, eg. 

      i="simulation"
j=14
sbatch --job-name=$i.$j.run --output=$i.$j.out --export=i=$i,j=$j jobscript.sbatch

      (The latter only works on the command line; you cannot use environment variables in #SBATCH lines in the job script.)

      Command line arguments:

      Command line arguments can also be used in the same way as command line argument for shell scripts. All command line arguments given to sbatch that follow after the job script name, will be passed to the job script. In fact, SLURM will not look at any of these arguments, so you must place all sbatch arguments before the script name, e.g.: 

      sbatch  -p debug  jobscript.sbatch  FirstArgument SecondArgument ...

      In this example, -p debug is interpreted by SLURM, while in your submission script you can access FirstArgument, SecondArgument, etc., by referring to $1, $2, ....

      Email Notification[edit]

      Email notification works, but you need to add the email address and type of notification you may want to receive in your submission script, eg. 

         #SBATCH --mail-user=YOUR.email.ADDRESS
   #SBATCH --mail-type=ALL

      If you omit the mail-user option, the scheduler will use the primary email address associated with your Compute Canada account.

      The sbatch man page (type man sbatch on Niagara) explains all possible mail-types.

      Example submission script (MPI)[edit]

      Suppose you want to run an MPI application called appl_mpi_ex with 320 processes. The job script could look as follows: 

      #!/bin/bash 
#SBATCH --nodes=8
#SBATCH --ntasks=320
#SBATCH --time=1:00:00
#SBATCH --job-name mpi_ex
#SBATCH --output=mpi_ex_%j.txt

cd $SLURM_SUBMIT_DIR

module load intel/2018.2
module load openmpi/3.1.0rc3

mpirun ./appl_mpi_ex

      Submit this script (if it is called mpi_ex.sh) with the command: 

      nia-login07:~$ sbatch mpi_ex.sh

      • First line indicates that this is a bash script.

      • Lines starting with #SBATCH go to SLURM.

      • sbatch reads these lines as a job request (which it gives the name mpi_ex)

      • In this case, SLURM looks for 8 nodes with 40 cores on which to run 320 tasks, for 1 hour.

      • Once it found such a node, it runs the script:

        • Change to the submission directory;
        • Loads modules;
        • Runs the appl_mpi_ex application with mpirun (srun should work too).
      • To use hyperthreading, just change --ntasks=320 to --ntasks=640, and add --bind-to none to the mpirun command (the latter is necessary for OpenMPI only, not when using IntelMPI).

      Example submission script (OpenMP)[edit]

      Suppose you want to run a single-node, multi-threaded application called appl_openmp_ex that uses OpenMP. The job script could look as follows: 

      #!/bin/bash
#SBATCH --nodes=1
#SBATCH --cpus-per-task=40
#SBATCH --time=1:00:00
#SBATCH --job-name openmp_ex
#SBATCH --output=openmp_ex_%j.txt

cd $SLURM_SUBMIT_DIR

module load intel/2018.2

export OMP_NUM_THREADS=$SLURM_CPUS_PER_TASK

./openmp_example
# or "srun ./openmp_example".

      Submit this script (if it is called openmp_ex.sh) with the command: 

      nia-login07:~$ sbatch openmp_ex.sh
      • First line indicates that this is a bash script.
      • Lines starting with #SBATCH go to SLURM.
      • sbatch reads these lines as a job request (which it gives the name openmp_ex) .
      • In this case, SLURM looks for one node with 40 cores to be run inside one task, for 1 hour.
      • Once it found such a node, it runs the script:
        • Change to the submission directory;
        • Loads modules (must be done again in the submission script on Niagara);
        • Sets an environment variable to set the number of threads to 40 (no hyperthreading in this example);
        • Runs the appl_openmp_ex application.
      • To use hyperthreading, just change --cpus-per-task=40 to --cpus-per-task=80.

      Monitoring queued jobs[edit]

      Once the job is incorporated into the queue, there are some command you can use to monitor its progress.

      • squeue or sqc (a caching version of squeue) to show the job queue (squeue -u $USER for just your jobs);

      • qsum shows a summary of qudue by user

      • squeue -j JOBID to get information on a specific job

        (alternatively, scontrol show job JOBID, which is more verbose).

      • squeue --start -j JOBID to get an estimate for when a job will run; these tend not to be very accurate predictions.

      • scancel -i JOBID to cancel the job.

      • sinfo -pcompute to look at available nodes.

      • jobperf JOBID to get an instantaneous view of the cpu and memory usage of the nodes of the job while it is running.

      • sacct to get information on your recent jobs.

      For more information, check out the wiki page devoted to Running jobs.

      Visualization[edit]

      Information about how to use visualization tools on Niagara is available on Visualization page.

      Further information[edit]

      Useful sites

      Support

      • support@scinet.utoronto.ca
      • niagara@computecanada.ca

    Intel Math Kernel Library, a software library of optimized math routines

    Rapid Access Service

    Message Passing Interface

    Retrieved from "https://docs.alliancecan.ca/mediawiki/index.php?title=Niagara_Quickstart&oldid=58232"