# Using Jupyter Notebooks on Bridges-2

This document explains how to run a Jupyter notebook on Bridges-2 using a Jupyter client on your local machine in a web browser.

## Login to Bridges-2
Connect to Bridges-2 via ssh, gissh, or XSEDE Single Sign-On.

I generally use [SSH](https://en.wikipedia.org/wiki/Secure_Shell). In the commands described below replace `<username>` with your XSEDE username.

$ ssh <username>@bridges2.psc.edu

For example, on MacOSX on [Terminal](https://support.apple.com/guide/terminal/welcome/mac) I can type


## Connect to a compute node using `interact`
Get a Bridges-2 compute node allocated for you by using the `interact` command.

:::info
:warning: You may have to wait for nodes to be allocated to you.
:::

For example, the `interact` below command asks for one node, and 4 cores on that node. You can vary the number of nodes and cores as needed.

$ interact -n 4

For example, on MacOSX on [Terminal](https://support.apple.com/guide/terminal/welcome/mac) I can type the command


to request one node with 9 cores, 16Gb of memory and d walltime of 8 hours.

## Load an Anaconda module
To see what anaconda modules are available, you can use the commands `module avail` or `module spider`.

Running the command

module avail anaconda

should list all the installed Anaconda distributions.

For example, on MacOSX on [Terminal](https://support.apple.com/guide/terminal/welcome/mac) I can type the command


## Find the hostname of the node you are running on.
You will need the hostname when you are mapping a port on your local machine to the port on Bridges-2 compute node.

Find the hostname of the node you are on from the prompt, or type the hostname command.

$ hostname

r001.ib.bridges2.psc.edu

5. Start a Jupyter notebook and find the port number and token.
Start a Jupyter notebook. From the output of that command, find the port that you are running on and your token. Pay attention to the port number you are given. You will need it to make the connection between the compute node and your local machine.

The port number Jupyter uses on the compute node can be different each time a notebook is started. Jupyter will attempt first to use port 8888, but if it is taken – by a different Jupyter user for example – it increases the port number by one and tries again, and repeats this until it finds a free port. The one it settles on is the one it will report.

[I 10:40:03.543 NotebookApp] JupyterLab extension loaded from /opt/packages/anaconda3/lib/python3.8/site-packages/jupyterlab
[I 10:40:03.543 NotebookApp] JupyterLab application directory is /opt/packages/anaconda3/share/jupyter/lab
[I 10:40:03.545 NotebookApp] Serving notebooks from local directory: /jet/home/user
[I 10:40:03.545 NotebookApp] Jupyter Notebook 6.1.4 is running at:
[I 10:40:03.545 NotebookApp] http://r001.ib.bridges2.psc.edu:8889/?token=cd3618a1655ff19783fb38a87ccbe7fa5bac8b09c7888e91
[I 10:40:03.545 NotebookApp]  or http://127.0.0.1:8889/?token=cd3618a1655ff19783fb38a87ccbe7fa5bac8b09c7888e91
[I 10:40:03.545 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
[C 10:40:03.550 NotebookApp]

    To access the notebook, open this file in a browser:
        file:///jet/home/user/.local/share/jupyter/runtime/nbserver-60525-open.html
    Or copy and paste one of these URLs:
        http://r001.ib.bridges2.psc.edu:8889/?token=cd3618a1655ff19783fb38a87ccbe7fa5bac8b09c7888e91
     or http://127.0.0.1:8888/?token=cd3618a1655ff19783fb38a87ccbe7fa5bac8b09c7888e91
In this case, the port number you have been given on the compute node is 8889.

6. Map a port on your local machine to the port Jupyter is using on the Bridges-2 compute node
Use a second connection to Bridges-2 to map the port 8888 in your local machine to the port you are using (8889 in this example) on the compute node. This is a bit of the chicken-and-the-egg situation: if you knew what node and what port you would end up on, you could have done the mapping on the first connection. But there is no way to know that a-priori, hence this.

On a separate shell, connect to Bridges-2 with ssh and map the port Jupyter is using on the compute node to whatever port you like on the localhost. The format of this command is:

ssh -L local-port:compute-host-name:compute-node-port bridges2.psc.edu -l <username>

You must use the correct compute node name and port that you have been allocated. In this case, because you were connected to port 8889 on compute node r001, that command would look like

$ ssh -L 8888:r001.ib.bridges2.psc.edu:8889   bridges2.psc.edu -l <username>

Here the localhost port is “8888”. After the first “:” comes the long name of the compute node, a colon, and the port where Jupyter is running. Here, that string is `r001.ib.bridges2.psc.edu:8889`.

Note that even though the port on the compute node is 8889 in this case, we still use local port 8888 as usual.

7. Open a browser window to connect to the Jupyter server.
On your local machine, start up a browser and point it to `http://localhost:8888`. You will be prompted to enter a token to make the connection. Use the token given to when you started the Jupyter server on the Bridges-2 compute node (step 6 above).

8. When you are done, close your interactive session on Bridges-2
Your allocation will be incurring SUs for the entire time that you are connected to your interactive session on the Bridges-2 compute node. When you are finished, don’t forget to return to the Bridges-2 interactive session and end the Jupyter server with Control-C, and then end your interactive session by typing exit.