# Example -- Connecting to Kernel on HPC Cluster

## Submitting Jobs to Computing Node
1. Use libyt API [`yt_run_JupyterKernel`](../../libyt-api/yt_run_jupyterkernel.md#yt_run_jupyterkernel) in simulation and compile:
   ```c++
   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`.
2. Submit the job to HPC cluster, your simulation should be running by now.
3. Create connection file `libyt_kernel_connection.json` in the same folder where simulation executable is. An example of `libyt_kernel_connection.json`:
   ```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"
   }
   ```

   ```{eval-rst}
   .. tip::
      - ``ip`` should be the internal ip of the computing node, where MPI root process is. Normally, we can find it in ``/etc/hosts``:
   
        .. code-block:: bash
           
           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.
   ```
   
4. Wait for incoming connection from Jupyter Notebook / JupyterLab (See below [Connecting to Kernel](#connecting-to-kernel))
5. Shutdown the kernel. ([How to Exit](./frontend.md#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](#login-node) before going through [Local Laptop](#local-laptop) Section.

```{note}
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

1. Complete [Starting Jupyter Notebook / JupyterLab -- Step 1, 2, and 3](./jupyter-notebook-access.md#starting-jupyter-notebookjupyterlab).
2. Launch Jupyter Notebook / JupyterLab in no-browser mode with port `XXXX` and allowing access from other IP address (`--ip="0.0.0.0"`):
   ```bash
   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.
3. You should see something like:
   ```text
   http://127.0.0.1:XXXX/lab?token=<token>
   ```
   - `<token>` is generated by Jupyter.

### Local Laptop
1. Find login node's internal ip address. Normally, we can find it in `/etc/hosts`:
   ```bash
   cat /etc/hosts
   ```
   Here, we assume login node's internal ip is `192.168.0.150`.
2. After [Login Node](#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.
   ```{eval-rst}
   .. tip::
      An SSH connection would be like:
      
      .. code-block:: bash
         
         ssh -p <host_port> <user>@<host>
   
      SSH port forwarding would be like:
      
      .. code-block:: bash
         
         ssh -p <host_port> -N <user>@<host> -L localhost:YYYY:192.168.0.150:XXXX
      
      ``YYYY`` is the port you want to bind to on local laptop, 
      and ``XXXX`` is the port where JupyterLab binds to on login node. 
      If there is no ``<host_port>``, simply remove ``-p <host_port>``.
   ```
3. Leave the terminal open. (It's normal if it doesn't print anything after connection.)
4. Copy and paste the link from [Login Node -- Step 3](#login-node) and change `XXXX` to `YYYY` in browser.
5. Click "Libyt" kernel and connect to libyt kernel launched by libyt API [`yt_run_JupyterKernel`](../../libyt-api/yt_run_jupyterkernel.md#yt_run_jupyterkernel).