Difference between revisions of "Niagara Quickstart"

From SciNet Users Documentation
Jump to: navigation, search
(Testing with Graphics: X-forwarding)
(Logging in)
 
(196 intermediate revisions by 8 users not shown)
Line 2: Line 2:
 
|image=[[Image:Niagara.jpg|center|300px|thumb]]
 
|image=[[Image:Niagara.jpg|center|300px|thumb]]
 
|name=Niagara
 
|name=Niagara
|installed=Jan 2018
+
|installed=Jan 2018/March 2020
|operatingsystem= CentOS 7.4
+
|operatingsystem= CentOS 7.6
 
|loginnode= niagara.scinet.utoronto.ca
 
|loginnode= niagara.scinet.utoronto.ca
|nnodes=  1500 nodes (60,000 cores)
+
|nnodes=  2,024 nodes (80,960 cores)
 
|rampernode=188 GiB / 202 GB   
 
|rampernode=188 GiB / 202 GB   
 
|corespernode=40 (80 hyperthreads)
 
|corespernode=40 (80 hyperthreads)
Line 15: Line 15:
 
=Specifications=
 
=Specifications=
  
The Niagara cluster is a large cluster of 1500 Lenovo SD350 servers each with 40 Intel "Skylake" cores at 2.4 GHz.  
+
The Niagara cluster is a large cluster of 2,024 Lenovo SD530 servers each with 40 Intel "Skylake" at 2.4 GHz or 40 Intel "CascadeLake" cores at 2.5 GHz.  
The peak performance of the cluster is 3.02 PFlops delivered / 4.6 PFlops theoretical.  It is the 53rd fastest supercomputer on the [https://www.top500.org/list/2018/06/?page=1 TOP500 list of June 2018].  
+
The peak performance of the cluster is about 3.6 PFlops (6.25 PFlops theoretical).  It was the 53rd fastest supercomputer on the [https://www.top500.org/list/2018/06/?page=1 TOP500 list of June 2018], and is at number 113 on the [https://www.top500.org/lists/top500/list/2021/06/ 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).  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.
+
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 24 hours and favours large jobs.
  
* See the [https://support.scinet.utoronto.ca/education/go.php/370/content.php/cid/1383/ "Intro to Niagara"] recording
+
* See the [https://www.youtube.com/watch?v=l-E2CFGh0BE&feature=youtu.be "Intro to Niagara"] recording
  
= Using Niagara: Logging in =
+
More detailed hardware characteristics of the Niagara supercomputer can be found [https://docs.computecanada.ca/wiki/Niagara on this page].
  
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 [https://www.scinethpc.ca/getting-a-scinet-account/ requesting a SciNet Consortium Account on the CCDB site.]
+
Note: Documentation about the "GPU expansion to Niagara" called "Mist" can be found on [[Mist | its own page]].
  
Otherwise, as with all SciNet and CC (Compute Canada) compute systems, access to Niagara is done via ssh (secure shell) only.
+
= Getting started on Niagara =
Just open a terminal window (e.g. MobaXTerm on Windows), then ssh into the Niagara login nodes with your CC credentials:
+
 
 +
Access to Niagara is not enabled automatically for everyone with a Compute Canada account, but anyone with an active Compute Canada account can get their access enabled.
 +
 +
If you have an active Compute Canada 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 [https://www.computecanada.ca/research-portal/accessing-resources/resource-allocation-competitions Compute Canada RAC]), go to the [https://ccdb.computecanada.ca/services/opt_in 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 [https://docs.scinet.utoronto.ca/index.php/FAQ FAQ] is also a useful resource.  If at any time you require assistance, or if something is unclear, please do not hesitate to [mailto:support@scinet.utoronto.ca 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 [https://support.scinet.utoronto.ca/education/browse.php?category=-1&search=scmp101&include=all&filter=Filter 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. Connecting with [https://docs.computecanada.ca/wiki/Connecting_with_PuTTY PuTTY] on Windows or Connecting with [https://docs.computecanada.ca/wiki/Connecting_with_MobaXTerm MobaXTerm]), then SSH into the Niagara login nodes with your CC credentials:
  
 
  $ ssh -Y MYCCUSERNAME@niagara.scinet.utoronto.ca
 
  $ ssh -Y MYCCUSERNAME@niagara.scinet.utoronto.ca
Line 34: Line 45:
  
 
  $ ssh -Y MYCCUSERNAME@niagara.computecanada.ca
 
  $ ssh -Y MYCCUSERNAME@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 [[SSH_Changes_in_May_2019 | (See here how)]]. This check prevents you from falling victim of [https://en.wikipedia.org/wiki/Man-in-the-middle_attack man-in-the-middle attacks.]
  
 
* The Niagara login nodes are where you develop, edit, compile, prepare and submit jobs.
 
* 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.
 
* These login nodes are not part of the Niagara compute cluster, but have the same architecture, operating system, and software stack.
 
* The optional <code>-Y</code> is needed to open windows from the Niagara command-line onto your local X server.
 
* The optional <code>-Y</code> 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.
+
* You can only connect 4 times in a 2-minute window to the login nodes.
 +
* To run on Niagara's compute nodes, you must [[#Submitting_jobs | submit a batch job]].
  
If you cannot log in, be sure first to check the [https://docs.scinet.utoronto.ca System Status] on this site's front page.
+
If you cannot log in, be sure to first check the [https://docs.scinet.utoronto.ca System Status] on this site's front page.
  
= Locating your directories =
+
== Your various directories ==
  
== home and scratch ==
+
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.
  
You have a home and scratch directory on the system, whose locations will be given in the form
+
=== home and scratch ===
  
<code>$HOME=/home/g/groupname/myccusername</code>
+
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
  
<code>$SCRATCH=/scratch/g/groupname/myccusername</code>
+
$HOME=/home/g/groupname/myccusername
 +
$SCRATCH=/scratch/g/groupname/myccusername
  
For example:
+
where groupname is the name of your PI's group, and myccusername is your CC username.  For example:
  
 
   nia-login07:~$ pwd
 
   nia-login07:~$ pwd
Line 62: Line 77:
 
NOTE: home is read-only on compute nodes.
 
NOTE: home is read-only on compute nodes.
  
== project and archive==
+
=== project and archive/nearline ===
  
Users from groups with RAC storage allocation will also have a project and/or archive directory.
+
Users from groups with [https://www.computecanada.ca/research-portal/accessing-resources/resource-allocation-competitions 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:
  
<code>$PROJECT=/project/g/groupname/myccusername</code>
+
$PROJECT=/project/g/groupname/myccusername
 +
$ARCHIVE=/archive/g/groupname/myccusername
  
<code>$ARCHIVE=/archive/g/groupname/myccusername</code>
+
NOTE: Currently archive space is available only via [[HPSS]], and is not accessible on the Niagara login, compute, or datamover nodes.
 
 
NOTE: Currently archive space is available only via [[HPSS|HPSS]]
 
  
 
'''''IMPORTANT: Future-proof your scripts'''''
 
'''''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.
+
When writing your scripts, use the environment variables (<tt>$HOME</tt>, <tt>$SCRATCH</tt>, <tt>$PROJECT</tt>, <tt>$ARCHIVE</tt>) 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. <font color=red>Material on /project is expected to be relatively immutable over time.</font> 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==
 
[http://en.wikipedia.org/wiki/IBM_General_Parallel_File_System 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.
+
=== Storage and quotas ===
  
Active GPC Users got access to the new system, Niagara, on April 9, 2018.
+
You should familiarize yourself with the [[Data_Management#Purpose_of_each_file_system | various file systems]], what purpose they serve, and how to properly use them. This table summarizes the various file systemsSee the [[Data_Management | Data Management]] page for more details.
 
 
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 over data generated on the GPC after April 5th, 2018.
 
 
 
Data stored in scratch has also not been transfered 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 users, CCUSERNAME amd SCINETUSERNAME will be the same. Make sure you use the slash (\) before the first $SCRATCH; it cause 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 slash in front of the last occurrence of $SCRATCH.
 
 
 
If you are using rsync, we advice to refrain from using the -a flags, and if using cp, refrain from using the -a and -p flags.
 
 
 
==== For Non-GPC Users ====
 
 
 
Those of you new to SciNet, but with 2018 RAC allocations on Niagara, will have your accounts created and ready for you 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 [https://www.scinethpc.ca/getting-a-scinet-account/ 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 <code>nia-datamover1</code> or <code>nia-datamover2</code>.
 
* 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|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 [https://www.computecanada.ca/research-portal/accessing-resources/resource-allocation-competitions Compute Canada RAC allocation].
 
 
 
== Storage and quotas ==
 
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 171: Line 104:
 
|-
 
|-
 
| $HOME
 
| $HOME
|colspan="2"| 100 GB per user
+
|colspan="2"| 100 GB / 250,000 files per user
 
|align="right"| 1 MB
 
|align="right"| 1 MB
 
|  
 
|  
Line 178: Line 111:
 
| read-only
 
| read-only
 
|-
 
|-
|rowspan="6"| $SCRATCH
+
|rowspan="2"| $SCRATCH
|colspan="2"| 25 TB per user (dynamic per group)
+
|colspan="2"| 25 TB / 6,000,000 file per user
|align="right" rowspan="6" | 16 MB
+
|align="right" rowspan="2" | 16 MB
|rowspan="6"| 2 months
+
|rowspan="2"| 2 months
|rowspan="6"| no
+
|rowspan="2"| no
|rowspan="6"| yes
+
|rowspan="2"| yes
|rowspan="6"| yes
+
|rowspan="2"| yes
 
|-
 
|-
|align="right"|up to 4 users per group
+
|align="right"|50-500TB per group
|align="right"|50TB
+
|align="right"|[[Data_Management#Quotas_and_purging | depending on group size]]
|-
 
|align="right"|up to 11 users per group
 
|align="right"|125TB
 
|-
 
|align="right"|up to 28 users per group
 
|align="right"|250TB
 
|-
 
|align="right"|up to 60 users per group
 
|align="right"|400TB
 
|-
 
|align="right"|above 60 users per group
 
|align="right"|500TB
 
 
|-
 
|-
 
| $PROJECT
 
| $PROJECT
Line 210: Line 131:
 
|-
 
|-
 
| $ARCHIVE
 
| $ARCHIVE
|colspan="2"| by group allocation
+
|colspan="2"| by group (nearline) allocation
 
|align="right"|  
 
|align="right"|  
 
|
 
|
Line 226: Line 147:
 
|}
 
|}
  
<ul>
+
=== Moving data to Niagara ===
<li>[https://docs.scinet.utoronto.ca/images/9/9a/Inode_vs._Space_quota_-_v2x.pdf Inode vs. Space quota (PROJECT and SCRATCH)]</li>
 
<li>[https://docs.scinet.utoronto.ca/images/0/0e/Scratch-quota.pdf dynamic quota per group (SCRATCH)]</li>
 
<li>Compute nodes do not have local storage.</li>
 
<li>Archive space is on [[HPSS|HPSS]].</li>
 
<li>Backup means a recent snapshot, not a replica of all data or version that ever was.</li>
 
<li><p><code>$BBUFFER</code> stands for the [[Burst Buffer]], a faster parallel storage tier for temporary data.</p></li></ul>
 
 
 
==File/Ownership Management (ACL)==
 
* By default, at SciNet, users within the same group already have read permission to each other's files (not write)
 
* You may use access control list ('''ACL''') to allow your supervisor (or another user within your group) to manage files for you (i.e., create, move, rename, delete), while still retaining your access and permission as the original owner of the files/directories. You may also let users in other groups or whole other groups access (read, execute) your files using this same mechanism.
 
  
<!--
+
If you need to move data to Niagara for analysis, or when you need to move data off of Niagara, use the following guidelines:
===Using  setfacl/getfacl===
+
* If your data is less than 10GB, move the data using the login nodes.
* To allow [supervisor] to manage files in /project/g/group/[owner] using '''setfacl''' and '''getfacl''' commands, follow the 3-steps below as the [owner] account from a shell:
+
* 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 .
<pre>
 
1) $ /scinet/gpc/bin/setfacl -d -m user:[supervisor]:rwx /project/g/group/[owner]
 
  (every *new* file/directory inside [owner] will inherit [supervisor] ownership by default from now on)
 
  
2) $ /scinet/gpc/bin/setfacl -d -m user:[owner]:rwx /project/g/group/[owner]
+
Details of how to use the datamover nodes can be found on the [[Data_Management#Moving_data | Data Management ]] page.
  (but will also inherit [owner] ownership, ie, ownership of both by default, for files/directories created by [supervisor])
 
  
3) $ /scinet/gpc/bin/setfacl -Rm user:[supervisor]:rwx /project/g/group/[owner]
+
= Loading software modules =
  (recursively modify all *existing* files/directories inside [owner] to also be rwx by [supervisor])
 
  
  $ /scinet/gpc/bin/getfacl /project/g/group/[owner]
+
You have two options for running code on Niagara: use existing software, or [[Niagara_Quickstart#Compiling_on_Niagara:_Example | compile your own]].  This section focuses on the former.
  (to determine the current ACL attributes)
 
  
  $ /scinet/gpc/bin/setfacl -b /project/g/group/[owner]
+
Other than essentials, all installed software is made available [[Using_modules | 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 [[Using_modules | found on the modules page]].
  (to remove any previously set ACL)
 
  
PS: on the datamovers getfacl, setfacl and chacl will be on your path
+
Common module subcommands are:
</pre>
 
For more information on using [http://linux.die.net/man/1/setfacl <tt>setfacl</tt>] or [http://linux.die.net/man/1/getfacl <tt>getfacl</tt>] see their man pages.
 
 
 
-->
 
===Using mmputacl/mmgetacl===
 
* You may use gpfs' native '''mmputacl''' and '''mmgetacl''' commands. The advantages are that you can set "control" permission and that [http://publib.boulder.ibm.com/infocenter/clresctr/vxrx/index.jsp?topic=%2Fcom.ibm.cluster.gpfs.doc%2Fgpfs31%2Fbl1adm1160.html POSIX or NFS v4 style ACL] are supported. You will need first to create a /tmp/supervisor.acl file with the following contents:
 
<pre>
 
user::rwxc
 
group::----
 
other::----
 
mask::rwxc
 
user:[owner]:rwxc
 
user:[supervisor]:rwxc
 
group:[othegroup]:r-xc
 
</pre>
 
 
 
Then issue the following 2 commands:
 
<pre>
 
1) $ mmputacl -i /tmp/supervisor.acl /project/g/group/[owner]
 
2) $ mmputacl -d -i /tmp/supervisor.acl /project/g/group/[owner]
 
  (every *new* file/directory inside [owner] will inherit [supervisor] ownership by default as well as
 
  [owner] ownership, ie, ownership of both by default, for files/directories created by [supervisor])
 
 
 
  $ mmgetacl /project/g/group/[owner]
 
  (to determine the current ACL attributes)
 
  
  $ mmdelacl -d /project/g/group/[owner]
+
* <code>module load <module-name></code>: load the default version of a particular software.
  (to remove any previously set ACL)
+
* <code>module load <module-name>/<module-version></code>: load a specific version of a particular software.
 +
* <code>module purge</code>: unload all currently loaded modules.
 +
* <code>module spider</code> (or <code>module spider <module-name></code>): list available software packages.
 +
* <code>module avail</code>: list loadable software packages.
 +
* <code>module list</code>: list loaded modules.
  
  $ mmeditacl /project/g/group/[owner]
+
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.
  (to create or change a GPFS access control list)
 
  (for this command to work set the EDITOR environment variable: export EDITOR=/usr/bin/vi)
 
</pre>
 
  
NOTES:
+
There are handy abbreviations for the module commands. <code>ml</code> is the same as <code>module list</code>, and <code>ml <module-name></code> is the same as <code>module load <module-name></code>.
* There is no option to recursively add or remove ACL attributes using a gpfs built-in command to existing files. You'll need to use the -i option as above for each file or directory individually. [[Recursive_ACL_script | Here is a sample bash script you may use for that purpose]]
+
== Software stacks: NiaEnv and CCEnv ==
  
* mmputacl will not overwrite the original linux group permissions for a directory when copied to another directory already with ACLs, hence the "#effective:r-x" note you may see from time to time with mmgetacf. If you want to give rwx permissions to everyone in your group you should simply rely on the plain unix 'chmod g+rwx' command. You may do that before or after copying the original material to another folder with the ACLs.
+
On Niagara, there are two available software stacks:
  
* In the case of PROJECT, your group's supervisor will need to set proper ACL to the /project/G/GROUP level in order to let users from other groups access your files.
+
=== NiaEnv ===
 
 
* ACL's won't let you give away permissions to files or directories that do not belong to you.
 
 
 
* We highly recommend that you never give write permission to other users on the top level of your home directory (/home/G/GROUP/[owner]), since that would seriously compromise your privacy, in addition to disable ssh key authentication, among other things. If necessary, make specific sub-directories under your home directory so that other users can manipulate/access files from those.
 
 
 
For more information on using [http://publib.boulder.ibm.com/infocenter/clresctr/vxrx/index.jsp?topic=%2Fcom.ibm.cluster.gpfs.doc%2Fgpfs31%2Fbl1adm11120.html <tt>mmputacl</tt>] or [http://publib.boulder.ibm.com/infocenter/clresctr/vxrx/index.jsp?topic=%2Fcom.ibm.cluster.gpfs.doc%2Fgpfs31%2Fbl1adm11120.html <tt>mmgetaclacl</tt>] see their man pages.
 
 
 
===Recursive ACL script ===
 
You may use/adapt '''[[Recursive_ACL_script| this sample bash script]]''' to recursively add or remove ACL attributes using gpfs built-in commands
 
 
 
Courtesy of Agata Disks (http://csngwinfo.in2p3.fr/mediawiki/index.php/GPFS_ACL)
 
 
 
==Scratch Disk Purging Policy==
 
 
 
In order to ensure that there is always significant space available for running jobs '''we automatically delete files in /scratch that have not been accessed or modified for more than 2 months by the actual deletion day on the 15th of each month'''. Note that we recently changed the cut out reference to the ''MostRecentOf(atime,ctime)''. This policy is subject to revision depending on its effectiveness. More details about the purging process and how users can check if their files will be deleted follows. If you have files scheduled for deletion you should move them to more permanent locations such as your departmental server or your /project space or into HPSS (for PIs who have either been allocated storage space by the RAC on project or HPSS).
 
 
 
On the '''first''' of each month, a list of files scheduled for purging is produced, and an email notification is sent to each user on that list. You also get a notification on the shell every time your login to Niagara. Furthermore, at/or about the '''12th''' of each month a 2nd scan produces a more current assessment and another email notification is sent. This way users can double check that they have indeed taken care of all the files they needed to relocate before the purging deadline. Those files will be automatically deleted on the '''15th''' of the same month unless they have been accessed or relocated in the interim. If you have files scheduled for deletion then they will be listed in a file in /scratch/t/todelete/current, which has your userid and groupid in the filename. For example, if user xxyz wants to check if they have files scheduled for deletion they can issue the following command on a system which mounts /scratch (e.g. a scinet login node): '''ls -1 /scratch/t/todelete/current |grep xxyz'''. In the example below, the name of this file indicates that user xxyz is part of group abc, has 9,560 files scheduled for deletion and they take up 1.0TB of space:
 
  
 +
A [https://docs.scinet.utoronto.ca/index.php/Modules_specific_to_Niagara Niagara software stack] tuned and compiled for this machine. This stack is available by default, but if not, can be reloaded with
 +
<pre>module load NiaEnv</pre>
 +
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
 +
<pre>module load NiaEnv/2018a</pre>
 +
You can override the system default for the epoch version by creating a file called <b><tt>.modulerc</tt></b> in your home directory with the line <b><tt>module-version NiaEnv/VERSION default</tt></b>, e.g. like so:
 
<pre>
 
<pre>
[xxyz@nia-login03 ~]$ ls -1 /scratch/t/todelete/current |grep xxyz
+
echo "module-version NiaEnv/2019b default" > $HOME/.modulerc
-rw-r----- 1 xxyz    root      1733059 Jan 17 11:46 3110001___xxyz_______abc_________1.00T_____9560files
 
 
</pre>
 
</pre>
 
+
After this, subsequent logins and jobs will use the 2019b stack even when the system default is different.
The file itself contains a list of all files scheduled for deletion (in the last column) and can be viewed with standard commands like more/less/cat - e.g. '''more /scratch/t/todelete/current/3110001___xxyz_______abc_________1.00T_____9560files'''
+
<p>Similarly, you can make an older epoch your personal default, like so
 
 
Similarly, you can also verify all other users on your group by using the ls command with grep on your group. For example: '''ls -1 /scratch/t/todelete/current |grep abc'''. That will list all other users in the same group that xxyz is part of, and have files to be purged on the 15th. Members of the same group have access to each other's contents.
 
 
 
'''NOTE:''' Preparing these assessments takes several hours. If you change the access/modification time of a file in the interim, that will not be detected until the next cycle. A way for you to get immediate feedback is to use the ''''ls -lu'''' command on the file to verify the ctime and ''''ls -lc'''' for the mtime. If the file atime/ctime has been updated in the meantime, coming the purging date on the 15th it will no longer be deleted.
 
 
 
==How much Disk Space Do I have left?==
 
 
 
The <tt>'''/scinet/niagara/bin/diskUsage'''</tt> command, available on the login nodes and datamovers, provides information in a number of ways on the home, scratch, project and archive file systems. For instance, how much disk space is being used by yourself and your group (with the -a option), or how much your usage has changed over a certain period ("delta information") or you may generate plots of your usage over time. Please see the usage help below for more details.
 
 
<pre>
 
<pre>
Usage: diskUsage [-h|-?| [-a] [-u <user>]
+
echo "module-version NiaEnv/2018a default" > $HOME/.modulerc
      -h|-?: help
 
      -a: list usages of all members on the group
 
      -u <user>: as another user on your group
 
 
</pre>
 
</pre>
  
Did you know that you can check which of your directories have more than 1000 files with the <tt>'''/scinet/niagara/bin/topUserDirOver1000list'''</tt> command and which have more than 1GB of material with the <tt>'''/scinet/niagara/bin/topUserDirOver1GBlist'''</tt> command?
+
No modules are loaded by default on Niagara except NiaEnv.
  
Note:
+
=== CCEnv ===
* information on usage and quota is only updated every 3 hours!
 
  
== I/O Tips ==
+
The same  [https://docs.computecanada.ca/wiki/Modules software stack available on Compute Canada's General Purpose clusters] [https://docs.computecanada.ca/wiki/Graham Graham] and [https://docs.computecanada.ca/wiki/Cedar Cedar] can be used on Niagara too, with:
 
+
<pre>module load CCEnv</pre>
* $HOME, $SCRATCH, and $PROJECT all use the parallel file system called GPFS.
+
Or, if you want the same default modules loaded as on Béluga, then do
* Your files can be seen on all Niagara login and compute nodes.
+
<pre>module load CCEnv StdEnv</pre>
* GPFS is a high-performance file system which provides rapid reads and writes to large data sets in parallel from many nodes.
+
or, if you want the same default modules loaded as on Cedar and Graham, do
* But accessing data sets which consist of many, small files leads to poor performance.
+
<pre>module load CCEnv arch/avx2 StdEnv</pre>
* Avoid reading and writing lots of small amounts of data to disk.<br />
 
 
 
* 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.
 
* The [[Burst Buffer]] is better for i/o heavy jobs and to speed up checkpoints.
 
 
 
= 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:
 
<source lang="bash">
 
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
 
 
 
  ...
 
</source>
 
Common module subcommands are:
 
<ul>
 
<li><p><code>module load &lt;module-name&gt;</code></p>
 
<p>use particular software</p></li>
 
<li><p><code>module purge</code></p>
 
<p>remove currently loaded modules</p></li>
 
<li><p><code>module spider</code></p>
 
<p>(or <code>module spider &lt;module-name&gt;</code>)</p>
 
<p>list available software packages</p></li>
 
<li><p><code>module avail</code></p>
 
<p>list loadable software packages</p></li>
 
<li><p><code>module list</code></p>
 
<p>list loaded modules</p></li></ul>
 
 
 
On Niagara, there are really two software stacks:
 
 
 
<ol style="list-style-type: decimal;">
 
<li><p>A Niagara software stack tuned and compiled for this machine. This stack is available by default, but if not, can be reloaded with</p>
 
<source lang="bash">module load NiaEnv</source></li>
 
<li><p>The same software stack available on Compute Canada's General Purpose clusters [https://docs.computecanada.ca/wiki/Graham Graham] and [https://docs.computecanada.ca/wiki/Cedar Cedar], compiled (for now) for a previous generation of CPUs:</p>
 
<source lang="bash">module load CCEnv</source>
 
<p>If you want the same default modules loaded as on Cedar and Graham, then afterwards also <code>module load StdEnv</code>.</p></li></ol>
 
 
 
Note: the <code>*Env</code> modules are '''''sticky'''''; remove them by <code>--force</code>.
 
  
 
== Tips for loading software ==
 
== Tips for loading software ==
  
<ul>
+
* 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 [[bashrc guidelines|here]].
<li><p>We advise '''''against''''' loading modules in your .bashrc.</p>
+
* Instead, load modules by hand when needed, or by sourcing a separate script.
<p>This could lead to very confusing behaviour under certain circumstances.</p></li>
+
* Load run-specific modules inside your job submission script.
<li><p>The default .bashrc and .bash_profile files on Niagara can be found [[bashrc guidelines|here]]
+
* Short names give default versions; e.g. <code>intel</code> → <code>intel/2018.2</code>. It is usually better to be explicit about the versions, for future reproducibility.
<li><p>Instead, load modules by hand when needed, or by sourcing a separate script.</p></li>
+
* Modules often require other modules to be loaded first. Solve these dependencies by using [[Using_modules#Module_spider | <code>module spider</code>]].
<li><p>Load run-specific modules inside your job submission script.</p></li>
 
<li><p>Short names give default versions; e.g. <code>intel</code> → <code>intel/2018.2</code>.</p>
 
<p>It is usually better to be explicit about the versions, for future reproducibility.</p></li>
 
<li><p>Handy abbreviations:</p></li></ul>
 
 
 
<pre class="sh">
 
  ml → module list
 
  ml NAME → module load NAME  # if NAME is an existing module
 
  ml X → module X
 
</pre>
 
 
 
* Modules sometimes require other modules to be loaded first.<br />
 
Solve these dependencies by using <code>module spider</code>.
 
 
 
== Module spider ==
 
 
 
Oddly named, the module subcommand spider is the search-and-advice facility for modules.
 
 
 
Suppose one wanted to load the openmpi module. Upon trying to load the module, one may get the following message:
 
<source lang="bash">
 
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).
 
</source>
 
So while that fails, following the advice that the command outputs, the next command would be:
 
<source lang="bash">
 
nia-login07:~$ module spider openmpi
 
------------------------------------------------------------------------------------------------------
 
  openmpi:
 
------------------------------------------------------------------------------------------------------
 
    Versions:
 
        openmpi/2.1.3
 
        openmpi/3.0.1
 
        openmpi/3.1.0
 
 
 
------------------------------------------------------------------------------------------------------
 
  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.0
+
= Available compilers and interpreters =
------------------------------------------------------------------------------------------------------
 
</source>
 
So this gives just more detailed suggestions on using the spider command. Following the advice again, one would type:
 
<source lang="bash">
 
nia-login07:~$ module spider openmpi/3.1.0
 
------------------------------------------------------------------------------------------------------
 
  openmpi: openmpi/3.1.0
 
------------------------------------------------------------------------------------------------------
 
    You will need to load all module(s) on any one of the lines below before the "openmpi/3.1.0"
 
    module is available to load.
 
  
      NiaEnv/2018a  gcc/7.3.0
+
* For most compiled software, one should use the Intel compilers (<tt>icc</tt> for C, <tt>icpc</tt> for C++, and <tt>ifort</tt> for Fortran). Loading an <tt>intel</tt> module makes these available.  
      NiaEnv/2018a  intel/2018.2
+
* The GNU compiler suite (<tt>gcc, g++, gfortran</tt>) is also available, if you load one of the <tt>gcc</tt> modules.
</source>
+
* To compile mpi code, you must additionally load an <tt>openmpi</tt> or <tt>intelmpi</tt> module.
These are concrete instructions on how to load this particular openmpi module. Following these leads to a successful loading of the module.
+
* Open source interpreted, interactive software is also available:
<source lang="bash">
+
** [[Python]]
nia-login07:~$ module load NiaEnv/2018a  intel/2018.2  # note: NiaEnv is usually already loaded
+
** [[R]]
nia-login07:~$ module load openmpi/3.1.0
+
** Julia
</source>
+
** [[Octave]]
<source lang="bash">
+
    
nia-login07:~$ module list
+
Please visit the corresponding page for details on using these tools. For information on running MATLAB applications on Niagara, visit [[MATLAB| this page]].
Currently Loaded Modules:
 
  1) NiaEnv/2018a (S)  2) intel/2018.2  3) openmpi/3.1.0
 
 
 
   Where:
 
  S: Module is Sticky, requires --force to unload or purge</source>
 
  
= Running Commercial Software =
+
= Using Commercial Software =
  
* Possibly, but you have to bring your own license for it.
+
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 | ssh tunneling]].
 
* 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.
 
* 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.
+
* 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,  
+
* That means no [[MATLAB]], Gaussian, IDL,  
* Open source alternatives like Octave, Python, R are available.
+
* 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.
 
* 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.
 
* In some cases, if you have a license, you can use software in the 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 | commercial software page]].
  
 
= Compiling on Niagara: Example =
 
= Compiling on Niagara: Example =
  
Suppose one want to compile an application from two c source files, appl.c and module.c, which use the Gnu Scientific Library (GSL). This is an example of how this would be done:
+
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:
 
<source lang="bash">
 
<source lang="bash">
 +
nia-login07:~$ module load NiaEnv/2019b
 
nia-login07:~$ module list
 
nia-login07:~$ module list
 
Currently Loaded Modules:
 
Currently Loaded Modules:
   1) NiaEnv/2018a (S)
+
   1) NiaEnv/2019b (S)
 
   Where:
 
   Where:
 
   S:  Module is Sticky, requires --force to unload or purge
 
   S:  Module is Sticky, requires --force to unload or purge
  
nia-login07:~$ module load intel/2018.2 gsl/2.4
+
nia-login07:~$ module load intel/2019u4
  
 
nia-login07:~$ ls
 
nia-login07:~$ ls
Line 510: Line 255:
 
nia-login07:~$ icc -c -O3 -xHost -o appl.o appl.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 -c -O3 -xHost -o module.o module.c
nia-login07:~$ icc  -o appl module.o appl.o -lgsl -mkl
+
nia-login07:~$ icc  -o appl module.o appl.o -mkl
  
 
nia-login07:~$ ./appl
 
nia-login07:~$ ./appl
Line 516: Line 261:
 
Note:
 
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 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, for 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.
+
* 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 [https://software.intel.com/en-us/articles/intel-mkl-link-line-advisor MKL link line advisor].
 
* 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 [https://software.intel.com/en-us/articles/intel-mkl-link-line-advisor MKL link line advisor].
  
= Testing =
+
= 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.
 
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 [[Parallel Debugging with DDT|DDT]] debugger on the login nodes after <code>module load ddt</code>.
 +
* 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 <tt>--clean</tt> 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.
  
<ul>
+
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.
<li><p>Small test jobs can be run on the login nodes.</p>
+
nia-login07:~$ salloc --nodes N --time=M:00:00 --x11
<p>Rule of thumb: couple of minutes, taking at most about 1-2GB of memory, couple of cores.</p></li>
+
where N is again the number of nodes, and M is the number of hours you wish the job to run.
<li><p>You can run the the ddt debugger on the login nodes after <code>module load ddt</code>.</p></li>
+
The <tt>--x11</tt> is required if you need to use graphics while testing your code through salloc, e.g. when using a debugger such as [[Parallel Debugging with DDT|DDT]] or DDD, See the [[Testing_With_Graphics | Testing with graphics]] page for the options in that case.
<li><p>Short tests that do not fit on a login node, or for which you need a dedicated node, request an<br />
 
interactive debug job with the salloc command</p>
 
  
nia-login07:~$ salloc -pdebug --nodes N --time=1:00:00
+
= Submitting jobs =
  
<p>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.</p>
+
<!-- == Progressive approach to run jobs on niagara == -->
<p>Alternatively, on Niagara, you can use the command</p>
+
<!-- We would like to emphasize the need for users to adopt a more progressive and explicit approach for testing, running and scaling up of jobs on niagara. [[Progressive_Approach | '''Here is a set of steps we suggest that you follow.''']] -->
  
  nia-login07:~$ debugjob N
+
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.
  
<p>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 30 minutes.</p>
+
Niagara uses SLURM as its job schedulerMore-advanced details of how to interact with the scheduler can be found on the [[Slurm | Slurm page]].
<p>Finally, if your debugjob process takes more than 1 hour, you can request an interactive job from the regular queueNote, 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.</p>
 
  
nia-login07:~$ salloc --nodes N --time=M:00:00
+
You submit jobs from a login node by passing a script to the sbatch command:
  
<p>where N is again the number of nodes, and M is the number of hours you wish the job to run.</p>
+
nia-login07:scratch$ sbatch jobscript.sh
</li>
 
</ul>
 
  
 +
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.
  
== Testing with Graphics: X-forwarding ==
+
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).
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:
 
  
<ul>
+
Jobs will run under your group's RRG allocation, or, if the your group has none, under a RAS allocation (previously called `default' allocation).
<li> You can use the <code>debugjob</code> command which automatically provides X-forwarding support.
 
<source lang="bash">
 
$ ssh  niagara.scinet.utoronto.ca -X
 
  
USER@nia-login07:~$ debugjob
+
Some example job scripts can be found below.
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 ~]$
 
</source>
 
 
 
<li> If <code>debugjob</code> 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:
 
<ol>
 
<li>In the 1st terminal
 
<ul>
 
<li> ssh to <code>niagara.scinet.utoronto.ca</code> and issue your <code>salloc</code> command
 
<li> wait until your resources are allocated and you are assigned the nodes
 
<li> take note of the node where you are logged to, ie. the head node, let's say <code>niaWXYZ</code>
 
</ul>
 
<source lang="bash">
 
$ 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 ~]$
 
</source>
 
 
 
<li> On the second terminal:
 
<ul>
 
<li> ssh into <code>niagara.scinet.utoronto.ca</code> now using the <code>-X</code> flag in the ssh command
 
 
 
<li> after that <code>ssh -X niaWXYZ</code>, ie. you will ssh carrying on the '-X' flag into the head node of the job
 
 
 
<li> in the <code>niaWXYZ</code> you should be able to use graphics and should be redirected by x-forwarding to your local terminal
 
</ul>
 
 
 
<source lang="bash">
 
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
 
</source>
 
 
 
</ol>
 
</ul>
 
 
 
 
 
Observations:
 
<ul>
 
<li> 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.
 
<li> If you are in Mac OS, substitute -X by -Y
 
<li> Instead of using two terminals, you could just use <code>screen</code> to request the resources and then detach the session and ssh into the head node directly.
 
</ul>
 
 
 
= 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:
 
Keep in mind:
 
+
* Scheduling is by node, so in multiples of 40 cores.
<ul>
+
* Your job's maximum walltime is 24 hours.  
<li><p>Scheduling is by node, so in multiples of 40 cores.</p></li>
+
* Jobs must write their output to your scratch or project directory (home is read-only on compute nodes).
<li><p>For users with an allocation, the maximum walltime is 24 hours. For those without an allocation, the maximum walltime is 12 hours.</p></li>
+
* Compute nodes have no internet access.
<li><p>Jobs must write to your scratch or project directory (home is read-only on compute nodes).</p></li>
+
* 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).  
<li><p>Compute nodes have no internet access.</p>
+
* [[Data_Management#Moving_data | Move your data]] to Niagara before you submit your job.
<p>Download data you need beforehand on a login node.</p></li></ul>
 
 
 
== SLURM nomenclature: jobs, nodes, tasks, cpus, cores, threads  ==
 
 
 
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.
 
 
 
{| class="wikitable"
 
!term
 
!meaning
 
!SLURM term
 
!related scheduler options
 
|-
 
|job
 
|scheduled piece of work for which specific resources were requested.
 
|job
 
|<tt>sbatch, salloc</tt>
 
|-
 
|node
 
|basic computing component with several cores (40 for Niagara) that share memory 
 
|node
 
|<tt>--nodes -N</tt>
 
|-
 
|mpi process
 
|one of a group of running programs using Message Passing Interface for parallel computing
 
|task
 
|<tt>--ntasks -n --ntasks-per-node</tt>
 
|-
 
|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
 
|<tt>--ncpus-per-task</tt>
 
|-
 
|thread
 
|one of possibly multiple simultaneous execution paths within a program, which can share memory.
 
| -
 
| <tt>--ncpus-per-task</tt> '''and''' <tt>OMP_NUM_THREADS</tt>
 
|-
 
|hyperthread
 
|a thread run in a collection of threads that is larger than the number of physical cores.
 
| -
 
| -
 
|}
 
  
 
== Scheduling by Node ==
 
== Scheduling by Node ==
<ul>
 
<li>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, this is a bit different.
 
<li><p>All job resource requests on Niagara are scheduled as a multiple of '''nodes'''.</p></li>
 
<li>The nodes that your jobs run on are exclusively yours.
 
<ul>
 
<li>No other users are running anything on them.</li>
 
<li>You can ssh into them to see how things are going.</li></ul>
 
</li>
 
<li><p>Whatever your requests to the scheduler, it will always be translated into a multiple of nodes allocated to your job.</p></li>
 
<li><p>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.</p></li>
 
<li><p>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.</p></li></ul>
 
  
== Hyperthreading: Logical CPUs vs. cores ==
+
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'''.
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.
+
* The nodes that your jobs run on are exclusively yours, for as long as the job is running on them.
So the OS and scheduler see 80 logical cpus.
+
** No other users are running anything on them.
 
+
** You can [[SSH]] into them to see how things are going.
Using 80 logical cpus vs. 40 real cores typically gives about a 5-10% speedup (Your Mileage May Vary).
+
* 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.
Because Niagara is scheduled by node, hyperthreading is actually fairly easy to use:
+
* If you run serial jobs you must still use all 40 cores on the node.  Visit the [[Running_Serial_Jobs_on_Niagara | serial jobs]] page for examples of how to do this.
<ul>
+
* 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 [mailto:support@scinet.utoronto.ca contact us] to get assistance.
<li>Ask for a certain number of nodes N for your jobs.</li>
 
<li>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)</li>
 
<li>But you should also test if running 80xN mpi processes or threads gives you any speedup.</li>
 
<li>Regardless, your usage will be counted as 40xNx(walltime in years).</li>
 
</ul>
 
  
 
== Limits ==
 
== 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 [https://www.computecanada.ca/research-portal/accessing-resources/resource-allocation-competitions/ 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 <tt>-p</tt> parameter to <tt>sbatch</tt> or <tt>salloc</tt>, but if you do not specify one, your job will run in the <tt>compute</tt> partition, which is the most common case.  
+
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 [https://www.computecanada.ca/research-portal/accessing-resources/resource-allocation-competitions/ 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 <tt>-p</tt> parameter to <tt>sbatch</tt> or <tt>salloc</tt>, but if you do not specify one, your job will run in the <tt>compute</tt> partition, which is the most common case.  
  
 
{| class="wikitable"
 
{| class="wikitable"
 
!Usage
 
!Usage
 
!Partition
 
!Partition
!Running jobs
+
!Limit on Running jobs
!Submitted jobs (incl. running)
+
!Limit on Submitted jobs (incl. running)
 
!Min. size of jobs
 
!Min. size of jobs
 
!Max. size of jobs
 
!Max. size of jobs
Line 722: Line 333:
 
!Max. 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 ||compute || 50 || 1000 || 1 node (40&nbsp;cores) || default:&nbsp;20&nbsp;nodes&nbsp;(800&nbsp;cores) <br> with&nbsp;allocation:&nbsp;1000&nbsp;nodes&nbsp;(40000&nbsp;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&nbsp;cores) || 4 nodes (160 cores)|| N/A || 1 hour
 
|-
 
|-
|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
 
|-
 
|-
|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 vfsshort || 2 per user|| 10 per user || N/A || N/A || 15 minutes || 1 hour
|-
 
|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.
+
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.
  
== SLURM Accounts ==
+
== File Input/Output Tips ==
  
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 <tt>rrg-</tt> or <tt>rpp-</tt>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 <tt>def-</tt>.
+
It is important to understand the file systems, so as to perform your file I/O (Input/Output) responsiblyRefer to the [[Data_Management | Data Management]] page for details about the file systems.
 
+
* Your files can be seen on all Niagara login and compute nodes.
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.  
+
* $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.
To select the account, just add
+
* 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 diskMany small files on the system waste space and are slower to access, read and write. If you must write many small files, use [[User_Ramdisk | ramdisk]].
    #SBATCH -A [account]
+
* 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|checkpoints]].
to the job scripts, or use the <tt>-A [account]</tt> to <tt>salloc</tt> or <tt>debugjob</tt>.  
 
 
 
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 ==
 
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 <tt>#SBATCH</tt> 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, <tt>-p debug</tt> is interpreted by SLURM, while in your submission script you can access <tt>FirstArgument</tt>, <tt>SecondArgument</tt>, etc., by referring to <code>$1, $2, ...</code>.
 
 
 
== Email Notification ==
 
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
 
 
 
The sbatch man page (type <tt>man sbatch</tt> on Niagara) explains all possible mail-types.
 
  
 
== Example submission script (MPI) ==
 
== Example submission script (MPI) ==
  
 
<source lang="bash">#!/bin/bash  
 
<source lang="bash">#!/bin/bash  
#SBATCH --nodes=8
+
#SBATCH --nodes=2
#SBATCH --ntasks=320
+
#SBATCH --ntasks-per-node=40
 
#SBATCH --time=1:00:00
 
#SBATCH --time=1:00:00
#SBATCH --job-name mpi_job
+
#SBATCH --job-name=mpi_job
 
#SBATCH --output=mpi_output_%j.txt
 
#SBATCH --output=mpi_output_%j.txt
 +
#SBATCH --mail-type=FAIL
  
 
cd $SLURM_SUBMIT_DIR
 
cd $SLURM_SUBMIT_DIR
  
module load intel/2018.2
+
module load NiaEnv/2019b
module load openmpi/3.1.0
+
module load intel/2019u4
 +
module load openmpi/4.0.1
  
 
mpirun ./mpi_example
 
mpirun ./mpi_example
 
# or "srun ./mpi_example"
 
# or "srun ./mpi_example"
 
</source>
 
</source>
Submit this script with the command:
+
Submit this script from your scratch directory with the command:
  
     nia-login07:~$ sbatch mpi_job.sh
+
     nia-login07:scratch$ sbatch mpi_job.sh
  
 
<ul>
 
<ul>
<li><p>First line indicates that this is a bash script.</p></li>
+
<li>First line indicates that this is a bash script.</li>
<li><p>Lines starting with <code>#SBATCH</code> go to SLURM.</p></li>
+
<li>Lines starting with <code>#SBATCH</code> go to SLURM.</li>
<li><p>sbatch reads these lines as a job request (which it gives the name <code>mpi_job</code>)</p></li>
+
<li>sbatch reads these lines as a job request (which it gives the name <code>mpi_job</code>)</li>
<li><p>In this case, SLURM looks for 8 nodes with 40 cores on which to run 320 tasks, for 1 hour.</p></li>
+
<li>In this case, SLURM looks for 2 nodes each running 40 tasks (for a total of 80 tasks), for 1 hour</li>
<li><p>Note that the mpifun flag "--ppn" (processors per node) is ignored.</p></li>
+
<li>Note that the mpifun flag "--ppn" (processors per node) is ignored.</li>
<li><p>Once it found such a node, it runs the script:</p>
+
<li>Once it found such a node, it runs the script:
 
<ul>
 
<ul>
 
<li>Change to the submission directory;</li>
 
<li>Change to the submission directory;</li>
 
<li>Loads modules;</li>
 
<li>Loads modules;</li>
<li>Runs the <code>mpi_example</code> application.</li>
+
<li>Runs the <code>mpi_example</code> application (SLURM will inform mpirun or srun on how many processes to run).
 +
</li>
 
</ul>
 
</ul>
<li>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).</li>
+
<li>To use hyperthreading, just change <code>--ntasks-per-node=40</code> to <code>--ntasks-per-node=80</code>, and add <code>--bind-to none</code> to the mpirun command (the latter is necessary for OpenMPI only, not when using IntelMPI).</li>
 
</ul>
 
</ul>
  
Line 829: Line 400:
 
#SBATCH --cpus-per-task=40
 
#SBATCH --cpus-per-task=40
 
#SBATCH --time=1:00:00
 
#SBATCH --time=1:00:00
#SBATCH --job-name openmp_job
+
#SBATCH --job-name=openmp_job
 
#SBATCH --output=openmp_output_%j.txt
 
#SBATCH --output=openmp_output_%j.txt
 +
#SBATCH --mail-type=FAIL
  
 
cd $SLURM_SUBMIT_DIR
 
cd $SLURM_SUBMIT_DIR
  
module load intel/2018.2
+
module load NiaEnv/2019b
 +
module load intel/2019u4
  
 
export OMP_NUM_THREADS=$SLURM_CPUS_PER_TASK
 
export OMP_NUM_THREADS=$SLURM_CPUS_PER_TASK
Line 841: Line 414:
 
# or "srun ./openmp_example".
 
# or "srun ./openmp_example".
 
</source>
 
</source>
Submit this script with the command:
+
Submit this script from your scratch directory with the command:
  
 
     nia-login07:~$ sbatch openmp_job.sh
 
     nia-login07:~$ sbatch openmp_job.sh
Line 856: Line 429:
 
* To use hyperthreading, just change <code>--cpus-per-task=40</code> to <code>--cpus-per-task=80</code>.
 
* To use hyperthreading, just change <code>--cpus-per-task=40</code> to <code>--cpus-per-task=80</code>.
  
= Monitoring queued jobs =
+
== Monitoring queued jobs ==
  
Once the job is incorporated into the queue, there are some command you can use to monitor its progress.
+
Once the job is incorporated into the queue, there are some commands you can use to monitor its progress.
  
 
<ul>
 
<ul>
 
<li><p><code>squeue</code> or <code>sqc</code> (a caching version of squeue) to show the job queue (<code>squeue -u $USER</code> for just your jobs);</p></li>
 
<li><p><code>squeue</code> or <code>sqc</code> (a caching version of squeue) to show the job queue (<code>squeue -u $USER</code> for just your jobs);</p></li>
<li><p><code>qsum</code> shows a summary of qudue by user
 
 
<li><p><code>squeue -j JOBID</code> to get information on a specific job</p>
 
<li><p><code>squeue -j JOBID</code> to get information on a specific job</p>
 
<p>(alternatively, <code>scontrol show job JOBID</code>, which is more verbose).</p></li>
 
<p>(alternatively, <code>scontrol show job JOBID</code>, which is more verbose).</p></li>
 
<li><p><code>squeue --start -j JOBID</code> to get an estimate for when a job will run; these tend not to be very accurate predictions.</p></li>
 
<li><p><code>squeue --start -j JOBID</code> to get an estimate for when a job will run; these tend not to be very accurate predictions.</p></li>
 
<li><p><code>scancel -i JOBID</code> to cancel the job.</p></li>
 
<li><p><code>scancel -i JOBID</code> to cancel the job.</p></li>
<li><p><code>sinfo -pcompute</code> to look at available nodes.</p></li>
 
 
<li><p><code>jobperf JOBID</code> to get an instantaneous view of the cpu and memory usage of the nodes of the job while it is running.</p></li>
 
<li><p><code>jobperf JOBID</code> to get an instantaneous view of the cpu and memory usage of the nodes of the job while it is running.</p></li>
 
<li><p><code>sacct</code> to get information on your recent jobs.</p></li>
 
<li><p><code>sacct</code> to get information on your recent jobs.</p></li>
 +
</ul>
  
<li><p>More utilities like those that were available on the GPC are under development.</p></li></ul>
+
Further instructions for monitoring your jobs can be found on the [[Slurm#Monitoring_jobs | Slurm page]]. The [https://my.scinet.utoronto.ca my.SciNet] site is also a very useful tool for monitoring your current and past usage.
  
 
= Visualization =
 
= Visualization =
 
Information about how to use visualization tools on Niagara is available on [[Visualization]] page.
 
Information about how to use visualization tools on Niagara is available on [[Visualization]] page.
  
= Further information =
+
= Support =
 
 
'''Useful sites'''
 
 
 
* SciNet: https://www.scinet.utoronto.ca
 
* Niagara: https://docs.computecanada.ca/wiki/niagara
 
* System Status: https://docs.scinet.utoronto.ca/index.php/Main_Page
 
* Training: https://support.scinet.utoronto.ca/education
 
 
 
'''Support'''
 
  
* support@scinet.utoronto.ca
+
* [mailto:support@scinet.utoronto.ca support@scinet.utoronto.ca]
* niagara@computecanada.ca
+
* [mailto:niagara@computecanada.ca niagara@computecanada.ca]

Latest revision as of 20:50, 5 October 2021

Niagara
Niagara.jpg
Installed Jan 2018/March 2020
Operating System CentOS 7.6
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

Specifications

The Niagara cluster is a large cluster of 2,024 Lenovo SD530 servers each with 40 Intel "Skylake" at 2.4 GHz or 40 Intel "CascadeLake" cores at 2.5 GHz. 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). 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.

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 a Compute Canada account, but anyone with an active Compute Canada account can get their access enabled.

If you have an active Compute Canada 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 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 CC (Compute Canada) compute systems, access to Niagara is done via SSH (secure shell) only. Open a terminal window (e.g. Connecting with PuTTY on Windows or Connecting with 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 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/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/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/myccusername
$ARCHIVE=/archive/g/groupname/myccusername

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
50-500TB per group depending on group size
$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 Compute Canada's General Purpose clusters Graham and Cedar can be used on Niagara 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

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. intelintel/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:

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

Submit this script from your scratch directory with the command:

   nia-login07:~$ sbatch openmp_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 openmp_job) .
  • 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;
    • Sets an environment variable;
    • Runs the openmp_example application.
  • To use hyperthreading, just change --cpus-per-task=40 to --cpus-per-task=80.

Monitoring queued jobs

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

  • <p>squeue or sqc (a caching version of squeue) to show the job queue (squeue -u $USER for just your jobs);</p>
  • <p>squeue -j JOBID to get information on a specific job

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

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

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

  • </ul>

    Further instructions for monitoring your jobs can be found on the Slurm page. The my.SciNet site is also a very useful tool for monitoring your current and past usage.

    Visualization

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

    Support