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 - 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.

2 - 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.

3 - Real-Time

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

In principle, real-time execution is supported on all platforms. However, we recommend to use an optimized Linux installation.

Operating System and Kernel

For minimum latency several kernel and driver settings can be optimized.

To get started, we recommend the Redhat Real-time Tuning Guide.

A PREEMPT_RT patched Linux kernel is recommended. Precompiled kernels for Fedora can be found here: http://ccrma.stanford.edu/planetccrma/software/

Use the tuned tool for improving general real-time performance. Please adjust the setting isolated_cpucores according to your hardware and enable the realtime profile as follows:

  $ dnf install tuned-profiles-realtime
  $ echo "realtime" > /etc/tuned/active_profile
  $ echo "isolated_cpucores=6-7" >> /etc/tuned/realtime-variables.conf
  $ systemctl enable tuned && systemctl start tuned
  $ systemctl reboot

Running a real-time simulation

As a reference, real-time simulation examples are provided in the Examples/Cxx folder of the DPsim repository.

In order to run a real-time simulation, the simulation process must be started in a special way in order to change the execution priority, scheduler and CPU affinity. For this purpose the chrt and taskset commands are used. In the following example, we pin the execution of the simulation to CPU cores 6-7 which have been reserved previously by the tuned real-time profile (see above).

  $ taskset --all-tasks --cpu-list 6-7 \
  $ chrt --fifo 99 \
  $ Examples/Cxx/RT_DP_CS_R_1

More details:

Some proposals for the selection of appropriate server hardware:

  • Server-grade CPU, e.g. Intel Xeon. A multi-core system enables true parallel execution of several decoupled systems
  • Server-grade network cards, e.g. Intel PRO/1000. These allow offloading of UDP checksumming to the hardware