Plateforme Jupyter Notebooks¶

Description du service¶

JupyterLab est un environnement web de développement interactif pour les “Notebooks”, ou bloc-notes, Jupyter, le code et les données. Un Notebook Jupyter est une application web qui vous permet de créer et de partager des documents contenant du code, du texte descriptif, de la visualisation et des équations. C’est donc un moyen pratique d’explorer les données, de documenter et de partager son travail. Vous pouvez trouver plus d’informations sur le site web du projet Jupyter. La plateforme Jupyter Notebooks est destinée à tout utilisateur disposant d’un compte calcul au CC-IN2P3.

Pour une compréhension générale de l’outil, veuillez vous référer à la documentation officielle de JupyterLab. Si vous rencontrez un problème, veuillez soumettre un ticket au support utilisateur.

Accès¶

Vous pouvez accéder à ce service en cliquant sur ce lien : notebook.cc.in2p3.fr. L’accès est accordé via la fédération d’identité eduGAIN ou en saisissant votre identifiant et votre mot de passe de votre compte calcul.

Après authentification, votre serveur de bloc-notes JupyterLab sera lancé et persistera jusqu’à votre déconnexion (la fermeture de la page Web n’arrête pas le bloc-note).

Une fois connecté, le serveur de notebooks fournira l’accès aux zones de stockage suivantes :

• répertoire HOME : /pbs/home/u/username
• répertoire THRONG : /pbs/throng
• répertoire SOFTWARE : /pbs/software
• répertoire SPS : /sps/x selon vos groupes primaire et secondaires

% ln -s /pbs/throng/ccin2p3 $HOME/throng_ccin2p3

Les notebooks sont fournis avec l’interpréteur Python inclus dans une distribution récente d’Anaconda. Si l’environnement Python fourni par défaut ne répond pas à vos besoins, vous pouvez ajouter le vôtre.

La recette pour inclure un tel noyau personnalisé dans votre instance JupyterLab est donnée dans la section ci-dessous. Le CC-IN2P3 fournit également des scripts spécifiques pour vous aider à configurer des noyaux personnalisés à partir d’environnements Python ou ROOT disponibles.

Conseils pratiques¶

• Démarrage
  • S’il vous est impossible d’ouvrir un serveur de notebooks, veuillez suivre l’une des démarches suivantes classées par priorité :
    • vérifiez que votre HOME ne soit pas plein avec la commande df -h $HOME ;
    • videz le cache de votre navigateur ;
    • supprimez le repertoire $HOME/.jupyter/lab/workspaces ;
    • supprimez le repertoire $HOME/.jupyter (si pas sauvegardé, le fichier $HOME/.jupyter/jupyter_notebook_config.py pourra être re-généré par la commande jupyter notebook --generate-config).
• Exécution
  • Les STDOUT et STDERR de votre serveur de notebooks sont envoyés à /var/log/notebookserver/notebookserver.log ;
  • Les notebooks ne sont pas limités en nombre de CPU ou temps d’utilisation ; ils sont limités en RAM par groupe ou par login. Par défaut, tout groupe bénéficie de 2 Go, , veuillez contacter support utilisateur pour demander plus de mémoire.
• Logout
  • Pour arrêter votre serveur de notebook, utilisez File > Log Out :
    • Les notebooks CPU inactifs sont détruits après 72 heures ;
    • Les notebooks GPU inactifs sont détruits après 24 heures.

Noyaux disponibles¶

Pour les langages Golang, Julia, R et C++/ROOT, des noyaux prêts à l’emploi sont disponibles à l’emplacement suivant :

/pbs/software/centos-7-x86_64/jupyter_kernels/

Afin de les rendre disponible dans votre bloc-note, il suffit de copier le répertoire du noyau désiré, ici Golang v1.13.6, dans l’emplacement dédié de son répertoire utilisateur $HOME/.local/share/jupyter/kernels/ :

% mkdir -p $HOME/.local/share/jupyter/kernels/  # Si ce répertoire n'existe pas encore

% cp -r /pbs/software/centos-7-x86_64/jupyter_kernels/Golang-1.13.6 $HOME/.local/share/jupyter/kernels/.

Ajouter un noyau personnalisé¶

Pour ajouter un noyau personnalisé, il faut fournir à Jupyter un fichier de configuration approprié :

1. Tout d’abord, créez un nouveau répertoire dans $HOME/.local/share/jupyter/kernels/, disons python-3.8 (dans cet exemple nous voulons ajouter un noyau personnalisé Python 3.8)

   Si l’arborescence des répertoires n’existe pas encore, vous devez la créer.

   % mkdir -p $HOME/.local/share/jupyter/kernels/python-3.8
   

2. Allez dans ce répertoire et créez un fichier kernel.json

   % cd $HOME/.local/share/jupyter/kernels/python-3.8
   % vi kernel.json
   

   Le fichier kernel.json ressemblera à ceci :

   {
     "display_name": "conda3",
     "language":     "python",
     "argv": [
         "<PATH TO THE SCRIPT>/jupyter-helper.sh",
         "-f",
         "{connection_file}"
     ]
   }
   

   display_name est le nom que vous souhaitez donner à votre noyau personnalisé et sera affiché dans votre instance JupyterLab. Vous pouvez également mettre à jour le paramètre language. Mais la partie la plus importante est le script jupyter-helper.sh.

3. Le script jupyter-helper.sh fournira les détails pour configurer l’environnement du nouveau noyau. Ce script ressemblera à ceci :

   #!/bin/bash
   
   module load Programming_Languages/conda/<version>
   conda activate your_env
   
   # Uncomment and adapt the following line
   # if your kernel does not start
   # export PYTHONPATH=/path/to/your_env
   
   exec python -m ipykernel_launcher "$@"
   

   La première partie configure l’environnement requis (ici, nous mettons en place un environnement Anaconda), et la dernière ligne indique à Jupyter comment démarrer ce nouveau noyau. Pour que le noyau puisse s’initialiser il faut que le script ait les permissions d’exécution :

   % chmod +x jupyter-helper.sh
   

/pbs/software/centos-7-x86_64/jupyter_kernels/jupyter_helper_scripts

Environnement python pour GPU¶

Dans la recette suivante nous décrirons l’installation de Jax comme exemple.

1. Premièrement se connecter à un notebook GPU, afin d’avoir CUDA installé. Ouvrir une nouvelle fenêtre de terminal.

2. Charger une version récente de python :

   % module load Programming_Languages/python/3.9.1
   

3. Créer un environnement virtuel python :

   % cd /path/to/
   % python -m venv --system-site-packages "jax_env"
   

4. Activer l’environnement puis modifier la variable PYTHONPATH comme suit :

   % source /path/to/jax_env/bin/activate
   % export PYTHONPATH=/path/to/jax-env/
   

5. Maintenant, installer la librairie python basé sur CUDA, et d’autres paquets si nécessaire. Ici nous installerons simplement Jax. Pour ce faire choisir le paquet adéquat pour la version de CUDA et cudnn installé qui peuvent être trouvé dans la section GPU.

   % python -m pip install "jax[cuda11_cudnn805]" -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html --prefix=/path/to/jax_env
   

6. Tester que le paquet est bine installé et que le device GPU est bien trouvé :

   % python -c "import jax; print(jax.devices())"
   

7. Enfin, créer un noyau personnalisé avec cet environnement comme décrit plus haut.

Extensions JupyterLab disponibles¶

Plusieurs extensions à JupyterLab sont disponibles :

• Voilà permet la prévisualisation d’un bloc-note en HTML, cette prévisualisation peut se faire soit dans JupyterLab, soit dans un nouvel onglet du navigateur (dans ce cas, il faut autoriser les fenêtes pop-up), l’interactivité fournie par les extensions ipywidgets et ipympl (voir ci-dessous) peut être conservée par la prévisualisation, pour plus de détails merci de consultez le dépôt officiel de Voilà ;
• Jupytext offre la possibilité de synchroniser ses bloc-notes dans un ou plusieurs autres formats, tels que le Markdown, qui permettra ainsi le stockage de ses bloc-notes dans des dépôts Git, pour plus de détails merci de consulter le dépôt officiel de Jupytext ;
• ipywidgets permet d’accroître l’interactivité avec le bloc-note grâce à des gadgets logiciels (widgets), pour plus de détails merci de consulter le dépôt officiel de ipywidgets ;
• ipympl offre de l’interactivité avec les graphes créés avec matplotlib, pour plus de détails merci de consulter le dépôt officiel de ipympl ;
• jupyterlab-latex permet la prévisualisation de documents LaTeX (fichiers *.tex) directement dans un bloc-note, pour plus de détails merci de consulter le dépôt officiel de jupyterlab-latex ;
• LaTeX peut aussi être utilisé pour les légendes des graphes créés avec matplotlib et pour convertir et exporter un bloc-note en document PDF.

Si vous avez besoin d’aide pour utiliser la plateforme JupyterLab, ou pour configurer votre propre noyau personnalisé, veuillez contacter le support utilisateur.