BwUniCluster2.0/Jupyter

Jupyter can be used as an alternative to accessing HPC resources via SSH. For this purpose only a web browser is required. Within the website source code of different programming languages can be edited and executed. Furthermore different user interfaces and terminals are available.

1 Short description of Jupyter

Jupyter is a web application, central component of Jupyter is the Jupyter Notebook. It is a document, which can contain formatted text, executable code sections and (interactive) visualizations (image, sound, video, 3D views).

The Jupyter notebooks are executed in an interactive session on the compute nodes of the respective cluster. Access is via any web browser. Data is prepared and visualized on the server and therefore does not have to be transmitted over the network. Only the resulting text, image, sound and video data is transmitted. Starting point of a Jupyter session is the HOME directory of the user on the respective cluster.

JupyterLab is a modern user interface, within which one or more Jupyter notebooks can be opened, edited and executed. The individual notebooks can be arranged as tabs or tiled. JupyterLab is the standard user interface. Besides JupyterLab the classic notebook user interface is available, in which only one Jupyter notebook per browser tab can be opened at a time.

A Jupyter Kernel describes a separate process, in which one Jupyter Notebook is executed at a time. Different kernels are available for different programming languages or language versions.

Before a Jupyter session is started, the access authorization must be checked first. This is done via JupyterHub, where the resources are selected, for example the number of CPU cores, GPUs or the required main memory.

A detailed documentation of the Jupyter project can be found at https://jupyter.readthedocs.io.

2 Access requirements

To use Jupyter on the HPC resources of SCC, the respective access requirements for bwUniCluster 2.0 and ForHLR apply. Registration at https://bwidm.scc.kit.edu/ is required.

The Jupyter service is only accessible within the KIT network. If the service is to be used from outside, a VPN Connection to the KIT network must be established first.

3 Login process

Login takes place at uc2-jupyter.scc.kit.edu or fh2-jupyter.scc.kit.edu respectively. For login, KIT username, KIT password and a 2-factor authentication is required.

If you are not yet logged in to KIT, you will first be automatically redirected to the corresponding login page. Select your home organization (e.g. KIT) and press Continue. In the Login section that appears, enter your KIT username and password (not the service password). After pressing the Login button you will be redirected to the second factor query page. Enter the one-time password (e.g. from KIT Token or Google Authenticator App) and press Validate. Now you will be redirected to the JupyterHub page, after pressing the "Sign in with your KIT Account" button you are logged in.

4 Selection of the compute resources

The Jupyter notebooks are executed in an interactive session on the compute nodes of the HPC clusters. Just like accessing an interactive session with SSH, resource allocation is done by the Workload Manager Slurm. The selection of resources for Jupyter is realized via drop-down menus. Only jobs with a maximum of one node are possible.

Available for selection are

• Partition/Queue
• Runtime
• Number of GPUs
• Number of CPU cores
• Amount of main memory

After the selection is made, the interactive job is started with the spawn button. As when requesting interactive compute resources with the `salloc` command, waiting times may occur. These are usually the longer the larger the requested resources are.

If by mistake an impossible resource combination is selected, an error message is displayed.

5 JupyterLab

JupyterLab ist die Standard-Benutzeroberfläche. Im Folgenden werden nur deren wesentlichen Funktionen kurz vorgestellt. Eine ausführliche Dokumentation steht unter https://jupyterlab.readthedocs.io zur Verfügung.

5.1 Menüleiste

Die Menüleiste am oberen Rand von JupyterLab verfügt über übergeordnete Menüs, in denen die in JupyterLab verfügbaren Aktionen mit ihren Tastenkombinationen angezeigt werden. Die Standardmenüs sind:

• File: Aktionen im Zusammenhang mit Dateien und Verzeichnissen
• Edit: Aktionen im Zusammenhang mit der Bearbeitung von Dokumenten und anderen Aktivitäten
• View: Aktionen, die das Erscheinungsbild von JupyterLab verändern
• Run: Aktionen zum Ausführen von Code in verschiedenen Aktivitäten wie Notebooks und Code-Konsolen
• Kernel: Aktionen zur Verwaltung von Kerneln, die separate Prozesse zur Ausführung von Code sind
• Tabs: eine Liste der geöffneten Dokumente und Aktivitäten im Dockpanel
• Settings: allgemeine Einstellungen und ein Editor für erweiterte Einstellungen
• Help: eine Liste von Hilfelinks zu JupyterLab und zum Kernel

5.2 Linke Seitenleiste

In der linken Seitenleiste befinden sich ausklappbare Tabs. Die relevantesten sind:

• Dateibrowser: Wechsel in Verzeichnisse und Öffnen von Dateien mit linker Maustaste, Kontextmenü mit rechter Maustaste
• Laufende Kernel: Übersicht über laufende Kernel
• Befehlsübersicht
• Tab-Übersicht
• Lmod-Software Auswahl: Suche und Laden/Entladen von Lmod Software Modulen

5.3 Haupt-Arbeitsbereich

Der Hauptarbeitsbereich in JupyterLab ermöglicht es, Dokumente (Notebooks, Textdateien usw.) und andere Aktivitäten (Terminals, Code-Konsolen usw.) in Tabs anzuordnen, in der Größe zu verändern und zu unterteilen. Mit gedrückter linker Maustaste können die Tabs ergriffen und neu positioniert werden.

In einer neuen JupyterLab Sitzung ist zunächst der Launcher-Tab geöffnet. In diesem befinden sich Knöpfe zum Starten neuer Notebooks, Code-Konsolen und anderer Funktionen. Bei geöffneten Notebooks kann ein neuer Launcher-Tab gestartet werden, indem im Dateibrowser Tab der linken Seitenleiste das Plus-Symbol gedrückt wird, durch Aufruf von File > New Launcher in der oberen Menüleiste oder durch die Tastenkombination Ctrl+Shift+L.

5.4 Classic Notebook

Die klassische Jupyter Notebook Benutzeroberfläche bietet nur jeweils ein geöffnetes Jupyter Notebook bzw. ein Terminal pro Browser-Tab. Aus der JupyterLab Benutzeroberfläche heraus ist die klassische Anzeige erreichbar in der Menüleiste unter Help > Launch Classic Notebook. Das Anklicken des JupyterHub Logos oben links führt zurück auf JupyterLab Oberfläche.

6 Abmelden

Von einer laufenden Jupyter Sitzung können Sie sich durch Aufruf von File > Log Out in der oberen Menüleiste abmelden.

Achtung Bitte beachten Sie, dass Ihre interaktive Sitzung im Hintergrund weiterläuft! Dies belastet beispielsweise auf dem ForHLR Ihr Rechenzeitkontingent.

Solange die interaktive Sitzung läuft, können Sie diese jederzeit wieder betreten. Je nach Dauer der Abwesenheit ist die erneute Eingabe von Einmalpasswort und eventuell KIT Passwort nötig.

Wollen Sie die interaktive Sitzung vor Erreichen ihrer Laufzeit beenden, können Sie dies über das Hub Control Panel tun. Unter File > Hub Control Panel in der oberen Menüleiste wird dieses in einem neuen Browser-Tab geöffnet. Durch Drücken des Stop My Server Knopfes wird die Sitzung beendet. Sie können sich nun über den Logout Knopf oben rechts abmelden oder über den Start My Server Knopf direkt eine neue Sitzung starten, beispielsweise mit veränderter Ressourcen-Auswahl.

7 Auswahl von Software

Für die Auswahl der benötigten Lmod Softwaremodule steht in der linken Seitenleiste der entsprechender Tab Softwares zur Verfügung. Durch Eingabe im Suchfeld kann die Liste der verfügbaren Module eingegrenzt werden. Das gewünschte Modul wird über den Load Knopf geladen. In der Liste mit den geladenen Modulen können diese mit dem Unload Knopf entfernt werden.

Bitte beachten Bei bereits geöffneten Jupyter Notebooks werden neu geladene Softwaremodule erst nach Neustart des Kernels aktiv (Kernel > Restart Kernel in der oberen Menüleiste). Terminals müssen geschlossen und neu geöffnet werden.

8 Installation eigener Software

`pip install`