Install

DPsim is a Python module and C++ library for dynamic power system simulation.

The quickest route to a result is the Python module: install it, then work through the tutorials, which build up one idea at a time from a source and a resistor. If you would rather read a finished study than build one, the example notebooks run complete scenarios and plot them.

Building from source is only needed for a platform without a published wheel, or to work on DPsim itself; see build.

Try it without installing

The example notebooks run in the browser with no local installation:

Python package

DPsim is published on PyPI and installs like any other Python package:

python3 -m venv venv
source venv/bin/activate
pip install dpsim

On Windows the same three steps are:

py -m venv venv
venv\Scripts\activate
pip install dpsim

macOS

DPsim currently does not provide a pre-built macOS wheel. On macOS, install DPsim from source using the native setup script included in the repository.

The setup has been tested on Apple Silicon and uses the standard CMake build together with Homebrew-provided dependencies.

First make sure the Xcode Command Line Tools are installed:

xcode-select --install

Then clone DPsim and run the macOS setup script:

git clone https://github.com/sogno-platform/dpsim.git
cd dpsim

chmod +x scripts/install-macos.sh
./scripts/install-macos.sh

The setup script prepares the complete native development environment. It installs the required Homebrew dependencies, creates a local Python virtual environment called dpsim-python, configures and builds DPsim with CMake, installs the Python package, and registers a DPsim Python Jupyter kernel.

The native build includes support for:

• Apple Silicon (arm64) and Intel (x86_64) macOS
• CMake and Ninja
• Eigen 3
• SuiteSparse / KLU
• Graphviz
• OpenMP through Homebrew libomp
• Python bindings through pybind11
• C++ examples
• JupyterLab and the DPsim Python environment

After installation, activate the Python environment with:

source dpsim-python/bin/activate

The Python package can then be used normally:

import dpsim
import dpsimpy

For C++ development, the build directory created by the setup script is already configured with the required macOS-specific CMake settings. Normal rebuilds therefore only require:

cmake --build build --parallel "$(sysctl -n hw.ncpu)"

The macOS-specific dependency paths and compiler settings are stored in the CMake build directory and do not have to be specified again for subsequent builds.

To recreate the complete local environment and build tree from scratch, run:

CLEAN=1 ./scripts/install-macos.sh

This removes the local DPsim build directory, Python environment and registered DPsim Jupyter kernel before recreating them.

The default macOS setup builds the DPsim simulation core, Python bindings, OpenMP support, Graphviz support and C++ examples.

Note: CIM/CGMES support and VILLASnode integration are not enabled by the default macOS setup script and require their respective native dependencies to be configured separately.

Supported versions

DPsim needs CPython 3.10 or newer, both for the wheels and for a source build. One wheel is published per platform and CPython version:

Free-threaded interpreters (cp3XXt) and PyPy are not built, and neither are 32-bit or Arm wheels. Older DPsim releases additionally ship CPython 3.9 wheels.

The two wheels are not equivalent. The Windows one is built without VILLASnode, real-time support and Sundials, because those do not build there, so co-simulation, real-time execution and the ODE-based generator are missing from it:

Do not build from source to close that gap; on Windows there are two easier routes to the full package. Either run the Linux wheel inside WSL2, where a plain pip install dpsim gives you everything, or use the sogno/dpsim container described below, which ships the same complete build.

The wheel pulls in NumPy 2.0 or newer, pandas 2.0 or newer and SciPy 1.10 or newer.

If you prefer conda, the equivalent is:

conda create -n dpsim python=3.13
conda activate dpsim
pip install dpsim

Docker

You need Docker installed first. The prepared image on Docker Hub bundles the module together with a JupyterLab session:

docker run -p 8888:8888 sogno/dpsim

Then open http://localhost:8888/lab?token=3adaa57df44cea75e60c0169e1b2a98ae8f7de130481b5bc.

Note that the image pins that access token in its startup command, so it is the same for everyone who runs the image. Publish the port on localhost only, as above, and do not expose it to an untrusted network.

To build the image yourself rather than pulling it, see build.