jupyter-for-hpc.md

@@ -58,4 +58,90 @@ On JUWELS and JURECA currently the following kernel are installed:
 * C++ (14,17,1z)
 * Julia
 * Bash
-but you can create your own specialized Jupyter kernel if you like (and need).
+but you can create your own specialized Jupyter kernel if you like (and need):
\ No newline at end of file
+
+#### Setup your own specialized Jupyter-Kernel
+The installed kernels might not suite your needs and you want to switch to a different software stage or want to load additional software modules.  
+In that case you need to set up your own specialized Jupyter kernel (located in ''${HOME}/.local/share/jupyter/kernels/'').  
+This can be done in the terminal in a few steps on the supercomputer:
+1. LOAD the modules you need 
+  * start with ''module --force purge'' to remove any module which is already loaded
+  * ensure this includes a recent Python 3.x (even if you are not planing to use Python)
+  * example:
+    ```shell 
+    module --force purge
+    module use /usr/local/software/jureca/OtherStages
+    module load Stages/Devel-2018a
+    module load GCCcore/.5.5.0
+    module load Jupyter
+    ```
+
+2. CREATE a new Python virtual environment (VENV) on the supercomputer
+  * e.g. in ''$HOME/venv_mykernel/''
+  * more: https://docs.python.org/3/library/venv.html
+  * example:
+    ```shell 
+    cd $HOME
+    python3 -m venv venv_mykernel
+    ```
+
+3. ACTIVATE the new Python virtual environment (VENV) in your terminal
+  * the loaded modules modify $PYTHONPATH 
+    * ensure(!!!) the first entry is the ''site-package'' directory of your VENV (use ''python -m site'')
+    * ''export PYTHONPATH=<DIR-OF-VENV>/lib/python3.6/site-packages:${PYTHONPATH}''
+  * example:
+    ```shell 
+    source ${HOME}/venv_mykernel/bin/activate
+    (venv)$ export PYTHONPATH=${HOME}/venv_mykernel/lib/python3.6/site-packages:${PYTHONPATH}
+    ```
+
+4. PIMP your VENV
+  * install ipykernel with ''pip''
+  * install any other python software you need with ''pip''
+  * example:
+    ```shell 
+    (venv) $ pip install ipykernel
+    (venv) $ <install whatever else you need in your Python virtual environment using pip>
+    ```
+
+5. INSTALL your personal Jupyter kernel
+  * location of the new Jupyter kernel: ''${HOME}/.local/share/jupyter/kernels/mykernel/''
+  * more: http://ipython.readthedocs.io/en/stable/install/kernel_install.html
+  * example:
+    ```shell 
+    (venv) $ python3 -m ipykernel install --user --name=mykernel
+    ```
+
+Now, modify this basic jupyter kernel to suite your needs.
+
+6. WRITE a launch script
+  * that sets up your environment
+    * load the same modules as in (1)
+  * followed by the IPython kernel launch
+    * load the Python virtual environment as in (3)
+  * example (e.g. ${HOME}/venv_mykernel/mykernel.sh):
+    ```shell 
+    #!/usr/bin/env bash
+
+    module --force purge
+    module load Stages/Devel-2018a
+    module load GCCcore/.5.5.0
+    module load Jupyter
+
+    source ${HOME}/venv_mykernel/bin/activate
+    export PYTHONPATH=${HOME}/venv_mykernel/lib/python3.6/site-packages:${PYTHONPATH}
+
+    exec python -m ipykernel $@
+    ```
+
+7. MODIFY the Jupyter kernel configuration file
+  * located in ${HOME}/.local/share/jupyter/kernels/mykernel/kernel.json file
+  * it must call your launch script: 
+  * example:
+    ```shell 
+    "argv": [
+      "${HOME}/venv_mykernel/mykernel.sh",
+      "-f",
+      "{connection_file}"
+    ],
+    ```