BwUniCluster2.0/Jupyter (Deutsch)

Als Alternative zum Zugriff auf die HPC Ressourcen mittels SSH kann Jupyter verwendet werden. Hierfür ist lediglich ein Webbrowser nötig. Innerhalb der Website kann Quellcode verschiedener Programmiersprachen editiert und ausgeführt werden. Weiterhin stehen unterschiedliche Benutzerschnittstellen und Terminals zur Verfügung.

Kurzbeschreibung Jupyter

Bei Jupyter handelt es sich um eine Webanwendung, zentrale Komponente von Jupyter ist das Jupyter Notebook. Hierbei handelt es sich um ein Dokument, welches gleichzeitig formatierten Fließtext, ausführbare Code-Abschnitte und (interaktive) Visualisierungen (Bild, Ton, Video, 3D Ansichten) beinhalten kann.

Die Jupyter Notebooks werden in einer interaktiven Sitzung auf den Compute-Knoten des jeweiligen Clusters ausgeführt. Zugegriffen wird über einen beliebigen Webbrowser. Daten werden auf dem Server aufbereitet und visualisiert und müssen somit nicht über das Netzwerk übertragen werden. Es werden lediglich die resultierenden Text-, Bild-, Ton- und Video-Daten übermittelt. Ausgangspunkt einer Jupyter Sitzung ist das HOME-Verzeichnis des Nutzers auf dem jeweiligen Cluster.

JupyterLab ist eine moderne Benutzeroberfläche, innerhalb welcher ein oder mehrere Jupyter Notebooks geöffnet, bearbeitet und ausgeführt werden können. Die einzelnen Notebooks können als Tabs oder gekachelt angeordnet werden. JupyterLab ist die Standard Benutzeroberfläche. Neben JupyterLab steht die klassische Notebook Oberfläche zur Verfügung, in welcher nur jeweils ein Jupyter Notebook pro Browser-Tab geöffnet werden kann.

Ein Jupyter Kernel bezeichnet einen separaten Prozess, in welchem jeweils ein Jupyter Notebook ausgeführt wird. Für unterschiedliche Programmiersprachen oder Sprachversionen stehen unterschiedliche Kernel bereit.

Bevor eine Jupyter Sitzung gestartet wird, muss zunächst die Zugriffsberechtigung geprüft werden. Dies geschieht über JupyterHub, wo zudem die Ressourcenauswahl getroffen wird, beispielsweise die Anzahl an CPU-Kernen, GPUs oder der benötigte Hauptspeicher.

Eine ausführliche Dokumentation des Jupyter Projekts findet sich unter https://jupyter.readthedocs.io.

Zugangsvoraussetzungen

Zur Nutzung von Jupyter auf den HPC Ressourcen des SCC gelten die jeweiligen Zugriffsvoraussetzungen für [bwUniCluster 2.0](https://wiki.bwhpc.de/e/BwUniCluster_2.0_User_Access) und [ForHLR](https://wiki.scc.kit.edu/hpc/index.php?title=ForHLR_-_User_Access). Die Registrierung auf [1](https://bwidm.scc.kit.edu/) wird vorausgesetzt.

Der Jupyter Service ist nur innerhalb des KIT Netzes erreichbar. Soll der Dienst von außerhalb verwendet werden, muss zunächst eine [VPN Verbindung](https://wiki.bwhpc.de/e/BwUniCluster_2.0_User_Access_New#Establishing_network_access ) ins KIT Netz hergestellt werden.

Anmeldevorgang

Die Anmeldung erfolgt unter [uc2-jupyter.scc.kit.edu](https://uc2-jupyter.scc.kit.edu) bzw. [fh2-jupyter.scc.kit.edu](https://fh2-jupyter.scc.kit.edu). Für die Anmeldung wird der KIT Benutzername, das KIT Passwort und eine 2-Faktor Authentifizierung benötigt.

Falls Sie noch nicht am KIT eingeloggt sind, werden Sie zunächst automatisch auf die entsprechende Login-Seite weitergeleitet. Wählen Sie Ihre Heimatorganisation (z.B. KIT) aus und drücken sie auf Fortfahren. Im nun eingeblendeten Abschnitt Einloggen tragen Sie Ihren KIT Benutzernamen und das KIT Passwort ein (nicht das Service Passwort). Nach dem Drücken des Einloggen Knopfes werden Sie auf die Abfrageseite für den zweiten Faktor geleitet. Tragen Sie hier das Einmalpasswort ein (beispielsweise von KIT Token oder Google Authenticator App) und drücken Sie auf Prüfen. Nun werden Sie auf die JupyterHub Seite weitergeleitet, nach dem Drücken des "Sign in with your KIT Account" Knopfes sind Sie angemeldet.


Auswahl der Compute-Ressourcen

Die Jupyter Notebooks werden in einer interaktiven Sitzung auf den Compute-Knoten der HPC Clusters ausgeführt. Genau wie beim Zugriff auf eine interaktive Sitzung mit SSH findet die Ressourcenzuteilung über den Workload Manager Slurm statt. Die Wahl der Ressourcen für Jupyter wird über Dropdown-Menüs realisiert. Es sind nur Jobs mit maximal einem Knoten möglich.

Zur Auswahl stehen

- Partition/Queue - Laufzeit - Anzahl an GPUs - Anzahl CPU-Kerne - Menge an Hauptspeicher

Nachdem die Auswahl getroffen ist, wird der interaktive Job mit dem Spawn Knopf gestartet. Wie beim Anfordern von interaktiven Compute-Ressourcen mit dem `salloc` Befehl kann es zu Wartezeiten kommen. Diese sind in der Regel um so länger, je größer die angeforderten Ressourcen sind.


Sollte versehentlich eine nicht mögliche Ressourcenkombination gewählt werden, wird dies mit einer Fehlermeldung angezeigt.


JupyterLab

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

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


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


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*.


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.

Abmelden

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

!!! error "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.


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.

!!! info "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. 


Installation eigener Software

`pip install`