jupyter-viz-extension 0.5.1

A JupyterLab extension.

jupyter_viz_extension

jupyter_viz_extension or short JuViz is an extension for JupyterLab that enables the usage of ParaView trame within JupyterLab. It bridges Cloud and interactive Visualization, allowing users to run and control their customized visualization and analysis apps, written in trame, from inside the JupyterLab. It was written with Cloud-Computing and HPC in mind and is designed to be platform-independant.

Installation and Configuration

Requirements

For the extension, you only need 2 Components:

• JupyterLab >= 3.0
• JupyterServerProxy >= 3

The extension itself is not linked to any trame dependencies, as these are loaded at runtime when the app is launched.

Installation

To install the extension, execute:

pip install jupyter_viz_extension

Configuration

JuViz can be configured with different Configuration classes. These contain the platform/architecture specific code and can be used to configure how ParaView and trame Instances are launched, where trame app configs are stored, etc. The Configuration class is selected at runtime via the JUVIZ_CONFIGURATION environment variable.

Existing Configurations can be found in the configurations sub-package

To start correctly, set the JUVIZ_CONFIGURATION environment variable before starting JupyterLab:

export JUVIZ_CONFIGURATION=desktop

Adding a trame app to JuViz

To add a trame app to JuViz that can be configured and executed in JupyterLab, you need to:

1. Copy the App and all its Assets and required Files, to the Cluster.
   • By default, JuViz will look at all locations in the JUPYTER_PATH environment variable and try to detect apps that are in the trame subdirectory.
   • In most cases, ~/.local/share/jupyter/trame is a valid location for alls
   • Put your trame app in a new subdirectory in the trame forder. For example: ~/.local/share/jupyter/trame/my-app
2. You now need to tell JuViz some details about your app and how it should be launched:
   • Create a file called app.yml with the following values:
     • name: Display name of the App that is used in the UI
     • working_directory: The working directory of a launched instance, i.e., from where the launch command should be executed
     • command: The launch command to execute. This should: load all dependencies, prepare the environment and launch the app.
   • The launch command will be passed some arguments for trame, which are generated by JuViz before the launch (authentication key, etc.) in the JUVIZ_ARGS variable. These must be forwarded to trame when the app is started: python my-app/__init__.py $JUVIZ_ARGS

Thats it! Now your app should be available and launchable in the JuViz UI.

Connect a trame app to a ParaView Server

ToDo

Creating a custom Configuration

To create a new Configuration for a new system, create a new Python file in the configurations sub-package and create a new class that inherits from jupyter_viz_extension.configurations.Configuration (or any other Configuration if desired). Here you can override exiting methods of the class and customize, how things are executed. Take a look at the doc-strings of the base Configuration class for a more detailed explanation.

Contributing

Development install

Note: You will need NodeJS to build the extension package.

The jlpm command is JupyterLab's pinned version of yarn that is installed with JupyterLab. You may use yarn or npm in lieu of jlpm below.

pip install -e "."
jupyter labextension develop . --overwrite
jupyter server extension enable jupyter_viz_extension
jlpm build

You can watch the source directory and run JupyterLab at the same time in different terminals to watch for changes in the extension's source and automatically rebuild the extension.

jlpm watch
# Run JupyterLab in another terminal
jupyter lab

With the watch command running, every saved change will immediately be built locally and available in your running JupyterLab. Refresh JupyterLab to load the change in your browser (you may need to wait several seconds for the extension to be rebuilt).