Niagara Quickstart

System information and Specifications

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 is the 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.

Using Niagara: Logging in

Those of you new to SciNet and belonging to a group whose primary PI doesn't have a RAC, to gain access to niagara you will need first to follow the old route of requesting a SciNet Consortium Account on the CCDB site.

Otherwise, as with all SciNet and CC (Compute Canada) compute systems, access to Niagara is done via ssh (secure shell) only. Just 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.

Locating your directories

Home and scratch

Users have a home and scratch directory on the system, whose locations will be given by

$HOME=/home/g/groupname/myccusername

$SCRATCH=/scratch/g/groupname/myccusername

For example:

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

nia-login07:~$ cd $SCRATCH

nia-login07:rzon$ pwd
/scratch/s/scinet/rzon

project and archive

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

Use the environment variables (HOME, SCRATCH, PROJECT, ARCHIVE) instead of the actual paths! The paths may change in the future.

Data Management

Purpose of each file system

/home

/home is intended primarily for individual user files, common software or small datasets used by others in the same group, provided it does not exceed individual quotas. Otherwise you may consider /scratch or /project. /home is read-only on the compute nodes.

/scratch

/scratch is to be used primarily for temporary or transient files, for all the results of your computations and simulations, or any material that can be easily recreated or reacquired. You may use scratch as well for any intermediate step in your workflow, provided it does not induce too much IO or too many small files on this disk-based storage pool, otherwise you should consider burst buffer (/bb). Once you have your final results, those that you want to keep for the long term, you may migrate them to /project or /archive. /scratch is purged on a regular basis and has no backups.

/project

/project is intended for common group software, large static datasets, or any material very costly to be reacquired or re-generated by the group. Material on /project is expected to be relatively immutable over time. Temporary or transient files should be kept on scratch, not project. High data turnover induces the consumption of a lot of tapes on the TSM backup system, long after this material has been deleted, due to backup retention policies and the extra versions kept of the same file. Users abusing the project file system and using it as scratch will be flagged and contacted. Note that on niagara /project is only available to groups with RAC allocation.

/bb (burst buffer)

/bb is basically a very fast, very high performance alternative to /scratch, made of solid-state drives (SSD). You may request this resource instead, if you anticipate a lot of IO/IOPs (too much for scratch) or when you notice your job is not performing well running on scratch or project because of IO bottlenecks. Keep in mind, we can only offer 232TB for all niagara users at any given time. Once you get your results you may bundle/tarball them and move to scratch, project or archive. /bb is purged very frequently.

/archive

/archive is a nearline storage pool, if you want to temporarily offload semi-active material from any of the above file systems. In practice users will offload/recall material as part of their regular workflow, or when they hit their quotas on scratch or project. That material can remain on HPSS for a few months to a few years. Note that on niagara /archive is only available to groups with RAC allocation.

Performance

GPFS is a high-performance filesystem which provides rapid reads and writes to large datasets in parallel from many nodes. As a consequence of this design, however, the file system performs quite poorly at accessing data sets which consist of many, small files. For instance, you will find that reading data in from one 16MB file is enormously faster than from 400 40KB files. Such small files are also quite wasteful of space, as the blocksize for the scratch and project filesystems is 16MB. This is something you should keep in mind when planning your input/output strategy for runs on SciNet.

For instance, if you run multi-process jobs, having each process write to a file of its own is not an scalable I/O solution. A directory gets locked by the first process accessing it, so all other processes have to wait for it. Not only has the code just become considerably less parallel, chances are the file system will have a time-out while waiting for your other processes, leading your program to crash mysteriously. Consider using MPI-IO (part of the MPI-2 standard), which allows files to be opened simultaneously by different processes, or using a dedicated process for I/O to which all other processes send their data, and which subsequently writes this data to a single file.

Migration to Niagara

Migration for Existing Users of the GPC

Niagara is replacing the General Purpose Cluster (GPC) and the Tightly Coupled Cluster (TCS) at SciNet. The TCS was decommissioned last fall, and the compute nodes of the GPC were decommissioned on April 21, 2018, while the storage attached to the GPC will be decommissioned on May 30, 2018..

Active GPC Users have access to Niagara since April 9, 2018.

Active GPC Users got access to the new system, Niagara, on April 9, 2018.

Users' home and project folder were last copied over from the GPC to Niagara on April 5th, 2018, except for files whose name start with a period that were in their home directories (these files were never synced).

It is the user's responsibility to copy to Niagara any data generated on the GPC after April 5th, 2018.

Data stored in scratch has also not been transferred automatically. Users are to clean up their scratch space on the GPC as much as possible (remember it's temporary data!). Then they can transfer what they need using datamover nodes.

To enable this transfer, there will be a short period during which you can have access to Niagara as well as to the GPC storage resources. This period will end on May 30, 2018..

To copy substantial amounts of data (i.e.,more than 10 GB), please use the datamovers of both the GPC (called gpc-logindm01 and gpc-logindm02) and the Niagara datamovers (called nia-dm1 and nia-dm2). For instance, to copy a directory abc from your GPC scratch to your Niagara scratch directory, you can do the following:

$ ssh CCUSERNAME@niagara.computecanada.ca
$ ssh nia-dm1
$ scp -r SCINETUSERNAME@gpc-logindm01:\$SCRATCH/abc $SCRATCH/abc

For many of you, CCUSERNAME and SCINETUSERNAME will be the same. Make sure you use the backslash (\) before the first $SCRATCH; it causes the value of scratch on the remote node (i.e., here, gpc-logindm01) to be used. Note that the gpc-logindm01 will ask for your SciNet password.

You can also go the other way:

$ ssh SCINETUSERNAME@login.scinet.utoronto.ca
$ ssh gpc-logindm01
$ scp -r $SCRATCH/abc CCUSERNAME@nia-dm1:\$SCRATCH/abc

Again, pay attention to the backslash in front of the last occurrence of $SCRATCH.

If you are using rsync, we advise to refrain from using the -a flags, and if using cp, refrain from using the -a and -p flags.

Non-GPC users

Those who are new to SciNet, but have 2018 RAC allocations on Niagara, will have their accounts created and ready for them to login.

New, non-RAC users: we are still working out the procedure to get access. If you can't wait, for now, you can follow the old route of requesting a SciNet Consortium Account on the CCDB site.

Moving data

Move amounts less than 10GB through the login nodes.

• Only Niagara login nodes visible from outside SciNet.
• Use scp or rsync to niagara.scinet.utoronto.ca or niagara.computecanada.ca (no difference).
• This will time out for amounts larger than about 10GB.

Move amounts larger than 10GB through the datamover nodes.

• From a Niagara login node, ssh to nia-datamover1 or nia-datamover2.
• Transfers must originate from this datamover.
• The other side (e.g. your machine) must be reachable from the outside.
• If you do this often, consider using [Globus], a web-based tool for data transfer.

Moving data to HPSS/Archive/Nearline using the scheduler.

• HPSS is a tape-based storage solution, and is SciNet's nearline a.k.a. archive facility.
• Storage space on HPSS is allocated through the annual Compute Canada RAC allocation.

Moving Data using Globus

Please check the comprehensive documentation [here]

Niagara endpoint is "computecanada#niagara"

Storage and quotas

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 (dynamic per group)		16 MB	2 months	no	yes	yes
	up to 4 users per group	50TB
	up to 11 users per group	125TB
	up to 28 users per group	250TB
	up to 60 users per group	400TB
	above 60 users per group	500TB
$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

• Inode vs. Space quota (PROJECT and SCRATCH)
• dynamic quota per group (SCRATCH)
• Compute nodes do not have local storage.
• Archive space is on HPSS
• Backup means a recent snapshot, not an achive of all data that ever was.

• $BBUFFER stands for the Buffer, a faster parallel storage tier for temporary data.

Loading software modules

Other than essentials, all installed software is made available using module commands. These modules set environment variables (PATH, etc.) This allows multiple, conflicting versions of a given package to be available. module spider shows the available software.

For example:

nia-login07:~$ module spider
---------------------------------------------------
The following is a list of the modules currently av
---------------------------------------------------
  CCEnv: CCEnv

  NiaEnv: NiaEnv/2018a

  anaconda2: anaconda2/5.1.0

  anaconda3: anaconda3/5.1.0

  autotools: autotools/2017
    autoconf, automake, and libtool 

  boost: boost/1.66.0

  cfitsio: cfitsio/3.430

  cmake: cmake/3.10.2 cmake/3.10.3

  ...

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

On Niagara, there are really two 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
   

   If you want the same default modules as those loaded on Cedar and Graham, also run module load StdEnv.

Note: the *Env modules are sticky; remove them by --force.

Tips for loading software

We advise against loading modules in your .bashrc on Niagara. This can lead to very confusing behaviour under certain circumstances. Instead, load modules by hand when needed, or by sourcing a separate script, and 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.

There are some handy abbreviations of the module command:

        ml → module list
        ml NAME → module load NAME  # if NAME is an existing module
        ml X → module X

Modules sometimes require other modules to be loaded first.

Solve these dependencies by using module spider.

Module spider

Oddly named, the module subcommand spider is the search-and-advise facility for modules.

Suppose one wanted to load the openmpi module. Upon trying to load the module, one may get the following message:

nia-login07:~$ module load openmpi
Lmod has detected the error:  These module(s) exist but cannot be loaded as requested: "openmpi"
   Try: "module spider openmpi" to see how to load the module(s).

So while that fails, following the advice that the command outputs, the next command would be:

nia-login07:~$ module spider openmpi
------------------------------------------------------------------------------------------------------
  openmpi:
------------------------------------------------------------------------------------------------------
     Versions:
        openmpi/2.1.3
        openmpi/3.0.1
        openmpi/3.1.0rc3

------------------------------------------------------------------------------------------------------
  For detailed information about a specific "openmpi" module (including how to load the modules) use
  the module s full name.
  For example:

     $ module spider openmpi/3.1.0rc3
------------------------------------------------------------------------------------------------------

So this gives just more details suggestions on using the spider command. Following the advice again, one would type:

nia-login07:~$ module spider openmpi/3.1.0rc3
------------------------------------------------------------------------------------------------------
  openmpi: openmpi/3.1.0rc3
------------------------------------------------------------------------------------------------------
    You will need to load all module(s) on any one of the lines below before the "openmpi/3.1.0rc3"
    module is available to load.

      NiaEnv/2018a  gcc/7.3.0
      NiaEnv/2018a  intel/2018.2

These are concrete instructions on how to load this particular openmpi module. Following these leads to a successful loading of the module.

nia-login07:~$ module load NiaEnv/2018a  intel/2018.2
nia-login07:~$ module load openmpi/3.1.0rc3

nia-login07:~$ module list
Currently Loaded Modules:
  1) NiaEnv/2018a (S)   2) intel/2018.2   3) openmpi/3.1.0.rc3

  Where:
   S:  Module is Sticky, requires --force to unload or purge

Running commercial software

• 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

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

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.

Submitting jobs

• 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.

Scheduling by node

• 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

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).

Example submission script (OpenMP)

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

./appl_openmp_ex

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.

Example submission script (MPI)

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).

Monitoring queued jobs

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

• squeue or qsum to show the job queue (squeue -u $USER for just your jobs);

• 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.

  Since this is not very accurate, you might be interested to know how far back in the queue your job is. This can be accomplished with the following bash function:

  function qpos() {
      if [ "$#" -eq 0 ]; then
           squeue -u "$USER" | tail -n-1 | tr -s ' ' | cut -d' ' -f2 | while read jid; do
              squeue | tr -s ' ' | cut -d' ' -f2 | sort -n | cat -n | grep "$jid"
          done | tr -s ' ' | sort -n -t' ' -k1 
      fi
      for jid in "$@"; do
          squeue | tr -s ' ' | cut -d' ' -f2 | sort -n | cat -n | grep "$jid"
      done
  }
  

  Usage:

  qpos
  
  

• 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.

Data management and I/O tips

• $HOME, $SCRATCH, and $PROJECT all use the parallel file system called GPFS.
• Your files can be seen on all Niagara login and compute nodes.
• GPFS is a high-performance file system which provides rapid reads and writes to large data sets in parallel from many nodes.
• But accessing data sets which consist of many, small files leads to poor performance.
• Avoid reading and writing lots of small amounts of data to disk.
  

• Many small files on the system would waste space and would be slower to access, read and write.
• Write data out in binary. Faster and takes less space.
• Burst buffer (to come) is better for i/o heavy jobs and to speed up checkpoints.

Resource Allocation Competition

Message Passing Interface

Globus is a file transfer service

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

Rapid Access Service