Getting Started

Once you have a MIT Supercloud account there are a number of steps you can take to prepare for the tutorial that we provide to all users. Please read the material and follow the instrutions below. Completing the instructions are not a prerequisite for the tutorial, but will help you get the most out of it. Please take note of any questions you have or issues you experience so that we can discuss them at the tutorial. If you get stuck you cannot wait until the tutorial please send us an email describing what you were trying to do, what you tried, and any result or error that occurred.  Copying and pasting the commands you ran and the output you recieve is really helpful, even if it long and ugly.

This is a brief overview of how to get started. We have more extensive matieral in the How to Use section of this site (some of this material links to those pages). If you are interested in learning more, we recommend that you take our online course "Introduction to High Performance Scientific Workflows".  For more information on the course and how to access it click on the "Online Courses" link in the left panel.

Logging in Via ssh

The first thing you should do when you get a new account is verify that you can log in. The primary way to access the MIT Supercloud system is through ssh. Instructions for different operating systems are below. Keep in mind that you will only be able to access the system from ssh from the machine where you generated your ssh key. You will not be able to log in until we have sent you an email stating that we have created your account, which will contain your username.

Mac and Linux:

First open a command line terminal window. Enter the following command, where USERNAME is your username on the MIT Supercloud system:

ssh USERNAME@txe1-login.mit.edu

Windows:

You will need to ssh in to the same environment where you generated your ssh keys. If you generated your keys in bash (Ubuntu/Windows Subsystem for Linux), MobaXterm, Cygwin, or other terminal-based program, follow the instructions above for Mac/Linux. If you gerated your keys using PuTTY, open a PuTTY window. In the box labeled "Host Name" enter USERNAME@txe1-login.mit.edu, where USERNAME is your username on the MIT Supercloud system. Keep the ssh box checked (this should be default) and Port should be set to 22. Click "Open" to start the session. You may also need to indicate your private key on the Connection -> SSH -> Auth page.

Shared HPC Clusters

The MIT Supercloud is an HPC-style shared cluster. You are sharing this resources with a number of other researchers, staff, and students so it is important that you read this page and use the system as intended.

Being a cluster, there are several machines connected together with a network. We refer to these as nodes. Most nodes in the cluster are referred to as compute nodes, this is where the computation is done on the system (where you will run your code). When you ssh into the system you are on a special purpose node called the login node. The login node, as its name suggests, is where you log in and is for editing code and files, installing packages and software, downloading data, and starting jobs to run your code on one of the compute nodes.

Each job is started using a piece of software called the scheduler, which you can think of as a resource manager. You let it know what resources you need and what you want to run, and the scheduler will find those resources and start your job on them. When your job completes those resources are relinquished. The scheduler is what ensures that no two jobs are using the same resources, so it is very important not to run anything unless it is submitted properly through the scheduler.

Software and Packages

The first thing you may want to do is make sure the system has the sofware and packages you need. We have installed a lot of software and packages on the system already, even though it may not be immediately obvious that it is there. Review our page on Software and Package Management, paying particular attention to the section on modules and installing packages for the language that you use. If you are ever unsure if we have a particular software, and you cannot find it, please send us an email and ask before you spend a lot of time trying to install it. If we have it, we can point you to it, provide advice on how to use it, and if we don't have it we can often give pointers on how to install it. Futher, if a lot of people request the same software, we may consider adding it to the system image.

Linux Command Line

The MIT Supercloud runs Linux, so much of what you do on the cluster involves the Linux command line. That doesn't mean you have to be a Linux expert to use the system! However the more you can get comfortable with the Linux command line and a handful of basic commands, the easier using the system will be. If you are already familiar with Linux, feel free to skip this section, or skim as a refresher.

Most Linux commands deal with directories and files. A directory, synonymous to a folder, contains files and other directories. The list of directories that lead to a particular directory or file is called its path. In Linux, directories on a path are separated by forward slashes '/'. It is also important to note that everything in Linux is case sensitive, so a file myScript.sh is not the same as the file myscript.sh. When you first log in you are in you home directory. Your home directory is where you can put all the code and data you need to run your job. Your home directory is not accessible to other users, if you need a space to share files with othe users, let us know and we can make a shared group directory for you. The path to your home directory on Supercloud is /home/gridsan/[USERNAME], where [USERNAME] is your username. The character ~ is also shorthand for your home directory in any Linux commands.

Anytime after you start typing a Linux command you can press the "Tab" button your your keyboard. This called tab-complete, and will try to autocomplete what you are typing. This is particularly helpful when typing out long directory paths and file names. Pressing "Tab" once will complete if there is a single completion, pressing it twice will list all potential completions. It is a bit difficult to explain in text, but you can try it out yourself and watch the short demonstration here.

Finally, below is a list of Linux Commands. Try them out for yourself at the command line.

  • Creating, navigating and viewing directories:
    • pwd: tells you the full path of the directory you are currently in
    • mkdir dirname: creates a directory with the name "dirname"
    • cd dirname: change directory to directory "dirname"
      • cd ../: takes you up one level
    • ls: lists the files in the directory
      • ls -a: lists all files including hidden files
      • ls -l: lists files in "long format" including ownership and date of last update
      • ls -t: lists files by date stamp, most recently updated file first
      • ls -tr: lists files by dates stamp in reverse order, most recently updated file is listed last (this is useful if you have a lot of files, you want to know which file you changed last and the list of files results in a scrolling window)
      • ls dirname: lists the files in the directory "dirname"
  • Viewing files
    • more filename: shows the first part of a file, hitting the space bar allows you to scroll through the rest of the file, q will cause you to exit out of the file.
    • less filename: allows you to scroll through the file, forward and backward, using the arrow keys.
    • tail filename: shows the last 10 lines of a file (useful when you are monitoring a logfile or output file to see that the values are correct)
      • tail <number> filename: show you the last &lt;number> lines of a file.
      • tail -f filename: shows you new lines as they are written to the end of the file. Press CMD+C or Control+C to exit. This is helpful to monitor the log file of a batch job.
  • Copying, moving, renaming, and deleting files
    • mv filename dirname: moves filename to directory dirname.
      • mv filename1 filename2: moves filename1 to filename2, in essence renames the file. The date and time are not changed by the mv command.
    • cp filename dirname: copies to directory dirname.
      • cp filename1 filename2: copies filename1 to filename2. The date stamp on filename2 will be the date/time that the file was moved
      • cp -r dirname1 dirname2: copies directory dirname1 and its contents to dirname2.
    • rm filename: removes (deletes) the file

Transferring Files to MIT Supercloud

One of the first tasks is to get your code, data, and any other files you need into your home directory on the system. If your code is in github you can use git commands on the system to clone your repository to your home directory. You can also transfer your files to your home directory from your computer by using the commands scp or rsync. Read the page on Accessing and Transferring Data and Files to learn how to use these commands and transfer what you need to your home directory.

Testing your Code

At this point you may want to do a test-run of your code. You always want to start small in your test runs, so you should choose a small example that tests the functionality of what you would ulitimately like to run on the system. If your test code is serial and runs okay on a moderate personal laptop or desktop you can request an interactive session to run your code in by executing the command:

LLsub -i

After you run this command you will be on a compute node and you can do a test-run of your code. This command will allocate one core to your job. If your test code is multithreaded or parallel, or uses a lot of memory, you should request a full node to be sure you don't impact other jobs on the system:

LLsub -i full

These commands by no means represent the full use of the system, and most likely won't be the primary way you run your code. In our tutorial we go over much more on how to submit jobs and will make sure you have the tools you need to get the most out of the MIT Supercloud.