Dynaωo - An hybrid C++/Modelica suite of simulation tools for power systems

http://dynawo.org

This repository contains Dynaωo's project code.

Table of Contents

• About Dynaωo
• Getting started!
• Installation
  • Dynaωo Binaries
  • Building requirements
    • Linux
    • Windows
  • Building Dynaωo
    • Linux
    • Windows
  • Launch Dynaωo
    • Linux
    • Windows
  • Docker Dynaωo
• Dynaωo Documentation
• Get involved
• Quoting Dynaωo
• License
• Maintainers
• Roadmap
• Links

About Dynaωo

Dynaωo is an hybrid C++/Modelica open source suite of simulation tools for power systems. It aims at providing power system stakeholders with a transparent, flexible, interoperable and robust suite of simulation tools that could ease collaboration and cooperation in the power system community.

The nature of power system dynamics is deeply evolving towards a more diverse and difficult to predict behavior due to the massive changes going on in the power system (large penetration of power-electronic based components such as Renewable Energies Sources - RES - or High Voltage Direct Current - HVDC - lines, booming use of complex automata, control strategies or smart grids). Due to this radical change from physically-driven to numerically-driven dynamics, being able to assess the system stability becomes harder but is still essential as any generalized incident will be unacceptable for the economy and the consumers. This requires to have access to a transparent, flexible, robust and easy to use suite of simulation tools that will allow to run collaborative studies in a very simple way by sharing not only the same data but also the same modeling and solving choices in an open-source frame. Such tools will ensure to get similar results and to agree upon optimal and shared actions on the system to accompany the ongoing changes in the best possible way. This analysis has motivated us to launch a new effort on simulation tools that finally ends up in the development of the Dynaωo's software.

To achieve this goal, Dynaωo is based on two mains principles: the use of a high-level modeling language Modelica and a strict separation between modeling and solving parts. Modelica is an equation-based, declarative and object-oriented modeling language that is easy to read and understand (the equations are written in a similar way than they are written in textbooks for example) and already used in different and various industrial sectors. Using this language enables to easily share and discuss the modeling choices done because the final models implementation is available in an understandable way, even for the end-user. It is important to mention that Modelica-based tools already exist (Dymola, OpenModelica, JModelica, etc.) but they are not efficient enough for large-scale simulation of power system, which was one of the motivation for Dynaωo. In addition to this, the Modelica language itself has some limitations that are adressed in Dynaωo by the possibility to use C++ models in a similar way than Modelica models. The second important point in Dynaωo is the strict separation between modeler and solvers - it means that the models only expose a few methods to the solvers such as the residual evaluation, the Jacobian evaluation or the zero-crossing functions or in other words that the numerical resolution method doesn't interfere in the modeling part. This feature has several advantages: it enables to easily test or use new solvers, it eases the addition of new model and it allows modeling expert not to bother about numerical difficulties and vice versa.

Dynaωo's primary focus has been on long-term and short-term stability studies but the very encouraging results obtained and the flexibility of the approach led to an extension of the initiative. Dynaωo is now evolving towards a complete and coherent suite of simulation tools, sharing the same philosophy:

• DynaFlow for steady-state calculations
• DySym for short-circuit calculations
• DynaWaltz for long-term stability simulations
• DynaSwing for short-term stability studies
• DynaWave for stability studies and system design with a high-penetration of power-electronics based components (quasi-EMT)

High level vision of the Dynaωo initiative

Getting started!

To get started with Dynaωo you have different possibilities, depending on your background and what you want to do:

• If you are interested in the models available and want to have a quick look to them, please open the Dynaωo Modelica library in OpenModelica for example.
• If you want to launch simulations and examples with Dynaωo and observe the performances, you can use the pre-built distribution and the examples directory.
• If you want to checkout the repository and build it yourself to be able to modify the tool, please follow the build instructions available here

All validated models are included into the Dynaωo Modelica library. Don't hesitate to open it in OpenModelica to see what are the available models and simulate the simple full Modelica illustrative examples we provide.

In addition, we also provide an example directory containing validated test cases for DynaFlow, DynaWaltz and DynaSwing. Don't hesitate to simulate them and open the associated documentation.

Installation

Dynaωo Distribution

You can download a pre-built Dynaωo release to start testing it. Pre-built releases are available for Linux and Windows:

• Linux
• Windows

If you are on MacOS you can use Docker.

Linux Requirements for Distribution

• Compilers: C and C++ (gcc or clang), C++11 compatible for C++ standard
• Python2 or Python3
• Binary utilities: curl and unzip
• CMake

Note For Python you need to have the python command available in your PATH. If you don't have one, you can use an environment variable to point to your Python version with export DYNAWO_PYTHON_COMMAND="python3".

You can install the dependencies for Ubuntu or Fedora with:

$> apt install -y g++ unzip curl python
$> dnf install -y gcc-c++ unzip curl python

Windows Requirements for Distribution

On Windows you can either run Dynaωo with distribution models and in this case nothing is required. If you want to be able to add new models you will need:

• Visual Studio 2019
• CMake
• Python2 or Python3

Note For Python you need to have the python command available in your PATH. If you don't have one you can use an environment variable to point to your Python version with set DYNAWO_PYTHON_COMMAND=python3.

Using a distribution

Linux

You can launch the following commands to download and test the latest distribution:

$> curl -L $(curl -s -L -X GET https://api.github.com/repos/dynawo/dynawo/releases/latest | grep "Dynawo_Linux" | grep url | cut -d '"' -f 4) -o Dynawo_Linux_latest.zip
$> unzip Dynawo_Linux_latest.zip
$> cd dynawo
$> ./dynawo.sh jobs-with-curves sources/examples/DynaWaltz/IEEE14/IEEE14_GeneratorDisconnections/IEEE14.jobs
$> ./dynawo.sh help
$> ./dynawo.sh jobs-help

Windows

Download the zip of the distribution and unzip it somewhere. Then open either Command Prompt or x64 Native Tools Command Prompt for VS2019 (to be able to use your own models) and use cd to go into the directory you previously unzipped. You should see a dynawo.cmd file at the top of the folder. You can then launch a simulation with:

> dynawo jobs sources\examples\DynaWaltz\IEEE14\IEEE14_GeneratorDisconnections\IEEE14.jobs
> dynawo jobs-with-curves sources\examples\DynaWaltz\IEEE14\IEEE14_GeneratorDisconnections\IEEE14.jobs

You can set up the curves to open in your preferred browser with set DYNAWO_BROWSER=C:\Program Files (x86)\Mozilla Firefox\firefox.exe for example.

Building requirements

You can build Dynaωo from sources. Dynaωo is available on two platforms Linux and Windows. Linux has been tested on Centos and Debian based distributions, for other distributions don't hesitate to contact us if you run in problems. Only Windows 10 has been tested for Windows. If you are on MacOS we recommend you to use a Docker solution.
If you have any issue building Dynaωo don't hesitate to send us an email with your errors and we will try to answer you back quickly.

In the following we give a list of requirements needed to build Dynaωo and its dependencies.

Linux

Global

• Compilers: C and C++ (gcc, clang or Apple Clang with Xcode or Command Line Tools), C++11 compatible for C++ standard

OpenModelica Compiler

• Compiler: Fortran (gfortran)
• Build systems: autoconf, automake, libtool, pkgconf, make, CMake
• Binary utilities: xz, patch, GNU sed, msgfmt from gettext, rsync
• Java (openjdk for example)
• Libraries: expat, BLAS, LAPACK
• lpsolve55 or bison and flex (to let OpenModelica compiles lpsolve itself)

Dynaωo user

• CMake: minimum version 3.9.6
• Python2 or Python3
• Python packages: lxml
• Binary utilities: curl or wget, xmllint

Note For Python you need to have the python command available in your PATH. If you don't have one you can use an environment variable to point to your Python version with export DYNAWO_PYTHON_COMMAND="python3".

Dynaωo developer

• Doxygen: minimum version 1.8, Graphviz and LaTeX to build full documentation
• Python packages: psutil
• LCOV: 1.7 to 1.13 versions work fine

Windows

• Visual Studio 2019, Visual Studio 2015 was also tested
• CMake
• Python2 or Python3

Note For Python you need to have the python command available in your PATH. If you don't have one you can use an environment variable to point to your Python version with set DYNAWO_PYTHON_COMMAND=python3.

Building Dynaωo

Linux

You can install the following packages to have no dependency problem in the following steps. This example works for Ubuntu until 19.04 included:

$> apt-get install -y git gcc g++ gfortran autoconf pkgconf automake make libtool cmake hwloc openjdk-8-jdk libblas-dev liblpsolve55-dev libarchive-dev doxygen doxygen-latex liblapack-dev libexpat1-dev libsqlite3-dev zlib1g-dev gettext patch clang python-pip libncurses5-dev libreadline-dev libdigest-perl-md5-perl unzip gcovr lcov libboost-all-dev qt4-qmake qt4-dev-tools lsb-release libxml2-utils python-lxml python-psutil wget libcurl4-openssl-dev rsync bash-completion

For Ubuntu 20.04 use:

$> apt install -y git gcc g++ gfortran autoconf pkgconf automake make libtool cmake hwloc openjdk-8-jdk libblas-dev liblpsolve55-dev libarchive-dev doxygen doxygen-latex liblapack-dev libexpat1-dev libsqlite3-dev zlib1g-dev gettext patch clang python3-pip libncurses5-dev libreadline-dev libdigest-perl-md5-perl unzip gcovr lcov libboost-all-dev qt5-default lsb-release libxml2-utils python-lxml python-psutil wget libcurl4-openssl-dev rsync libopenblas-openmp-dev

And for Fedora:

$> dnf install -y git gcc gcc-c++ gcc-gfortran autoconf automake make libtool cmake hwloc java-1.8.0-openjdk-devel blas-devel lapack-devel lpsolve-devel expat-devel glibc-devel sqlite-devel libarchive-devel zlib-devel doxygen doxygen-latex qt-devel gettext patch wget python-devel clang llvm-devel ncurses-devel readline-devel unzip perl-Digest-MD5 vim gcovr python-pip python-psutil boost-devel lcov gtest-devel gmock-devel xz rsync python-lxml graphviz libcurl-devel bash-completion

To build Dynaωo you need to clone this repository and launch the following commands in the source code directory, it will create a myEnvDynawo.sh file that will be your personal entrypoint to launch Dynaωo and parametrise some options.

$> git clone https://github.com/dynawo/dynawo.git dynawo
$> cd dynawo
$> echo '#!/bin/bash
export DYNAWO_HOME=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)

export DYNAWO_SRC_OPENMODELICA=$DYNAWO_HOME/OpenModelica/Source
export DYNAWO_INSTALL_OPENMODELICA=$DYNAWO_HOME/OpenModelica/Install

export DYNAWO_LOCALE=en_GB
export DYNAWO_RESULTS_SHOW=true
export DYNAWO_BROWSER=firefox

export DYNAWO_NB_PROCESSORS_USED=1

export DYNAWO_BUILD_TYPE=Release

$DYNAWO_HOME/util/envDynawo.sh $@' > myEnvDynawo.sh
$> chmod +x myEnvDynawo.sh
$> ./myEnvDynawo.sh build-user

Below is a description of some environment variables that might be changed in myEnvDynawo.sh:

You can have more information about compilation options here.

Warning: If you're working behind a proxy make sure you have exported the following proxy environment variables

$> export http_proxy=http://login:mdp@proxy_address:proxy_port/
$> export https_proxy=https://login:mdp@proxy_address:proxy_port/
$> export no_proxy=localhost,127.0.0.0/8,::1
$> export HTTP_PROXY=$http_proxy;export HTTPS_PROXY=$https_proxy;export NO_PROXY=$no_proxy;

Windows

Open x64 Native Tools Command Prompt for VS2019 and run the following commands:

> git config --global core.eol lf
> git config --global core.autocrlf input
> set OPENMODELICAHOME=
> set OPENMODELICALIBRARY=
> md dynawo-project && cd dynawo-project
> git clone https://github.com/dynawo/dynawo.git dynawo
> cd dynawo
> cmake -S dynawo/3rdParty -B b-3-p -DCMAKE_INSTALL_PREFIX=../d-3-p -DOPENMODELICA_INSTALL=../OpenModelica/Install -DOPENMODELICA_SRC=../OpenModelica/Source -DOMDEV_HOME=../OMDev -G "NMake Makefiles"
> cmake --build b-3-p
> cmake -S dynawo -B b -DCMAKE_INSTALL_PREFIX=../d-i -DDYNAWO_HOME=.. -DINSTALL_OPENMODELICA=../../OpenModelica/Install -DDYNAWO_THIRD_PARTY_DIR=../../d-3-p -G "NMake Makefiles
> cmake --build b --target install
> cmake --build b --target models
> cmake --build b --target solvers

Warning We try to limit as far as possible the name of the build and install folders (for example d-i instead of dynawo-install or b-3-p for build-3rd-parties) because of Windows limitation of length of path for folders. We know it causes problems and the only solution is to install Dynaωo in a shorter length directory path.

Warning Only the build directories (b and b-3-p) can be located in the dynawo folder, the install (d-i and d-3-p), OMDev and OpenModelica folders should be located outside to avoid problems with CMake.

Launch Dynaωo

Linux

Once you have build Dynaωo you can start launching a simulation with the command:

$> ./myEnvDynawo.sh jobs-with-curves examples/DynaWaltz/IEEE14/IEEE14_GeneratorDisconnections/IEEE14.jobs

You can also list all available commands with:

$> ./myEnvDynawo.sh help

We advise you to deploy our autocompletion script to help you with the available commands, it will also set an alias (dynawo) in your bashrc or zshrc to be able to call Dynaωo from anywhere. You can launch one of the two following commands:

$> ./myEnvDynawo.sh deploy-autocompletion --deploy --shell-type bash
$> ./myEnvDynawo.sh deploy-autocompletion --deploy --shell-type zsh

Then you can launch:

$> dynawo help
$> dynawo jobs-with-curves examples/DynaWaltz/IEEE14/IEEE14_GeneratorDisconnections/IEEE14.jobs

Windows

Once you have build Dynaωo you can start launching a simulation with the command:

> cd ..\d-i
> dynawo jobs ..\dynawo\examples\DynaWaltz\IEEE14\IEEE14_GeneratorDisconnections\IEEE14.jobs
> dynawo jobs-with-curves ..\dynawo\examples\DynaWaltz\IEEE14\IEEE14_GeneratorDisconnections\IEEE14.jobs

You can set up the curves to open in your preferred browser with set DYNAWO_BROWSER=C:\Program Files (x86)\Mozilla Firefox\firefox.exe for example. Use also set DYNAWO_PYTHON_COMMAND=python3 for example to setup your python command.

Docker

We provide on Docker Hub an image of Dynaωo master. You can use it by launching the following command:

$> docker run -it dynawo/dynawo

You can have more information on how to use Docker to build and try Dynaωo here.

Dynaωo Documentation

You can download Dynaωo documentation here.

Get involved!

Dynaωo is an open-source project and as such, questions, discussions, contributions and feedbacks are very welcome. It is also an ongoing project and we are actively working on improving it and making it better so we encourage you to regularly check the project status and progresses.

Regarding contributions, the final details, methodology and testing procedures for accepting a contribution is still under discussion. Until it is defined, we recommend to proceed in the following way: first report the problem or explain the planned modifications in an e-mail to [email protected] in order to get a first feedback from us (we will check if efforts are already conducted on the topic on our side and if your proposition is in phase with the project evolution) and then submit a pull-request that will serve as the basis for final discussions and review.

Quoting Dynaωo

If you use Dynaωo in your work or research, it is not mandatory but we kindly ask you to quote the following paper in your publications or presentations:

A. Guironnet, M. Saugier, S. Petitrenaud, F. Xavier, and P. Panciatici, “Towards an Open-Source Solution using Modelica for Time-Domain Simulation of Power Systems,” 2018 IEEE PES Innovative Smart Grid Technologies Conference Europe (ISGT-Europe), Oct. 2018.

License

Dynaωo is licensed under the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, you can obtain one at http://mozilla.org/MPL/2.0. You can also see the LICENSE file for more information.

Dynaωo is using some external libraries to run simulations:

• OpenModelica, a Modelica environment developed and maintained by the Open Source Modelica Consortium distributed under a GPL V3.0 or OSMC Public License V1.2. The current version used is V1.13.2.
• SUNDIALS, a suite of solvers developed and maintained by the Lawrence Livermore National Lab and distributed under a BSD-3-Clause license. The 4.1.0 version is currently used.
• SuiteSparse, and in particular KLU, a LU decomposition library that is part of the suite sparse project, developed and maintained by T. A. Davis et al. at the University of Florida distributed under a LGPL-2.1+. The version 4.5.4 of suite sparse is the one used by Dynaωo.
• Adept, an automatic differentiation library that has been developed and maintained at the University of Reading by R.J. Hogan distributed under Apache-2.0. It is the version 2.0.5 that is integrated into Dynaωo.
• Xerces-C++ a validating XML parser written in a portable subset of C++ and distributed under the Apache Software License, Version 2.0. The current version used is 3.2.2.
• NICSLU which is another LU decomposition library. It is developed and maintained by Tsinghua University and is optional at the moment into Dynaωo. It is distributed under a GNU LGPL license.
• jQuery that is distributed into Dynaωo to display results into a minimalistic GUI after the simulation. The current version used is the 1.3.4 distributed under both a MIT and a GPL license.
• cpplint, a tool used during Dynaωo compilation process to ensure that the C++ files follow the Google's C++ style. It is distributed under a CC-By 3.0 License.

Maintainers

Dynaωo is currently maintained by the following people in RTE:

• Mathilde Bongrain, [email protected]
• Gautier Bureau, [email protected]
• Marco Chiaramello, [email protected]
• Quentin Cossart, [email protected]
• Adrien Guironnet, [email protected]
• Romain Losseau, [email protected]
• Florentine Rosiere, [email protected]
• Marianne Saugier, [email protected]

In case of questions or issues, you can also send an e-mail to [email protected].

Roadmap

Below are the major development axis identified for Dynaωo for the next few months, with associated contents and due date. It is important to notice that the development content and the due dates may be subject to change due to unforeseen complexity in implementing features or priority changes.

Axis 1 - Models development

• PV and Wind WECC model: under final validation and integration, September 2021
• HVDC standard model: expected September 2020: Available since V1.2.0
• Additional models for steady-state calculations (Static Var Compensator, voltage regulation, etc.): Available in the master
• Standard regulation models (governors, voltage regulators, power system stabilizers): under progress
• IEC 61400 Wind model: December 2021

Axis 2 - Test cases

• Adding large scale test cases (national and panEuropean ones): internally ready but postponed to December 2021 (anonymisation) for public availability
• New examples section: Available since V1.2.0.
• NordicTestSystem case: under validation for Dynaωo and delayed in Modelica (waiting for updates in OpenModelica), September 2021
• ENTSO-E controller test case: under validation for Dynaωo and Modelica, June 2021

Axis 3 - Dependencies, architecture and performances

• Switch to Sundials V5.0.0 and Suitesparse V5.3.0: Available in the master
• Switch to a newer IIDM library version: Available in the master
• Performances improvements: Available in the master
• Ancilarry services - contingency analysis and margin calculation: under progress, new repository dynawo-algorithms
• Dynaωo connectivity analysis improvement (system splitting): postponed 2021
• Symbolic Jacobian use for Modelica models: waiting for OpenModelica update

Links

For more information about Dynaωo:

• Consult Dynaωo website
• Contact us at [email protected]