Kernel management

Available kernels

For Julia, Golang, R and C++/ROOT langages, ready-to-use kernels are available in the directory:

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

In order to use one of them, you simply need to copy the given kernel directory (here Golang-1.13.6) to your own $HOME/.local/share/jupyter/kernels/ area:

% mkdir -p $HOME/.local/share/jupyter/kernels/  # If your kernel area does not exist yet

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

Add a custom kernel

In order to add a custom kernel, you need to provide a proper configuration file to Jupyter. This configuration file will call upon a Python or Anaconda virtual environment requiring the following package dependences:

ipykernel, pyzmq and zeromq for any kernel:
- ipykernel depends on pyzmq which depends on zeromq.
dask4in2p3 when using the Dask functionality.

Important

The Python kernel environment must be self-sufficient, i.e. all required Python modules must be available in the environment. See the jupyter-helper.sh example below.

Please take into account Anaconda usage recommendations.

Once your virtual environment is set, please follow the following steps to prepare a custom kernel:

Create a new directory in $HOME/.local/share/jupyter/kernels/, let say python-3.9 (in this example we want to add a Python 3.9 custom kernel)

If the directory tree does not exist yet, then you have to create it.
```
% mkdir -p $HOME/.local/share/jupyter/kernels/python-3.9
```

Go into that directory and create a kernel.json file that will look like this:

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

display_name is the name you want to give to your custom kernel, and will be displayed in your JupyterLab instance. You may want to update the language key as well. But the most important part is the jupyter-helper.sh script.

Alternatively you may run the following line:

% python -m ipykernel install --user --name python-3.9 --display-name "Python (python-3.9)"

this will create a ~/.local/share/jupyter/kernels/python-3.9/kernel.json file similar to:

{
  "argv": [
    "/work/scratch/env/$USER/.conda/envs/NAME/bin/python",
    "-m",
    "ipykernel_launcher",
    "-f",
    "{connection_file}"
  ],
  "display_name": "Python (python-3.9)",
  "language": "python",
  "metadata": {
    "debugger": true
  }
}

The script jupyter-helper.sh will provide the requirements to set up the environment of the new kernel. This script will look like this:
```
#!/bin/bash
source /usr/share/Modules/init/bash

module load Programming_Languages/anaconda/3.9
conda activate your_env

unset PYTHONPATH
export PYTHONPATH=/path/to/your_env:$PYTHONPATH

exec python -m ipykernel_launcher "$@"
```
The first part sets up the required environment (here we are setting up the Anaconda virtual environment your_env), and the last line tells Jupyter how to start that new kernel. For the kernel to be able to initialize, the script must have execute permissions:
```
% chmod +x jupyter-helper.sh
```

Note

CC-IN2P3 provides the jupyter-helper.sh script to set up custom kernels, for instance for the most recent ROOT or Python environments already provided in the software area. The full list of available scripts can be found in the following file:

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

GPU based python environment

In the following recipe we will take the installation of JAX as an example.

Connect on a notebook server associated to a GPU, in order to have CUDA installed. Then open a new terminal window.

Load a recent python version:

% module load Programming_Languages/python/3.9.1

Create a python virtual environment (jax_env for this example).
Install the CUDA based python library you wish to install and other needed packages as well. Here we will simply install JAX. To do so you will need to choose the package corresponding to CUDA 11.4 and the compatible cudnn version.
```
% python -m pip install "jax[cuda11_cudnn805]" -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html --prefix=/path/to/jax_env
```
```
% python -m pip install "jax[cuda11_cudnn805]"  "jaxlib[cuda11_cudnn805]"
```
Attention

GPU functionality on the Jupyter platform is limited compared to the computing platform. What can be executed in a job cannot always be executed on the platform.
Test that the package is well installed and find the GPU devices:
```
% python -c "import jax; print(jax.devices())"
```
Create your custom kernel with this virtual environment as described above.