Local Mathematica with Remote Kernel

Mathematica supports running the computation kernel on a different host than the Mathematica frontend itself. This functionality allows us to use the processing speed and memory (512 GB) of a VSC-5 cluster node for Mathematica computations while still having a local frontend.

The following instructions only work on Linux and macOS, we are trying to find a way to do the same on Windows. However, it should be possible to use the WSL (Windows Subsystem for Linux) and follow the Linux instructions (you would need to install Mathematica into WSL, too). Also, you need to use the SSH key-based login to the VSC-5, see the Access to VSC Wiki entry for information on how to set this up.

The instructions are split into the steps that are only needed once and the steps that need to be done each time the remote kernel should be used.

Steps Needed to be Done Only Once

Download the tunnel.sh script and make it executable (on the command line type "chmod +x tunnel.sh"). Remember the location where you saved the script.
This script contains the logic needed to connect to a remote SSH server and correctly start the Mathematica kernel there.
Start Mathematica and add a new remote kernel.
- Go to "Evaluation -> Kernel Configuration Options" and click "Add".
- Type in a descriptive name (e.g. "VSC-5 Remote Kernel") and select "Advanced Options".
- In "Arguments to MLOpen" type in the following on one line:
```
-LinkMode Listen -LinkProtocol TCPIP -LinkHost 127.0.0.1 -LinkOptions MLDontInteract
```
- In "Shell command to launch kernel" type in the following on one line:
```
"/path/to/tunnel.sh" VSCUSERNAME@localhost:9998 /opt/sw/vsc4/VSC/x86_64/generic/Mathematica/12.3.1/bin/math `linkname`
```
  Make sure you specify the correct path where you saved the script and the correct VSC-5 username, not your local username. The path to the Mathematica kernel may change in the future when the VSC-5 adds a new Mathematica release.
- Check the "Raw MathLink connection" box.
- Click on "OK" to close the dialog and then "OK" another time to get back to the main Mathematica interface.
After these steps you have a new kernel configuration defined that starts a kernel not locally on your host but on the VSC-5.
Update your SSH configuration file ~/.ssh/config to make connecting to the VSC-5 cluster using SSH keys easier. Put the following lines into it, using your VSC-5 username
```
Host vsc5.vsc.ac.at
Port 27
User VSCUSERNAME
```
Now you can connect to the VSC-5 cluster by just entering ssh vsc5.vsc.ac.at.

Connect to the Remote Kernel

The following steps are needed to connect to the remote kernel:

Open a terminal on your computer and copy-paste (or enter) the following commands:
```
ssh vsc5.vsc.ac.at
salloc -p zen3_0512_a100x2 --gres=gpu:1
```
The command creates a new SSH connection to the VSC-5 login node vsc5.vsc.ac.at. Inside this connection the GPU node is allocated which is reserved as long as the shell is not closed. Additionally, the name of the reserved cluster node is output for use.
Note the name of the cluster node, it has the form "nXXXX-YYY".
Open another terminal on your computer and execute the following command:
```
ssh -L 9998:nXXXX-YYY:22 -N vscuser@vsc5.vsc.ac.at
```
Substitute "nXXXX-YYY" with the cluster node hostname from the last step. This command creates another connection to the VSC-5 login node and a tunnel that connects the local port 9998 with the SSH port on the reserved cluster node.
Start Mathematica and under "Evaluation -> Notebook's Kernel" select the remote kernel that you added.

When you enter something in the frontend, the remote kernel on the VSC-5 cluster node is automatically started and the computation performed. If you enter "SystemInformation[]" the output will show you that the kernel is indeed running on the cluster node.

After you are finished, make sure that you release the job allocation for the cluster node by exiting the shell that was started in step 1.