Specifications

Niagara
Niagara
Installed	Jan 2018/March 2020
Operating System	CentOS 7.9
Number of Nodes	2,024 nodes (80,960 cores)
Interconnect	Mellanox Dragonfly+
Ram/Node	188 GiB / 202 GB
Cores/Node	40 (80 hyperthreads)
Login/Devel Node	niagara.scinet.utoronto.ca
Vendor Compilers	icc (C) ifort (fortran) icpc (C++)
Queue Submission	Slurm

The Niagara cluster is a large cluster of 2,024 Lenovo SD530 servers each with 40 Intel "Skylake" cores at 2.4 GHz (1548 nodes) or 40 Intel "CascadeLake" cores at 2.5 GHz (476 nodes). The peak performance of the cluster is about 3.6 PFlops (6.25 PFlops theoretical). It was the 53rd fastest supercomputer on the TOP500 list of June 2018, and is at number 113 on the current list (June 2021).

Each node of the cluster has 188 GiB / 202 GB RAM per node (at least 4 GiB/core for user jobs and at most 170 GiB/node roughly). 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 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.

Note: Documentation about the "GPU expansion to Niagara" called "Mist" can be found on its own page.

Getting started on Niagara

Access to Niagara is not enabled automatically for everyone with an account with the Digital Reseach Alliance of Canada (formerly Compute Canada), but anyone with an active Alliance account can get their access enabled.

If you have an active Alliance account but you do not have access to Niagara yet (e.g. because you are new to SciNet or belong to a group whose primary PI does not have an allocation as granted in the annual Alliance (formerly Compute Canada) RAC), go to the opt-in page on the CCDB site. After clicking the "Join" button, it usually takes only one or two business days for access to be granted.

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

Niagara runs CentOS 7, which is a type of Linux. You will need to be familiar with Linux systems to work 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 Alliance (formerly Compute Canada) compute systems, access to Niagara is done via SSH (secure shell) only. As of January 22 2022, authentication is only allowed via SSH keys. Please refer to this page to generate your SSH key pair and make sure you use them securely.

Open a terminal window (e.g. Connecting with PuTTY on Windows or Connecting with MobaXTerm), then SSH into the Niagara login nodes with your Alliance (formerly Compute Canada) credentials:

$ ssh -i /path/to/ssh_private_key -Y MYALLIANCEUSERNAME@niagara.scinet.utoronto.ca

or

$ ssh -i /path/to/ssh_private_key -Y MYALLIANCEUSERNAME@niagara.computecanada.ca

The first time you login to Niagara, please make sure you are actually accessing Niagara by checking if the login node ssh host key fingerprint matches (See here how). This check prevents you from falling victim of man-in-the-middle attacks.

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.
You can only connect 4 times in a 2-minute window to the login nodes.
To run on Niagara's compute nodes, you must submit a batch job.

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

Your various directories

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

You have a home and scratch directory on the system, the paths to which are stored in the environment variables $HOME and $SCRATCH. The locations are of the form

$HOME=/home/g/groupname/myallianceusername
$SCRATCH=/scratch/g/groupname/myallianceusername

where groupname is the name of your PI's group, and myallianceusername is your Alliance (formerly Compute Canada) 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/nearline

Users from groups with RAC storage allocation will also have a project directory and possible an archive (a.k.a. "nearline") directory, the paths to which are stored in the environment variables $PROJECT and $ARCHIVE. They follow the naming convention:

$PROJECT=/project/g/groupname/myallianceusername
$ARCHIVE=/archive/g/groupname/myallianceusername

NOTE: Currently archive space is available only via HPSS, and is not accessible on the Niagara login, compute, or datamover nodes.

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

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 / 250,000 files per user		1 MB		yes	yes	read-only
$SCRATCH	25 TB / 6,000,000 file per user		16 MB	2 months	no	yes	yes
$SCRATCH	50-500TB per group	depending on group size	16 MB	2 months	no	yes	yes
$PROJECT	by group allocation		16 MB		yes	yes	yes
$ARCHIVE	by group (nearline) allocation				dual-copy	no	no
$BBUFFER	10 TB per user		1 MB	very short	no	yes	yes

Moving data to Niagara

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

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>: load the default version of a particular software.
module load <module-name>/<module-version>: load a specific version of a particular software.
module purge: unload all 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

On Niagara, there are two available software stacks:

NiaEnv

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

This loads the default (set of modules), which is currently the 2019b epoch. Before September 1, the default was NiaEnv/2018a. Users are encourage to use the 2019b stack, but to make sure old job scripts or older software installations in your home directory continue to work, you may need to use

module load NiaEnv/2018a

You can override the system default for the epoch version by creating a file called .modulerc in your home directory with the line module-version NiaEnv/VERSION default, e.g. like so:

echo "module-version NiaEnv/2019b default" > $HOME/.modulerc

After this, subsequent logins and jobs will use the 2019b stack even when the system default is different.

Similarly, you can make an older epoch your personal default, like so

echo "module-version NiaEnv/2018a default" > $HOME/.modulerc

No modules are loaded by default on Niagara except NiaEnv.

CCEnv

The same software stack available on Alliance (formerly Compute Canada)'s General Purpose clusters too, with:

module load CCEnv

Or, if you want the same default modules loaded as on Béluga, then do

module load CCEnv StdEnv

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

module load CCEnv arch/avx2 StdEnv/2020

Tips for loading software

We advise against loading modules in your .bashrc. This can 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 often require other modules to be loaded first. Solve these dependencies by using module spider.

Available compilers and interpreters

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.
To compile mpi code, you must additionally load an openmpi or intelmpi module.
Open source interpreted, interactive software is also available:
- Python
- R
- Julia
- Octave

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

Using Commercial Software

May I use commercial software on Niagara?

Possibly, but you have to bring your own license for it. You can connect to an external license server using ssh tunneling.
SciNet and Template:The Alliance 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 freely available 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, and 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 Alliance (formerly Compute Canada) stack.

The list of commercial software which is installed on Niagara, for which you will need a license to use, can be found on the commercial software page.

Compiling on Niagara: Example

Suppose one wants to compile an application from two c source files, appl.c and module.c, which use the Math Kernel Library. This is an example of how this would be done:

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

nia-login07:~$ module load intel/2019u4

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 -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).
Linking with the Intel Math Kernel Library (MKL) 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 and Debugging

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: tests should run no more than a couple of minutes, taking at most about 1-2GB of memory, and use no more than a couple of cores.
You can run 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 debug command:

nia-login07:~$ debugjob --clean 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 gives you 22 minutes. The --clean argument is optional but recommended as it will start the session without any modules loaded, thus mimicking more closely what happens when you submit a job script.

Finally, if your debugjob process takes more than 1 hour, you can request an interactive job from the regular queue using the salloc command. Note, however, that this may take some time to run, since it will be part of the regular queue, and will be run when the scheduler decides.

nia-login07:~$ salloc --nodes N --time=M:00:00 --x11

where N is again the number of nodes, and M is the number of hours you wish the job to run. The --x11 is required if you need to use graphics while testing your code through salloc, e.g. when using a debugger such as DDT or DDD, See the Testing with graphics page for the options in that case.

Submitting jobs

Once you have compiled and tested your code or workflow on the Niagara login nodes, and confirmed that it behaves correctly, you are ready to submit jobs to the cluster. Your jobs will run on some of Niagara's 1548 compute nodes. When and where your job runs is determined by the scheduler.

Niagara uses SLURM as its job scheduler. More-advanced details of how to interact with the scheduler can be found on the Slurm page.

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

nia-login07:scratch$ sbatch jobscript.sh

This puts the job in the queue. It will run on the compute nodes in due course. Note that you must submit your job from a login node. You cannot submit jobs from the datamover nodes.

In most cases, you should not submit from your $HOME directory, but rather, from your $SCRATCH directory, so that the output of your compute job can be written out (as mentioned above, $HOME is read-only on the compute nodes).

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

Some example job scripts can be found below.

Keep in mind:

Scheduling is by node, so in multiples of 40 cores.
Your job's maximum walltime is 24 hours.
Jobs must write their output to your scratch or project directory (home is read-only on compute nodes).
Compute nodes have no internet access.
Your job script will not remember the modules you have loaded, so it needs to contain "module load" commands of all the required modules (see examples below).
Move your data to Niagara before you submit your job.

Scheduling by Node

On many systems that use SLURM, the scheduler will deduce from the specifications of the number of tasks and the number of cpus-per-node what resources should be allocated. On Niagara things are a bit different.

All job resource requests on Niagara are scheduled as a multiple of nodes.
The nodes that your jobs run on are exclusively yours, for as long as the job is running on them.
- 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 and 202GB is the amount of memory on the node.
If you run serial jobs you must still use all 40 cores on the node. Visit the serial jobs page for examples of how to do this.
Since there are 40 cores per node, your job should use N x 40 cores. If you do not, we will contact you to help you optimize your workflow. Or you can contact us to get assistance.

Limits

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 job 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	Limit on Running jobs	Limit on Submitted jobs (incl. running)	Min. size of jobs	Max. size of jobs	Min. walltime	Max. walltime
Compute jobs	compute	50	1000	1 node (40 cores)	default: 20 nodes (800 cores) with allocation: 1000 nodes (40000 cores)	15 minutes	24 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 (5 in total)	10 per user	N/A	N/A	15 minutes	72 hours
Inspecting archived data, small archival actions in HPSS	archiveshort vfsshort	2 per user	10 per user	N/A	N/A	15 minutes	1 hour

Even if you respect these limits, your jobs will still have to wait in the queue. The waiting time depends on many factors such as your group's allocation amount, how much allocation has been used in the recent past, the number of requested nodes and walltime, and how many other jobs are waiting in the queue.

File Input/Output Tips

It is important to understand the file systems, so as to perform your file I/O (Input/Output) responsibly. Refer to the Data Management page for details about the file systems.

Your files can be seen on all Niagara login and compute nodes.
$HOME, $SCRATCH, and $PROJECT all use the parallel file system called GPFS.
GPFS is a high-performance file system which provides rapid reads and writes to large data sets in parallel from many nodes.
Accessing data sets which consist of many, small files leads to poor performance on GPFS.
Avoid reading and writing lots of small amounts of data to disk. Many small files on the system waste space and are slower to access, read and write. If you must write many small files, use ramdisk.
Write data out in a binary format. This is faster and takes less space.
The Burst Buffer is another option for I/O heavy-jobs and for speeding up checkpoints.

Example submission script (MPI)

#!/bin/bash 
#SBATCH --nodes=2
#SBATCH --ntasks-per-node=40
#SBATCH --time=1:00:00
#SBATCH --job-name=mpi_job
#SBATCH --output=mpi_output_%j.txt
#SBATCH --mail-type=FAIL

cd $SLURM_SUBMIT_DIR

module load NiaEnv/2019b
module load intel/2019u4
module load openmpi/4.0.1

mpirun ./mpi_example
# or "srun ./mpi_example"

Submit this script from your scratch directory with the command:

   nia-login07:scratch$ sbatch mpi_job.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_job)
In this case, SLURM looks for 2 nodes each running 40 tasks (for a total of 80 tasks), for 1 hour
Note that the mpifun flag "--ppn" (processors per node) is ignored.
Once it found such a node, it runs the script:
- Change to the submission directory;
- Loads modules;
- Runs the mpi_example application (SLURM will inform mpirun or srun on how many processes to run).
To use hyperthreading, just change --ntasks-per-node=40 to --ntasks-per-node=80, and add --bind-to none to the mpirun command (the latter is necessary for OpenMPI only, not when using IntelMPI).

Example submission script (OpenMP)

#!/bin/bash
#SBATCH --nodes=1
#SBATCH --cpus-per-task=40
#SBATCH --time=1:00:00
#SBATCH --job-name=openmp_job
#SBATCH --output=openmp_output_%j.txt
#SBATCH --mail-type=FAIL

cd $SLURM_SUBMIT_DIR

module load NiaEnv/2019b
module load intel/2019u4

export OMP_NUM_THREADS=$SLURM_CPUS_PER_TASK

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