/dynawo

This repository contains Dynaωo's simulation tool code.

Primary LanguageC++Mozilla Public License 2.0MPL-2.0

Dynaωo - An hybrid C++/Modelica time-domain simulation tool for power systems

Build Status Quality Gate Status Coverage MPL-2.0 License

http://dynawo.org

This repository contains Dynaωo's simulation tool code.

Table of Contents

About Dynaωo

Dynaωo is an open source time domain simulation tool for power systems using the Modelica language. It aims at providing power system stakeholders with a transparent, flexible, interoperable and robust simulation tool 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 simulation tool 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 time-domain 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 RMS simulations and most of the tests done until now have been for long-term and short-term stability studies. However, the simulation tool structure offers great flexibility and makes it also possible to run other types of power system simulations, as long as the user provides the necessary models and solvers. Different initiatives are under discussion or submission to test the possibility to use Dynaωo for EMT simulations or multi-system simulations. Only validated models are included into the library that is still under construction. We plan to be able to release a new set of models in the near future, with for example HVDC, wind and solar power plants models or more different standard regulation models, etc.

Dynaωo Distribution

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

Linux Requirements for Distribution

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

You can install the dependencies for Ubuntu or Fedora with:

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

MacOS Requirements for Distribution

  • Command Line Tools (with xcode-select --install)
  • CMake

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:

Using a distribution

Linux and MacOS

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 -d Dynawo_Linux_latest
$> Dynawo_Linux_latest/bin/execDynawo.sh jobs-with-curves Dynawo_Linux_latest/testcases/IEEE14/IEEE14_SyntaxExamples/IEEE14_ModelicaModel/IEEE14.jobs
$> Dynawo_Linux_latest/bin/execDynawo.sh help
$> Dynawo_Linux_latest/bin/execDynawo.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-file testcases\IEEE14\IEEE14_BasicTestCases\IEEE14_LoadVariation\IEEE14.jobs

Building requirements

You can also build Dynaωo from sources. Dynaωo is a cross-platform software and has been tested on Linux platforms (Centos and Debian based), for other distributions don't hesitate to contact us if you run in problems. It has also been tested on MacOS (only on Mojave), a complete procedure to help non-developers install it on this platform will be available soon. We recently added Windows compatibility and you can now completly build and develop Dynawo on it.
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.

Unix (Linux and MacOS)

Global

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

OpenModelica Compiler

Dynaωo user

  • CMake: minimum version 3.9.6 (last version to compile with c++98 compiler)
  • Python2
  • Python packages: lxml
  • Binary utilities: curl or wget, xmllint

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

Building Dynaωo

Linux

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

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

This one works 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=xdg-open

export DYNAWO_NB_PROCESSORS_USED=1

export DYNAWO_BUILD_TYPE=Release
export DYNAWO_CXX11_ENABLED=YES

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

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

MacOS

The difficult part of building Dynaωo on MacOS is the compilation of OpenModelica. We propose two solutions, one with pre-built binaries for OpenModelica and one with building OpenModelica.

With pre-built OpenModelica

Use the following commands in a terminal to download those binaries and use them to build Dynaωo:

$> curl -L $(curl -s -L -X GET https://api.github.com/repos/dynawo/dynawo/releases/latest | grep "Dynawo_MacOS" | grep url | cut -d '"' -f 4) -o $HOME/Dynawo_MacOS_latest.zip
$> unzip $HOME/Dynawo_MacOS_latest.zip -d $HOME/Dynawo_MacOS_latest
$> git clone https://github.com/dynawo/dynawo.git dynawo
$> cd dynawo
$> mkdir OpenModelica
$> mv $HOME/Dynawo_MacOS_latest/OpenModelica OpenModelica/Install
$> rm -rf $HOME/Dynawo_MacOS_latest*
$> 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="open -a Safari"
export DYNAWO_NB_PROCESSORS_USED=1

export DYNAWO_BUILD_TYPE=Release
export DYNAWO_CXX11_ENABLED=YES
export DYNAWO_COMPILER=CLANG

export PATH="$(dirname $(xcrun -f llvm-cov))":$PATH

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

With building OpenModelica

A solution has been develop but it is not yet available on Github and we advise you to contact us so we can provide you with it. This solution should be available soon once it is completely stable.

Launch Dynaωo

Linux and MacOS

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

$> ./myEnvDynawo.sh jobs-with-curves nrt/data/IEEE14/IEEE14_BasicTestCases/IEEE14_DisconnectLine/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 nrt/data/IEEE14/IEEE14_BasicTestCases/IEEE14_DisconnectLine/IEEE14.jobs

Windows

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

> cd ..\d-i
> dynawo --jobs-file ..\dynawo\nrt\data\IEEE14\IEEE14_BasicTestCases\IEEE14_DisconnectLine\IEEE14.jobs

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 rte-dynawo@rte-france.com 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:

In case of questions or issues, you can also send an e-mail to rte-dynawo@rte-france.com.

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 - Test cases and models development

  • Adding larger IEEE cases
  • Adding large scale test cases (national and panEuropean ones): postponed to February 2020
  • Adding new models (standard regulations for generators, static var compensator, etc.)
  • PV WECC model: under progress, expected December 2019
  • Nordic32 case: expected February 2020

Axis 2 - Dependencies upgrade and cross-platform deployment

  • Switch to OpenModelica V1.13 version and DAE mode use
  • Switch to SUNDIALS V4.0 version
  • Switch to a newer IIDM library version: postponed to June 2020
  • Mac portability
  • Windows portability: under progress
  • Switch to Modelica V3.2.3

Axis 3 - Dynaωo structure evolution

  • Performance improvement: under progress, expected December 2019
  • New initialization strategy: using Modelica initEquations section into Dynaωo: postponed
  • Dynaωo connectivity analysis improvement (system splitting): postponed December 2020

Links

For more information about Dynaωo: