1. Installation#

In this notebook, we will install the syssimx package and its dependencies.

1.1. Basic Setup (Recommended)#

We are using a Miniconda or Anaconda virtual environment. This ensures that all dependencies are met and compatible with each other. We refer to the Anaconda documentation for installation instructions.
We activate the base environment and install jupyter and ipykernel.
We register the virtual environment as a jupyter kernel, so that it can be selected in jupyter notebooks.
We start Jupyter from that virtual environment or select that kernel in VS Code.

Use ! as a prefix to run a shell command in a notebook cell.
Use % as a prefix to run a magic command in a notebook cell (can change IPython behavior and are parsed by IPython itself not the shell).

General Remarks:

We require conda for managing the virtual environment and installing opensim dependencies (not available via pip).
We are using Python 3.11 or Python 3.12 for this package (opensim is not available for Python > 3.12 yet)
We recommend using VS Code as IDE for editing and running notebooks.

1.2. Installation via pip#

syssimx provides pip extras for optional feature groups. You can install just what you need:

syssimx[fmu] – FMI / Modelica support
syssimx[fem] – FEM / NGSolve integrations
syssimx[dev] – development + docs tooling
syssimx[all] – all pip‑installable features
syssimx[full] – all pip‑installable features + dev tooling

Examples:

pip install syssimx
pip install "syssimx[fmu]"
pip install "syssimx[viz,dev]"

OpenSim is conda‑only and must be installed separately with ABI‑compatible NumPy/SciPy (see section below).

OpenModelica 1.26+ is required on Windows for reliable sampling behavior in FMUs generated from OpenModelica (e.g., when sample(...) in FMI co-simulation).

1.3. Python 3.11 Installation#

We are using the base conda environment as the starting point for creating our virtual environment.

The following commands create a new conda environment named env-311 with Python 3.11 and the flag -y automatically confirms all prompts.

You can change the environment name as you like.

!conda create -n env-311 python=3.11 -y

Then swicth to the newly created kernel in the top right corner of the notebook editor in VS Code. It should be named env-311 in this example.

We can now install the syssimx package and its dependencies in this environment.

!pip install "syssimx[full]"

1.3.1. OpenSim under Python 3.11#

In order to allow all our dependencies to work correctly, we need to ensure that we do not any numpy version greater than 2.0 since the OpenSim dependencies are not compatible with it yet (see OpenSim: Scripting in Python).

!conda install -c opensim-org -c conda-forge "opensim=4.5.2=py311np125" "numpy=1.25.*" "scipy<1.12" "simbody" -y

This installation will cause our conda environment to have incompatible package versions.

We can fix it by first uninstalling the numpy packages.

!conda run -n env-311 python -m pip uninstall -y numpy
!conda run -n env-311 python -m pip uninstall -y numpy 

After that, we can reinstall numpy with a compatible version using conda.

!conda install -n env-311 -c conda-forge "numpy=1.25.*" "scipy<1.12" -y

1.3.2. Verification#

We can now verify the installation by importing the following packages in a notebook cell:

%load_ext autoreload
%autoreload 2
try:
    import syssimx
    print(f"syssimx version: {syssimx.__version__}")

    import fmpy
    print(f"FMPy version: {fmpy.__version__}")
    
    import opensim
    print(f"OpenSim version: {opensim.__version__}")

    import ngsolve
    print(f"NGSolve version: {ngsolve.__version__}")

    import numpy
    print(f"Numpy version: {numpy.__version__}")

    import scipy
    print(f"SciPy version: {scipy.__version__}")
    
except ImportError as e:
    print(f"ImportError: {e}")

1.4. Python 3.12 Installation#

To install syssimx with Python 3.12, we can create a new conda environment named env-312 with Python 3.12 and the flag -y automatically confirms all prompts.

!conda env remove -n env-312 -y
!conda create -n env-312 python=3.12 -y

Then swicth to the newly created kernel in the top right corner of the notebook editor in VS Code. It should be named env-312 in this example.

We can now install the syssimx package and its dependencies in this environment.

!pip install "syssimx[full]"

1.4.1. OpenSim under Python 3.11#

In order to allow all our dependencies to work correctly, we need to ensure that we do not generate any conflicts in the dependencies (see OpenSim: Scripting in Python).

We run the following commands to install the opensim conda package along with compatible versions of numpy and scipy.

# Python 3.12 (OpenSim py312np20)
!conda install -c opensim-org -c conda-forge "opensim=4.5.2=py312np20" "numpy=2.0.*" "scipy>=1.12" "simbody" -y

1.4.2. Verify Installation#

%load_ext autoreload
%autoreload 2
try:
    import syssimx
    print(f"syssimx version: {syssimx.__version__}")

    import fmpy
    print(f"FMPy version: {fmpy.__version__}")
    
    import opensim
    print(f"OpenSim version: {opensim.__version__}")

    import ngsolve
    print(f"NGSolve version: {ngsolve.__version__}")

    import numpy
    print(f"Numpy version: {numpy.__version__}")

    import scipy
    print(f"SciPy version: {scipy.__version__}")
    
except ImportError as e:
    print(f"ImportError: {e}")

1.5. OpenSim Interdependencies#

OpenSim is a native (compiled) dependency that is Application-Binary-Interface‑coupled (ABI-coupled) to a specific NumPy build. This means:

OpenSim wheels are not available on PyPI; installation is conda‑only.
Each OpenSim conda build is tied to a NumPy ABI tag (e.g., py311np125, py312np20).
Mixing a different NumPy version can cause import errors (_ARRAY_API not found, numpy.core.multiarray failed to import).

Because of this, the reliable workflow is:

Install syssimx via pip (pip‑installable dependencies only).
Install OpenSim via conda, pinning NumPy/SciPy to the ABI‑compatible versions for that OpenSim build.

If you install OpenSim first and then let pip upgrade NumPy, you can break the ABI compatibility. Installing pip packages first avoids pip overriding conda’s pinned NumPy.

1.5.1. ABI‑compatible combinations#

Python 3.11 + OpenSim py311np125 → numpy=1.25.* and scipy<1.12
Python 3.12 + OpenSim py312np20 → numpy=2.0.* and scipy>=1.12

Installation

Contents