Skip to content

JupyterLab in BEAR Portal

Note

Information on running JupyterLab in BEAR Portal. The instructions assume that you have already logged in.

Launching JupyterLab in BEAR Portal

From the menu bar at the top of the page, select the ‘Interactive Apps’ menu and then select ‘JupyterLab’. (If you cannot see the ‘Interactive Apps’ menu when you log in to the BEAR Portal this means that you need to follow the steps listed in the Access Requirements for BEAR Portal section.)

portal-home-interactive-menu

This will bring up a page for you to specify options for your job, such as:

  • the BEAR project to use
  • the duration for which you want to run the interactive app
  • the QOS to run the job against
  • the number of cores to use in your job.

You will also need to specify which Jupyter kernel to load. (Please see the video tutorial for further information on setting these options.)

portal-jupyterlab

Info

To load additional modules against your chosen kernel, please use the JupyterLab Lmod extension.

Once you are happy with the selected options, click the ‘Launch’ button at the bottom of the page. When you have done this a BlueBEAR job will be submitted to the cluster.

Note

The length of time you will have to wait for this job to start will depend on the resources you have requested - more cores, or asking for GPUs, will mean that you will likely have to wait longer for the resource to become available.

Once the resource is available you’ll see a ‘Connect to Jupyter’ button appear on the page. Clicking on this will take you to the JupyterLab Server instance. When you have finished your work please click on the ‘Delete’ button to stop the job and release the compute resources.

portal-rstudio

Info

To see information relating to your BEAR Portal jobs please refer to the Portal Job Output page.

Loading Modules

JupyterLab includes the Jupyter Lmod extension, which allows the loading of application modules (as listed on BEAR Applications) from within the Jupyter graphical user interface. Once you’ve entered the JupyterLab session for the first time you will see the following screen, from where you can access the Lmod extension interface by clicking on the blue icon in the list on the left of the window:

portal-jupyter-lmod1

Once the Lmod extension interface appears you can use the search bar at the top (see arrow 1) to filter the displayed modules and then click on ‘Load’ to load a module and its dependencies (see arrow 2). Note that there will be a delay whilst the modules load, although there is no graphical indication that this is happening.

portal-jupyter-lmod2

Note

If your Notebook is active (and has an active kernel) prior to loading a module using the above method then you will need to reload the kernel before the module can be used.

Add packages in Julia

To add packages in Julia, at the top of your Notebook you will need to add the following lines:

using Pkg
Pkg.activate(".julia")

This places the Manifest.toml and Project.toml files needed to add julia packages to your .julia directory. You will need to run the above commands whenever you restart your kernel.

Using a virtual environment

Whilst it isn’t possible to use a virtual environment as a kernel, there is a workaround for accessing the contents of a virtual environment described here.

Video Tutorial

For further information, please see our video tutorial which covers JupyterLab usage in detail and is available to watch here:

Note

The information presented in this video about reloading the kernel (starting at 5:12) has changed slightly in the newer versions of JupyterLab on BEAR Portal.
The process is now as follows:

  1. Click on the kernel name on the right of the window.
    jupyterlab-kernel-location
  2. Click the “Select” button in the pop-up.
    jupyterlab-kernel-select
  3. Wait for the kernel status to show “Idle” (as already described).

Known Issues and Advice

Accessing BEAR project directories from the JupyterLab sidebar

JupyterLab starts in your home directory. To access storage outside your home directory, e.g. a RDS project storage, you should create a symbolic link (symlink) from the required path inside your home directory, using the ln -s command.
See Symlinks to BEAR Project directories for further information on this process.

JupyterLab GUI functionality

Warning

This has the potential to result in conflicts between Python packages so care should be taken to ensure that adding this path doesn’t affect the running of your code.

The BEAR Portal JupyterLab app runs inside an Apptainer container, with its own stack of dependencies. These are separate to those required by the running kernel but there are occasions where a notebook needs access to e.g. the ipywidgets package in order to provide some graphical functions.
In these scenarios, please run the following command in a cell to add the relevant container path to the notebook’s Python Path:

import sys
sys.path.append("/usr/local/lib/python3.9/site-packages")

Troubleshooting

Info

The Portal Job Output may provide clues to any issues you’re experiencing.

  • If your JupyterLab sessions fail to start then first check that you’ve removed any user-wide Python modules, as these may be causing conflicts.

  • If you experience persistent issues with Jupyter running on BEAR Portal, please remove the ~/.local/share/jupyter/ directory and its contents by executing the following command:

    rm -r ~/.local/share/jupyter/