Orion HPC Server

1. Introduction

This guide walks you through the steps of connecting to the Orion High Performance Computing (HPC) Server, installing Visual Studio Code on your computer and compiling and running programs in C/C++, OpenMP, CUDA, MPI and Matlab on the remote server. Before connecting to the server, you will need a username and password. Contact the system administrator, Dr. Vincent Roberge (vincent.roberge(at)rmc.ca), to get an account created for you.

2. Server Specifications

The Orion HPC Server is a Dell Precision server equipped with 256 GB of RAM and dual Intel Xeon Gold 5218R CPUs with 20 hyper-threaded cores for a total of 40 cores or 80 virtual cores. The server is configured with an NVIDIA RTX4070 Ti graphics processing unit (GPU) with 7,680 cores and 12 GB DDR6 RAM supporting CUDA compute capability 8.9. The server runs Linux Ubuntu 24.04.

3. SSH Connection to the Server

This user guide assumes that you are on a Windows computer. If you are working from a Linux or a Mac computer, the commands will be slightly different. From your Windows computer, you can connect to the Orion HPC Server using SSH as follows:

> ssh <username>@orionhpc.duckdns.org -p 22223

In the previous command, make sure that you replace "<username>" with your actual username

Important note: In this manual, commands that are to be run on Windows starts with “>” and commands that are to be run on the Orion server starts with “$”. Do not include the “>” or “$” when typing your commands.

Once you have confirmed that you can connect to Orion, let’s create an SSH profile for your connection. On your Windows computer, start a command prompt (not PowerShell but cmd.exe) and type:

> mkdir %USERPROFILE%\.ssh
> type nul > %USERPROFILE%\.ssh\config
> notepad %USERPROFILE%\.ssh\config

Enter the following text and save the file. Make sure that you replace "username" with your actual username as assigned to you by the system administrator.

Host orion
    HostName orionhpc.duckdns.org
    Port 22223
    User username

From the command prompt, you can now connect to the Orion server using the following command. It should prompt you to enter your password twice.

> ssh orion

Once you have logged successfully onto Orion, it is recommended to change your password using the following command. You must use a complex password (more than 8 characters, with upper cases, lower cases and digit).

$ passwd

You can now log off.

$ exit

From your Windows computer, generate an SSH public key that you will upload onto the Orion server. This will allow you to log onto the server without a password. This will save you quite a bit of time later on when programming in Visual Studio Code.
In the Windows command prompt, generate an RSA public key and copy the key to the cluster:

> ssh-keygen
> type %USERPROFILE%\.ssh\id_rsa.pub | ssh orion "cat > id_rsa.pub"

Now, login to the server again and add the public key to your authorized_keys file. Do not forget to replace "username" with your actual username:

> ssh orion
$ mkdir -p ~/.ssh/
$ dos2unix id_rsa.pub 
$ cat id_rsa.pub >> ~/.ssh/authorized_keys

You can now log off and try logging to Orion again, it should not ask you for a password.

$ exit
> ssh orion

4. Installing Visual Studio Code

Visual Studio Code (VSCode) is a free Integrated Development Environment (IDE) that runs on several operating systems including Windows, Linux and Mac. It is highly configurable and allows you to develop code using Makefile and perform remote debugging without any lag. This makes it the perfect IDE to program on the Orion server. VSCode is free; you can download it from the internet and install it on your computer. VSCode does not require admin privilege to install and installs, by default, in your user profile directory.

Once installed, start VSCode. On the left toolbar, click on the Extensions icon and install the following extensions:

  • Nsight Visual Studio Code Edition
  • C/C++ IntelliSense
  • Remote Development
  • Makefile Tools
  • Shell Debugger

Once these extensions are installed, you can use VSCode to connect to Orion. Click on the remote connection button in the bottom left corner of the VSCode window and select Connect to Host. Type orion.

It may ask you for the operating system of the remote host, select Linux. Once you are connected, click on Menu > Terminal > New Terminal. This gives you a bash terminal on Orion. You can type id and pwd to confirm that you are connected as yourself and that you are in your home directory.

Important note: Once connected to a remote server, the VSCode will automatically install the VSCode server in your home directory on the remote server; this may take a few seconds. You will also need to reinstall the extensions listed above on VSCode once you are running on the remote server.

5. Running a C/C++ Program

This section covers how to compile, run and debug a C/C++ program on the Orion server using VSCode. First, use the following command in the VSCode terminal to download the example code in your home directory:

$ cd ~
$ wget --user cluster --password computing http://roberge.duckdns.org/files/orion/prime_cpp.zip

Unzip the start code:

$ unzip prime_cpp.zip

Go to Menu > File > Open Folder and open the prime_cpp directory. Inspect the content of the prime.cpp file. This code computes the number of prime numbers between 2 and n. To compile and run the code, click on the debug icon on the left toolbar to open the debug window and then select Run debug from the drop-down menu in the left window. Then click on the green arrow just left of the drop-down menu. The start code should run successfully. You should see the output of the program in the TERMINAL window.

Important note: To run your code, always use the Run and Debug (Ctrl+Shift+D) button on the left toolbar, select the run configuration in the drop-down menu and click Start Debugging (F5). This allows you to use the Makefile and the build and launch tasks that have been manually programmed in the tasks.json and launch.json files (keep reading to learn about these two files).
Tip: If you use the Debug or run button on the right-hand side of VSCode, you will be using some default task and launch parameters and the project will fail. To avoid this mistake, right-click on the Debug or run button on the right-hand side of VSCode and disable its visibility.

This project has been configured to be compiled using a Makefile. Inspect the content of the source file and the Makefile. The Makefile is a bit complex but complete. It can be used as a starting point when creating your own C/C++ projects. Now, inspect the content of the .vscode directory, which is used by VSCode to configure the project.

The c_cpp_properties.json file is used by the VSCode to perform the syntax highlighting and to allow you to see function definitions and perform auto-completion. It is not used during the compilation. If the c_cpp_properties.json is not configured correctly, you may see errors highlighted in your code, but your code still compiles correctly. These errors are false positives due to the misconfiguration.

The launch.json file configures the launch option for your program. In this example, there is a “Run debug” and a “Run release” launch configuration. For both configurations, you can see the path to the binary being executed. You can also see the arguments used. Note that the launch configurations were configured with a pre-launch task which compiles the program before it is run.

The tasks.json file configures the compilation tasks. Here, it calls the Makefile with the appropriate target.

To debug your program, add breakpoints by clicking to the left of the line number in the .cpp source file and compile and run your program in debug mode. When the program stops at a breakpoint, you can see the content of variables on the left window. To see the content of arrays, add an entry such as the following in the watch window:

(double[5]) *input

This entry would allow you to see the first 5 values of the array input. By the way, there is no array in this C++ example, but knowing this trick will prove invaluable when writing your own code in VSCode. To print the value of a single element of an array, you can type something like the following in the DEBUG CONSOLE tab:

input[5]

This entry would allow you to see the 6th element of array input. Remember that C/C++ is zero indexed.

Another useful trick, VSCode has an auto-format feature and fixes the indentation of your code. To use it, simply type:

  • On Windows: Shift + Alt + F or Ctrl + k followed by Ctrl + f
  • On Mac: Shift + Option + F
  • On Linux: Ctrl + Shift + I

Once your code is working in debug mode, compile it and run it in release mode. This will ensure that it works correctly in release mode. However, to measure accurate runtimes, you must run the code without the GDB debugger attached. For this, go to the Terminal tab and call the program directly. In this case, call:

$ release/prime

6. Running an OpenMP Program (multicore CPU)

Now that you have run a sequential program, let’s use OpenMP to take advantage of the multicore processor installed in the Orion server. First, download the example code :

$ cd ~
$ wget --user cluster --password computing http://roberge.duckdns.org/files/orion/prime_omp.zip

Unzip the start code:

$ unzip prime_omp.zip

Go to Menu > File > Open Folder and open the prime_omp directory. Inspect the content of the prime.cpp file. This code also computes the number of prime numbers between 2 and n, but now uses multiple threads. You can inspect the Makefile to see the options used to compile the program.

Adjust the number of threads and run the program. Run it outside of the debugger to get the real runtime of the program. As an example, the following command will run the program with 4 to 12 threads with increments of 4.

$ make release
$ release/prime_omp 4 4 12

Inspect the launch.json file in the .vscode directory to see how VSCode can be configured to pass arguments to the program

7. Running a CUDA Program (GPU)

The GPU contains a very large number of cores when compared to multicore CPUs, but each core is much simpler in design. GPUs are optimized for massively parallel programs that exploit data-level parallelism. To test the GPU installed on the Orion HPC Server, download the CUDA example program using the following commands:

$ cd ~
$ wget --user cluster --password computing http://roberge.duckdns.org/files/orion/prime_cuda.zip

Unzip the start code:

$ unzip prime_cuda.zip

Go to Menu > File > Open Folder and open the prime_cuda directory. Inspect the content of the prime.cu file, the Makefile and the files in the .vscode directory. When you are ready, compile and run the example program using the launch button. You should note a much higher speedup compared to the OpenMP program. You can also launch the program right from the terminal to avoid the debugger overhead.

$ make release
$ release/prime

8. Running an MPI Program (Distributed and Multicore)

For highly complex tasks, it is sometimes necessary to use the computing power of multiple computers connected together in a cluster. This can be achieved using a high-performance multi-process library for distributed systems such as Message Passing Interface (MPI). Although you have access to a single server, you can still run MPI on the server. Go ahead and download the MPI example program in your home directory:

$ cd ~
$ wget --user cluster --password computing http://roberge.duckdns.org/files/orion/prime_mpi.zip

Unzip the start code:

$ unzip prime_mpi.zip

Go to Menu > File > Open Folder and open the prime_mpi directory. Inspect the content of the various files in the directory.

You are now ready to compile and run the MPI example program. Use the launch button and select mpirun release. Mpirun is the application that launches the multiple processes on the server.

Debugging an MPI program is a bit tricky because mpirun is the first process to run, which, in turn, starts several instances of your program. If you try debugging your program in the standard way, the debugger will start debugging mpirun and not your application. This will fail catastrophically. To debug your MPI program, compile your program in DEBUG mode using the Makefile.

$ make debug

Note that there is a line of code at the beginning of the main() function that is included only in debug mode:

#ifndef NDEBUG
wait_for_debugger(world_rank, 0);
#endif

This line of code makes process 0 wait for the debugger to attach to it. Once the program is compiled in debug mode, insert at least one breakpoint into the source code and use the command prompt to launch the program:

$ make run-debug

Process 0 will spin lock until the debugger attaches to it. Now, from VSCode, use the launch button and select attach debug. You will be prompted to select the PID of the process to attach to. Typically, process 0 of your program will be the process named prime with the lowest PID. Once attached, process 0 will start running automatically and should stop at your first breakpoint. You can now use the debugger normally.

9. Running a Matlab program

Three methods exist to run Matlab programs on the Orion server. The first method uses SSH X11 forwarding to run Matlab with a GUI environment. It works well, but the GUI is a bit slow. The SSH connection must also remain active for the duration of the program execution. The second method consists of running Matlab from the command prompt using the tmux terminal multiplexer. There is no GUI and programs can run in the background even if the SSH connection is terminated. The third method is by using VSCode to program remotely in Matlab. Let’s look at these three methods in more detail.

9.1 Matlab with SSH X11 Forwarding

To run Matlab with a GUI environment, you need to have MobaXterm installed on your Windows computer. MobaXterm is a free application that can easily be found here. There are two editions available: an installer edition and a portable edition that does not require any installation.

Once you have MobaXterm, start the program. Click on the session icon to configure a new session. Select SSH and enter the remote host orionhpc.duckdns.org, your username and port 22223. In the advanced settings tab, make sure that X11-forwarding is checked. You can now click on Ok.

Back to the main window, double-click on the session to initiate the connection. It will ask you for your password. Once you have a command prompt, start Matlab by typing the command matlab. Matlab will start on the server, but the GUI will be forwarded to your Windows computer. Wait a few seconds for the GUI to appear. This may take up to a minute. You can now use all the features of Matlab from your Windows computer. Remember that your SSH connection must remain active; otherwise, your Matlab session terminates.

To run the Matlab example code, from the Matlab command prompt, type the following commands to download and run the code:

>> urlwrite('http://roberge.duckdns.org/files/orion/prime_parfor.m','prime_parfor.m','Username','cluster','Password','computing');
>> prime_parfor()

9.2 Matlab From the Command Prompt Using Tmux

The second method of running Matlab is to run it from the command prompt in a terminal created using tmux. Tmux is a terminal multiplexer; it allows the user to create terminals, run programs, detach from the terminal, terminate the SSH session, come back later and reattach to the tmux terminal to see the result of the program. Here are the steps in details:

Connect to the Orion HPC Server using SSH as you did earlier:

$ ssh orion

Create a tmux terminal named matlab-session and launch Matlab without the GUI:

$ tmux new -s matlab-session
$ matlab -nodesktop -nosplash

You can now interact with Matlab, enter commands, run scripts, etc. Let’s assume you are running a program that takes a long time to terminate. You can detach from the tmux session by typing Ctrl-b followed by d. Once detached, you can terminate the SSH session by typing exit. At a later time, you can reconnect using SSH and list the running tmux terminals using:

$ tmux ls

You can then reconnect to a terminal by typing tmux a -t followed by the terminal name or number as displayed by the previous command. As an example, to reconnect to the matlab-session terminal, you would enter:

$ tmux a -t matlab-session

When working in Matlab in command prompt mode, you cannot use plotting functions. However, you can save all your workspace variables using the save command, transfer the file to your Windows computer and use Matlab there to plot your results. You can use an SFTP session in MobaXterm to transfer files between the Orion server and your computer.

9.3 Matlab in Visual Studio Code

It is also possible to remotely develop and run Matlab programs in VSCode. For this, you need to install the Matlab extension by MathWorks in VSCode and then type Ctrl+Shift+P, and search for “Preferences: Open User Settings (JSON)”. Once you are in the user settings file, add the following line at the end just before the closing curly bracket:

"MATLAB.startDebuggerAutomatically": true

When entering this line, you may need to add a comma just before it. Look at the file template; you should be able to figure it out. Save and close the file. You can now edit and debug Matlab code in VSCode. To run a program, select the run icon in the top right window of VSCode. The execution will pause on any breakpoint you enter.

10. Conclusion

Thank you for using the Orion HPC Server. You now know how to run programs in C/C++, OpenMP, CUDA, MPI and Matlab. If you have comments or requests, do not hesitate to contact the system administrator.

Scroll to Top