jupyterlab-trame-manager

jupyterlab-trame-manager (previously known as jupyter-viz-extension or 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 jupyterlab_trame_manager

Configuration

The extension 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 TRAME_MANAGER_CONFIGURATION environment variable.

Existing Configurations can be found in the configurations sub-package

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

export TRAME_MANAGER_CONFIGURATION=desktop

Adding a trame app to the extension

To add a trame app to the Extension 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, it 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 the Extension 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 the extension before the launch (authentication key, etc.) in the TRAME_INSTANCE_ARGS variable. These must be forwarded to trame when the app is started: python my-app/__init__.py $TRAME_INSTANCE_ARGS

Thats it! Now your app should be available and launchable in the 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 jupyterlab_trame_manager.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 jupyterlab_trame_manager
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).