Connecting to Kernel on HPC Cluster

Table of contents

Submitting Jobs to Computing Node
Connecting to Kernel
- Login Node
- Local Laptop

Submitting Jobs to Computing Node

Use libyt API yt_run_JupyterKernel in simulation and compile:
```
if (yt_run_JupyterKernel("LIBYT_STOP", true) != YT_SUCCESS) {
    // some error message
}
```
It will launch libyt Jupyter kernel once it detects LIBYT_STOP. Remember to make libyt to use user provided connection file by setting true.
Submit the job to HPC cluster, your simulation should be running by now.

Create connection file libyt_kernel_connection.json in the same folder where simulation executable is, for example:

{
  "transport": "tcp",  
  "ip": "192.168.0.151",  
  "control_port": 53545,  
  "shell_port": 63994,  
  "stdin_port": 58177,  
  "iopub_port": 51243,  
  "hb_port": 61501,  
  "signature_scheme": "hmac-sha256",  
  "key": "64e13a6faaf1470eb1f86df565543923"
}

ip should be the internal ip of the computing node, where MPI root process is. Normally, we can find it in /etc/hosts:
```
cat /etc/hosts
```
Ports should be unused.

Wait for connection from Jupyter Notebook / JupyterLab (See below Connecting to Kernel)
Shutdown the kernel. (How to Exit)

Connecting to Kernel

We will start a no-browser Jupyter Notebook / JupyterLab on login node. Then we use SSH tunneling (SSH port forwarding) to connect to this no-browser notebook. Finally, we can open the web browser on our local laptop and connect to libyt Jupyter kernel.

Please go through Login Node before going through Local Laptop Section.

We don’t need a running simulation before going through these steps. These steps can also check if SSH tunneling is working and can launch other kernels (like ipykernel) on login node, not just connecting to libyt kernel.

Complete Starting Jupyter Notebook / JupyterLab – Step 1, 2, and 3.
Launch Jupyter Notebook / JupyterLab in no-browser mode with port XXXX and allowing access from other IP address:
```
jupyter-lab --no-browser --port=XXXX --ip="0.0.0.0"
jupyter notebook --no-browser --port=XXXX --ip="0.0.0.0"
```
Change XXXX to some unused port, this is just a placeholder.
You should see something like:
```
http://127.0.0.1:XXXX/lab?token=<token>
```
- <token> is generated by Jupyter.

Local Laptop

Find login node’s internal ip address. Normally, we can find it in /etc/hosts:
```
cat /etc/hosts
```
Here, we assume login node’s internal ip is 192.168.0.150.
After login node has started a no-browser jupyter notebook, use SSH port forwarding and connect to the Jupyter Notebook / JupyterLab server on the login node.
```
ssh -p <host_port> -N <user>@<host> -L localhost:YYYY:192.168.0.150:XXXX
```
- Replace <host_port>, <user>, and <host> to SSH connection settings. For example, an SSH connection would be like:
```
ssh -p <host_port> <user>@<host>
```
  If there is no <host_port>, simply remove -p <host_port>.
- YYYY is the port you want to bind to on local machine.
Leave the terminal open. (It’s normal if it doesn’t print anything after connection.)
Copy and paste the link from Login Node – Step 3 and change XXXX to YYYY in browser.
Click “Libyt” kernel and connect to libyt Jupyter kernel launched by libyt API yt_run_JupyterKernel.