Jupyter Notebook Access¶

Requirements¶

Compile libyt in jupyter kernel mode (-DJUPYTER_KERNEL=ON).
Call libyt API yt_run_JupyterKernel.
Python package jupyter_libyt and jedi. If ipython is already installed, jedi is likely installed as well.

Setting Up¶

During simulation runtime, libyt will activate libyt Jupyter kernel (libyt kernel). We need another process to start Jupyter Notebook/JupyterLab and connect to libyt kernel.

Tip

The process of starting Jupyter Notebook/JupyterLab and running simulation are separate and independent. Which means the Python used to launch the Jupyter Notebook/JupyterLab doesn’t need to be the same as the one used in the simulation.

Starting Jupyter Notebook/JupyterLab¶

Step 1 – Get jupyter_libyt

pip install jupyter-libyt

Step 2 – Make sure libyt kernel is discoverable by Jupyter

jupyter-libyt == 0.1.0

After installing libyt, add <libyt-install-prefix>/share/jupyter to JUPYTER_PATH.

export JUPYTER_PATH=<libyt-install-prefix>/share/jupyter:$JUPYTER_PATH

jupyter-libyt >= 0.2.0

Installing jupyter-libyt will also install the kernel spec for libyt_kernel.

Caution

Since jupyter-libyt 0.2.0, it has dropped the support for Python 3.7. If you are using Python 3.7, please use jupyter-libyt 0.1.0.

Check if libyt_kernel is listed:

jupyter kernelspec list

Step 3 – Set Env variable LIBYT_KERNEL_INFO_DIR

Export environment variable LIBYT_KERNEL_INFO_DIR to where the simulation executable directory is.

export LIBYT_KERNEL_INFO_DIR=<path-to-simulation-dir>

Tip

Jupyter Notebook / JupyterLab will grab the connection information file libyt_kernel_connection.json in the folder LIBYT_KERNEL_INFO_DIR.

Step 4 – Launch Jupyter Notebook/JupyterLab

jupyter notebook # launch Jupyter Notebook
jupyter lab      # launch JupyterLab

Step 5 – Connect to libyt kernel

Click Libyt to connect to libyt kernel once the simulation is running and libyt kernel is activated.

Running Simulation¶

Compile libyt in jupyter kernel mode (-DJUPYTER_KERNEL=ON).
Call libyt API yt_run_JupyterKernel. When flag file is detected, libyt will activate libyt kernel.
libyt API yt_run_JupyterKernel returns YT_SUCCESS after libyt kernel shuts down by Jupyter Notebook / JupyterLab (see How to Exit).
Simulation can continue its process.

Example¶

Known Limitations¶

The functionality is limited to taking Python inputs and printing outputs from all the MPI processes only. libyt hasn’t done implementing Jupyter’s full feature, like data streaming, supporting ipwidgets yet.
See Limitations in MPI Related Python Tasks.