Example – Connecting to Kernel on HPC Cluster¶

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 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. An example of libyt_kernel_connection.json:
```
{
  "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. If the ports are in use, then libyt will block and wait for you to provide a new one.
Wait for incoming 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 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.

Login Node¶

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 (--ip="0.0.0.0"):
```
jupyter notebook --no-browser --port=XXXX --ip="0.0.0.0"
jupyter lab --no-browser --port=XXXX --ip="0.0.0.0"
```
Change XXXX to some unused port on login node, 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 laptop.
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 kernel launched by libyt API yt_run_JupyterKernel.