This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Getting Started

How to install, build and run the DPsim project.

1: Real-Time
2: Build
3: Install

1 - Real-Time

This page describes recommended techniques to optimize the host operating system for real-time execution of DPsim.

DPsim supports real-time execution, where the simulation time equals the real or wall clock time, on any system. However, without modifying system parameters the minimum time step reliably achievable will not be in the range of microseconds. This is due to operating system noise and other processes interfering with the simulation. With proper tuning, we have achieved real-time time steps as low as 5 us synchronized to a FPGA using VILLASnode. Synchronizing the time step to an external source is only necessary, when very high time step accuracy, with maximum deviations in the nanoseconds, is required.

Operating System and Kernel

Using a Linux kernel with the PREEMPT_RT feature improves latency when issuing system calls and enables the FIFO scheduler that lets us avoid preemption during the real-time simulation.

Most distributions offer a binary package for a PREEMPT_RT enabled kernel. For example on Rocky Linux:

sudo dnf --enablerepo=rt install kernel-rt kernel-rt-devel

More aggressive tuning can involve isolating a set of cores for exclusive use by the real-time simulation. This way, the kernel will not schedule any processes on these cores. Add the kernel parameters isolcpus and nohz_full using, for example, grubby:

sudo grubby --update-kernel=ALL --args="isolcpus=9,11,13,15 nohz_full=9,11,13,15"

Something similar, but less invasive and non-permanent can be achieved using tuna:

sudo tuna isolate -c 9,11,13,15

To avoid real-time throttling to cause overruns disable this feature:

sudo bash -c "echo -1 > /proc/sys/kernel/sched_rt_runtime_us"

Note that this is not persistent when rebooting.

Simulation Model Tuning

Real time capable models cannot issue any system calls during simulation as the context switch to the kernel introduces unacceptable latencies. This means models cannot allocate memory, use mutexes or other interrupt-driven synchronization primitives, read or write data from files. You should turn off logging, when time steps in the low milliseconds are desired. There is a RealTimeDataLogger that can be used to output simulation results in these cases. Note however, that this logger pre-allocated the memory required for all of the logging required during simulations. Your machine may run out of memory, when the simulation is long or you log too many signals.

You can increase the performance of your simulation by adding the -flto and -march=native compiler flags:

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 8801cbe8d..4a2843269 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -79,7 +79,7 @@ include(CheckSymbolExists)
 check_symbol_exists(timerfd_create sys/timerfd.h HAVE_TIMERFD)
 check_symbol_exists(getopt_long getopt.h HAVE_GETOPT)
 if(CMAKE_BUILD_TYPE STREQUAL "Release" OR CMAKE_BUILD_TYPE STREQUAL "RelWithDebInfo")
-       add_compile_options(-Ofast)
+       add_compile_options(-Ofast -flto -march=native)
 endif()

 # Get version info and buildid from Git

Running a Real-Time Simulation

Before running a simulation, you can run the following commands as root:

echo "evacuating cores"
tuna isolate -c 9,11,13,15

echo "disabling RT throttling"
echo -1 > /proc/sys/kernel/sched_rt_runtime_us

echo "stopping systemd services"
systemctl stop polkit
systemctl stop containerd
systemctl stop crond
systemctl stop chronyd

As a reference, real-time simulation examples are provided in the dpsim/examples/cxx and dpsim-villas/examples/cxx folder of the DPsim repository.

To benefit from the PREEMPT_RT feature and the isolated cores, the simulation has to be started using the chrt command to set the scheduling policy and priority, and the taskset command to pin the process to the isolated cores.

In the following example, we set the FIFO scheduling policy with the highest priority (99) and pin the execution of the simulation to CPU cores 9,11,13,15 which have been reserved previously (see above).

# the simple RT_DP_CS_R_1 simulation
taskset -c 9,11,13,15 chrt -f 99 build/dpsim/examples/cxx/RT_DP_CS_R_1

# Cosimulation using VILLASnode, FPGA synchronized time step, and exchanging data via Aurora interface.
# Here we need sudo, to interact with the FPGA. We disable logging (log=false) and set the time step to 50 us (-t 0.00005).
sudo taskset -c 9,11,13,15 chrt -f 99 build/dpsim-villas/examples/cxx/FpgaCosim3PhInfiniteBus -o log=false -t 0.00005 -d 10

2 - Build

Docker based

Clone the repository

$ git clone git@github.com:sogno-platform/dpsim.git

or using https if you do not have an account

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

In the repository, there is a Docker file with all required dependencies

$ cd dpsim
$ docker build -t sogno/dpsim:dev -f Packaging/Docker/Dockerfile.dev .

Alternatively, the image can be pulled from DockerHub like so

$ docker pull sogno/dpsim:dev

For OS specific instructions on how to install requirements, see the sections below.

Next, run a Docker container

$ cd dpsim
$ docker run -it -p 8888:8888 -v $(pwd):/dpsim --privileged sogno/dpsim:dev bash

The option -p maps the port 8888 of the container to the docker host. This is required to access the jupyter lab instance inside the container. The option --privileged is required for debug builds.

For Windows, you might need to specify the current directory with curly brackets

$ docker run -it -p 8888:8888 -v ${pwd}:/dpsim --privileged sogno/dpsim:dev bash

Now, you should be in an interactive session inside the docker container.

The DPsim C++ and Python library without C++ examples or documentation can be built as follows

$ cd /dpsim
$ mkdir build && cd build
$ cmake ..
$ cmake --build . --target dpsimpy

If you need other libraries that are not built by default, you need to target them specifically, for example if you need `dpsimpy´ and ´dpsimpyvillas´:

$ cmake --build . --target dpsimpy dpsimpyvillas

To build everything run

$ cmake --build .

To use other libraries that are installed, use the relevant option defined in the CMakeList.txt files, for example for GSL below, and then build as usual:

$ cmake .. -DWITH_GSL=ON

If you would like to use the Python package, it has to be added to the path. The following command adds the dpsimpy C++/Python package as well as the dpsim pure Python package.

$ cd /dpsim/build
$ export PYTHONPATH=$(pwd):$(pwd)/../python/src/

If you are using conda or other ways to develop with environments, please keep in mind that this will become specific for your setup. For this case, from within the environment already active:

$ cd /dpsim/build
$ conda develop $(pwd) && conda develop $(pwd)/Source/Python && conda develop $(pwd)/../Source/Python

To run jupyter lab

$ cd /dpsim
$ jupyter lab --ip="0.0.0.0" --allow-root --no-browser

To install dpsim run

$ cd /dpsim/build
$ sudo make install

CMake for Linux

The most recent list of requirements can be found in the Dockerfiles.

Make sure that the required dependencies are installed. The fedora installation script in the DPsim repository is a good place to start from.

Note: There are currently no Debian packages for villas-node and libcimpp16v29a. If you want to use these optional feature, you have to build them manually.

Install Sundials

$ git clone --branch v3.1.1 https://github.com/LLNL/sundials.git
$ mkdir sundials/build
$ pushd sundials/build
$ cmake .. \
    -DBUILD_SHARED_LIBS=ON \
    -DBUILD_STATIC_LIBS=OFF \
    -DEXAMPLES_ENABLE_C=OFF
$ make -j$(nproc) install
$ popd

The following steps to clone, build and install are the same as for the Docker setup.

CMake for Windows

Make sure that the required dependecies are installed:

Visual Studio 2017 with C++ Desktop development package
CMake for Windows
Git for Windows
For Python support, install Python3, for example, Anaconda, and add Python to your PATH.

Clone the project as explained for Docker.

Open a windows command prompt and navigate into the new DPsim folder. Generate a Visual Studio project with CMake and use it to build the project

$ mkdir build
$ cd build
$ cmake -G "Visual Studio 15 2017 Win64" ..

Open Visual Studio and load the Visual Studio project from the build directory within the DPsim folder.

You can either build the project from within Visual Studio or from the command line by running the following command in the windows command prompt

$ cmake --build .

To install the Python package use Visual Studio and the Release configuration to build the DPsim Python module and then build the INSTALL project.

CMake for macOS

Make sure that the required dependecies are installed

$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
$ brew install gcc9 git cmake graphviz python3 gsl eigen spdlog
$ sudo pip3 install numpy

Clone the source as explained for the Docker setup.

Compile

$ mkdir build
$ cmake ..
$ make -j$(sysctl -n hw.ncpu)

To install the generated Python module to your system

$ sudo make install

Python Package for pypi

Follow the previous steps to set up the Docker container.

To build the Python package run

$ python3 setup.py bdist_wheel

Documentation

Python

Install Sphinx or use the Docker image.

Generate the Python documentation by running Sphinx via CMake:

$ mkdir -p build && cd build
$ cmake ..
$ make docs

The resulting documentation will be generated in Documentation/html/.

C++

Install Doxygen or use the Docker image.

Generate the C++ documentation by running Doxygen via CMake:

$ mkdir -p build && cd build
$ cmake ..
$ make docs_cxx

The resulting documentation will be generated in Documentation/html/Cxx.

3 - Install

DPsim is a Python module / C++ library for complex power system simulation. As a Python module, the easiest way to get to know DPsim is via Jupyter Notebooks.

Docker

First, you need to install Docker. Then, you could either build a docker image by yourself as described in the build instructions or download a prepared image from Docker Hub as described in the following.

To start a Jupyter session, run a DPsim Docker container

	$ docker run -p 8888:8888 sogno/dpsim

And access the session by opening the following link: http://localhost:8888/lab?token=3adaa57df44cea75e60c0169e1b2a98ae8f7de130481b5bc

Python

Currently, the pypi packages are not maintained. Until we have updated the packages, please use the docker installation.

Prerequisites

First, you need to make sure that Python is installed and your version is compatible. An easy way to install Python and all required packages is the Anaconda distribution. To get started, install the latest installer for Python 3.x from the downloads section. Then, run the Anaconda Prompt and create a new conda environment:

$ conda create -n dpsim python=3.6

After creating the environment you need to make sure that it is activated. The current environment is displayed at the beginning of the command line in brackets. It should read "(dpsim)…". In case it is not activated, run:

$ activate dpsim

Pip Package Installation

Then, DPsim can be installed as a Python module:

$ pip install dpsim

From Source

To build and install DPsim from the source files, please refer to the build section.