Skip to content

JupyterLab🔗

Introduction🔗

JupyterLab is a tool for interactive code development and data visualization. It enables a user to create workflows for building, manipulating, connecting, executing and post-processing Modelon Impact models.

Install JupyterLab for Modelon Impact on-premise🔗

For Modelon Impact on-premise, JupyterLab is installed by default. See the section JupyterHub Advanced Tools on how to access it.

Install JupyterLab for Modelon Impact Desktop🔗

This guide describes how we recommend installing and configuring JupyterLab for Modelon Impact Desktop on Windows. After finishing the guide you will have:

  • Installed JupyterLab
  • Configured a Python kernel including:
  • Created a start script for JupyterLab.

Prerequisites🔗

The following is needed for the setup of JupyterLab on Windows for Modelon Impact :

  • A working Modelon Impact Desktop installation on Windows.

This guide has been tested for Modelon Impact-1.5.X (release 2022.1).

Approach🔗

To simplify the setup and launch of JupyterLab for first-time users, a batch script has been prepared that can be used for these purposes. In short, the script performs the following steps:

  1. Creation of a virtual environment of the OCT Python distribution. See "Why a virtual environment?" for the reasoning behind why we use this.
  2. Installation of necessary packages (JupyterLab and Modelon Impact Client ) not already existing in the OCT Python distribution.
  3. Starting JupyterLab in the folder where the script is saved.

The script is set up in such a way that it can be run both for setup and launch. The setup steps (1, 2) will only run the first time. Consequent runs will only start JupyterLab.

1. Create JupyterLab.bat🔗

The batch script code for setup is outlined below. Comments have been added (REM) to explain what each line of code is doing.

REM Copyright 2022 Modelon AB

REM Edit by user
set IMPACT_INSTALL_DIR=C:\ModelonImpact-1.5.1
set VENV_NAME=OCT

REM Convenience variables
set OCT_PATH=%IMPACT_INSTALL_DIR%\oct-dist
set VENV_PATH=%OCT_PATH%\%VENV_NAME%

REM First time setup if venv does not exist
if not exist %VENV_PATH%\ (
REM Create venv of OCT distribution
"%OCT_PATH%\Python37\python.exe" -m venv "%VENV_PATH%" --system-site-packages

REM Activate new venv
call "%VENV_PATH%\Scripts\activate.bat"

REM Install packages
pip install pip==22.0.3
pip install jupyterlab==3.2.4 modelon-impact-client

REM Create Jupyter kernel
python -m ipykernel install --user --name=%VENV_NAME%
)

REM Activate new venv
call "%VENV_PATH%\Scripts\activate.bat"

REM Set env vars needed to run OCT
call "%OCT_PATH%\setenv.bat"

REM Launch Jupyter Lab
if %errorlevel% neq 0 pause
"%VENV_PATH%\Scripts\jupyter-lab.exe"
if %errorlevel% neq 0 pause
pause
  • Copy the above code to a text file and save it as JupyterLab.bat.

Note

JupyterLab will open in the folder where JupyterLab.bat is saved.

2. Edit user configurations🔗

There are two lines that need to be edited to reflect the local setup:

REM Edit by user:
set IMPACT_INSTALL_DIR=C:\ModelonImpact-X.X.X
set VENV_NAME=OCT

Explanation:

  • IMPACT_INSTALL_DIR - Point to your Modelon Impact installation directory. By default, this is C:\ModelonImpact-X.X.X, X.X.X being the Modelon Impact version number.
  • VENV_NAME - Name of the virtual environment (Optional to edit).

To edit JupyterLab.bat, right-click the file and click edit. This will open up an editor where the code can be edited.

  • Edit the values of the two variables and save.

3. First-time setup and launch🔗

The file is now configured and ready to be executed. The first time JupyterLab.bat runs it will install all necessary components and set the virtual environment up. After the setup is finished, it will start JupyterLab. Consequent runs, JupyterLab will be started without performing the setup steps.

  • Run JupyterLab.bat by double-clicking JupyterLab.bat.

When started, JupyterLab runs as a local server and is opened within a web browser.

This concludes the guide on how to set up JupyterLab for Windows!

Why a virtual environment?🔗

Modelon Impact comes with a Python interface to the calculation engine OPTIMICA Compiler Toolkit. It is possible to set up a Jupyter kernel where this interface is accessible, which is done in this guide.

When working with Python in general it is natural to install 3rd party libraries and incorporate them into your code. However, it is NOT recommended to install 3rd party libraries directly into the OCT Python distribution. If this is done, there is a chance that crucial dependencies of OCT will be overwritten by mistake, making it unusable. This will not only corrupt the Python environment you are scripting in but also the Modelon Impact backend as it also uses this Python distribution to run simulations, compilations, etc.

Therefore this guide creates an "OCT"-Jupyter kernel using a virtual environment that will be used in JupyterLab. With this setup, the user can install 3rd party packages without tampering directly with the Modelon Impact backend environment. Note that it is still possible to mess up the dependencies in the created virtual environment. The advantage of this approach is that the damage is limited to the Jupyter kernel and the Modelon Impact backend is kept in its original state.

Attention

Known OCT dependencies that can cause issues if updated:

  • Numpy
  • Scipy

Install 3rd party libraries🔗

We recommend installing 3rd party libraries by running the following code in a notebook:

import sys
!{sys.executable} -m pip install <package name>

This makes sure that the installed package is installed to the Python distribution of the selected kernel for the notebook.