JupyterLab

This article is a draft

This is not a complete article: This is a draft, a work in progress that is intended to be published into an article, which may or may not be ready for inclusion in the main wiki. It should not necessarily be considered factual or authoritative.

Introduction

JupyterLab is now the recommended general-purpose user interface to use on a JupyterHub. From a JupyterLab server, you can manage your remote files and folders, and you can launch Jupyter applications like a terminal, (Python 3) notebooks, RStudio and a Linux desktop.

The subsection JupyterHub on clusters contains the list of available Jupyter hubs at Compute Canada.

Launching a JupyterLab server as a job

JupyterHub Server Options form

On Béluga and Hélios, once the authentication is done on JupyterHub, your Web browser is redirected to either a previously launched Jupyter server or a form that allows you to configure and submit a new interactive session on the cluster. In any case, the JupyterLab server is running on dedicated compute resources.

In the Server Options form, you can:

• Select the compute account to be used (any def-*, rrg-*, rpp-* or ctb-* account you have access to)
• Set the amount of hours required for the session
• Set the number of CPU cores that will be reserved on a single node
• Set the amount of memory for the entire session
• (Optional on Béluga) Select one or two GPUs
• Select a User Interface - this is where JupyterLab should be selected

The JupyterLab Interface

When JupyterLab is ready to be used, the interface has multiple panels.

Default home tab when JupyterLab is loaded

Menu bar on top

• In the File menu:
  • Hub Control Panel: if you want to manually stop the JupyterLab server and the corresponding job on the cluster. This is useful when you want to start a new JupyterLab server with more or less resources
  • Log Out: the JupyterHub session will end, which will also stop the JupyterLab server and the corresponding job on the cluster
• Most other menu items are related to notebooks and Jupyter applications

Tool selector on left

• File Browser (folder icon):
  • This is where you can browse in your home, project and scratch spaces
  • It is also possible to upload files
• Running Terminals and Kernels:
  • To stop kernel sessions and terminal sessions
• Commands
• Property Inspector
• Open Tabs:
  • To navigate between application tabs
  • To close application tabs - the corresponding kernels remain active

Loaded modules and available modules

• Softwares (blue cubic icon):
  • Compute Canada modules can be loaded and unloaded in the JupyterLab session
  • The search box can search for available modules and give the result in the Available Modules panel. Note: some modules are hidden until their dependency is loaded - we recommend that you first look for a specific module with module spider module_name from a terminal.
  • The next sub-panel is the list of Loaded Modules in the whole JupyterLab session. Note: while python and ipython-kernel modules are loaded by default, additional modules must be loaded before launching some other applications and notebooks. For example: scipy-stack.
  • The last sub-panel is the list of Available modules, similar to the output of module avail. By clicking on a module's name, detailed information about the module is displayed. By clicking on the Load link, the module will be loaded.

Application area on right

• The Launcher tab is opened by default
  • It contains all available Jupyter applications and notebooks, depending on which modules are loaded

Status bar at the bottom

• By clicking on the icons, this brings you to the Running Terminals and Kernels tool.

Jupyter Applications

This section presents the main supported Jupyter applications on JupyterLab with the Compute Canada software stack.

Terminal

Terminal launcher button

This launcher will open a terminal in a new JupyterLab tab:

• The terminal runs a (Bash) shell on the remote compute node without the need of an SSH connection
  • Gives access to the remote filesystems (/home, /project, /scratch)
  • Allows running compute tasks
• The terminal allows copy-and-paste operations of text:
  • Copy operation: select the text, then press Ctrl+C
    • Note: usually, Ctrl+C is used to send a SIGINT signal to a running process, or to cancel the current command. To get this behaviour in JupyterLab's terminal, click on the terminal to deselect any text before pressing Ctrl+C
  • Paste operation: press Ctrl+V

Python (notebook)

Searching for scipy-stack modules

If any of the following scientific Python packages is required by your notebook, before you open this notebook, you must load the scipy-stack module from the JupyterLab Softwares tool:

• ipython, ipython_genutils, ipykernel, ipyparallel
• matplotlib
• numpy
• pandas
• scipy
• Other notable packages: Cycler, futures, jupyter_client, jupyter_core, mpmath, pathlib2, pexpect, pickleshare, ptyprocess, pyzmq, simplegeneric, sympy, tornado, traitlets
• And many more (click on the scipy-stack module to see all Included extensions)

To open an existing Python notebook:

• Go back to the File Browser
• Browse to the location of the *.ipynb file
• Double-click on the *.ipynb file:
  • This will open the Python notebook in a new JupyterLab tab
  • An IPython kernel will start running in background for this notebook

To open a new Python notebook in the current File Browser directory:

• Click on the Python 3.x launcher under the Notebook section:
  • This will open a new Python 3 notebook in a new JupyterLab tab
  • A new IPython kernel will start running in background for this notebook

RStudio

RStudio launcher button

To enable the RStudio launcher, the following three modules need to be loaded:

1. gcc
2. r
3. rstudio-server

Depending on the software environment version, you should load the following two modules (r is loaded automatically):

• With StdEnv/2020, it is not yet working
• With StdEnv/2018.3, load modules: gcc/7.3.0, rstudio-server/1.2.1335
• With StdEnv/2016.4, load modules: gcc/7.3.0, rstudio-server/1.2.1335

This RStudio launcher will open or reopen an RStudio interface in a new Web browser tab:

• It is possible to reopen an active RStudio session after the Web browser tab was closed
• The RStudio session will end when the JupyterLab session will end

Desktop

Desktop launcher button

This Desktop launcher will open or reopen a remote Linux desktop interface in a new Web browser tab:

• This is equivalent to running a VNC server on a compute node, then creating an SSH tunnel and finally using a VNC client, but you need nothing of all this with JupyterLab!
• It is possible to reopen an active desktop session after the Web browser tab was closed
• The desktop session will end when the JupyterLab session will end