DynawoDocumentation PDF

Dynaωo Documentation
January 31, 2019

Contents
List of Figures 5
1 Introduction 6
2 Install procedure 8
2.1 Building Dynaωo . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2 Launching Dynaωo . . . . . . . . . . . . . . . . . . . . . . . . 10
2.3 Third parties . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3 Configure Dynaωo 13
3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.1.1 Dynaωo inputs . . . . . . . . . . . . . . . . . . . . . . 14
3.1.2 Dynaωo outputs . . . . . . . . . . . . . . . . . . . . . . 15
3.2 Dynaωo input files . . . . . . . . . . . . . . . . . . . . . . . . 16
3.2.1 jobs file . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.2.2 iidm file . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.2.3 dyd file . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.2.4 par file . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3.2.5 crv file . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.3 Dynaωo input files modification . . . . . . . . . . . . . . . . . 21
3.3.1 jobs file . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.3.1.1 Simulate several scenarios . . . . . . . . . . . 21
3.3.1.2 Change the solver . . . . . . . . . . . . . . . 22
3.3.1.3 Specify stop conditions for the simulation . . 22
3.3.1.4 Specify what kind of models to use . . . . . . 23
3.3.1.5 Start a simulation from the end of another one 23
3.3.1.6 Run a simulation with no iidm file . . . . . . 23
3.3.1.7 Configure the jobs outputs . . . . . . . . . . . 24
3.3.2 dyd file . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.3.2.1 Use a black-box model . . . . . . . . . . . . . 26
3.3.2.2 Use a Modelica model from Dynaωo library . 26
1
3.3.2.3 Use a Modelica model not in Dynaωo Library 26
3.3.2.4 Assemble unit Modelica models in a macro
model . . . . . . . . . . . . . . . . . . . . . . 27
3.3.2.5 Use a template model . . . . . . . . . . . . . 27
3.3.2.6 Write connections . . . . . . . . . . . . . . . 28
3.3.2.7 Associate a dynamic model to a static com-
ponent . . . . . . . . . . . . . . . . . . . . . . 28
3.3.2.8 Define sets of connections . . . . . . . . . . . 29
3.3.2.9 Define sets of static references . . . . . . . . . 29
3.3.3 par file . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.3.3.1 Set a reference to a value stored in the iidm file 30
3.3.3.2 Enter a table of parameter . . . . . . . . . . . 30
3.3.4 crv file . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.3.4.1 Add a new curve to the curve file . . . . . . . 31
3.4 Basic errors in input files . . . . . . . . . . . . . . . . . . . . . 31
3.4.1 dyd file . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.4.1.1 Missing connection . . . . . . . . . . . . . . . 31
3.4.1.2 Invalid connection due to connector’s type . . 32
3.4.1.3 Invalid connection due to inconsistency . . . . 32
3.4.2 par file . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.4.2.1 Parameter not found . . . . . . . . . . . . . . 33
3.4.2.2 Wrong type of parameter . . . . . . . . . . . 33
3.4.3 crv file . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
3.4.3.1 Wrong variable name in crv file . . . . . . . . 34
4 Functional documentation 35
4.1 Dynaωo Overview . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.2 Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4.2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . 39
4.2.2 C++ library . . . . . . . . . . . . . . . . . . . . . . . . 41
4.2.2.1 Network model . . . . . . . . . . . . . . . . . 41
4.2.2.2 OmegaRef model . . . . . . . . . . . . . . . . 45
4.2.2.3 Variation area model . . . . . . . . . . . . . . 45
4.2.3 Modelica library . . . . . . . . . . . . . . . . . . . . . 46
4.2.3.1 Library content . . . . . . . . . . . . . . . . . 46
4.2.3.2 Preassembled models . . . . . . . . . . . . . . 48
4.3 Solvers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
4.3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . 49
4.3.1.1 Differential Algebraic Equations . . . . . . . . 49
4.3.1.2 System resolution . . . . . . . . . . . . . . . . 50
4.3.1.3 Prediction-Correction scheme . . . . . . . . . 51
2
4.3.1.4 Discrete event handling . . . . . . . . . . . . 51
4.3.1.5 Solvers in Dynaωo . . . . . . . . . . . . . . . 52
4.3.2 Simplified solver . . . . . . . . . . . . . . . . . . . . . . 53
4.3.2.1 Introduction . . . . . . . . . . . . . . . . . . 53
4.3.2.2 Prediction step . . . . . . . . . . . . . . . . . 54
4.3.2.3 Correction step . . . . . . . . . . . . . . . . . 54
4.3.2.4 Discontinuities handling . . . . . . . . . . . . 57
4.3.2.5 Time step management . . . . . . . . . . . . 57
4.3.2.6 Algebraic equations restoration . . . . . . . . 59
4.3.3 Variable time-step solver . . . . . . . . . . . . . . . . . 60
4.3.3.1 Introduction . . . . . . . . . . . . . . . . . . 60
4.3.3.2 Prediction step . . . . . . . . . . . . . . . . . 61
4.3.3.3 Correction step . . . . . . . . . . . . . . . . . 61
4.3.3.4 Events detection . . . . . . . . . . . . . . . . 62
4.3.3.5 Time-step and order management . . . . . . . 62
4.3.3.6 Algebraic equations restoration . . . . . . . . 63
5 Advanced documentation 64
5.1 Code organization . . . . . . . . . . . . . . . . . . . . . . . . . 65
5.2 Dynaωo executables . . . . . . . . . . . . . . . . . . . . . . . 66
5.2.1 Dynaωo commands . . . . . . . . . . . . . . . . . . . . 67
5.2.2 Compilation and simulation of a single Modelica model 67
5.2.3 Compilation and simulation of complex models . . . . 72
5.2.4 Generation of a xml summary of the parameters and
variables of a compiled model . . . . . . . . . . . . . . 78
5.3 Adding a model to the Dynaωo library . . . . . . . . . . . . . 79
5.3.1 Adding a Modelica model in the Dynaωo Modelica library 79
5.3.2 Adding a Modelica model in the Dynaωo precompiled
library . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
5.4 Adding a new solver . . . . . . . . . . . . . . . . . . . . . . . 85
Bibliography 87
Appendix A Dynaωo License 89
Appendix B Dynaωo Documentation License 99
Appendix C OpenModelica License 110
Appendix D SUNDIALS License 119
Appendix E SuiteSparse License 122
3
Appendix F Adept License 124
Appendix G NICSLU License 131
Appendix H jQuery MIT License 137
Appendix I jQuery GPL License 139
Appendix J ccplint License 148
4
List of Figures
1 Separation between modelling and solving parts in Dynaωo . . 6

2 Dynaωo scope in the range of dynamic phenomena . . . . . . 7
3 Dynaωo results on IEEE14_DisconnectLine case . . . . . . . . 11
4 Dynaωo input and output files . . . . . . . . . . . . . . . . . . 14
5 Separation between modelling and solving parts in Dynaωo . . 36

6 Building a global model from different unit models in Dynaωo 37
7 Exchange between the modelling and the solving parts in Dynaωo 38
8 π line model . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
9 Restorative load model . . . . . . . . . . . . . . . . . . . . . . 44
10 Static Var Compensator model . . . . . . . . . . . . . . . . . 45
11 Differences between solvers for a line disconnection . . . . . . 53
12 Simplified solver algorithm for one time step . . . . . . . . . . 58
5
1 Introduction
Dynaωo is an hybrid C++/Modelica open source time domain sim-

ulation tool for power systems. 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.
To achieve this goal, Dynaωo is based on two mains principles: the use
of a high-level modelling language Modelica and a strict separation between
the modelling and the solving parts.
It is an ongoing project based on previous works conducted particularly in

two R&D European projects: Pegase and iTesla. These projects have con-
tributed to the choices that are the basis upon which Dynaωo is built: they
proved the usability of the Modelica language for power system simulations
and contributed to the development of numerical resolution strategies that
are integrated into Dynaωo.
Figure 1: Separation between modelling and solving parts in Dynaωo
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 others types of power system simulations, as
6
long as the user provides the necessary models and solvers. Different initia-
tives are under discussion or submission to test the possibility to use Dynaωo
for EMT simulations or multi-system simulations.
Figure 2: Dynaωo scope in the range of dynamic phenomena
Only validated models are included into the library that is still
under construction. We plan to release a new set of models in the near
future, e.g. HVDC, wind and solar power plants models or more different
standard regulation models.
Dynaωo is licensed under the terms of the Mozilla Public License, v2.0. The
source code is hosted into a GitHub repository.
In the following sections of this document, the reader will find:
• Installation directions to be able to compile and use Dynaωo;
• Configuration directions to be able to create the needed input files in

order to simulate a given test case;
• Detailed information about the Dynaωo simulator, its architecture,

models and solvers;
• Advanced information on the code organization, the procedure to follow

to add a new model or a new solver into Dynaωo;
7
2 Install procedure
Contents
2.1 Building Dynaωo . . . . . . . . . . . . . . . . . . . 8
2.2 Launching Dynaωo . . . . . . . . . . . . . . . . . . 10
2.3 Third parties . . . . . . . . . . . . . . . . . . . . . 10
2.1 Building Dynaωo

For the moment Dynaωo has only be tested on Linux platforms (Centos
and Debian based) and provided that you can install system packages there
should be no problem on other Linux distribution. For MacOS and Windows
users a Docker solution will be provided in a near future. We also plan to
provide compliation compatibility for Windows.
Dynaωo and its dependencies will need some system packages to work. Here
is the list of all packages you can install to have no dependency problem in
the following steps.
Command 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
libxerces -c - 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
Command for Fedora:
$ > dnf install -y git gcc gcc - c ++ gcc - gfortran autoconf

automake make libtool cmake hwloc
8
java -1.8.0 - openjdk - devel blas - devel lapack - devel
lpsolve - devel expat - devel glibc - devel sqlite - devel
xerces -c - 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
To build Dynaωo you need to clone its repository and launch the following
commands in the source code directory:
$ > git clone https :// github . com / dynawo / dynawo . git dynawo
$ > cd dynawo
$ > echo '#!/ bin / bash
export DYNAWO_HOME = $ ( cd " $ ( dirname " $ { BASH_SOURCE [0]}") " &&
pwd )
export O P E N M O D E L I C A _ V E R S I O N =1 _9_4
export SRC_OPENMODELICA = $DYNAWO_HOME / OpenModelica / Source
export I N S T A L L _ O P E N M O D E L I C A = $DYNAWO_HOME / OpenModelica / Install
export DYNAWO_LOCALE = en_GB

export USE_ADEPT = YES
export RESULTS_SHOW = true
export BROWSER = xdg - open
export NB_ PR OC ES SO RS _U SE D = $ (( $ ( nproc -- all ) / 2) )
export BUILD_TYPE = Release

export CXX11_ENABLED = YES
$DYNAWO_HOME / util / envDynawo . sh $@ ' > myEnvDynawo . sh

$ > chmod + x myEnvDynawo . sh
$ > ./ myEnvDynawo . sh build - omcDynawo
$ > ./ myEnvDynawo . sh build - all
Below is a description of some environment variables that might be changed

in the file myEnvDynawo.sh:
BROWSER Default browser command

NB_PROCESSORS_USED Maximum number of cores to use
BUILD_TYPE Build type : Release or Debug
Warning: If you’re working behind a proxy make sure you have exported
the following proxy environement variables:
$ > export http_proxy =
9
$ > export https_proxy =
$ > 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 ;
2.2 Launching Dynaωo

Once you have installed and compiled Dynaωo as explained in part ??, you
can launch a simulation by calling:
$ > ./ myEnvDynawo . sh jobs

nrt / data / IEEE / I E E E 1 4 _ B l a c k B o x M o d e l s / IEEE14 . jobs
This command launches a simple simulation on the IEEE 14-bus network that
should succeed if your installation went well and your compilation finished
successfully.
The correctness of the simulation can be checked by looking into the outputs
directory and compare its content with the ones from the reference outputs
directory (especially the curves file).
$ > cd nrt / data / IEEE / I E E E 1 4 _ B l a c k B o x M o d e l s

$ > ls outputs
$ > diff outputs / curves / curves . csv
reference / outputs / curves / curves . csv
All the simulation outputs are stored into the outputs directory, as specified
in the jobs file.
It is also possible to display directly simulation results - plots - into a simple

GUI (created for demonstration purpose) by using for example the following
command:
$ > ./ myEnvDynawo . sh jobs - with - curves

nrt / data / IEEE / I E E E 1 4 _ D i s c o n n e c t L i n e / IEEE14 . jobs
For example, for this line disconnection simulation, the plot for the voltage
module in p.u. on bus 10 should look like this:
2.3 Third parties

To run a simulation, Dynaωo uses several external libraries that are down-
loaded and compiled during the building process:
10
Figure 3: Dynaωo results on IEEE14_DisconnectLine case
• OpenModelica [7], a Modelica [1] environment developed and main-

tained by the Open Source Modelica Consortium distributed under a
GPL V3.0 or OSMC Public License V1.2. Dynaωo is currently using
the version 1.9.4 of the OpenModelica compiler to compile Modelica
models either at run-time or beforehand during the compilation pro-
cess. OpenModelica compiler source code is modified to match spe-
cific needs from Dynaωo; these modifications are available in dynawo/
3rdParty/omcUpdate_1_9_4.
• SUNDIALS [11], a suite of solvers developed and maintained by the

Lawrence Livermore National Lab distributed under a BSD-3-Clause
license.
Dynaωo is currently using the version 2.7.0 from SUNDIALS. Small
modifications on the library are applied to fit Dynaωo’s needs and
are available in dynawo/3rdParty/sundials. In particular, KINSOL
and IDA from the SUNDIALS library are called to solve the Algebraic
Equations and Differential Algebraic Equations systems arising during
the simulation.
• SuiteSparse, a suite of sparse matrix algorithms and in particular KLU

[4], a LU decomposition library that is developed and maintained by
T. A. Davis et al. at the University of Florida. Dynaωo currently uses
the V 4.5.4 version of the suite sparse library that is distributed under
a LGPL-2.1+ license. KLU is used inside KINSOL and IDA to make
the LU decomposition required during Newton-Raphson resolutions.
11
• Adept [13] [12], an automatic differentiation library that is developed
and maintained at the University of Reading by R.J. Hogan. The 1.1
version is currently employed into Dynaωo to evaluate the Jacobian
matrices for Modelica models during the simulation and distributed
under both Apache-2.0, GPL-2.0 and MIT licenses.
• NICSLU [2] which is another LU decomposition library. It is developed

and maintained by Tsinghua University and is optional at the moment
into Dynaωo.If downloaded by the user, it could be used for LU decom-
position in a similar way than KLU. This library is distributed under
GNU LGPL license for open-source projects.
In addition to these libraries needed for the simulation process, Dynaωo

downloads the code for two other libraries:
• jQuery is used to provide a minimalistic GUI with Dynaωo that enables

to visualize the results into a browser. jQuery is distributed under both
a MIT and GPL license.
• cpplint, a tool used during Dynaωo compilation process to ensure that

the C++ files follow the Google's C++ style.
Finally, Dynaωo also uses a large number of other system libraries for its
compilation process, the unit testing process or to build its source documen-
tation. These libraries must be installed by the developer before compiling
Dynaωo and the complete list is given in 2.1.
12
3 Configure Dynaωo
Contents
3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . 13
3.1.1 Dynaωo inputs . . . . . . . . . . . . . . . . . . . . 14
3.1.2 Dynaωo outputs . . . . . . . . . . . . . . . . . . . 15
3.2 Dynaωo input files . . . . . . . . . . . . . . . . . . 16
3.2.1 jobs file . . . . . . . . . . . . . . . . . . . . . . . . 16
3.2.2 iidm file . . . . . . . . . . . . . . . . . . . . . . . . 17
3.2.3 dyd file . . . . . . . . . . . . . . . . . . . . . . . . 19
3.2.4 par file . . . . . . . . . . . . . . . . . . . . . . . . . 20
3.2.5 crv file . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.3 Dynaωo input files modification . . . . . . . . . . 21
3.3.1 jobs file . . . . . . . . . . . . . . . . . . . . . . . . 21
3.3.2 dyd file . . . . . . . . . . . . . . . . . . . . . . . . 25
3.3.3 par file . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.3.4 crv file . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.4 Basic errors in input files . . . . . . . . . . . . . . 31
3.4.1 dyd file . . . . . . . . . . . . . . . . . . . . . . . . 31
3.4.2 par file . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.4.3 crv file . . . . . . . . . . . . . . . . . . . . . . . . . 34
3.1 Overview
The following section will provide information on:
• How to create the input files in order to simulate a given test case;
13
• How to configure the input files in order to get the necessary output
files to analyse the obtained results;
The list of input files and the most important output files are summarized
in the figure below:
Figure 4: Dynaωo input and output files
3.1.1 Dynaωo inputs

To run a simulation, Dynaωo needs most of the time five input files:
• A file providing the simulation settings: the jobs file (.jobs extension);
• A file providing the static description of the test grid to simulate: the
iidm file (.iidm extension);
• A file providing the dynamic description of the test grid to simulate:

the dynamic data file (.dyd extension);
• A file providing the needed parameters of the simulation: the parameter

file (.par extension);
• A file providing the list of the variables to plot at the end of the simu-
lation: the curves file (.crv extension);
The crv file is optional: with no crv file, no curves will be available at the end
of the simulation but the simulation can be run anyway. The iidm file can
also be optional for small test cases where the whole system is represented
in the dyd file (see paragraph 3.3.1.6). Other files are mandatory.
All jobs, iidm, dyd, par and crv files are XML files. Their extension can also
be .xml. For each file, there is an associated xsd file used to validate the xml
14
file and to check that it respects a certain format. The xsd file defines which
elements and attributes are permitted and in which order. In that sense, they
can help the user write or modify one or several input files. The different xsd
files are to be found in the install directory in dynawo/share/xsd.
• jobs.xsd for the jobs file;
• dyd.xsd for the dyd file;
• parameters.xsd for the par file;
• curvesInput.xsd for the crv file;
The iidm.xsd is directly located in the install directory of the IIDM library
and can be found in share/iidm/xsd.
3.1.2 Dynaωo outputs

After a simulation that went well, Dynaωo generates the following output
files:
• A file providing the chronological list of events that happened during

the simulation: component connection, disconnection, automata acti-
vation, etc (timeline.txt).
• A file providing the list of constraints that happened in the network

during the simulation (constraints.txt);
• A file providing the static state of the network at the end of the simula-
tion (output.iidm). This iidm file can be used to start another dynamic
simulation;
• A file providing the value of the desired variables at each time step in
order to visualize their evolution through time (curves.crv);
• A file providing information about how the simulation went (dynamo.log).

This log file contains error messages if the simulation crashed;
• Files providing the variables values after initialization for each model.
The values can be printed after local (or individual model) initialization
or global (or system) initialization.
The input jobs file should be configured properly in order to give access to
all these outputs (see paragraph 3.3.1.7).
15
3.2 Dynaωo input files
The following sections get into more details regarding the five input files and
give some examples based on the non regression test IEEE14 present in the
Dynaωo repository.
Warning: the following example files are extracted from IEEE14 case in
Dynaωo and might not be complete, hence not work as they are presented
here.
3.2.1 jobs file

The jobs file gathers information about the solver to use, the models to use,
the simulation characteristics and the outputs wanted.
Here is an example on a jobs file:
jobs file example

1 <? xml version = '1.0 ' encoding = ' UTF -8 ' ? >
2 < dyn : jobs xmlns : dyn = " http :// www . rte - france . com / dynawo " >
3 < dyn : job name = " IEEE14 test case " >
4 < dyn : solver lib = " l ib d y na w o _S o l ve r S I M . so "
parFile = " solvers . par " parId = " 1 " / >
5 < dyn : modeler compileDir = " outputs / compilation " >
6 < dyn : network iidmFile = " IEEE14 . iidm "
parFile = " IEEE14 . par " parId = " 18 " / >
7 < dyn : dynModels dydFile = " IEEE14 . dyd " / >
8 < dyn : pr ecompi ledMod els u seStan dardMo dels = " true " / >
9 < dyn : modelicaModels us eStan dardMo dels = " true " / >
10 </ dyn : modeler >
11 < dyn : simulation startTime = " 0 " stopTime = " 100 "
activateCriteria = " false " / >
12 < dyn : outputs directory = " outputs " >
13 < dyn : curves inputFile = " IEEE14 . crv " exportMode = " CSV " / >
14 < dyn : timeline exportMode = " TXT " / >
15 < dyn : logs >
16 < dyn : appender tag = " " file = " dynawo . log "
lvlFilter = " DEBUG " / >
17 </ dyn : logs >
18 </ dyn : outputs >
19 </ dyn : job >
20 </ dyn : jobs >
In this example, we want to simulate a 100 second scenario on IIDM net-

work IEEE14.iidm described by dynamic models included in IEEE14.dyd.
The models compiled by Dynaωo will be exported in outputs/compilation
16
directory. Network parameters are stored in IEEE14.par file, set 18.
The solver used is the simplified solver, and its parameters are described in
solvers.par file, set 1.
At the end of the simulation, the user will have the possibility to plot the
different variables listed in IEEE14.crv, thanks to a csv file generated by
Dynaωo in outputs/curves directory.
The chronology of events that happened during the simulation will also be
available in a text file in outputs/timeline directory.
Absolute and relative paths can be used and mixed in a single jobs file.
Relative paths refer to the directory where the jobs file is located.
3.2.2 iidm file

The iidm file represents the network to simulate with a static representation:
it lists all the components present in the network and how they are connected.
Basically, the iidm file is composed of:
• the substations, which contain one or more voltage levels, which them-
selves contain buses, loads, generators, etc;
• the branches (lines and transformers) that connect buses defined in the
voltage levels;
Here is an example of an iidm file (extraction from IEEE14.iidm):
iidm file example

1 <? xml version ="1.0" encoding =" UTF -8" ? >
2 < iidm : network
xmlns : iidm = " http :// www . itesla_project . eu / schema / iidm /1 _0 "
id = " ieee14bus " caseDate = " 2017 -06 -09 T10 :14:24.146+02:00 "
forecastDistance = " 0 " sourceFormat = " CIM1 " >
3 < iidm : substation id = " _BUS___10_SS " name = " BUS 10 _SS "
country = " AF " geographicalTags = " _SGR_01 " >
4 < iidm : voltageLevel id = " _BUS___10_VL " name = " BUS
10 _VL " nominalV = " 13.8 " topologyKind = " BUS_BREAKER " >
5 < iidm : busBreakerTopology >
6 < iidm : bus id = " _BUS___10_TN " v = " 14.524137 "
angle = " -15.113294 " / >
7 </ iidm : busBreakerTopology >
17
8 < iidm : load id = " _LOAD__10_EC " name = " LOAD 10 "
loadType = " UNDEFINED " p0 = " 9.0 " q0 = " 5.8 "
bus = " _BUS___10_TN "
connectableBus = " _BUS___10_TN " p = " 9.0 "
q = " 5.8 " / >
9 </ iidm : voltageLevel >
10 </ iidm : substation >
11 < iidm : substation id = " _BUS___11_SS " name = " BUS 11 _SS "
country = " AF " geographicalTags = " _SGR_01 " >
12 < iidm : voltageLevel id = " _BUS___11_VL " name = " BUS
11 _VL " nominalV = " 13.8 " topologyKind = " BUS_BREAKER " >
13 < iidm : busBreakerTopology >
14 < iidm : bus id = " _BUS___11_TN " v = " 14.5959015 "
angle = " -14.809061 " / >
15 </ iidm : busBreakerTopology >
16 < iidm : load id = " _LOAD__11_EC " name = " LOAD 11 "
loadType = " UNDEFINED " p0 = " 3.5 " q0 = " 1.8 "
bus = " _BUS___11_TN "
connectableBus = " _BUS___11_TN " p = " 3.5 "
q = " 1.8 " / >
17 </ iidm : voltageLevel >
18 </ iidm : substation >
19 < iidm : line id = " _BUS___10 - BUS___11 -1 _AC " name = " BUS
10 - BUS 11 -1 " r = " 0.156256 " x = " 0.365778 " g1 = " 0.0 "
b1 = " 0.0 " g2 = " 0.0 " b2 = " 0.0 " bus1 = " _BUS___10_TN "
connectableBus1 = " _BUS___10_TN "
voltageLevelId1 = " _BUS___10_VL " bus2 = " _BUS___11_TN "
connectableBus2 = " _BUS___11_TN "
voltageLevelId2 = " _BUS___11_VL " p1 = " -3.628976 "
q1 = " -1.291152 " p2 = " 3.639966 " q2 = " 1.316878 " >
20 < iidm : currentLimits1 permanentLimit = " 4183.7 " / >
21 </ iidm : line >
22 </ iidm : network >
In this example, the network is composed of only two voltage levels connected
through one line.
The first voltage level (_BUS___10_VL) has one bus (_BUS___10_TN)

and one load (_LOAD__10_EC). The second voltage level (_BUS___11_VL)
has also one bus (_BUS___11_TN) and one load (_LOAD__11_EC).
The line connects the bus _BUS___10_TN of voltage level _BUS___10_VL

and the bus _BUS___11_TN of the voltage level _BUS___11_VL.
iidm files are very dense and can be very large in case of large systems because
they provide a lot of information:
18
• the static parameters with their values. For example, for the line
the static parameters are: the resistance (R), the reactance (X), the
conductances on both sides (G1, G2) and the susceptances on both
sides (B1, B2). They are used by Dynaωo to build the network model.
• the load flow outputs obtained thanks to another simulation module:

the voltages amplitude and angle at each bus (V, θ) and the active and
reactive power at each injection point: (P, Q) for the load in this ex-
ample. They are used by Dynaωo to initialize the dynamic simulation.
• the network topology in the initial situation. We have seen in our ex-
ample that we have information about the connection between different
voltage levels through a line.
3.2.3 dyd file

The dyd file gathers the dynamics models to use with their characteristics
and if needed, their connections.
Here is an example of a dyd file (extraction from IEEE14.dyd):
dyd file example

2 < dyn : d y n a m i c M o d e l s A r c h i t e c t u r e
xmlns : dyn = " http :// www . rte - france . com / dynawo " >
3 < dyn : blackBoxModel id = " _LOAD__10_EC "
lib = " LOAD_ALPHA_BETA . so " parFile = " IEEE14 . par " parId = " 7 "
staticId = " _LOAD__10_EC " / >
4 < dyn : blackBoxModel id = " _LOAD__11_EC "
lib = " LOAD_ALPHA_BETA . so " parFile = " IEEE14 . par " parId = " 8 "
staticId = " _LOAD__11_EC " / >
5 < dyn : connect id1 = " _LOAD__10_EC " var1 = " LOAD_terminal "
id2 = " NETWORK " var2 = " _B US __ _1 0_ TN _A CP IN " / >
6 < dyn : connect id1 = " _LOAD__11_EC " var1 = " LOAD_terminal "
id2 = " NETWORK " var2 = " _B US __ _1 1_ TN _A CP IN " / >
7 </ dyn : dynamicModelsArchitecture >
In this example, we have two dynamic models: load _LOAD__10_EC and

load _LOAD__11_EC.
The connections between these models are written at the end of the file: the
load output terminal is connected to the pin of a bus given in the iidm file.
The connections between the dynamics models are provided with the key-
19
word “connect”.
Here the load models are precompiled black-box models but the dyd file can
use other kind of models such as macro Modelica models assembling different
unit Modelica models, or template models. See following sections for more
information about the different types of models supported by the dyd file.
In most cases, the iidm file provides information about the network topology
and the static parameters, and the dyd file provides information about the
dynamic behaviour of components given in the iidm file.
When a static component has no equivalent in the dyd file, Dynaωo uses a
default C++ model for the component. This is often the case for the lines
for example. It can also be the case for any other component, but the reader
should keep in mind that the default C++ models are basic and simple
models. In order to obtain accurate and detailed results from a dynamic
simulation, it is important to use accurate and detailed models.
3.2.4 par file

The par file contains all the parameters for the simulation: the solver pa-
rameters and the dynamic models’ parameters. All these parameters are
gathered in sets.
Here is an example of a par file (extraction from IEEE14.par):
par file example

2 < parametersSet xmlns = " http :// www . rte - france . com / dynawo " >
3 < set id = " 7 " >
4 < par type = " DOUBLE " name = " LOAD_alpha " value = " 1.5 " / >
5 < par type = " DOUBLE " name = " LOAD_beta " value = " 2.5 " / >
6 < reference type = " DOUBLE " name = " LOAD_P0Pu "
origData = " IIDM " origName = " p_pu " / >
7 < reference type = " DOUBLE " name = " LOAD_Q0Pu "
origData = " IIDM " origName = " q_pu " / >
8 < reference type = " DOUBLE " name = " LOAD_U0Pu "
origData = " IIDM " origName = " v_pu " / >
9 < reference type = " DOUBLE " name = " LOAD_UPhase0 "
origData = " IIDM " origName = " angle_pu " / >
10 </ set >
11 </ parametersSet >
20
For each parameter, the user should give the name, the type (DOUBLE,
INT, BOOL or STRING) and the value of the parameter.
Sometimes, the par file contains references to parameters present in the iidm
file (see paragraph 3.3.3.1).
3.2.5 crv file

The curves file lists all variables or parameters to plot.
Here is an example of a crv file (extraction from IEEE14.crv):
crv file example

2 < curvesInput xmlns = " http :// www . rte - france . com / dynawo " >
3 <! - - Curves for scenario -->
4 < curve model = " NETWORK " variable = " _ B U S _ _ _ 1 0 _ T N _ U p u _ v a l u e " / >
5 < curve model = " NETWORK " variable = " _ B U S _ _ _ 1 1 _ T N _ U p u _ v a l u e " / >
6 </ curvesInput >
In this example, the curves available are the voltage amplitudes of buses
_BUS___10_TN and _BUS___10_TN in per unit.
3.3 Dynaωo input files modification

Dynaωo input files (jobs, iidm, dyd, par and crv) have been briefly described
in the previous section. This section aims at giving more details on each file
in order to help the user parametrize its inputs easily and autonomously.
3.3.1 jobs file

3.3.1.1 Simulate several scenarios
A jobs file can contain several jobs. For each job, the description is the same
as illustrated in the previous section. The different jobs can be listed in the
jobs file as in the example bellow:
1 < jobs xmlns = " http :// www . rte - france . com / dynawo " >
2 < job name = " MyFirstJOB " >
3 ...
4 </ job >
5 < job name = " MySecondJOB " >
6 ...
21
7 </ job >
8 </ jobs >
3.3.1.2 Change the solver

The jobs file specifies the solver library to use for the simulation. In Dynaωo
two solvers are available:
• the simplified solver (fixed time step solver): library libdynawo_SolverSIM.so;
• the IDA solver (variable time step solver): library libdynawo_SolverIDA.so;
For IDA solver, IDA order 1 and IDA order 2 can be used (fill the value for
the parameter “order” in the par file).
1 < job name = " MyJOB " >

2 < solver lib = " l ib d y na w o _S o l ve r I DA . so " parFile = " MyPAR . xml "
parId = " 0 " / >
3 ...
4 </ job >
The solver library is stored in the install directory in dynawo/lib.
3.3.1.3 Specify stop conditions for the simulation

The jobs file specifies the following simulation settings:
• the start time of the simulation;
• the stop time of the simulation;
• whether to activate criteria or not;
When criteria are not activated, simulation will stop at the stop time given
by the user. When criteria are activated, the simulation could stop before
the stop time if a criteria is not respected. The most commonly used criteria
is “U < 0.8 ∗ U N om”;

2 ...
3 < simulation startTime = " 0 " stopTime = " 100 "
activateCriteria = " true " / >
4 ...
5 </ job >
22
3.3.1.4 Specify what kind of models to use
Dynamic models used by Dynaωo are either precompiled models or Modelica
models. The user should specify which kind of models he wants to use (he
can use both). These items may have an additional “directory” attribute
with the path to case-specific models.

2 ...
3 < modeler compileDir = " outputs / compilation " >
4 ...
5 < pr ecompi ledMod els us eStan dardMo dels = " true " / >
6 < modelicaModels directory = " MyDirectory "
useS tanda rdMode ls = " true " / >
7 </ modeler >
8 ...
9 </ job >
3.3.1.5 Start a simulation from the end of another one

In order to start a simulation from the end of another simulation, the item
“initialState” should be added in the modeler section of the job file. The
name of the dumpFile should be specified. This binary file contains the values
of all variables and their derivatives at the end of the previous simulation
and is needed to initialize the new simulation at the same operating point
that the end of the previous simulation. To obtain this file, use the finalState
item of the outputs section (see paragraph 3.3.1.7).

2 ...
3 < modeler compileDir = " outputs / compilation " >
4 < dynModels dydFile = " MyDyd . dyd " / >
5 < initialState file = " dumpFile " / >
6 ...
7 </ modeler >
8 ...
9 </ job >
3.3.1.6 Run a simulation with no iidm file

It is not mandatory to provide the jobs file with an iidm file as long as the
whole system is described in the dyd file. We use this technique for small
test cases such as unitary test cases with a few number of components. In
that case, all models are listed in the dyd file, as well as all connections.
23
Static components and topology normally defined in the iidm file should
consequently be defined in the dyd file (buses, lines, etc).
3.3.1.7 Configure the jobs outputs

The user can specify in the jobs file what outputs he wants to get from the
simulation. The outputs are to be found in the jobs file directory or in a
user-chosen directory when the attribute “directory” is provided:
< outputs directory = " outputs / " >
Several outputs are available with Dynaωo:
• Initialization: the user can have access to the results of the initializa-
tion stages (local and/or global) by adding the item “dumpInitValues”
in the jobs file.
< dumpInitValues local = " true " global = " true " / >
• Constraints: the user can have access to the list of constraints that
happened during the simulation by adding the item “constraints” in
the jobs file, and by specifying the export mode.
< constraints exportMode = " TXT " / >
Two export modes are available for constraints: TXT or XML.
• Timeline: the user can have access to the list of events that happened
during the simulation and the instant of their occurrence by adding the
item “timeline” in the jobs file, and by specifying the export mode.
< timeline exportMode = " TXT " / >
Three export modes are available for the timeline: TXT, XML or CSV.
• Final state: the user can have access to the final state of the simulation
thanks to two files: the iidm file and the dump file. The user can specify
which of those he wants to obtain. The iidm output file contains the
static data of the network at the end of the simulation. The dump
file is a binary file that contains the value of all dynamic variables and
derivatives at the end of the simulation and that enables to restart
another simulation from this operating point.
< finalState exportIIDMFile = " true " exportDumpFile = " true " / >
24
• Curves: the user can plot curves at the end of the simulation. To
do so, he should specify the name of the file containing the list of the
variables to be plotted and the export mode.
< curves inputFile = " MyCurves . crv " exportMode = " CSV " / >
Two export modes are available for curves export: CSV or XML.
• Logs: the user can have access to different log files that give informa-
tion about the execution of the compilation and the simulation, and
that could help him in case of failure. The main log file corresponds to
the appender with no tag named “dynawo.log” in the example below.
1 < logs >

2 < appender tag = " " file = " dynawo . log " lvlFilter = " DEBUG " / >
3 < appender tag = " NETWORK " file = " network . log "
4 < appender tag = " MODELER " file = " modeler . log "
5 < appender tag = " COMPILE " file = " compile . log "
6 < appender tag = " PARAMETERS " file = " param . log "
7 < appender tag = " VARIABLES " file = " variables . log "
8 < appender tag = " EQUATIONS " file = " equations . log "
9 </ logs >
For each “appender”, a format could be configured to set how the log
should be printed. By default, the format of the “appender” is the
following:
%Y -% m -% d % H :% M :% S | < lvlFilter > | log
where “lvlFilter” is used to filter the trace exported by giving the min-
imum level exported. For example, if a level filter of “WARN” is set,
only logs declared as “WARN” or “ERROR” will be exported.
The available filters are: DEBUG, INFO, WARN, ERROR.
3.3.2 dyd file

Different types of dynamic models can be used by Dynaωo and specified in
the dyd file:
25
• Black-box models;
• Modelica models;
• Template models;
The following subsections explain how to use these models and how to write
the dyd file in the different cases.
3.3.2.1 Use a black-box model

Black box models are precompiled black-box libraries. In order to use a black
box model, the user should specify the model library, the associated par file
and the parameters’ set.
< blackBoxModel id = " Model " lib = " MODEL_LIB . so "

parFile = " MyPar . par " parId = " 5 " >
The models libraries are stored in the install directory in dynawo/ddb.
3.3.2.2 Use a Modelica model from Dynaωo library

Several Modelica models are included in the Dynaωo Modelica library. Most
of the time, the Modelica models used by the dynamic simulation are present
in this library. To use one of these models, the user should specify the name
of the dynamic and the init models in the Modelica library, the associated
par file and the parameters’ set.
1 < modelicaModel id = " MacroModel " >

2 < unitDynamicModel id = " Model1 " name = " Model1 "
initName = " Model1_INIT " parFile = " MyPar . par " parId = " 2 " / >
3 </ modelicaModel >
The name of the model should include the whole path through the library,
for example for a transformer: Dynawo.Electrical.Branches.Transformer.
3.3.2.3 Use a Modelica model not in Dynaωo Library

To use a Modelica model that is not in the library, the user should provide
the path to the dynamic and the init models to use. To do so, two attributes
should be added to the “unitDynamicModel” item: “moFile” and “initFile”.
26
2 < unitDynamicModel id = " MyModel " name = " MyModel "
moFile = " myDirectory / MyModel . mo "
initFile = " myDirectory / MyModel_INIT . mo "
parFile = " MyPar . par " parId = " 1 " / >
3.3.2.4 Assemble unit Modelica models in a macro model

In the dyd file, several “unitDynamicModel” can be assembled to build a
macro model. To define a macro model, the user should list in the “modeli-
caModel” section the different “unitDynamicModel” present and their con-
nections. The connections between the dynamic models are provided with
the keyword “connect”, and the connections between the initialization models
are provided with the keyword “initConnect"".

4 < connect id1 = " Model1 " var1 = " var1 " id2 = " Model2 "
var2 = " var1 " / >
5 < initConnect id1 = " Model1 " var1 = " var1 " id2 = " Model2 "
var2 = " var1 " / >
We use this technique for example to assemble the physical model of a gen-
erator with the models of its regulations: the result is a macro model of a
generator with its controllers.
3.3.2.5 Use a template model

Template model enables the user to define a macro model thanks to unit
Modelica models (see section "How to assemble unit Modelica models in a
macro model").
1 < modelTemplate id = " Template " >

2 <! - - insert here any unitDynamicModel , connect ,
initConnect ... -->
The template is instantiated as:
< m o d e l T e m p l a t e E x p a n s i o n id = " TemplateModel "

templateId = " Template " parFile = " MyPar . par " parId = " 6 " >
27
3.3.2.6 Write connections
The connections between the dynamics models are provided with the key-
word “connect”, and the connections between the initialization models are
provided with the keyword “initConnect”.
1 < connect id1 = " id1 " var1 = " var1 " id2 = " id2 " var2 = " var1 " / >
2 < initConnect id1 = " id1 " var1 = " var1 " id2 = " id2 " var2 = " var1 " / >
Here are a few rules to follow to write models connections:
• When connecting to the AC network (C++ model), the id to use is

“NETWORK”;
• For connections between precompiled models, id1 and id2 refer to the
models id and var1 and var2 are simply the variables name;
• For connections between unit Modelica models in a macro model, id1

and id2 refer to the unit models id and var1 and var2 are simply the
variables name;
• For connections between macro Modelica models, id1 and id2 refer to
the macro models id and var1 and var2 should be built as:
unitModelId_VariableNameInModel;
3.3.2.7 Associate a dynamic model to a static component

When an iidm file is used, a correspondence between the component in the
iidm file and its dynamic equivalent in the dyd file is made thanks to the
item “staticId”.
1 < modelicaModel id = " MyModel " staticId = " MyModelIIDMId " >
2 ...
3 < staticRef var = " DynVarName " staticVar = " StaticVarName " / >
Static references may be defined in order to describe which dynamic variables

may be used to update the iidm output file. Static references are often defined
for active and reactive power. Here is an example:
1 < modelicaModel id = " MyGenerator " staticId = " M yGene ratorI IDMId " >
2 ...
3 < staticRef var = " P_value " staticVar = " p " / >
4 < staticRef var = " Q_value " staticVar = " q " / >
5 < staticRef var = " state " staticVar = " state " / >
28
If no static references are done, the simulation will proceed but Dynaωo will
not be able to output an iidm file.
3.3.2.8 Define sets of connections

The connection between two different dynamic models in the dyd file often
needs more than one “connect” statement. For example, in order to con-
nect the reference frequency model to a generator model we need to connect
three variables: omega, omegaRef, running. In order not to write the three
connections for each generator model of the network, we can define a macro
connection in the dyd file:
1 < macroConnector id = " M 1 S _ O M E G A R E F _ C O N N E C T O R " >

2 < connect var1 = " om ega_gr p_@IN DEX@ " var2 = " M1S_omega " / >
3 < connect var1 = " r un n i ng _ g rp _ @ IN D E X@ " var2 = " M1S_running " / >
4 < connect var1 = " o m e g a R e f _ g r p _ @ I N D E X @ " var2 = " M1S_omegaRef " / >
5 </ macroConnector >
And then we can use this macro connection as many time as needed with the
keyword “macroConnect”:
1 < macroConnect connector = " M 1 S _ O M E G A R E F _ C O N N E C T O R "

id1 = " MODEL_OMEGA_REF " index1 = " 0 " id2 = " Generator0 " / >
A macro connection can also contain an “initConnect” statement.
3.3.2.9 Define sets of static references

For each dynamic model, we often need more than one “staticRef” statement
to describe the link between the dynamic model and the static equivalent.
For example, for the generator, we need to define three static references:
active power, reactive power and connection state. In order not to write the
three static references for each generator model of the network, we can define
a macro static reference in the dyd file:
1 < m a c r o S t a t i c R e f e r e n c e id = " GEN " >

2 < staticRef var = " P_value " staticVar = " p " / >
3 < staticRef var = " Q_value " staticVar = " q " / >
4 < staticRef var = " state " staticVar = " state " / >
5 </ macroStaticReference >
29
And then we can use this macro static reference as many time as needed with
the keyword “macroStaticRef”:
1 < modelicaModel id = " MyGenerator " staticId = " M yGene ratorI IDMId " >
2 ...
3 < macroStaticRef id = " GEN " / >
3.3.3 par file

3.3.3.1 Set a reference to a value stored in the iidm file
If the parameter’s value is stored in the iidm file, a reference to this value
can be added in the par file as in the example bellow:
1 <set >
2 < par type = " ParType " name = " ParName " value = " ParValue " / >
3 ...
4 < reference type = " RefType " name = " RefName " origData = " IIDM "
origName = " NameIIDM "
componentId = " M o d e l _ i d _ i n _ i i d m _ F i l e " / >
5 </ set >
When no componentId is given, it is assumed that the data is linked with

the static component which id is given by the staticId defined in the dyd file.
3.3.3.2 Enter a table of parameter

There is a special way of writing tables of parameters in the par file. To do
so use a “parTable” item as in the example bellow.
1 <set >
2 < parTable type = " DOUBLE " name = " MyTable " >
3 < par row = " 1 " column = " 1 " value = " 0.1 " / >
6 < par row = " 2 " column = " 2 " value = " 0 " / >
7 </ parTable >
8 ...
9 </ set >
30
3.3.4 crv file
3.3.4.1 Add a new curve to the curve file
To add a new curve to the crv file, the following line should be added in the
crv file:
< curve model = " ModelId " variable = " var " / >
Here are a few rules to follow to write models variables names:

• For precompiled models, ModelId refers to the model id and var is
simply the variable name;
• For Modelica models, ModelId refers to the macro model id and var
should be built as:
unitModelId_VariableNameInModel;
3.4 Basic errors in input files

While trying to create its own input files, the user might encounter some er-
ror messages. This section provides basic explanations for the most common
error messages related to the input files.
These error messages can be found in the dynawo.log file in the outputs
directory specified in the jobs file, usually named “outputs”.
3.4.1 dyd file

3.4.1.1 Missing connection
To be able to compile a Modelica model, Dynaωo needs it to be square,
i.e to have equal numbers of equations and variables. If it is not the case,
Dynaωo should return the following message in dynawo.log: “missing con-
nection for one/several external variable(s)” and provide the corresponding
variables when in DEBUG mode. Typically, this situation can happen if one
forgot to set a connect within a Modelica model in the .dyd file.
For example, if the user forgets to set the connection of Generator_omegaRefPu,

he might get the following error message:
31
1 | DEBUG | subModel : GeneratorPQ Var
- Generator_omegaRefPu_value - is external and not connected
2 | ERROR | missing connection for one / several external
variable ( s ) ( DYNSimulation . cpp :591 )
3.4.1.2 Invalid connection due to connector’s type

Connected variables should share the same type (basically Continuous, Dis-
crete, Boolean or Integer). For simplification purposes and in order to iden-
tify easily which are the interface variables of the model, the current Dynaωo
Modelica library offers to use specific connectors: ImPin whose attribute
named value is a Real, ZPin whose attribute named value is a discrete Real,
BPin whose attribute named value is a Boolean and ACPower whose at-
tributes are V a complex voltage and i a complex current.
For example, if we connect an ImPin connector (let’s say SP_setPoint) to

a BPin connector (Generator_running), we will get the following error mes-
sage:
| ERROR | connection between model SET_POINT variable (

SP_ setPoi nt_val ue ) of type CONTINUOUS and model
GeneratorPQ variable ( G e n e r a t o r _ r u n n i n g _ v a l u e ) of type
BOOLEAN is impossible ( DYNModelMulti . cpp :642 )
3.4.1.3 Invalid connection due to inconsistency

The connect statements in the dyd file should link two connectors or two
variables, but a connection between a connector and a variable is forbidden.
For example, if we connect the generator machine speed Generator_omegaRefPu

to a set point thanks to the variable SP_setPoint_value instead of using the
connector SP_setPoint, we will get the following error message:
| ERROR | impossible to connect two elements : element 1 ( id

SP_ setPoi nt_val ue : name : SP _setPo int_v alue ) not found in
model : GeneratorPQ ( GeneratorPQ ) element
32
: G e n e r a t o r _ o m e g a R e f P u impossible connection (
DYNModelMulti . cpp :605 )
Here Generator_omegaRefPu is an ImPin while SP_setPoint_value is a

Real. The connection is impossible.
3.4.2 par file

3.4.2.1 Parameter not found
The user should make sure that every parameter of every model is set either
via a par file or directly in the model. If a parameter’s value is not defined,
Dynaωo should return the following message: “parameter X not found in set
Y ”.
For example, if you forget to give a value for the parameter “alpha” of the
load model, you will get the following message:
| ERROR | parameter Load_alpha not found in set merged_Load

( P A R P a r a m e t e r s S e t I m p l . cpp :186 )
As the parameter “alpha” is not given a default value in the Modelica model
Dynawo.Electrical.Loads.LoadAlphaBeta, it needs to be present in the pa-
rameters set of the par file.
3.4.2.2 Wrong type of parameter

Parameter’s type declaration in the par file should match the parameter type
in the corresponding model.
For example, if you declare the generator parameter U P hase0 as an INT in

the par file instead of a DOUBLE, you will get the following message:
| ERROR | invalid parameter type in request of

Gen erator _UPhas e0 ( expected double , got integer , warning
with string you need to explicitly cast the parameter
given to newParameter ) ( PARParameterImpl . cpp :96 )
33
U P hase0 is defined as Real in the generator Modelica model and should be
declared as a DOUBLE in the par file.
3.4.3 crv file

3.4.3.1 Wrong variable name in crv file
Mistakes in variables names in the crv file won’t trigger any error message,
but simply won’t be taken into account in the generation of the output
curves.csv. If it happens that you can’t find the variable that was supposed
to figure in curves.csv, check that it is written correctly.
34
4 Functional documentation
Contents
4.1 Dynaωo Overview . . . . . . . . . . . . . . . . . . 35
4.2 Models . . . . . . . . . . . . . . . . . . . . . . . . . 39
4.2.1 Introduction . . . . . . . . . . . . . . . . . . . . . 39
4.2.2 C++ library . . . . . . . . . . . . . . . . . . . . . 41
4.2.3 Modelica library . . . . . . . . . . . . . . . . . . . 46
4.3 Solvers . . . . . . . . . . . . . . . . . . . . . . . . . 49
4.3.1 Introduction . . . . . . . . . . . . . . . . . . . . . 49
4.3.2 Simplified solver . . . . . . . . . . . . . . . . . . . 53
4.3.3 Variable time-step solver . . . . . . . . . . . . . . . 60
4.1 Dynaωo Overview

The nature of power system dynamics is deeply evolving towards a more di-
verse and difficult to predict behaviour 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 collab-
orative studies in a very simple way by sharing not only the same data but
also the same modelling and solving choices in an open-source frame. Such a
tool 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
35
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 modelling language Modelica and a strict sepa-
ration between modelling and solving parts.
Figure 5: Separation between modelling and solving parts in Dynaωo
Modelica is an equation-based, declarative and object-oriented mod-

elling language that is easy to read and understand. The equations
are written in a similar way as how they are written in textbooks for exam-
ple. Using this language enables to easily share and discuss the modelling
choices done because the final models implementation is available in an un-
derstandable way, even for the end-user. The Modelica language is already
used in different and various industrial sectors. 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 sys-
tem, which was one of the motivation for developing Dynaωo. In addition to
this, the Modelica language itself has some limitations that are addressed in
Dynaωo by the possibility to use C++ models in a similar way as Modelica
models. Anyway, in the end all Modelica models are converted to C++ by
Dynaωo.
In order to transform the Modelica code into an executable C code,

Dynaωo uses OpenModelica, which is an open-source Modelica-
based modelling and simulation environment, and particularly the
OpenModelica compiler. OpenModelica is the Modelica open source en-
vironment that is the most widely used today in the Modelica community
36
and that covers the best the language norm. As such and in order not to de-
velop an in-house solution that will be difficult to maintain in the long-term,
as well as to benefit from developments and progresses made for other in-
dustrial sectors simulations, we have made the choice to build Dynaωo upon
OpenModelica. In addition to the transformation done by the OpenMod-
elica compiler, Python scripts are implemented into Dynaωo to transform
the outputs from the OpenModelica compiler in a generic frame that is also
common to the C++ models available in Dynaωo. All the thereby generated
C++ models are then combined to build a global model that will interact
with the solving part.
Figure 6: Building a global model from different unit models in Dynaωo
To ensure acceptable performances both for compilation and simulation, a

mechanism has been created into Dynaωo to compile non squared Modelica
models individually (for example a generator model by itself) and before the
simulation. These compiled models are then only instantiated during the
simulation. This strategy enables to use Dynaωo for large-scale simulations
(French EHV-HV networks - i.e. 250 000 continuous and 250 000 discrete
variables) while keeping computation time in a range close to current simu-
lation tools.
The global model only exposes a few methods to the solvers such as
the residual functions, the Jacobian function or the zero-crossing functions.
Having a separation between the modelling and the solving parts means
37
that the choice of the numerical resolution method doesn’t interfere with the
models implementation. This feature has several advantages: it enables to
easily test or use new solvers, it eases the addition of new model and it allows
modelling experts not to bother about numerical difficulties and vice versa.
Figure 7: Exchange between the modelling and the solving parts in Dynaωo
There are currently two solvers included into Dynaωo:
• The first solver is a fixed time-step solver developed for long-term sta-
bility studies that is based on works done during the European project
Pegase. It is an order-1 Backward-Euler solver that focuses more on
performances than on accuracy as there is no control error scheme and
events are detected and applied in a synchronous way at time instants
corresponding to the time step values;
• The second solver is the variable time-step variable order BDF solver
called IDA and developed by the Lawrence Livermore National Lab as
part of the SUNDIALS suite of solvers. Contrary to the first solver,
IDA aims at running very accurate simulations by using a control error
scheme and by detecting the exact instant corresponding to an event,
thanks to its root findings mechanism;
One important idea in Dynaωo is that the same models could be used for
different stability studies, in particular one set of RMS models should be
usable for both short-term and long-term stability analysis. It is the solvers
approximations that enable to run long-term stability studies with accept-
able computation time and not a priori simplifications done at the modelling
stage.
More details on the philosophy of Dynaωo could be found into [10].
38
4.2 Models
4.2.1 Introduction
Dynaωo 's library is divided into two parts: a C++ part and a Modelica part.
Modelica is the favourite modelling language in Dynaωo for a lot of differ-

ent reasons: it is an open source language, widely used in different industrial
sectors (automotive, building, etc.), that is equation-based, declarative, high-
level and object oriented. It means that the person in charge of the modelling
task doesn’t have to bother about the way the equations will be solved but
only on the necessity to have as many equations as variables, which makes
it possible to just use equations from reference papers or textbooks without
having to modify them. With such an approach, model sharing becomes a
reality in the sense that it is very easy for any user to understand what is
done in a model without having to spend a lot of time and energy in trying
to understand the written code (as it is often the case with Fortran or C for
example). Another advantage in a long-term perspective is the possibility
to easily do multi-system simulations with a Modelica-based simulation tool.
Indeed, by nature, Modelica is not specific to one domain and so it is possible
(and some libraries already exist) to model prime movers or gas systems in
Modelica. All these advantages have motivated the choice to use Modelica
in Dynaωo. Nevertheless, the Modelica language also has a few drawbacks
that prevent us to exclusively base our solution on Modelica. For example, it
is very impractical to deal with connectivity analysis with Modelica models
(which is required in power system simulations to deal with system splitting)
or to have variable-size objects (there is no vector object in Modelica).
In order to be able to model any kind of object and to bypass the aforemen-
tioned Modelica's limitations, it is possible to use C++ models in Dynaωo.
This is particularly useful to model large-scale regulations that need to be
connected to a large number of components or to deal with the network
topology.
All library models are available in the ddb repository generated by Dynaωo
compilation and can be directly used into test cases. In addition, the ddb di-
rectory also contains the .so library corresponding to the preassembled mod-
els and two xml files - one describing the connection needed by the model
*.xml and one describing the parameters required and the model variables
*.desc.xml.
39
Below is an example of a Pi line model in Modelica. As explained earlier,
the model is easy to read and understand:
Pi Line implementation in Modelica

1 within D y n a w o . E l e c t r i c a l . L i n e s ;
2
3 /*
4 * Copyright ( c ) 2015 -2019 , RTE ( http :// www.rte - france.com )
5 * See AUTHORS.txt
6 * All rights reserved.
7 * This Source Code Form is subject to the terms of the
Mozilla Public
8 * License , v. 2 .0. If a copy of the MPL was not distributed
with this
9 * file , you can obtain one at http :// mozilla.org / MPL /2 .0 / .
10 * SPDX - License - Identifier : MPL -2 .0
11 *
12 * This file is part of Dynawo , an hybrid C ++/ Modelica open
source time domain simulation tool for power systems.
13 */
14
15 model Line " AC power line - PI model "

16
17 /*
18 Equivalent circuit and conventions :
19
20 I1 I2
21 ( terminal1 ) - - > - - - - - - - R + jX - - - - - - - < - - ( terminal2 )
22 | |
23 G + jB G + jB
24 | |
25 --- ---
26 */
27
28 import Dy nawo.C onnect ors ;
29
30 C onn ec to rs .A CP ow er terminal1 ;
31 C onn ec to rs .A CP ow er terminal2 ;
32
33 parameter S Iun it s. Re si st an ce RPu " Resistance in p.u ( base

SnRef ) " ;
34 parameter SIuni ts.Rea ctanc e XPu " Reactance in p.u ( base
SnRef ) " ;
35 parameter S I u ni t s .C o n du c t an c e GPu " Half - conductance in p.u
( base SnRef ) " ;
36 parameter S I u ni t s .S u s ce p t an c e BPu " Half - susceptance in p.u
( base SnRef ) " ;
37
40
38 protected
39 parameter T ype s. AC .I mp ed an ce ZPu ( re = RPu , im = XPu )
" Line impedance " ;
40 parameter T y p es . A C. A d mi t t an c e YPu ( re = GPu , im = BPu )
" Line half - admittance " ;
41
42 equation
43
44 ZPu * ( terminal2.i - YPu * terminal2.V ) = terminal2.V -
terminal1.V ;
45 ZPu * ( terminal1.i - YPu * terminal1.V ) = terminal1.V -
terminal2.V ;
46
47 end Line ;
4.2.2 C++ library

The C++ library contains three models:
• A network model that provides a default behaviour for any grid com-
ponent
• An “OmegaRef” model that calculates the rotation speed reference

value for the system.
• A variation area model that applies a variation on the (P, Q) values of

one area's loads.
4.2.2.1 Network model

The C++ network model is fundamental in Dynaωo. Indeed, as soon as there
is a static description of the network (iidm file) given in input, it is necessary
to map a default behaviour to any component that can be present into the
grid. Therefore, for each static component, there is a corresponding default
behaviour into the network model. These models are used if and only if no
other dynamic model is associated to the static component. Such a scheme
ensures to be able to run simulations even without any dynamic data (or
Modelica model). In this case, the simulation only uses the default C++
models. For most of these default models, the choice has been made to keep
a very simple behaviour consisting in maintaining the original power flows
and power injections (calculated a priori by a load flow module for example).
Each component is described with more details in the next parts.
41
Bus
The bus model contains two equations corresponding to the Kirchoff’s law
P
on the current i = 0. It is also possible to turn on or turn off a bus during
a simulation by using events.
In addition to this, the voltage module and angle are available as outputs
both in per unit, kV or degree for display as well as the bus connection state.
The model also enables to define an upper and a lower constraint limit for
the bus’ voltage. If they are violated, a constraint is printed out into the
output constraint file.
Line
The default line model in Dynaωo is a classical π line model.
Figure 8: π line model
The line can be connected or disconnected during the simulation, either on

both sides or only on one side. In addition, the line model gives access to a
large number of variables: P, Q or the current circulating into the line (at
each side) and the line status (open/close/close on one side).
If such limits exist in the input file (iidm file), current maximum limits are
added to the line. These limits correspond to the maximum current that the
line can support during a certain time. If the line is overloaded during more
time than this allowed time, the line will be tripped.
Transformer
Only two-windings transformers are handled by Dynaωo C++ model at the

moment. In the transformer model, conductance and susceptance are only
defined at the side 2 voltage level and they are, as the resistance and the
reactance, defined in side 2 voltage per-unit basis.
42
The transformer model could be connected to either a phase shifter automa-
ton to regulate the current on a line or to a tap changer to control the
bus module voltage. The tap changer automaton modifies the voltage ra-
tio applied between side 1 and side 2 to respect a certain set point on side
2, whereas the phase shifter can add a contribution to the voltage angle to
change the power flow going through a line. There are logs indicating a tap
change when the automata have to act.
As the line model it is possible to display the P, Q, current values going
through the transformer. In a similar way, maximum current limits could be
added to the transformer.
HVDC
The current implementation for the C++ HVDC model is a one that keeps
P and Q on the HVDC AC sides constant. There is no calculation of any
variables on the DC side.
The HVDC can be connected or disconnected during the simulation. The
user can have access to the active and reactive power injected by the link on
the network.
Generator
The generator model calculates the necessary current to follow set points for
P and Q. It doesn’t have any limits on P, Q or the current. The set points
can be modified during the simulation and the generator can be connected
or disconnected. In case the set point is modified, there is a log message
displayed into the timeline output that indicates the set point new value(s).
Load
The load model can represent different behaviours, depending on the param-
eters given by the user. The generic equations defining the load behaviour
are:
U α
P = zP ∗ P0 ∗ (1 + ∆PC ) ∗ ( )
U0
(4.1)
U
Q = zQ ∗ Q0 ∗ (1 + ∆QC ) ∗ ( )α
U0
43
The possible behaviours are:
• A voltage dependant load if the load is neither declared as restorative

or controllable - zP = zQ = 1 and ∆PC = ∆QC = 0. This is the default
model.
• A load with a possible variation coming from another model (for ex-
ample the variation area model). In this case, there is a delta applied
on P and Q at each instant that is determined by the other model. For
example, if we choose to apply a variation of 10 MW over 10 s, the load
value will vary by 1 MW every 1 s. In this case, ∆PC and ∆QC are
varying over time but zP and zQ are kept constant equal to 1. This is
the controllable load model.
• A restorative load model in which the load works as a first order restora-
tive one. zP and zQ can vary during the simulation.
zpt−1 ( UU )α zpt
0 +
1+Tp s +
( UU0 )αL
Figure 9: Restorative load model
Any load model can be connected or disconnected. It is also possible for the
user to have access to the output P , Q,PC and QC values.
Shunt
The shunt provides a constant reactive injection to the network. It can be

connected or disconnected either by an user action or by an automaton ac-
tion.
In order to simulate the necessary time between two actions on the same
shunt, a minimal waiting time has been introduced into the shunt model
between two actions (parameter noReclosingDelay).
44
Static Var Compensator
The static var compensator model controls the susceptance to respect a pre-
define set point. This is done through a PI structure as shown in Figure 10
control scheme:
BM ax
UC B
+ + Kp ∗ Kg +
− + +
BM in
UN et λ ∗ QN et
1
Kp ∗Ti
Figure 10: Static Var Compensator model
4.2.2.2 OmegaRef model

The “OmegaRef” model calculates the reference speed for each synchronous
area. This reference speed is determined by calculating a weighted barycen-
tre of the different speeds of the generators connected to the grid in the
synchronous area:
Hi ∗ SN om,i ∗ ωi
P
i
ωref = (4.2)
Hi ∗ SN om,i
P
i
This model is connected to all the generators of one synchronous area and
takes their speed as inputs to calculate the reference speed that is used into
the machine models.
4.2.2.3 Variation area model

This model enables to calculate the active and reactive power variation to
apply to a set of loads to match a given variation in a time window. Its
parameters are thus the starting and stopping time of the variation and the
required changes into P and Q.
45
4.2.3 Modelica library
The Dynaωo Modelica library contains several models to describe advanced
dynamic behaviours of the main grid components as well as simple models
equivalent to the C++ default models that are mainly used for testing in
full Modelica simulations. In addition to the individual models (.mo files),
Dynaωo 's code contains “preassembled” models that consists in a group of
Modelica models that are compiled together to create a single final model
library (.so) that could be directly used in the simulation (without being
compiled at run time). These preassembled models correspond to a coherent
dynamic behaviour (physical model + regulation models) and are built to
be associated to one static component. One example is the combination of
a synchronous machine model with its regulations (voltage regulators and
governors). This gives one preassembled model that can be directly used
during the simulation and associated to one particular generator (without
having to associate the three models to the generator).
4.2.3.1 Library content

In this part, we will briefly describe what is the content of Dynaωo 's Mod-
elica library. To understand in details the behaviour of each model and the
chosen modelling assumptions, we encourage the reader to directly dig into
the Modelica model or to look at the specific documentation that is auto-
matically built from the Modelica models.
The Dynaωo library is divided into three main parts:
• The “Connectors” part contains all the specific connectors defined into
Dynaωo that are used to connect together different models. This en-
ables to have clear interfaces between the different models or the differ-
ent parts of a model (regulation and physical model for example). For
each type of variable, there is a type of connector (BPin for boolean
values, ZPin for discrete values, ImPin for real values and ACPower for
connecting both complex voltages and complex currents)
• The “Electrical” part with the different models of the electrical com-
ponents and their controls.
• The “NonElectrical” part including all Dynaωo- specific blocks. In the

library, we have tried to use as much as possible existing blocks from
the Modelica Standard Library but when necessary, specific models
or blocks have been developed and are stored into this folder to be
46
reused several times. This folder also contains logs files that are used
to generate logs from the Modelica model during a simulation.
More details on the “Electrical” package are given in the next sections.
Bus
The bus package contains an InfiniteBus model. No other bus models are pro-
vided in the package as the default C++ model is generally used in Dynaωo
simulations and is simple enough to be understandable by everyone, even
written in C++.
Controls
The controls package gathers all the controls and regulations models for the
different components:
• Common models, such as set point, perturbation, step and switch-off,

are included into the Basics package.
• The Current package includes a current limit automaton model.
• The Generic package contains an example implementation to call a C

function from a Modelica model. This model can serve for example to
include an OPF-based automaton into a Dynaωo simulation.
• The Machines package with the different regulations for the machines
such as voltage regulations, governors or under-voltage protection.
• The Transformers package that includes the phase-shifter and tap changer
automata models.
• The Voltage package containing a tap changer locking automaton model.

It is an automaton that can lock the tap changer automaton in case
the voltage becomes too low in an area.
Events
Events models enable to change the connection status of the different grid
elements. They are all based on a similar basis with a time corresponding to
the event and a variable whose value will change at the event time.
47
Lines
There is at the moment one π line model included into Dynaωo.
Loads
Two load models are included into the package:

• A voltage dependent load model (LoadAlphaBeta)
• A constant P,Q load model (LoadPQ)
Machines
Different models with different levels of details constitute the Machines pack-
age. The most detailed model is a four-windings synchronous machine model
(GeneratorSynchronous). Others are simplified ones:
• GeneratorPQ in which the P output is modulated according to fre-
quency and the Q output is only modulated when large variations oc-
cur.
• GeneratorPV that modulates the P output according to frequency and
the Q outputs to keep U + λ ∗ Q as close as possible to a set point.
• GeneratorFictitious that acts as a voltage-dependent generator. P and
Q vary around their initial values depending on the voltage value.
Transformers
The transformers package contains both a fixed ratio transformer model and
a variable tap transformer model that can serve for phase shifter or tap
changer modelling.
4.2.3.2 Preassembled models

Preassembled models are Modelica models that are compiled together during
Dynaωo compilation to produce a .so library that can be directly used (as a
blackbox model) in a simulation. With this mechanism these models don’t
have to be compiled at run time but only instantiated which allows to have
acceptable performances with Dynaωo.
The different preassembled models delivered with Dynaωo are:
48
• CurrentLimitAutomaton corresponding to the current limit automaton
model
• Different event models
• GeneratorFictitious, MachinePV, MachinePQ and Machine4WNoRegul

corresponding to the different generator models
• GenericAutomaton that enables to call a C function every few s (cor-

responding to the GenericAutomaton model)
• Different load models: LoadAlphaBeta corresponding to the LoadAl-

phaBeta model, LoadOneTransformer which is a load alpha beta plus a
transformer, LoadTwoTransformers which is a load alpha beta behind
two transformers
• PhaseShifterI and PhaseShifterP that are phase shifter models control-

ling either the current or the active power
• TapChangerAutomaton, the tap changer automaton model
• TapChangerBlockingArea, the automaton that allows to block the tap

on transformers
4.3 Solvers
4.3.1 Introduction
4.3.1.1 Differential Algebraic Equations
The mathematical problem to be solved in power system time-domain simu-
lations is an explicit Differential Algebraic Equations (DAE) system:
Γ(y(t), ẏ(t), z(t), t) = 0 (4.3)

where y is the continuous variables vector, z the discrete variables vector and
t the time.
This problem could be rewritten as a semi-explicit one:


 fd (yd (t), y˙d (t), ya (t), z(t), t) = 0
(4.4)
 fa (yd (t), ya (t), z(t), t) = 0
49
where fd represents the differential equations vector, fa the algebraic equa-
tions vector, yd the differential continuous variables vector and ya the alge-
braic continuous variables vector.
The algebraic equations represent the network that is considered to have

an instantaneous response in phasor time-domain simulations (no delay) as
well as time-independant parts of the other models.
The differential equations correspond to a broad range of phenomena,

from short-term dynamics existing into the machine regulations, static var
compensator behaviours, induction machines, etc., to long-term dynamics
coming from the long-term regulations (secondary voltage/frequency con-
trols), load restoration behaviour, etc.
4.3.1.2 System resolution

To solve the problem and determine the variable values during a whole sim-
ulation, a numerical integration method has to be chosen to transform the
DAE system to a non-linear algebraic system corresponding to a particular
instant in time (time step):
y˙d (tn ) = h(yd (tn ), yd (tn−1 ), yd (tn−2 ), ...)) (4.5)
Using (4.5) the DAE system becomes for a time step tn :
Γ(yd (tn ), ya (tn ), h(yd (tn ), yd (tn−1 ), yd (tn−2 )...) = 0 (4.6)
that we can rewrite for simplicity purpose
F (x) = 0 (4.7)
This non linear algebraic system can then be solved using different iterative
methods, the most frequent in power system being the Newton method.
At each iteration i of the Newton algorithm, the new values for x are calcu-
lated using a first-order Taylor development:
F (xi+1 ) = F (xi ) + JF (xi )(xi+1 − xi ) (4.8)
where JF is the Jacobian, defined in the following way (α depending on the

integration method chosen):
∂F ∂F
JF = +α (4.9)
∂y ∂ ẏ
50
Using (4.7) and (4.8) leads to:
xi+1 = xi − JF (xi )−1 F (xi ) (4.10)
The Newton iterations are stopped whenever F (xi+1 ) is considered to be

close enough to zero.
4.3.1.3 Prediction-Correction scheme

Prediction-correction schemes aim at improving the convergence characteris-
tics of the numerical methods by combining two steps in the overall problem
resolution:
• A prediction step that consists in using past values (y(tn−1 , y(tn−2 ), ...),
of the variables to calculate initial values (y(tn0 ) <=> x0 ) for the next
time step. It is generally done by extrapolating a function that fits the
past values of the variables. This step gives a very good initial point
for the Newton used in the correction step and facilitates convergence,
especially when the system is evolving in a continuous way.
• A correction step that is the system resolution presented in the above

section - (4.3.1.2)
With such schemes, the convergence step iterations number is a good indi-
cator of the system evolution. Indeed, a slow convergence means that the
system has changed a lot since the last time step.
4.3.1.4 Discrete event handling

During a dynamic simulation, discrete events can occur. They can be:
• a change of the discrete variables values z(t);
• a change of the DAE system functions fd (t) and fa (t) (called modes);
A discrete variable value change corresponds for example to a trans-

former tap change or a breaker opening/closing.
A mode change corresponds for example to the switch from one regula-
tion mode to another (machine switching from standard regulation mode to
maximum reactive absorption limit, static var compensator switching from
standy to standard regulation mode, etc).
51
It is important to be able to correctly determine the time instants corre-
sponding to a discrete variable value change or to a mode change. This is
done by using a root detection mechanism that detects the zero crossing of
a set of functions called root functions (denoted r(y(t), ẏ(t), z(t), t) = 0) as-
sociated to each discrete variable or each f function that can change over time.
Some events can lead to very important discontinuities that dramatically

change the system evolution. For these events, a reinitialization of the DAE
system - ie calculation of new initial conditions - is necessary to manage to
go over the event and continue the simulation.
4.3.1.5 Solvers in Dynaωo

Two solvers are currently integrated into Dynaωo:
• A fixed time-step solver (called Simplified solver in the remaining

parts of this document) based on research work done during the Euro-
pean project Pegase [3, 6, 5]
• A variable time-step solver based on IDA, which is part of SUite of

Nonlinear and DIfferential/ALgebraic equation Solvers (SUNDIALS) -
a suite of solvers developed by the Lawrence Livermore National Lab
(LLNL) -, plus additional routines [11].
For the simulation of a given test case, the results obtained with these solvers
will be different, as the numerical methods applied are different. These dif-
ferences are illustrated in the figure below for a test simulating a line discon-
nection.
52
406
USIM
UIDA1
404 UIDA2
402
400
398
396
40 50 60
time (s)
Figure 11: Differences between solvers for a line disconnection
The solver integration in Dynaωo is generic enough to easily enable to inte-

grate other solvers. For example, the Sinusoidal Predictor Method has been
tested with Dynaωo [8, 9] and shows that it is straightforward to include a
new solver into the Dynaωo frame.
The next sections give more details about the two aforementioned solvers.
4.3.2 Simplified solver

4.3.2.1 Introduction
The Simplified solver is a fixed time-step solver, based on the work done
during the FP7 European project Pegase and particularly on the efforts con-
ducted by the University of Liege to derive a numerical approach to speed
up calculations for long term stability problems by filtering out the fast dy-
namics.
It uses an order-1 Backward Euler (BE) method, which means that y˙t =
yt −yt−1
h
. This method is an A-stable method thus if the system is stable, the
calculated solution will be stable. It is also an A-unstable method and as
53
such, a stable solution can be found by the solver even if it doesn’t exist for
the real system.
This solver goal is to have acceptable computation times for long-term dy-
namics simulations. It doesn’t aim at making accurate simulations to detect
oscillations or any other short-term dynamics. Its behaviour for long-term
dynamics has been compared against the variable time step solver to validate
the approximations done.
4.3.2.2 Prediction step

At the moment, there is no prediction in the Simplified solver algorithm.
Indeed, the variables starting values for the time step tn+1 are the variables
values calculated at time step tn . As a consequence, and considering the
chosen integration method (BE order 1), the differential variables are equal
to zero at the beginning of a new time step.
y0 (tn+1 ) = y(tn )
(4.11)
y˙0 (tn+1 ) = 0
It is important to mention that different prediction schemes have been tested
both during the Pegase project and internally in RTE after the project. These
alternatives have shown to be beneficial most of the time (especially when
the system evolution is “continuous") but have also led to very detrimental
behaviours in certain cases. The current choice is thus to stick to this “no-
prediction" approach. In the current version, this choice can’t be modified
by the user.
4.3.2.3 Correction step

The correction step is handled by a Newton-Raphson (NR) algorithm call-
ing a NR solver developed by the LLNL: Krylov Inexact Newton SOLver
(KINSOL). The approach used in KINSOL is an inexact NR method:
the Jacobian isn’t calculated at each iteration but kept constant for a few
iterations. Different criteria exist to force a recalculation of the Jacobian and
its associated LU decomposition, trying to track too slow convergence.
KINSOL parameters
At the moment, KINSOL is used in the following way:
54
• The tolerance is set to tolerance.
• The Jacobian matrix isn’t calculated at each iteration but only if the
solver hasn’t converged after n iterations or if the residual functions
hasn’t decreased enough after n2 iterations. Other conditions also exist
in KINSOL but can’t be modified by the software calling it.
• The iterations maximum number is set to nM ax .
By default, these parameters have the following values into Dynaωo: tolerance =
10−4 , n = 10, n2 = 5, nM ax = 30. They aren’t yet configurable by the user.
Jacobian evaluation
As already mentioned, the Jacobian matrix is not calculated at each NR it-

eration. The algorithm used is an inexact NR which aims at refreshing as
less as possible the Jacobian matrix to gain computation time. The Jaco-
bian calculation is only forced at the beginning of the NR iterations in the
following cases:
• For the first time step
• After an algebraic mode change
• After a non convergence
• After a root unstability detection (number of consecutive discrete vari-

able values or mode changes higher than a threshold)
Re-evaluations can happen during a time step, as explained in the previous

section, when the solver hasn’t converged after a certain number of iterations
or when the convergence speed is not good enough.
LU decomposition
When the Jacobian is evaluated, its LU decomposition is calculated in or-

der to solve the linear algebraic system appearing in (4.10). In Dynaωo, we
have made the choice to use publicly available and open source libraries to
resolve these linear algebraic systems and not to develop an in-house solution.
Most LU decomposition methods perform these two main steps:
55
• A symbolical factorization or pre-ordering in which the non zero struc-
ture (ie sparsity pattern) of the matrix gets permuted in order to im-
prove numerical properties as well as performance.
• A numerical factorization or factorization where the LU decomposition
is really done.
The symbolical factorization is the most costly part in the overall process.
That’s why, when the matrix structure doesn’t evolve (constant number and
position of the non zero entries), we only call the numerical part.
Symbolical vs numerical decomposition
After a call to the Jacobian evaluation method in Dynaωo, a method is

called to check if the matrix structure has changed or not. If the structure
has changed, the LU decomposition is reinitialized in order to force a new
complete decomposition (symbolical + numerical). Otherwise, only the nu-
merical part is done.
One can expect that symbolical decomposition is required only in the case of
important change in the system such as topological change, running status
of generators changes, etc. In practice, due to some numerical noises, the
number of non zeros elements in the matrix in large test cases often varies
from one decomposition to another. Complementary studies on this point
will be done in the next few months to try to detect the origin of these
numerical noises and decrease their impact on the computation time.
LU decomposition libraries
Two LU decomposition libraries could be used into Dynaωo at the moment:

• KLU [4], which has been deeply tested during the Pegase project and
has proved to be the most efficient of the existing LU decomposition
library available at this time for power system problems. This is the
library that we advise to use at the moment;
• NICSLU [2], which results from a more recent effort and that is also very
efficient for power system problems. NISCLU is in particular faster for
refactorization (numerical factorization only) but its integration into
SUNDIALS and its use in Dynaωo is still under experimentation;
It is possible to switch from KLU to NICSLU by modifying the solver pa-
rameter called “linearSolverName".
56
Residual function evaluation
In order to give KINSOL a better criterion to stop the NR algorithm, it is

necessary to provide a scaling vector to KINSOL. To calculate this scaling
vector, the residuals have to be calculated beforehand. These residuals are
identical to the ones that would be calculated by KINSOL at the beginning
of the NR algorithm. In order to gain time, the residual calculation method
has been modified in Dynaωo and the first residuals are not calculated again.
Values are taken from the scaling method calculation.
4.3.2.4 Discontinuities handling

At the end of a time step, the discrete variables value are compared with
their values at the previous time step, and the root functions are evaluate in
order to detect if a mode has changed during the iteration. When a change
is detected, the Simplified solver offers two different strategies:
• A “go-through" strategy in which the time step isn’t repeated;
• A “recalculate" strategy in which the time step is recalculated until
we reach a system state with no more discrete variable value or mode
change.
Regarding discontinuities detection, the Simplified solver algorithm doesn't
try to determine the exact event time as it could be the case with more de-
tailed solver. All the discrete variable and mode changes are considered at
the next (or previous) time-step depending on the strategy used. The delay
(or advance) is then equal at maximum to the time step.
At the moment, the different tests conducted with both strategies haven’t
permitted to exhibit a test case in which only one of the two strategies en-
ables to find the correct final state (= similar to IDA). As the “go-through”
strategy is more efficient because it requires less calculations, we advise to
use it by default. Nevertheless the user can choose to use one or the other
strategy by modifying the recalculatedStep parameter.
The algorithm for one time step for the Simplified solver (particularly for
discontinuity handling) is presented in Figure 12.
4.3.2.5 Time step management

The Simplified solver is based on a fixed time-step approach in the sense that
the different time steps are not calculated automatically to respect a certain
57
Start for tn+1
Calculate Reduce
y(tn+1 ) time step
Yes
No No
Succes? h 6= hM in ? Divergence
Yes
Calculate
g(tn+1 )
g(tn+1 ) 6= No
Go to tn+2
g(tn )?
Yes
Calculate
g(tn+1 ),
z(tn+1 )
and modes
Change?
Yes
No
Algebraic Restaure
Yes
mode algebraic Go to tn+2
change? equations
No
nbN R < Recalculate

Yes nbN RM ax ? Yes step?
No No
Go to tn+2 Go to tn+2
Figure 12: Simplified solver58algorithm for one time step

error (as it is done with variable time-step solvers).
However, when the system is facing important discontinuities or large distur-
bances, the NR algorithm can fail. In this case, the strategy is to decrease
the time step temporarily. The time step is then increased when the
system comes back to steady-state to reach its “normal" fixed value (the in-
crease is done in a progressive way, based on the convergence speed of the
NR). By default, the time step is set to 1 s in Dynaωo.
The time-step is updated in the following way in Dynaωo:

• When the time step is equal to its maximum value (hM ax) and the
NR algorithm converges, it doesn’t change.
• If the time step is not equal to its maximum values and the NR algo-
rithm converges, the time step is increased if the number of iterations
in the NR algorithm (nbN R) is lower than a target number nEf f . The
increase is proportional to the difference between this target number
and the number of iterations really needed.
nEf f
hN ew = h ∗ (4.12)
nbN R
A deadband nDeadband has been added to avoid oscillations between
time steps.
• If there is a divergence, the time step is multiplied by a factor kReduceStep.
A minimum time step (hM in) is used in Dynaωo to stop the simulation. If
the NR is divergent with this value the simulation is stopped.
All these parameters can be modified by the user and their default values
are: hM ax = 1s, hM in = 10−6 s, kReduceStep = 0.5, nEf f = 10, nDeadband = 2.
4.3.2.6 Algebraic equations restoration

As already mentioned in 4.3.1, the DAE system (4.3) can change during the
simulation because the differential equations or the algebraic equations can
change their form (mode).
In most of the cases, these changes are smooth changes (for example reach-
ing a limit) and the simulation can just go on without any special process.
Nevertheless, some changes lead to a deep change in the equations form (for
example a change in the network topology) and require to reinitialize the
DAE system by calculating new initial conditions for ya in the Simplified
solver case. This is done by calling a NR on the algebraic equations.
59
4.3.3 Variable time-step solver
4.3.3.1 Introduction
The variable time-step solver corresponds to a packaging of Implicit Differential-
Algebraic solver (IDA) plus some additional in-house routines to deal with
discrete variable values changes propagation or algebraic mode restoration.
Otherwise, the continuous variable calculation as well as the zero crossing
times determination are done by classical approaches from IDA.
The integration method used in IDA is a variable-coefficient, variable-order

Backward Differentiation Formula (BDF) in fixed-lead coefficient form. The
order q BDF formulation is given by the following multistep formula:
q
X
αn,i yn,i = hn y˙n (4.13)
i=0
The method order supported by IDA ranges from 1 to 5. Nevertheless all

tests done in Dynaωo have used order 1 or order 2 as the maximum possible
order. It seems sufficient enough to get accurate results while keeping ac-
ceptable time durations. This parameter could be set to any value (between
1 and 5) by the user.
The IDA solver contains a root finding routine enabling the solver to detect
the exact moment of a zero crossing, ie the exact moment corresponding to
a discrete variable value or a mode change. When such a moment is de-
tected, the solver will stop at this time-step and calculates the solution for
this time. Compared to the Simplified solver, the IDA solver focuses on accu-
racy, especially when used with small minimal time-step and high order. We
recommend to use it in off-line simulations to run very accurate simulations.
It has to be noticed that IDA is used in the ONE STEP mode in Dynaωo:
it means that the solver resolves one step and then returns to the main
Dynaωo code. Between time steps, a series of additional routines are called
into Dynaωo main code:
• Changes in the discrete variable values and mode are propagating, es-
pecially through the connectors
• In case of a severe event, the DAE problem is reinitialized in order to

go through this severe event
• Curves are plotted and criteria to stop the simulation are checked
60
• ...
In the next following parts, the main principles for this approach will be
briefly explained but a complete and thorough description is available in the
IDA documentation. The content of the next paragraphs will rather focus on
the conceptual ideas present in IDA than in the exact mathematical formu-
lations or the implementation details that are widely and clearly explained
in IDA documentation or Sundials website.
4.3.3.2 Prediction step

IDA uses a predictor-corrector scheme, ie initial values for the next time
step y0 (tn+1 ) are initialized using the historical values of y(tn ) and ẏ(tn ). It
is done using an interpolating polynomial that matches the previous values
and is coherent with the chosen multi-step method.
This prediction step enables to have initial values for the correction step that
should be close to the final values calculated, ie to have a correction step that
is convergent with only a few iterations.
4.3.3.3 Correction step

The correction step in IDA is done using a Newton-Raphson method. The
code is directly included into IDA. As the interpolating polynomial used in
the prediction scheme should give good initial values (in case the system
evolution is regular), the maximum number of iterations allowed for the
correction step is equal to 4 by default. It is not possible at the moment to
modify this parameter. The correction step is considered convergent when
the difference between the variable values at the iteration m and at the
iteration m+1 is small relative to the variable values themselves. If this ratio
becomes smaller than a threshold (defined through the relative and absolute
accuracies parameters), the Newton-Raphson is considered convergent and
the time step accepted.
The Jacobian matrix is never re-evaluated during the correction step (ie
during the Newton-Raphson algorithm). It is updated only in the following
cases:
• when it is the first time iteration
• when the time step variation is larger or smaller than a certain threshold
(5/3 or 3/5 by default)
• when the last NR calculation has not converged
61
As for the Simplified solver, the idea is to try to minimize the number of Jaco-
bian evaluations. However, the Jacobian evaluations are much more frequent
with IDA because of the time-step variations, especially for simulations with
a lots of events where the time-step decreases around the event and increases
during steady-state.
Regarding the LU decompositions that could be used with IDA in Dynaωo,
the user can choose to use KLU or NICSLU. Most of the simulations have
been done until now with KLU but NICSLU gives slightly better perfor-
mances (especially because the Jacobian is sometimes updated without any
change in its structure when using IDA).
4.3.3.4 Events detection

IDA contains a mechanism to detect the exact time corresponding to a change
in a discrete variable value or a mode. This detection is done using the root
of the zero-crossing functions defined to catch these changes. When a time-
step has been defined and accepted by IDA, the solver checks if there has
been a root change (ie a change in the signs of the zero-crossing functions
during the time-step). If such a change occurs, then it means that an event
occurs between tn and tn+1 . The exact time corresponding to the event
is determined by a dichotomy search. The solver determines what is the
smallest time corresponding to an event and stops at this time (it can’t be
smaller than the minimum time-step given to the solver).
4.3.3.5 Time-step and order management

IDA is a variable time-step and order solver. When the system is in steady-
state, the order used by the method should be 1 and the time-step large
(equal to the maximum time-step). During transients, where variables val-
ues change a lot, the order used by the method should be the maximum
allowed order and the time-step close to its minimal value: it means that the
system evolution is not regular and is difficult to predict. In this case, the
prediction step quality is poor if the solver tries to use large time steps and
the correction step won’t converge. To use the past data and the past system
evolution it is necessary to keep small time-steps for which this approxima-
tion is valid.
The time-step and order are changed by IDA using the Local Truncation
Error, which is an image of the convergence difficulty of the correction step
and so of the prediction phase viability.
62
4.3.3.6 Algebraic equations restoration
In a similar way than for the Simplified solver, in case of a severe event that
leads to a strong discontinuity in the system (for example a line disconnec-
tion), a reinitialization of the problem is done into Dynaωo before the next
time step. In the IDA case, it consists in two Newton-Raphson resolutions;
one on the algebraic equations enabling to calculate ya and one on the differ-
ential equations only to calculate the derivative values of differential variables
y˙d . These values are necessary to be able to relaunch correctly IDA after the
discontinuity.
63
5 Advanced documentation
Contents
5.1 Code organization . . . . . . . . . . . . . . . . . . 65
5.2 Dynaωo executables . . . . . . . . . . . . . . . . . 66
5.2.1 Dynaωo commands . . . . . . . . . . . . . . . . . . 67
5.2.2 Compilation and simulation of a single Modelica
model . . . . . . . . . . . . . . . . . . . . . . . . . 67
5.2.3 Compilation and simulation of complex models . . 72
5.2.4 Generation of a xml summary of the parameters
and variables of a compiled model . . . . . . . . . 78
5.3 Adding a model to the Dynaωo library . . . . . 79
5.3.1 Adding a Modelica model in the Dynaωo Modelica
library . . . . . . . . . . . . . . . . . . . . . . . . . 79
5.3.2 Adding a Modelica model in the Dynaωo precom-
piled library . . . . . . . . . . . . . . . . . . . . . . 83
5.4 Adding a new solver . . . . . . . . . . . . . . . . . 85
This chapter contains documentation on advanced features for readers that

would like to have a deep look in Dynaωo. It will explain:
• Dynaωo code organization (5.1)
• Dynaωo executables (5.2)
• how to add a new Modelica model to the library (5.3)
• how to add a new solver into Dynaωo (5.4)
64
5.1 Code organization
The Dynaωo source code repository is organized as follows:
cpplint
document
dynawo
3rd party
cmake
doxygen
sources
API
Common
Launcher
Modeler
ModelicaCompiler
Models
Simulation
Solvers
nrt
util
• the cpplint directory contains the Python scripts needed to use cpplint;
• the document directory contains the different latex documents used to
create this documentation as well as the Dynaωo website;
• the dynawo directory contains all the code related to Dynaωo itself and
the modifications on 3rd party. This is the most important directory;
• the nrt directory contains the testsuite used to check the correct behav-
ior of the simulation tool. They also serve as examples of the simulation
tool behavior and main principles;
• the util directory contains some utilities code e.g. to display the simula-
tion results in a browser or to compare the nrt results with a reference.
The main dynawo directory contains the following folders:
• the 3rd party folder contains the toolchains to download, potentially
modify and compile the necessary third-party libraries needed to run a
Dynaωo simulation;
• the cmake folder contains all the files related to the general configura-
tion of the compilation process;
65
• the doxygen folder contains the Dynaωo settings to build the source
code documentation;
• the sources folder contains the Dynaωo code.
Finally, the source code is divided into different subdirectories corresponding
to the different parts of the Dynaωo simulation tool. They are:
• the API directory contains the code related to all the Input/Output
files;
• the Common directory contains all the code dealing with common fea-
ture and methods as well as the dictionaries for logs;
• the Launcher folder contains the main file and the launcher;
• the Modeler folder corresponding to all the code related to the generic
API for the models, ie. the files that define the architecture and re-
quired methods expected from a model. It also contains the code re-
lated to the data transfer from the input data file to the models as well
as the generic methods for the Modelica models;
• the ModelicaCompiler directory contains the Python scripts that are
applied to the outputs produced by OpenModelica compiler. These
scripts allow to get a final C code in adequation with the Dynaωo API;
• the Models directory contains the Dynaωo models library (both C++
and Modelica models);
• the Simulation directory contains the files related to the handling of
the global simulation itself;
• the Solvers directory is the part of the code dealing with the resolution
of the DAE system.
5.2 Dynaωo executables

Once compiled, Dynaωo offers a certain number of utility binaries and scripts
mainly to handle compilation of Modelica models. Below we explain how to
use them to generate a .so library or to compile Modelica models at run-time.
Nevertheless, if you want to often use a new Modelica model into
your simulations, we recommend adding it to the Dynaωo library
(for this, see 5.3).
66
5.2.1 Dynaωo commands
To see all available Dynaωo commands run:
$ > ./ myEnvDynawo . sh help
In the following we will give examples on how to use some commands, and
particularly: compileModelicaOMC, generate-preassembled and dump-model.
To be able to execute Dynaωo from anywhere in the following examples you
can do:
$ > cd / root / of / dynawo / source / folder

$ > export MY_ENV_DYNAWO = $ ( pwd ) / myEnvDynawo . sh
5.2.2 Compilation and simulation of a single Modelica

model
The compileModelicaOMC option of the myEnvDynawo.sh script takes as input
a Modelica model and generates a .so library that can be used as input of
Dynaωo to simulate this model.
A summary of the possible arguments of the compileModelicaOMC option can
be obtained with the following command:
$ > $MY_ENV_DYNAWO co mp ile Mo de li ca OM C -- help
In the following, we will provide some examples of usage.
First example: Modelica model with no external variables

In the following we will show how to generate a .so library from a Modelica
model with no external variable and then use it in a Dynaωo simulation.
We take as example the following Modelica model:
Test.mo
1 model Test
2 parameter Real a = 1;
3 parameter Real b = 2;
4 Real u ( start = 1) ;
5 equation
6 a * der ( u ) = -b * u ;
7 end Test ;
To generate the .so library of this model, the command below can be used.
67
Warning, if you execute directly the command in the folder containing your
.mo file it will be deleted so be sure to make a copy of it and execute all the
following commands.
$> cd / path / to / Test . mo

$> mkdir -p compilation
$> cp Test . mo compilation
$> $MY_ENV_DYNAWO co mp ile Mo de li ca OM C -- model Test
-- output - dir compilation -- lib Test . so
In the compilation folder you will find the output model library Test.so.
To only generate the C++ files used to compile the model .so library, the
user can call the same command without the --lib argument. This will only
generate the C++ model files used to generate the library:
$ > cp Test . mo compilation

$ > $MY_ENV_DYNAWO co mp ile Mo de li ca OM C -- model Test
-- output - dir compilation
The following input files are needed in the same folder as the library to launch
a Dynaωo simulation of this basic model:
Test.jobs
3 < dyn : job name = " Test " >
6 < dyn : dynModels dydFile = " Test . dyd " / >
7 < dyn : pr ecompi ledMod els u seStan dardMo dels = " true " >
8 < dyn : directory path = " . " recursive = " false " / >
9 </ dyn : precompiledModels >
10 < dyn : modelicaModels us eStan dardMo dels = " false " / >
12 < dyn : simulation startTime = " 0 " stopTime = " 10 " / >
14 < dyn : curves inputFile = " Test . crv " exportMode = " CSV " / >
15 < dyn : logs >
17 </ dyn : logs >
19 </ dyn : job >
20 </ dyn : jobs >
68
Test.dyd
3 < dyn : blackBoxModel id = " Model " lib = " Test . so "
parFile = " Test . par " parId = " 1 " / >
Test.par
3 < set id = " 1 " >
4 < par type = " DOUBLE " name = " a " value = " 2. " / >
5 < par type = " DOUBLE " name = " b " value = " 10. " / >
6 </ set >
Test.crv
3 < curve model = " Model " variable = " u " / >
4 </ curvesInput >
solvers.par
3 < set id = " 1 " >
4 < par type = " DOUBLE " name = " hMin " value = " 0.000001 " / >
5 < par type = " DOUBLE " name = " hMax " value = " 1 " / >
6 < par type = " DOUBLE " name = " kReduceStep " value = " 0.5 " / >
7 < par type = " INT " name = " nEff " value = " 10 " / >
8 < par type = " INT " name = " nDeadband " value = " 2 " / >
9 < par type = " INT " name = " maxRootRestart " value = " 3 " / >
10 < par type = " INT " name = " maxNewtonTry " value = " 10 " / >
11 < par type = " STRING " name = " linearSolverName " value = " KLU " / >
12 < par type = " BOOL " name = " recalculateStep " value = " false " / >
13 </ set >
The following command is used to launch the simulation:
$ > cp compilation / Test . so / path / to / folder / with / input / files

$ > cd / path / to / folder / with / input / files
$ > $MY_ENV_DYNAWO jobs - with - curves Test . jobs
69
With different input files, it is also possible to let Dynaωo internally compiles
the model before launching the simulation. The following input files need to
be created in the same folder as the Test.mo file:
Test.job
7 < dyn : pr ecompi ledMod els u seStan dardMo dels = " false " / >
8 < dyn : modelicaModels us eStan dardMo dels = " true " >
10 </ dyn : modelicaModels >
15 < dyn : logs >
17 < dyn : appender tag = " COMPILE "
file = " dynawoCompiler . log " lvlFilter = " DEBUG " / >
18 </ dyn : logs >
20 </ dyn : job >
21 </ dyn : jobs >
Test.dyd
3 < dyn : modelicaModel id = " Model " >
4 < dyn : unitDynamicModel id = " TEST " name = " Test "
moFile = " Test . mo " / >
5 </ dyn : modelicaModel >
Test.crv
3 < curve model = " Model " variable = " TEST_u " / >
70
4 </ curvesInput >
And the same solvers.par file as previously.

$ > cd / path / to / Test . mo

Second example: Modelica model with external variables

In the following we will show how to generate a .so library from a Modelica
model containing some external variables (i.e. variables that will be con-
nected later to another model).
Please note that such simulation scenario cannot be handled by OpenMod-

elica.
We take as example the following Modelica model:
resources/exampleExecutables/TestCompile/ExternalVariables/Test.mo
1 model Test
5 Real v ;
6 equation
7 a * der ( u ) = -b * u ;
8 end Test ;
In this model the v variable needs to be connected later to another variable

of another model.
A Test.xml file is needed to declare the variable as external:
Test.xml
2 < e xter na l_ va ri ab le s xmlns = " http :// www . rte - france . com / dynawo "
xmlns : xi = " http :// www . w3 . org /2001/ XInclude " >
3 < variable type = " continuous " id = " v " / >
4 </ external_variables >
To generate the .so library of this model, the following commands are used:
$ > cd / path / to / Test . mo

$ > mkdir -p compilation
$ > cp Test . mo compilation
71
$ > cp Test . xml compilation
$ > $MY_ENV_DYNAWO co mp ile Mo de li ca OM C -- model Test
-- output - dir compilation -- lib Test . so
Warning, at this point you cannot directly launch a simulation with only
this model as it needs to be connected to another model providing the missing
equation on v. The way to do this is described in section 5.2.3.
5.2.3 Compilation and simulation of complex models

The generate-preassembled option takes as input a xml file that contains a
list of models and their connections and generates from it a .so library that
can be used as input of Dynaωo to simulate this model.
A summary of the possible arguments of the generate-preassembled options
can be obtained with the following command:
$ > $MY_ENV_DYNAWO generate - preassembled -- help

In the following, we will provide some examples of usage.
First example: Model with fully connected external variables

We take as example the following Modelica models:
rModel1.mo
1 model Model1
5 Real v ;
6 equation
7 a * der ( u ) = -b * u ;
8 end Model1 ;
And the second:
Model2.mo
1 model Model2
4 Real v ( start = 2) ;
5 equation
6 a * der ( v ) = b * v ;
7 end Model2 ;
In this example, the v variable from Model1 needs to be connected to the v
variable of Model2. The two models have their respective external variables
72
declared in xml files as shown in section 5.2.2.
The Test.xml file shown below describes to Dynaωo how to compile and
connect those two models:
resources/exampleExecutables/TestDydLibNoExternal/Test.xml
3 < dyn : modelicaModel id = " Test " >
4 < dyn : unitDynamicModel id = " MODEL1 " name = " Model1 " / >
6 < dyn : connect id1 = " MODEL1 " var1 = " v " id2 = " MODEL2 "
var2 = " v " / >
The following commands generate the associated Test.so library:
$ > cd / path / to / Test . xml

$ > ls
Model1 . mo Model1 . xml Model2 . mo Model2 . xml Test . xml
$ > cp Model1 . mo Model2 . mo Model1 . xml Model2 . xml compilation
$ > $MY_ENV_DYNAWO generate - preassembled -- model - list
Test . xml -- output - dir compilation
-- non - recursive - modelica - models - dir .
To launch a simulation with the compiled model the following input files
needs to be created in the same folder as the .so library:
Test.jobs
7 < dyn : pr ecompi ledMod els u seStan dardMo dels = " true " >
9 </ dyn : precompiledModels >
10 < dyn : modelicaModels us eStan dardMo dels = " false " / >
73
15 < dyn : logs >
17 </ dyn : logs >
19 </ dyn : job >
20 </ dyn : jobs >
Test.dyd
3 < dyn : blackBoxModel id = " Model " lib = " Test . so " / >
Test.crv
3 < curve model = " Model " variable = " MODEL1_u " / >
4 < curve model = " Model " variable = " MODEL1_v " / >
5 < curve model = " Model " variable = " MODEL2_v " / >
6 </ curvesInput >
$ > cp compilation / Test . so / path / to / folder / with / input / files

$ > cd / path / to / folder / with / input / files
In this example the parameters in Model1 and Model2 are fixed at the com-
pilation of the model and to change them the compilation needs to be run
again.
The Dynaωo par files can be used to avoid recompiling models just to change
parameters value. To do so, the following par file needs to be created in the
same folder as the .so library:
Test.par
74
3 < set id = " 1 " >
4 < par type = " DOUBLE " name = " MODEL1_a " value = " 1. " / >
5 < par type = " DOUBLE " name = " MODEL1_b " value = " 1. " / >
6 < par type = " DOUBLE " name = " MODEL2_a " value = " .1 " / >
7 < par type = " DOUBLE " name = " MODEL2_b " value = " .1 " / >
8 </ set >
And the dyd file needs to be modified as follows:
1 < dyn : blackBoxModel id = " Model " lib = " Test . so "
parFile = " Test . par " parId = " 1 " / >
To modify Model2 parameters it is now enough to modify the par file and
regenerating the .so library is not required.
With different input files, it is also possible to let Dynaωo internally compiles
the model before launching the simulation. To do so, the following files need
to be created in the same folder as the Model1.mo and Model2.mo files:
Test.jobs
7 < dyn : pr ecompi ledMod els u seStan dardMo dels = " false " / >
8 < dyn : modelicaModels us eStan dardMo dels = " true " >
10 </ dyn : modelicaModels >
15 < dyn : logs >
17 < dyn : appender tag = " COMPILE "
file = " dynawoCompiler . log " lvlFilter = " DEBUG " / >
18 </ dyn : logs >
20 </ dyn : job >
21 </ dyn : jobs >
75
Test.dyd
4 < dyn : unitDynamicModel id = " MODEL1 " name = " Model1 "
moFile = " Model1 . mo " / >
5 < dyn : unitDynamicModel id = " MODEL2 " name = " Model2 "
moFile = " Model2 . mo " parFile = " Test . par " parId = " 1 " / >
var2 = " v " / >
Test.par
3 < set id = " 1 " >
4 < par type = " DOUBLE " name = " a " value = " .1 " / >
5 < par type = " DOUBLE " name = " b " value = " .1 " / >
6 </ set >
Test.crv
3 < curve model = " Test " variable = " MODEL1_u " / >
4 < curve model = " Test " variable = " MODEL1_v " / >
5 < curve model = " Test " variable = " MODEL2_v " / >
6 </ curvesInput >
Second example: Model with partially connected external vari-

ables
This second example is based on the previous one. The difference is that we
let one of the external variable unconnected so that it can be connected later
to another model that provides an equation for it.
The Model1.mo and Model1.xml files are the same as in the first example.
A new variable w is added to Model2.
76
Model2.mo
1 model Model2
4 Real v ( start = 2) ;
5 Real w ;
6 equation
7 a * der ( v ) = b * v ;
8 end Model2 ;
Model2.xml
2 < e xter na l_ va ri ab le s xmlns = " http :// www . rte - france . com / dynawo "
3 < variable type = " continuous " id = " v " / >
4 < variable type = " continuous " id = " w " / >
The same xml file is used as in the first example to connect those models:
Test.xml
var2 = " v " / >
The following commands generate the associated Test.so library and a Test.xml
file summarizing the external variables of the combined models:
$ > cd / path / to / Test . xml

$ > ls
Model1 . mo Model1 . xml Model2 . mo Model2 . xml Test . xml
$ > cp Model1 . mo Model2 . mo Model1 . xml Model2 . xml compilation
$ > $MY_ENV_DYNAWO generate - preassembled -- model - list
Test . xml -- output - dir compilation
-- non - recursive - modelica - models - dir .
77
Test.xml
1 <? xml version ="1.0" encoding =" ISO -8859 -1" standalone =" no " ? >
2 < e xter na l_ va ri ab le s xmlns = " http :// www . rte - france . com / dynawo " >
3 < variable id = " MODEL2 . w " type = " continuous " / >
w is thus an external variable of the compiled model, as expected.
Warning, at this point you cannot directly launch a simulation contain-

ing only this generated model as it needs to be connected to another model
providing the missing equation on w. Please refer to the first example for the
creation of such connection.
5.2.4 Generation of a xml summary of the parameters

and variables of a compiled model
The dump-model option takes as input a compiled Dynaωo model and generates
a xml file that contains a list of the parameters and variables of this model.
A summary of the possible arguments of the dump-model options can be ob-
tained with the following command:
$ > $MY_ENV_DYNAWO dump - model -- help
The following command is used to generate a xml summary of the parameters

and variables of a compiled model:
$ > $MY_ENV_DYNAWO dump - model -m ./ Test . so -o Test . desc . xml
Below is given an example of a file generated by this command based on the

model of the first example of section 5.2.3:
Test.desc.xml
1 <? xml version ="1.0" encoding =" ISO -8859 -1" standalone =" no " ? >
2 < model xmlns = " http :// www . rte - france . com / dynawo " >
3 < name > Test </ name >
4 < elements >
5 < parameters >
6 < parameter name = " MODEL1_a " valueType = " DOUBLE "
cardinality = " 1 " readOnly = " false " defaultValue = " 1 " / >
7 < parameter name = " MODEL1_b " valueType = " DOUBLE "
8 < parameter name = " MODEL2_a " valueType = " DOUBLE "
78
9 < parameter name = " MODEL2_b " valueType = " DOUBLE "
10 </ parameters >
11 < variables >
12 < variable name = " MODEL1_u " valueType = " DOUBLE " / >
13 < variable name = " MODEL1_v " valueType = " DOUBLE " / >
14 < variable name = " MODEL2_v " valueType = " DOUBLE " / >
15 </ variables >
16 </ elements >
17 </ model >
5.3 Adding a model to the Dynaωo library

5.3.1 Adding a Modelica model in the Dynaωo Mod-
elica library
If you develop a new Modelica model and want to use it seamlessly and of-
ten into Dynaωo simulations, it is better to add it to the Dynaωo library.
Otherwise, you will have to manually refer to the directory where it is stored
into all your simulations.
To do this, the best way is to include your Modelica model into the Dynawo
library part of the code: dynawo/sources/Models/Modelica/Dynawo/. You
need to add your mo file into one existing directory or create a new direc-
tory containing your mo file. If your model is not squared (not the same
number of equations than variables), you must supplement it with a xml file
(called external variable file) to describe the pending equations that will be
connected to your model later on (see 5.2.2).
You also need to :
• add the mo file into the package.order file that deals with display orders
into OpenModelica;
• add the mo and xml files into the CMakeFiles.txt file that will ensure
that the model is integrated into the library
If an initialization model (e.g. to calculate initial values from P, Q, U, θ val-

ues at the node) is needed, it must be also be put into the aforementioned
files.
79
For example, to add a FrequencyDependantLoad to the Dynaωo library, you
first need to create the Modelica model and the associated xml file to describe
the connections between your model and other models:
FrequencyLoad.mo
1 within D y n a w o . E l e c t r i c a l . L o a d s ;
2
3 /*
4 * Copyright ( c ) 2015 -2019 , RTE ( http :// www.rte - france.com )
5 * See AUTHORS.txt
6 * All rights reserved.
7 * This Source Code Form is subject to the terms of the
Mozilla Public
8 * License , v. 2 .0. If a copy of the MPL was not distributed
with this
9 * file , you can obtain one at http :// mozilla.org / MPL /2 .0 / .
10 * SPDX - License - Identifier : MPL -2 .0
11 *
12 * This file is part of Dynawo , an hybrid C ++/ Modelica open
source time domain simulation tool for power systems.
13 */
14
15 model FrequencyLoad " Load with frequency dependant active
and reactive power "
16 extends B a s e C l a s s e s . B a s e L o a d ;
17
18 public
19 parameter Real Gamma " Active load sensitivity to
frequency " ;
20 parameter Real Delta " Reactive load sensitivity to
voltage " ;
21 parameter Real omegaRef0Pu = 1 " Reference frequency
value " ;
22
23 Connectors.ImPin omegaRefPu " Network angular reference
frequency in p.u ( base OmegaNom ) " ;
24
25 equation
26 if ( running.value ) then
27 PPu = PLoadPu.value * (( omegaRefPu / omegaRef0Pu ) ^
Gamma ) ;
28 QPu = QLoadPu.value * (( omegaRefPu / omegaRef0Pu ) ^
Delta ) ;
29 else
30 terminal.i = Complex (0) ;
31 end if ;
32
33 end FrequencyLoad ;
80
FrequencyLoad.xml
2 <! - -
3 Copyright ( c ) 2015 -2019 , RTE ( http :// www . rte - france . com )
4 See AUTHORS . txt
5 All rights reserved .
6 This Source Code Form is subject to the terms of the
Mozilla Public
7 License , v . 2.0. If a copy of the MPL was not
distributed with this
8 file , you can obtain one at http :// mozilla . org / MPL /2.0/.
9 SPDX - License - Identifier : MPL -2.0
10
11 This file is part of Dynawo , an hybrid C ++/ Modelica open
source time domain
12 simulation tool for power systems .
13 -->
14 < e xt er na l_ va ri ab le s xmlns = " http :// www . rte - france . com / dynawo "
15 < variable type = " continuous " id = " terminal . V . re " / >
16 < variable type = " continuous " id = " terminal . V . im " / >
17 < variable type = " continuous " id = " omegaRefPu . value " / >
You then need to add these two files into the dynawo/sources/Models/
Modelica/Dynawo/Electrical/Loads repository and to update the CMake-
Lists.txt and package.order to take into account these two new files.
CMakeLists.txt
1 # Copyright ( c ) 2015 -2019 , RTE ( http :// www . rte - france . com )
2 # See AUTHORS . txt
3 # All rights reserved .
4 # This Source Code Form is subject to the terms of the
Mozilla Public
5 # License , v . 2.0. If a copy of the MPL was not distributed
with this
6 # file , you can obtain one at http :// mozilla . org / MPL /2.0/.
7 # SPDX - License - Identifier : MPL -2.0
8 #
9 # This file is part of Dynawo , an hybrid C ++/ Modelica open
source time domain simulation tool for power systems .
10
11 SET ( MODEL_FILES
12 # Electrical Loads models
13 package . mo
14 BaseClasses . mo
15 BaseClasses_INIT . mo
16 FrequencyLoad . mo
81
17 FrequencyLoad . xml
18 LoadAlphaBeta . mo
19 LoadAlphaBeta . xml
20 LoadPQ . mo
21 LoadPQ . xml
22 Load_INIT . mo
23 LoadConnect_INIT . mo
24 L o a d A u x i l i a r i e s _ I N I T . mo
25 SwitchOffLoad . xml
26 )
27
28 #
29 # Modelica models install
30 #
31 FOREACH ( MODEL_FILE $ { MODEL_FILES } )
32 I NST AL L_ MO DE L_ FI LE ( $ { MODEL_FILE })
33 ENDFOREACH ( MODEL_FILE )
package.order
1 BaseClasses
2 BaseClasses_INIT
3 LoadPQ
4 FrequencyLoad
5 LoadAlphaBeta
6 Load_INIT
7 LoadConnect_INIT
8 LoadAuxiliaries_INIT
Once this is done, the frequency load model could be directly used into a
dyd file in the following way. Notice that there is a connection between the
frequency load model and a set point to provide a value for ω to the model.
resources/exampleLibrary/testFrequencyLoadWithMo.dyd
2 <! - -
4 See AUTHORS . txt
Mozilla Public
10
source time domain
82
13 -->
15 < dyn : modelicaModel id = " Te st _L oad Fr eq ue nc y " >
16 < dyn : unitDynamicModel id = " Generator "
name = " Dynawo . Electrical . Machines . GeneratorPQ "
initName
= " Dynawo . Electrical . Machines . GeneratorPQ_INIT "
parFile = " Load . par " parId = " 1 " / >
17 < dyn : unitDynamicModel id = " Line "
name = " Dynawo . Electrical . Lines . Line "
18 < dyn : unitDynamicModel id = " infBus "
name = " Dynawo . Electrical . Buses . InfiniteBus "
19 < dyn : unitDynamicModel id = " Load "
name = " Dynawo . Electrical . Loads . FrequencyLoad "
parFile = " Load . par " parId = " 4 "
initName = " Dynawo . Electrical . Loads . Load_INIT " / >
20 < dyn : connect id1 = " Line " var1 = " terminal1 " id2 = " Generator "
var2 = " terminal " / >
21 < dyn : connect id1 = " Line " var1 = " terminal2 " id2 = " infBus "
22 < dyn : connect id1 = " Generator " var1 = " terminal " id2 = " Load "
24 < dyn : blackBoxModel id = " SP_Omega " lib = " SET_POINT . so "
25 < dyn : connect id1 = " SP_Omega " var1 = " SP_setPoint "
id2 = " Te st _L oa dF re qu enc y " var2 = " G e n e r a t o r _ o m e g a R e f P u " / >
26 < dyn : blackBoxModel id = " SP_Omega2 " lib = " SET_POINT . so "
27 < dyn : connect id1 = " SP_Omega2 " var1 = " SP_setPoint "
id2 = " Te st _L oa dF re qu enc y " var2 = " Load_omegaRefPu " / >
5.3.2 Adding a Modelica model in the Dynaωo pre-

compiled library
In the example from the previous section, the model is only available as a .mo
file that is compiled at run-time. If you envision to use a model in different
simulations, it is recommended to also add it into the list of the precom-
piled models to be able to use it as a black-box model during the simulations
(calling the .so library generated by Dynaωo compilation). We recommend
doing preassembled models that correspond to a dynamic behaviour for one
83
component e.g. having different precompiled models for the loads: voltage-
dependant load, frequency-dependant load. . .
To create a preassembled model corresponding to the frequency-dependant

load model, it is necessary to add a new xml file into the preassembled models
directory dynawo/sources/Models/Modelica/PreassembledModels/. This
xml file name should be added into the CMakeLists.txt of the directory to
be compiled.
FrequencyLoadPAM.xml
2 <! - -
4 See AUTHORS . txt
Mozilla Public
10
source time domain
13 -->
15 <! - - Frequency Load Model -->
16 < dyn : modelicaModel id = " FrequencyLoad " >
17 < dyn : unitDynamicModel id = " LOAD "
name = " Dynawo . Electrical . Loads . FrequencyLoad "
initName = " Dynawo . Electrical . Loads . Load_INIT " / >
Once this is done, the model can be used as a black-box model into the
simulations.
testFrequencyLoadWithSo.dyd
2 <! - -
4 See AUTHORS . txt
84
Mozilla Public
10
source time domain
13 -->
15 < dyn : modelicaModel id = " Te st _L oad Fr eq ue nc y " >
16 < dyn : unitDynamicModel id = " Generator "
name = " Dynawo . Electrical . Machines . GeneratorPQ "
initName
= " Dynawo . Electrical . Machines . GeneratorPQ_INIT "
17 < dyn : unitDynamicModel id = " Line "
name = " Dynawo . Electrical . Lines . Line "
18 < dyn : unitDynamicModel id = " infBus "
name = " Dynawo . Electrical . Buses . InfiniteBus "
19 < dyn : connect id1 = " Line " var1 = " terminal1 " id2 = " Generator "
20 < dyn : connect id1 = " Line " var1 = " terminal2 " id2 = " infBus "
22 < dyn : blackBoxModel id = " Load " lib = " FrequencyLoad . so "
23 < dyn : connect id1 = " Load " var1 = " LOAD_terminal "
id2 = " Te st _L oa dF re qu enc y " var2 = " Ge ne ra to r_ te rm in al " / >
24 < dyn : blackBoxModel id = " SP_Omega " lib = " SET_POINT . so "
25 < dyn : connect id1 = " SP_Omega " var1 = " SP_setPoint "
id2 = " Te st _L oa dF re qu enc y " var2 = " G e n e r a t o r _ o m e g a R e f P u " / >
26 < dyn : blackBoxModel id = " SP_Omega2 " lib = " SET_POINT . so "
27 < dyn : connect id1 = " SP_Omega2 " var1 = " SP_setPoint " id2 = " Load "
var2 = " LOAD_omegaRefPu " / >
5.4 Adding a new solver

New solvers could easily be added into Dynaωo. Indeed, the architecture is
very generic and a basic common class has been defined (dynawo/sources/
85
Solvers/Common/DYNSolver.h) that gives all the methods that a solver
needs to implement to be integrated into the Dynaωo frame. The most
important ones are:
• the calculateIC method dealing with the initialization step;
• the solve method resolving the DAE problem for each time step;
• the reinit method is in charge of the algebraic equation restoration

when this step is needed.
If you want to add your own solver implementation, the simplest way is to
create a new directory SolverX and then to implement your solver there. You
can have a look to the SolverIDA and SolverSIM directories ; the first one
shows how to get connected to an existing solver library whereas the second
one is an example of a solver implementation specific to Dynaωo. Once it is
done and the solver compiled, you can use it directly into the jobs file in a
similar way than existing Dynaωo solvers.
86
Bibliography
[1] Modelica - a unified object-oriented language for physical systems mod-

eling - language specification - version 3.4, 04 2010.
[2] X. Chen, Y. Wang, and H. Yang. Nicslu: An adaptive sparse matrix

solver for parallel circuit simulation. Computer-Aided Design of Inte-
grated Circuits and Systems, IEEE Transactions on, 32(2):261 –274, feb.
2013.
[3] CRSA, RTE, TE, and TU/e. D4.1: Algorithmic requirements for simu-
lation of large network extreme scenarios. Technical report, tech. rep.,
PEGASE Consortium, 2011.
[4] T. A. Davis and E. Palamadai Natarajan. Algorithm 907: Klu, a direct

sparse solver for circuit simulation problems. ACM Trans. Math. Softw.,
37(3):36:1–36:17, Sept. 2010.
[5] D. Fabozzi and T. V. Cutsem. Simplified time-domain simulation of

detailed long-term dynamic models. In 2009 IEEE Power & Energy
Society General Meeting. IEEE, jul 2009.
[6] D. Fabozzi, T. V. Cutsem, A. Chieh, and P. Panciatici. On simplified

handling of state events in time-domain simulation. In Proc. of the 17th
Power System Computation Conference PSCC, 2011.
[7] P. Fritzson et al. Openmodelica system documentation, Feb. 2014.
[8] P.-M. Gibert, R. Losseau, A. Guironnet, P. Panciatici, D. Tromeur-

Dervout, and J. Erhel. Use of the sinusoidal predictor method within
a fully separated modeler/solver framework for fast and flexible EMT
simulations. In Proceedings of 8th International Conference on Sim-
ulation and Modeling Methodologies, Technologies and Applications.
SCITEPRESS - Science and Technology Publications, 2018.
87
[9] P.-M. Gibert, D. Tromeur-Dervout, P. Panciatici, F. Beaude, P. Wang,
and J. Erhel. A generic customized predictor corrector approach for
accelerating EMTP-like simulations. In 2017 IEEE Manchester Pow-
erTech. IEEE, jun 2017.
[10] A. Guironnet, M. Saugier, S. Petitrenaud, F. Xavier, and P.Panciatici.

Towards an open-source solution using Modelica for time-domain simu-
lation of power systems. In Proc. 8th IEEE PES ISGT Europe, Sarajevo,
Bosnia and Herzegovina, Oct 21–25 2018.
[11] A. C. Hindmarsh, P. N. Brown, K. E. Grant, S. L. Lee, R. Serban,

D. E. Shumaker, and C. S. Woodward. SUNDIALS: Suite of nonlin-
ear and differential/algebraic equation solvers. ACM Transactions on
Mathematical Software (TOMS), 31(3):363–396, 2005.
[12] R. J. Hogan. Fast reverse-mode automatic differentiation using expres-

sion templates in c++. ACM Trans. Math. Softw., 40(4):26:1–26:16,
July 2014.
[13] R. J. Hogan. Adept 2.0: a combined automatic differentiation and array

library for C++, Oct. 2017.
88
A Dynaωo License
89
Mozilla Public License Version 2.0
1 Definitions
1.1 “Contributor”
means each individual or legal entity that creates, contributes to the creation
of, or owns Covered Software.
1.2 “Contributor Version”

means the combination of the Contributions of others (if any) used by a
Contributor and that particular Contributor’s Contribution.
1.3 “Contribution”
means Covered Software of a particular Contributor.
1.4 “Covered Software”

means Source Code Form to which the initial Contributor has attached the
notice in Exhibit A, the Executable Form of such Source Code Form, and
Modifications of such Source Code Form, in each case including portions
thereof.
1.5 “Incompatible With Secondary Licenses”

means
(a) that the initial Contributor has attached the notice described in Exhibit
B to the Covered Software; or
(b) that the Covered Software was made available under the terms of ver-
sion 1.1 or earlier of the License, but not also under the terms of a
Secondary License.
90
1.6 “Executable Form”
means any form of the work other than Source Code Form.
1.7 “Larger Work”

means a work that combines Covered Software with other material, in a
separate file or files, that is not Covered Software.
1.8 “License”
means this document.
1.9 “Licensable”
means having the right to grant, to the maximum extent possible, whether
at the time of the initial grant or subsequently, any and all of the rights
conveyed by this License.
1.10 “Modifications”
means any of the following:
(a) any file in Source Code Form that results from an addition to, deletion
from, or modification of the contents of Covered Software; or
(b) any new file in Source Code Form that contains any Covered Software.
1.11 “Patent Claims” of a Contributor

means any patent claim(s), including without limitation, method, process,
and apparatus claims, in any patent Licensable by such Contributor that
would be infringed, but for the grant of the License, by the making, us-
ing, selling, offering for sale, having made, import, or transfer of either its
Contributions or its Contributor Version.
1.12 “Secondary License”

means either the GNU General Public License, Version 2.0, the GNU Lesser
General Public License, Version 2.1, the GNU Affero General Public License,
Version 3.0, or any later versions of those licenses.
91
1.13 “Source Code Form”
means the form of the work preferred for making modifications.
1.14 “You” (or “Your”)

means an individual or a legal entity exercising rights under this License. For
legal entities, “You” includes any entity that controls, is controlled by, or is
under common control with You. For purposes of this definition, “control”
means (a) the power, direct or indirect, to cause the direction or management
of such entity, whether by contract or otherwise, or (b) ownership of more
than fifty percent (50%) of the outstanding shares or beneficial ownership of
such entity.
2 License Grants and Conditions

2.1 Grants
Each Contributor hereby grants You a world-wide, royalty-free, non-exclusive
license:
(a) under intellectual property rights (other than patent or trademark) Li-
censable by such Contributor to use, reproduce, make available, modify,
display, perform, distribute, and otherwise exploit its Contributions, ei-
ther on an unmodified basis, with Modifications, or as part of a Larger
Work; and
(b) under Patent Claims of such Contributor to make, use, sell, offer for
sale, have made, import, and otherwise transfer either its Contributions
or its Contributor Version.
2.2 Effective Date

The licenses granted in Section 2.1 with respect to any Contribution become
effective for each Contribution on the date the Contributor first distributes
such Contribution.
2.3 Limitations on Grant Scope

The licenses granted in this Section 2 are the only rights granted under this
License. No additional rights or licenses will be implied from the distribution
92
or licensing of Covered Software under this License. Notwithstanding Section
2.1(b) above, no patent license is granted by a Contributor:
(a) for any code that a Contributor has removed from Covered Software;
or
(b) for infringements caused by: (i) Your and any other third party’s mod-
ifications of Covered Software, or (ii) the combination of its Contribu-
tions with other software (except as part of its Contributor Version);
or
(c) under Patent Claims infringed by Covered Software in the absence of

its Contributions.
This License does not grant any rights in the trademarks, service marks,
or logos of any Contributor (except as may be necessary to comply with the
notice requirements in Section 3.4).
2.4 Subsequent Licenses

No Contributor makes additional grants as a result of Your choice to dis-
tribute the Covered Software under a subsequent version of this License (see
Section 10.2) or under the terms of a Secondary License (if permitted under
the terms of Section 3.3).
2.5 Representation
Each Contributor represents that the Contributor believes its Contributions
are its original creation(s) or it has sufficient rights to grant the rights to its
Contributions conveyed by this License.
2.6 Fair Use

This License is not intended to limit any rights You have under applicable
copyright doctrines of fair use, fair dealing, or other equivalents.
2.7 Conditions
Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted in Section
2.1.
93
3 Responsibilities
3.1 Distribution of Source Form
All distribution of Covered Software in Source Code Form, including any
Modifications that You create or to which You contribute, must be under
the terms of this License. You must inform recipients that the Source Code
Form of the Covered Software is governed by the terms of this License, and
how they can obtain a copy of this License. You may not attempt to alter
or restrict the recipients’ rights in the Source Code Form.
3.2 Distribution of Executable Form

If You distribute Covered Software in Executable Form then:
(a) such Covered Software must also be made available in Source Code
Form, as described in Section 3.1, and You must inform recipients of
the Executable Form how they can obtain a copy of such Source Code
Form by reasonable means in a timely manner, at a charge no more
than the cost of distribution to the recipient; and
(b) You may distribute such Executable Form under the terms of this Li-
cense, or sublicense it under different terms, provided that the license
for the Executable Form does not attempt to limit or alter the recipi-
ents’ rights in the Source Code Form under this License.
3.3 Distribution of a Larger Work

You may create and distribute a Larger Work under terms of Your choice,
provided that You also comply with the requirements of this License for the
Covered Software. If the Larger Work is a combination of Covered Software
with a work governed by one or more Secondary Licenses, and the Covered
Software is not Incompatible With Secondary Licenses, this License permits
You to additionally distribute such Covered Software under the terms of such
Secondary License(s), so that the recipient of the Larger Work may, at their
option, further distribute the Covered Software under the terms of either this
License or such Secondary License(s).
3.4 Notices
You may not remove or alter the substance of any license notices (including
copyright notices, patent notices, disclaimers of warranty, or limitations of
94
liability) contained within the Source Code Form of the Covered Software,
except that You may alter any license notices to the extent required to remedy
known factual inaccuracies.
3.5 Application of Additional Terms

You may choose to offer, and to charge a fee for, warranty, support, indem-
nity or liability obligations to one or more recipients of Covered Software.
However, You may do so only on Your own behalf, and not on behalf of
any Contributor. You must make it absolutely clear that any such warranty,
support, indemnity, or liability obligation is offered by You alone, and You
hereby agree to indemnify every Contributor for any liability incurred by such
Contributor as a result of warranty, support, indemnity or liability terms You
offer. You may include additional disclaimers of warranty and limitations of
liability specific to any jurisdiction.
4 Inability to Comply Due to Statute or Reg-

ulation
If it is impossible for You to comply with any of the terms of this License
with respect to some or all of the Covered Software due to statute, judicial
order, or regulation then You must: (a) comply with the terms of this License
to the maximum extent possible; and (b) describe the limitations and the
code they affect. Such description must be placed in a text file included
with all distributions of the Covered Software under this License. Except
to the extent prohibited by statute or regulation, such description must be
sufficiently detailed for a recipient of ordinary skill to be able to understand
it.
5 Termination
5.1
The rights granted under this License will terminate automatically if You
fail to comply with any of its terms. However, if You become compliant,
then the rights granted under this License from a particular Contributor
are reinstated (a) provisionally, unless and until such Contributor explicitly
and finally terminates Your grants, and (b) on an ongoing basis, if such
Contributor fails to notify You of the non-compliance by some reasonable
95
means prior to 60 days after You have come back into compliance. Moreover,
Your grants from a particular Contributor are reinstated on an ongoing basis
if such Contributor notifies You of the non-compliance by some reasonable
means, this is the first time You have received notice of non-compliance with
this License from such Contributor, and You become compliant prior to 30
days after Your receipt of the notice.
5.2
If You initiate litigation against any entity by asserting a patent infringement
claim (excluding declaratory judgment actions, counter-claims, and cross-
claims) alleging that a Contributor Version directly or indirectly infringes
any patent, then the rights granted to You by any and all Contributors for
the Covered Software under Section 2.1 of this License shall terminate.
5.3
In the event of termination under Sections 5.1 or 5.2 above, all end user license
agreements (excluding distributors and resellers) which have been validly
granted by You or Your distributors under this License prior to termination
shall survive termination.
6 Disclaimer of Warranty
Covered Software is provided under this License on an “as is” basis, with-
out warranty of any kind, either expressed, implied, or statutory, including,
without limitation, warranties that the Covered Software is free of defects,
merchantable, fit for a particular purpose or non-infringing. The entire risk as
to the quality and performance of the Covered Software is with You. Should
any Covered Software prove defective in any respect, You (not any Contrib-
utor) assume the cost of any necessary servicing, repair, or correction. This
disclaimer of warranty constitutes an essential part of this License. No use
of any Covered Software is authorized under this License except under this
disclaimer.
7 Limitation of Liability
Under no circumstances and under no legal theory, whether tort (including
negligence), contract, or otherwise, shall any Contributor, or anyone who
distributes Covered Software as permitted above, be liable to You for any
96
direct, indirect, special, incidental, or consequential damages of any charac-
ter including, without limitation, damages for lost profits, loss of goodwill,
work stoppage, computer failure or malfunction, or any and all other com-
mercial damages or losses, even if such party shall have been informed of the
possibility of such damages. This limitation of liability shall not apply to
liability for death or personal injury resulting from such party’s negligence
to the extent applicable law prohibits such limitation. Some jurisdictions do
not allow the exclusion or limitation of incidental or consequential damages,
so this exclusion and limitation may not apply to You.
8 Litigation
Any litigation relating to this License may be brought only in the courts of a
jurisdiction where the defendant maintains its principal place of business and
such litigation shall be governed by laws of that jurisdiction, without refer-
ence to its conflict-of-law provisions. Nothing in this Section shall prevent a
party’s ability to bring cross-claims or counter-claims.
9 Miscellaneous
This License represents the complete agreement concerning the subject mat-
ter hereof. If any provision of this License is held to be unenforceable, such
provision shall be reformed only to the extent necessary to make it enforce-
able. Any law or regulation which provides that the language of a contract
shall be construed against the drafter shall not be used to construe this Li-
cense against a Contributor.
10 Versions of the License

10.1 New Versions
Mozilla Foundation is the license steward. Except as provided in Section 10.3,
no one other than the license steward has the right to modify or publish new
versions of this License. Each version will be given a distinguishing version
number.
97
10.2 Effect of New Versions
You may distribute the Covered Software under the terms of the version of
the License under which You originally received the Covered Software, or
under the terms of any subsequent version published by the license steward.
10.3 Modified Versions

If you create software not governed by this License, and you want to create a
new license for such software, you may create and use a modified version of
this License if you rename the license and remove any references to the name
of the license steward (except to note that such modified license differs from
this License).
10.4 Distributing Source Code Form that is Incompat-

ible With Secondary Licenses
If You choose to distribute Source Code Form that is Incompatible With
Secondary Licenses under the terms of this version of the License, the notice
described in Exhibit B of this License must be attached.
Exhibit A - Source Code Form License Notice

This Source Code Form is subject to 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/.
If it is not possible or desirable to put the notice in a particular file,
then You may include the notice in a location (such as a LICENSE file in a
relevant directory) where a recipient would be likely to look for such a notice.
You may add additional accurate notices of copyright ownership.
Exhibit B - “Incompatible With Secondary Li-

censes” Notice
This Source Code Form is “Incompatible With Secondary Licenses”, as de-
fined by the Mozilla Public License, v. 2.0.
98
B Dynaωo Documentation License
99
Creative Commons Attribution-ShareAlike 4.0
Creative Commons Attribution-ShareAlike 4.0 International Creative Com-

mons Corporation (“Creative Commons”) is not a law firm and does not
provide legal services or legal advice. Distribution of Creative Commons
public licenses does not create a lawyer-client or other relationship. Creative
Commons makes its licenses and related information available on an “as-is”
basis. Creative Commons gives no warranties regarding its licenses, any ma-
terial licensed under their terms and conditions, or any related information.
Creative Commons disclaims all liability for damages resulting from their use
to the fullest extent possible.
Using Creative Commons Public Licenses
Creative Commons public licenses provide a standard set of terms and condi-
tions that creators and other rights holders may use to share original works of
authorship and other material subject to copyright and certain other rights
specified in the public license below. The following considerations are for
informational purposes only, are not exhaustive, and do not form part of our
licenses.
Considerations for licensors: Our public licenses are intended for use by those
authorized to give the public permission to use material in ways otherwise
restricted by copyright and certain other rights. Our licenses are irrevocable.
Licensors should read and understand the terms and conditions of the license
they choose before applying it. Licensors should also secure all rights nec-
essary before applying our licenses so that the public can reuse the material
as expected. Licensors should clearly mark any material not subject to the
license. This includes other CC-licensed material, or material used under
an exception or limitation to copyright. More considerations for licensors :
wiki.creativecommons.org/Considerations for licensors
Considerations for the public: By using one of our public licenses, a licensor
grants the public permission to use the licensed material under specified terms
100
and conditions. If the licensor’s permission is not necessary for any reasonfor
example, because of any applicable exception or limitation to copyrightthen
that use is not regulated by the license. Our licenses grant only permissions
under copyright and certain other rights that a licensor has authority to
grant. Use of the licensed material may still be restricted for other reasons,
including because others have copyright or other rights in the material. A
licensor may make special requests, such as asking that all changes be marked
or described.
Although not required by our licenses, you are encouraged to respect those
requests where reasonable. More considerations for the public :
wiki.creativecommons.org/Considerations for licensees
Creative Commons Attribution-ShareAlike 4.0 International Public License
By exercising the Licensed Rights (defined below), You accept and agree to
be bound by the terms and conditions of this Creative Commons Attribution-
ShareAlike 4.0 International Public License (“Public License”). To the ex-
tent this Public License may be interpreted as a contract, You are granted
the Licensed Rights in consideration of Your acceptance of these terms and
conditions, and the Licensor grants You such rights in consideration of bene-
fits the Licensor receives from making the Licensed Material available under
these terms and conditions.
Section 1 Definitions.
a. Adapted Material means material subject to Copyright and Similar
Rights that is derived from or based upon the Licensed Material and
in which the Licensed Material is translated, altered, arranged, trans-
formed, or otherwise modified in a manner requiring permission under
the Copyright and Similar Rights held by the Licensor. For purposes
of this Public License, where the Licensed Material is a musical work,
performance, or sound recording, Adapted Material is always produced
where the Licensed Material is synched in timed relation with a moving
image.
b. Adapter’s License means the license You apply to Your Copyright

and Similar Rights in Your contributions to Adapted Material in ac-
cordance with the terms and conditions of this Public License.
c. BY-SA Compatible License means a license listed at creativecom-
101
mons.org/compatiblelicenses, approved by Creative Commons as es-
sentially the equivalent of this Public License.
d. Copyright and Similar Rights means copyright and/or similar rights

closely related to copyright including, without limitation, performance,
broadcast, sound recording, and Sui Generis Database Rights, without
regard to how the rights are labeled or categorized. For purposes of
this Public License, the rights specified in Section 2(b)(1)-(2) are not
Copyright and Similar Rights.
e. Effective Technological Measures means those measures that, in

the absence of proper authority, may not be circumvented under laws
fulfilling obligations under Article 11 of the WIPO Copyright Treaty
adopted on December 20, 1996, and/or similar international agree-
ments.
f. Exceptions and Limitations means fair use, fair dealing, and/or

any other exception or limitation to Copyright and Similar Rights that
applies to Your use of the Licensed Material.
g. License Elements means the license attributes listed in the name of

a Creative Commons Public License. The License Elements of this
Public License are Attribution and ShareAlike.
h. Licensed Material means the artistic or literary work, database, or

other material to which the Licensor applied this Public License.
i. Licensed Rights means the rights granted to You subject to the terms
and conditions of this Public License, which are limited to all Copyright
and Similar Rights that apply to Your use of the Licensed Material and
that the Licensor has authority to license.
j. Licensor means the individual(s) or entity(ies) granting rights under

this Public License.
k. Share means to provide material to the public by any means or process

that requires permission under the Licensed Rights, such as reproduc-
tion, public display, public performance, distribution, dissemination,
communication, or importation, and to make material available to the
public including in ways that members of the public may access the
material from a place and at a time individually chosen by them.
l. Sui Generis Database Rights means rights other than copyright

resulting from Directive 96/9/EC of the European Parliament and of
102
the Council of 11 March 1996 on the legal protection of databases,
as amended and/or succeeded, as well as other essentially equivalent
rights anywhere in the world.
m. You means the individual or entity exercising the Licensed Rights un-
der this Public License. Your has a corresponding meaning.
Section 2 Scope.
a. License grant.
1. Subject to the terms and conditions of this Public License, the Licensor
hereby grants You a worldwide, royalty-free, non-sublicensable, non-
exclusive, irrevocable license to exercise the Licensed Rights in the
Licensed Material to:
A. reproduce and Share the Licensed Material, in whole or in part;
and
B. produce, reproduce, and Share Adapted Material.
2. Exceptions and Limitations. For the avoidance of doubt, where Excep-
tions and Limitations apply to Your use, this Public License does not
apply, and You do not need to comply with its terms and conditions.
3. Term. The term of this Public License is specified in Section 6(a).
4. Media and formats; technical modifications allowed. The Licensor au-
thorizes You to exercise the Licensed Rights in all media and formats
whether now known or hereafter created, and to make technical mod-
ifications necessary to do so. The Licensor waives and/or agrees not
to assert any right or authority to forbid You from making techni-
cal modifications necessary to exercise the Licensed Rights, including
technical modifications necessary to circumvent Effective Technological
Measures. For purposes of this Public License, simply making modi-
fications authorized by this Section 2(a)(4) never produces Adapted
Material.
5. Downstream recipients.
A. Offer from the Licensor Licensed Material. Every recipient of the
Licensed Material automatically receives an offer from the Licen-
sor to exercise the Licensed Rights under the terms and conditions
of this Public License.
103
B. Additional offer from the Licensor Adapted Material. Every re-
cipient of Adapted Material from You automatically receives an
offer from the Licensor to exercise the Licensed Rights in the
Adapted Material under the conditions of the Adapter’s License
You apply.
C. No downstream restrictions. You may not offer or impose any
additional or different terms or conditions on, or apply any Ef-
fective Technological Measures to, the Licensed Material if doing
so restricts exercise of the Licensed Rights by any recipient of the
Licensed Material.
D. No endorsement. Nothing in this Public License constitutes or
may be construed as permission to assert or imply that You are,
or that Your use of the Licensed Material is, connected with, or
sponsored, endorsed, or granted official status by, the Licensor
or others designated to receive attribution as provided in Section
3(a)(1)(A)(i).
b. Other rights.
1. Moral rights, such as the right of integrity, are not licensed under this
Public License, nor are publicity, privacy, and/or other similar person-
ality rights; however, to the extent possible, the Licensor waives and/or
agrees not to assert any such rights held by the Licensor to the limited
extent necessary to allow You to exercise the Licensed Rights, but not
otherwise.
2. Patent and trademark rights are not licensed under this Public License.
3. To the extent possible, the Licensor waives any right to collect royal-
ties from You for the exercise of the Licensed Rights, whether directly
or through a collecting society under any voluntary or waivable statu-
tory or compulsory licensing scheme. In all other cases the Licensor
expressly reserves any right to collect such royalties.
Section 3 License Conditions.

Your exercise of the Licensed Rights is expressly made subject to the following
conditions.
104
a. Attribution.
1. If You Share the Licensed Material (including in modified form), You
must:
A. retain the following if it is supplied by the Licensor with the Li-

censed Material:
i. identification of the creator(s) of the Licensed Material and
any others designated to receive attribution, in any reasonable
manner requested by the Licensor (including by pseudonym
if designated);
ii. a copyright notice;
iii. a notice that refers to this Public License;
iv. a notice that refers to the disclaimer of warranties;
v. a URI or hyperlink to the Licensed Material to the extent
reasonably practicable;
B. indicate if You modified the Licensed Material and retain an in-
dication of any previous modifications; and
C. indicate the Licensed Material is licensed under this Public Li-
cense, and include the text of, or the URI or hyperlink to, this
Public License.
2. You may satisfy the conditions in Section 3(a)(1) in any reasonable

manner based on the medium, means, and context in which You Share
the Licensed Material. For example, it may be reasonable to satisfy the
conditions by providing a URI or hyperlink to a resource that includes
the required information.
3. If requested by the Licensor, You must remove any of the information

required by Section 3(a)(1)(A) to the extent reasonably practicable.
b. ShareAlike.
In addition to the conditions in Section 3(a), if You Share Adapted Material
You produce, the following conditions also apply.
1. The Adapter’s License You apply must be a Creative Commons license

with the same License Elements, this version or later, or a BY-SA
Compatible License.
105
2. You must include the text of, or the URI or hyperlink to, the Adapter’s
License You apply. You may satisfy this condition in any reasonable
manner based on the medium, means, and context in which You Share
Adapted Material.
3. You may not offer or impose any additional or different terms or con-
ditions on, or apply any Effective Technological Measures to, Adapted
Material that restrict exercise of the rights granted under the Adapter’s
License You apply.
Section 4 Sui Generis Database Rights.

Where the Licensed Rights include Sui Generis Database Rights that apply
to Your use of the Licensed Material:
a. for the avoidance of doubt, Section 2(a)(1) grants You the right to
extract, reuse, reproduce, and Share all or a substantial portion of the
contents of the database;
b. if You include all or a substantial portion of the database contents
in a database in which You have Sui Generis Database Rights, then
the database in which You have Sui Generis Database Rights (but not
its individual contents) is Adapted Material, including for purposes of
Section 3(b); and
c. You must comply with the conditions in Section 3(a) if You Share all
or a substantial portion of the contents of the database.
For the avoidance of doubt, this Section 4 supplements and does not replace
Your obligations under this Public License where the Licensed Rights include
other Copyright and Similar Rights.
Section 5 Disclaimer of Warranties and Limi-

tation of Liability.
a. Unless otherwise separately undertaken by the Licensor, to
the extent possible, the Licensor offers the Licensed Material
as-is and as-available, and makes no representations or war-
ranties of any kind concerning the Licensed Material, whether
express, implied, statutory, or other. This includes, with-
out limitation, warranties of title, merchantability, fitness for
106
a particular purpose, non-infringement, absence of latent or
other defects, accuracy, or the presence or absence of errors,
whether or not known or discoverable. Where disclaimers of
warranties are not allowed in full or in part, this disclaimer
may not apply to You.
b. To the extent possible, in no event will the Licensor be li-

able to You on any legal theory (including, without limitation,
negligence) or otherwise for any direct, special, indirect, in-
cidental, consequential, punitive, exemplary, or other losses,
costs, expenses, or damages arising out of this Public License
or use of the Licensed Material, even if the Licensor has been
advised of the possibility of such losses, costs, expenses, or
damages. Where a limitation of liability is not allowed in full
or in part, this limitation may not apply to You.
c. The disclaimer of warranties and limitation of liability provided above

shall be interpreted in a manner that, to the extent possible, most
closely approximates an absolute disclaimer and waiver of all liability.
Section 6 Term and Termination.

a. This Public License applies for the term of the Copyright and Similar
Rights licensed here. However, if You fail to comply with this Public
License, then Your rights under this Public License terminate automat-
ically.
b. Where Your right to use the Licensed Material has terminated under
Section 6(a), it reinstates:
1. automatically as of the date the violation is cured, provided it is

cured within 30 days of Your discovery of the violation; or
2. upon express reinstatement by the Licensor.
c. For the avoidance of doubt, this Section 6(b) does not affect any right
the Licensor may have to seek remedies for Your violations of this
Public License.
d. For the avoidance of doubt, the Licensor may also offer the Licensed
Material under separate terms or conditions or stop distributing the
Licensed Material at any time; however, doing so will not terminate
this Public License.
107
e. Sections 1, 5, 6, 7, and 8 survive termination of this Public License.
Section 7 Other Terms and Conditions.

a. The Licensor shall not be bound by any additional or different terms
or conditions communicated by You unless expressly agreed.
b. Any arrangements, understandings, or agreements regarding the Li-

censed Material not stated herein are separate from and independent
of the terms and conditions of this Public License.
Section 8 Interpretation.
a. For the avoidance of doubt, this Public License does not, and shall
not be interpreted to, reduce, limit, restrict, or impose conditions on
any use of the Licensed Material that could lawfully be made without
permission under this Public License.
b. To the extent possible, if any provision of this Public License is deemed

unenforceable, it shall be automatically reformed to the minimum ex-
tent necessary to make it enforceable. If the provision cannot be re-
formed, it shall be severed from this Public License without affecting
the enforceability of the remaining terms and conditions.
c. No term or condition of this Public License will be waived and no failure

to comply consented to unless expressly agreed to by the Licensor.
d. Nothing in this Public License constitutes or may be interpreted as

a limitation upon, or waiver of, any privileges and immunities that
apply to the Licensor or You, including from the legal processes of any
jurisdiction or authority.
Creative Commons is not a party to its public licenses. Notwithstanding,

Creative Commons may elect to apply one of its public licenses to material it
publishes and in those instances will be considered the “Licensor.” The text
of the Creative Commons public licenses is dedicated to the public domain
under the CC0 Public Domain Dedication. Except for the limited purpose
of indicating that material is shared under a Creative Commons public li-
cense or as otherwise permitted by the Creative Commons policies published
108
at creativecommons.org/policies, Creative Commons does not authorize the
use of the trademark “Creative Commons” or any other trademark or logo of
Creative Commons without its prior written consent including, without limi-
tation, in connection with any unauthorized modifications to any of its public
licenses or any other arrangements, understandings, or agreements concern-
ing use of licensed material. For the avoidance of doubt, this paragraph does
not form part of the public licenses.
Creative Commons may be contacted at creativecommons.org.
109
C OpenModelica License
110
Open Source Modelica Consortium (OSMC)
Public License (OSMC-PL)
— Start of Definition of OSMC Public License —

/∗
∗ This f i l e i s p a r t o f OpenModelica .
∗
∗ C o p y r i g h t ( c ) 1998−CurrentYear , Open Source
Modelica Consortium (OSMC) ,
∗ c /o L i n k p i n g s u n i v e r s i t e t , Department o f Computer
and I n f o r m a t i o n S c i e n c e ,
∗ SE−58183 L i n k p i n g , Sweden .
∗
∗ All rights reserved .
∗
∗ THIS PROGRAM IS PROVIDED UNDER THE TERMS OF GPL
VERSION 3 LICENSE OR
∗ THIS OSMC PUBLIC LICENSE (OSMC−PL) VERSION 1 . 2 .
∗ ANY USE, REPRODUCTION OR DISTRIBUTION OF THIS
PROGRAM CONSTITUTES
∗ RECIPIENT ’ S ACCEPTANCE OF THE OSMC PUBLIC LICENSE
OR THE GPL VERSION 3 ,
∗ ACCORDING TO RECIPIENTS CHOICE.
∗
∗ The OpenModelica s o f t w a r e and t h e Open Source
Modelica
∗ Consortium (OSMC) P u b l i c L i c e n s e (OSMC−PL) are
obtained
∗ from OSMC, e i t h e r from t h e above a d d r e s s ,
∗ from t h e URLs :
h t t p : / /www. i d a . l i u . s e / p r o j e c t s / OpenModelica or
∗ h t t p : / /www. openm od e lica . org , and i n t h e
OpenModelica d i s t r i b u t i o n .
111
∗ GNU v e r s i o n 3 i s o b t a i n e d from :
h t t p : / /www. gnu . org / c o p y l e f t / g p l . html .
∗
∗ This program i s d i s t r i b u t e d WITHOUT ANY WARRANTY;
without
∗ even t h e i m p l i e d warranty o f MERCHANTABILITY or
FITNESS
∗ FOR A PARTICULAR PURPOSE, EXCEPT AS EXPRESSLY SET
FORTH
∗ IN THE BY RECIPIENT SELECTED SUBSIDIARY LICENSE
CONDITIONS OF OSMC−PL .
∗
∗ See t h e f u l l OSMC P u b l i c L i c e n s e c o n d i t i o n s f o r
more d e t a i l s .
∗
∗/
— End of OSMC Public License Header —
The OSMC-PL is a public license for OpenModelica with three modes/al-

ternatives (GPL, OSMC-Internal-EPL, OSMC-External-EPL) for use and
redistribution, in source and/or binary/object-code form:
• GPL. Any party (member or non-member of OSMC) may use and
redistribute OpenModelica under GPL version 3.
• Level 1 members of OSMC may also use and redistribute OpenModelica
under OSMC-Internal-EPL conditions.
• Level 2 members of OSMC may also use and redistribute OpenModelica
under OSMC-Internal-EPL or OSMC-External-EPL conditions.
Definitions of OSMC Public license modes:
• GPL = GPL version 3.

• OSMC-Internal-EPL = These OSMC Public license conditions together
with Internally restricted EPL, i.e., EPL version 1.0 with the Additional
Condition that use and redistribution by an OSMC member is only al-
lowed within the OSMC member’s own organization (i.e., its own legal
entity), or for an OSMC member paying a membership fee correspond-
ing to the size of the organization including all its affiliates, use and
redistribution is allowed within/between its affiliates.
112
• OSMC-External-EPL = These OSMC Public license conditions to-
gether with Externally restricted EPL, i.e., EPL version 1.0 with the
Additional Condition that use and redistribution by an OSMC member,
or by a Licensed Third Party Distributor having a redistribution agree-
ment with that member, to parties external to the OSMC members own
organization (i.e., its own legal entity) is only allowed in binary/object-
code form, except the case of redistribution to other OSMC members
to which source is also allowed to be distributed.
[This has the consequence that an external party who wishes to use Open-
Modelica in source form together with its own proprietary software in all
cases must be a member of OSMC].
In all cases of usage and redistribution by recipients, the following conditions

also apply:
a) Redistributions of source code must retain the above copyright notice,

all definitions, and conditions. It is sufficient if the OSMC-PL Header
is present in each source file, if the full OSMC-PL is available in a
prominent and easily located place in the redistribution.
b) Redistributions in binary/object-code form must reproduce the above

copyright notice, all definitions, and conditions. It is sufficient if the
OSMC-PL Header and the location in the redistribution of the full
OSMC-PL are present in the documentation and/or other materials
provided with the redistribution, if the full OSMC-PL is available in a
prominent and easily located place in the redistribution.
c) A recipient must clearly indicate its chosen usage mode of OSMC-

PL, in accompanying documentation and in a text file OSMC-USAGE-
MODE.txt, provided with the distribution.
d) Contributor(s) making a Contribution to OpenModelica thereby also

makes a Transfer of Contribution Copyright. In return, upon the ef-
fective date of the transfer, OSMC grants the Contributor(s) a Contri-
bution License of the Contribution. OSMC has the right to accept or
refuse Contributions.
Definitions:
“Subsidiary license conditions” means:
113
The additional license conditions depending on the by the recipient chosen
mode of OSMC-PL, defined by GPL version 3.0 for GPL, and by EPL for
OSMC-Internal-EPL and OSMC-External-EPL.
“OSMC-PL” means:
Open Source Modelica Consortium Public License version 1.2, i.e., the li-
cense defined here (the text between “— Start of Definition of OSMC Public
License —” and “— End of Definition of OSMC Public License —”, or later
versions thereof.
“OSMC-PL Header” means:

Open Source Modelica Consortium Public License Header version 1.2, i.e.,
the text between “— Start of Definition of OSMC Public License —” and
“— End of OSMC Public License Header —”, or later versions thereof.
“Contribution” means:
a) in the case of the initial Contributor, the initial code and documenta-
tion distributed under OSMC-PL, and
b) in the case of each subsequent Contributor:
i) changes to OpenModelica, and

ii) additions to OpenModelica;
where such changes and/or additions to OpenModelica originate from and

are distributed by that particular Contributor. A Contribution ’originates’
from a Contributor if it was added to OpenModelica by such Contributor
itself or anyone acting on such Contributor’s behalf.
For Contributors licensing OpenModelica under OSMC-Internal-EPL or OSMC-

External-EPL conditions, the following conditions also hold:
Contributions do not include additions to the distributed Program which:
(i) are separate modules of software distributed in conjunction with Open-
Modelica under their own license agreement, (ii) are separate modules which
are not derivative works of OpenModelica, and (iii) are separate modules
of software distributed in conjunction with OpenModelica under their own
license agreement where these separate modules are merged with (weaved
together with) modules of OpenModelica to form new modules that are dis-
tributed as object code or source code under their own license agreement, as
114
allowed under the Additional Condition of internal distribution according to
OSMC-Internal-EPL and/or Additional Condition for external distribution
according to OSMC-External-EPL.
“Transfer of Contribution Copyright” means that the Contributors of a Con-

tribution transfer the ownership and the copyright of the Contribution to
Open Source Modelica Consortium, the OpenModelica Copyright owner, for
inclusion in OpenModelica. The transfer takes place upon the effective date
when the Contribution is made available on the OSMC web site under OSMC-
PL, by such Contributors themselves or anyone acting on such Contributors’
behalf. The transfer is free of charge. If the Contributors or OSMC so wish,
an optional Copyright transfer agreement can be signed between OSMC and
the Contributors, as specified in an Appendix of the OSMC Bylaws.
“Contribution License” means a license from OSMC to the Contributors of

the Contribution, effective on the date of the Transfer of Contribution Copy-
right, where OSMC grants the Contributors a non-exclusive, world-wide,
transferable, free of charge, perpetual license, including sublicensing rights,
to use, have used, modify, have modified, reproduce and or have reproduced
the contributed material, for business and other purposes, including but not
limited to evaluation, development, testing, integration and merging with
other software and distribution. The warranty and liability disclaimers of
OSMC-PL apply to this license.
“Contributor” means any person or entity that distributes (part of) Open-
Modelica.
“The Program” means the Contributions distributed in accordance with

OSMC-PL.
“OpenModelica” means the Contributions distributed in accordance with

OSMC-PL.
“Recipient” means anyone who receives OpenModelica under OSMC-PL, in-

cluding all Contributors.
“Licensed Third Party Distributor” means a reseller/distributor having signed

a redistribution/resale agreement in accordance with OSMC-PL and OSMC
Bylaws, with an OSMC Level 2 organizational member which is not an Affili-
ate of the reseller/distributor, for distributing a product containing part(s) of
OpenModelica. The Licensed Third Party Distributor shall only be allowed
115
further redistribution to other resellers if the Level 2 member is granting
such a right to it in the redistribution/resale agreement between the Level 2
member and the Licensed Third Party Distributor.
“Affiliate” shall mean any legal entity, directly or indirectly, through one or
more intermediaries, controlling or controlled by or under common control
with any other legal entity, as the case may be. For purposes of this definition,
the term “control” (including the terms “controlling,” “controlled by” and
“under common control with”) means the possession, direct or indirect, of
the power to direct or cause the direction of the management and policies of a
legal entity, whether through the ownership of voting securities, by contract
or otherwise.
NO WARRANTY
EXCEPT AS EXPRESSLY SET FORTH IN THE BY RECIPIENT SE-
LECTED SUBSIDIARY LICENSE CONDITIONS OF OSMC-PL, OPEN-
MODELICA IS PROVIDED ON AN “AS IS” BASIS, WITHOUT WAR-
RANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IM-
PLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR
CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABIL-
ITY OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is
solely responsible for determining the appropriateness of using and distribut-
ing OPENMODELICA and assumes all risks associated with its exercise of
rights under OSMC-PL , including but not limited to the risks and costs of
program errors, compliance with applicable laws, damage to or loss of data,
programs or equipment, and unavailability or interruption of operations.
DISCLAIMER OF LIABILITY
EXCEPT AS EXPRESSLY SET FORTH IN THE BY RECIPIENT SE-
LECTED SUBSIDIARY LICENSE CONDITIONS OF OSMC-PL, NEITHER
RECIPIENT NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABIL-
ITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEM-
PLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT
LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABIL-
ITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARIS-
ING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF OPEN-
116
MODELICA OR THE EXERCISE OF ANY RIGHTS GRANTED HERE-
UNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAM-
AGES.
A Contributor licensing OpenModelica under OSMC-Internal-EPL or OSMC-

External-EPL may choose to distribute (parts of) OpenModelica in object
code form under its own license agreement, provided that:
a) it complies with the terms and conditions of OSMC-PL; or for the

case of redistribution of OpenModelica together with proprietary code
it is a dual license where the OpenModelica parts are distributed un-
der OSMC-PL compatible conditions and the proprietary code is dis-
tributed under proprietary license conditions; and
b) its license agreement:
i) effectively disclaims on behalf of all Contributors all warranties

and conditions, express and implied, including warranties or con-
ditions of title and non-infringement, and implied warranties or
conditions of merchantability and fitness for a particular purpose;
ii) effectively excludes on behalf of all Contributors all liability for
damages, including direct, indirect, special, incidental and conse-
quential damages, such as lost profits;
iii) states that any provisions which differ from OSMC-PL are offered
by that Contributor alone and not by any other party; and
iv) states from where the source code for OpenModelica is available,
and informs licensees how to obtain it in a reasonable manner on
or through a medium customarily used for software exchange.
When OPENMODELICA is made available in source code form:
a) it must be made available under OSMC-PL; and
b) a copy of OSMC-PL must be included with each copy of OPENMOD-

ELICA.
c) a copy of the subsidiary license associated with the selected mode of

OSMC-PL must be included with each copy of OPENMODELICA.
Contributors may not remove or alter any copyright notices contained within
OPENMODELICA.
117
If there is a conflict between OSMC-PL and the subsidiary license conditions,
OSMC-PL has priority.
This Agreement is governed by the laws of Sweden. The place of jurisdiction

for all disagreements related to this Agreement, is Linkping, Sweden.
The EPL 1.0 license definition has been obtained from: http://www.eclipse.org/legal/epl-
v10.html. It is also reproduced in Appendix B of the OSMC Bylaws, and in
the OpenModelica distribution.
The GPL Version 3 license definition has been obtained from http://www.gnu.org/copyleft/gpl.htm
It is also reproduced in Appendix C of the OSMC Bylaws, and in the Open-
Modelica distribution.
— End of Definition of OSMC Public License —
118
D SUNDIALS License
119
SUNDIALS License
Copyright (c) 2002-2016, Lawrence Livermore National Security. Produced

at the Lawrence Livermore National Laboratory.
Written by A.C. Hindmarsh, D.R. Reynolds, R. Serban, C.S. Woodward,
S.D. Cohen, A.G. Taylor, S. Peles, L.E. Banks, and D. Shumaker.
LLNL-CODE-667205 (ARKODE)
UCRL-CODE-155951 (CVODE)
UCRL-CODE-155950 (CVODES)
UCRL-CODE-155952 (IDA)
UCRL-CODE-237203 (IDAS)
LLNL-CODE-665877 (KINSOL)
All rights reserved.
This file is part of SUNDIALS. For details, see http://computation.llnl.gov/projects/sundials

Redistribution and use in source and binary forms, with or without modifi-
cation, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice,

this list of conditions and the disclaimer below.
2. Redistributions in binary form must reproduce the above copyright

notice, this list of conditions and the disclaimer (as noted below) in the
documentation and/or other materials provided with the distribution.
3. Neither the name of the LLNS/LLNL nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND

CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WAR-
RANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WAR-
RANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICU-
LAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL LAWRENCE
LIVERMORE NATIONAL SECURITY, LLC, THE U.S. DEPARTMENT
120
OF ENERGY OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUEN-
TIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCURE-
MENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTH-
ERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFT-
WARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Additional BSD Notice

1. This notice is required to be provided under our contract with the U.S.
Department of Energy (DOE). This work was produced at Lawrence
Livermore National Laboratory under Contract No. DE-AC52-07NA27344
with the DOE.
2. Neither the United States Government nor Lawrence Livermore Na-

tional Security, LLC nor any of their employees, makes any warranty,
express or implied, or assumes any liability or responsibility for the
accuracy, completeness, or usefulness of any information, apparatus,
product, or process disclosed, or represents that its use would not in-
fringe privately-owned rights.
3. Also, reference herein to any specific commercial products, process, or

services by trade name, trademark, manufacturer or otherwise does
not necessarily constitute or imply its endorsement, recommendation,
or favoring by the United States Government or Lawrence Livermore
National Security, LLC. The views and opinions of authors expressed
herein do not necessarily state or reflect those of the United States
Government or Lawrence Livermore National Security, LLC, and shall
not be used for advertising or product endorsement purposes.
121
E SuiteSparse License
122
BSD-3-Clause License
Copyright (c) 〈year〉 〈owner〉 . All rights reserved.

1. Redistributions of source code must retain the above copyright notice,

this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright

notice, this list of conditions and the following disclaimer in the docu-
mentation and/or other materials provided with the distribution.
3. Neither the name of the copyright holder nor the names of its contrib-
utors may be used to endorse or promote products derived from this
software without specific prior written permission.

LAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPY-
RIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
123
F Adept License
124
Apache License
Version 2
January 2004
http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE,

REPRODUCTION, AND DISTRIBUTION
1 Definitions.
“License” shall mean the terms and conditions for use, reproduction, and
distribution as defined by Sections 1 through 9 of this document.
“Licensor” shall mean the copyright owner or entity authorized by the copy-
right owner that is granting the License.
“Legal Entity” shall mean the union of the acting entity and all other entities
that control, are controlled by, or are under common control with that entity.
For the purposes of this definition, ”control” means (i) the power, direct or
indirect, to cause the direction or management of such entity, whether by
contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
“You” (or “Your”) shall mean an individual or Legal Entity exercising per-
missions granted by this License.
“Source” form shall mean the preferred form for making modifications, in-
cluding but not limited to software source code, documentation source, and
configuration files.
“Object” form shall mean any form resulting from mechanical transformation
or translation of a Source form, including but not limited to compiled object
code, generated documentation, and conversions to other media types.
“Work” shall mean the work of authorship, whether in Source or Object
125
form, made available under the License, as indicated by a copyright notice
that is included in or attached to the work (an example is provided in the
Appendix below).
“Derivative Works” shall mean any work, whether in Source or Object form,
that is based on (or derived from) the Work and for which the editorial
revisions, annotations, elaborations, or other modifications represent, as a
whole, an original work of authorship. For the purposes of this License,
Derivative Works shall not include works that remain separable from, or
merely link (or bind by name) to the interfaces of, the Work and Derivative
Works thereof.
“Contribution” shall mean any work of authorship, including the original
version of the Work and any modifications or additions to that Work or
Derivative Works thereof, that is intentionally submitted to Licensor for in-
clusion in the Work by the copyright owner or by an individual or Legal Entity
authorized to submit on behalf of the copyright owner. For the purposes of
this definition, “submitted” means any form of electronic, verbal, or written
communication sent to the Licensor or its representatives, including but not
limited to communication on electronic mailing lists, source code control sys-
tems, and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but exclud-
ing communication that is conspicuously marked or otherwise designated in
writing by the copyright owner as ”Not a Contribution.”
“Contributor” shall mean Licensor and any individual or Legal Entity on be-
half of whom a Contribution has been received by Licensor and subsequently
incorporated within the Work.
2 Grant of Copyright License.

Subject to the terms and conditions of this License, each Contributor hereby
grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
irrevocable copyright license to reproduce, prepare Derivative Works of, pub-
licly display, publicly perform, sublicense, and distribute the Work and such
Derivative Works in Source or Object form.
3 Grant of Patent License.

Subject to the terms and conditions of this License, each Contributor hereby
grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
126
irrevocable (except as stated in this section) patent license to make, have
made, use, offer to sell, sell, import, and otherwise transfer the Work, where
such license applies only to those patent claims licensable by such Contributor
that are necessarily infringed by their Contribution(s) alone or by combina-
tion of their Contribution(s) with the Work to which such Contribution(s)
was submitted. If You institute patent litigation against any entity (includ-
ing a cross-claim or counterclaim in a lawsuit) alleging that the Work or a
Contribution incorporated within the Work constitutes direct or contribu-
tory patent infringement, then any patent licenses granted to You under this
License for that Work shall terminate as of the date such litigation is filed.
4 Redistribution.
You may reproduce and distribute copies of the Work or Derivative Works
thereof in any medium, with or without modifications, and in Source or
Object form, provided that You meet the following conditions:
(a) You must give any other recipients of the Work or Derivative Works a
copy of this License; and
(b) You must cause any modified files to carry prominent notices stating
that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works that You
distribute, all copyright, patent, trademark, and attribution notices
from the Source form of the Work, excluding those notices that do not
pertain to any part of the Derivative Works; and
(d) If the Work includes a ”NOTICE” text file as part of its distribution,
then any Derivative Works that You distribute must include a readable
copy of the attribution notices contained within such NOTICE file,
excluding those notices that do not pertain to any part of the Derivative
Works, in at least one of the following places: within a NOTICE text
file distributed as part of the Derivative Works; within the Source form
or documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and wherever
such third-party notices normally appear. The contents of the NOTICE
file are for informational purposes only and do not modify the License.
You may add Your own attribution notices within Derivative Works
that You distribute, alongside or as an addendum to the NOTICE
text from the Work, provided that such additional attribution notices
cannot be construed as modifying the License.
127
You may add Your own copyright statement to Your modifications and may
provide additional or different license terms and conditions for use, reproduc-
tion, or distribution of Your modifications, or for any such Derivative Works
as a whole, provided Your use, reproduction, and distribution of the Work
otherwise complies with the conditions stated in this License.
5 Submission of Contributions.
Unless You explicitly state otherwise, any Contribution intentionally sub-
mitted for inclusion in the Work by You to the Licensor shall be under the
terms and conditions of this License, without any additional terms or condi-
tions. Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed with
Licensor regarding such Contributions.
6 Trademarks.
This License does not grant permission to use the trade names, trademarks,
service marks, or product names of the Licensor, except as required for rea-
sonable and customary use in describing the origin of the Work and repro-
ducing the content of the NOTICE file.
7 Disclaimer of Warranty.
Unless required by applicable law or agreed to in writing, Licensor provides
the Work (and each Contributor provides its Contributions) on an ”AS IS”
BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
either express or implied, including, without limitation, any warranties or
conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or
FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible
for determining the appropriateness of using or redistributing the Work and
assume any risks associated with Your exercise of permissions under this
License.
8 Limitation of Liability.
In no event and under no legal theory, whether in tort (including negligence),
contract, or otherwise, unless required by applicable law (such as deliberate
128
and grossly negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special, incidental,
or consequential damages of any character arising as a result of this License
or out of the use or inability to use the Work (including but not limited to
damages for loss of goodwill, work stoppage, computer failure or malfunction,
or any and all other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9 Accepting Warranty or Additional Liabil-

ity.
While redistributing the Work or Derivative Works thereof, You may choose
to offer, and charge a fee for, acceptance of support, warranty, indemnity, or
other liability obligations and/or rights consistent with this License. How-
ever, in accepting such obligations, You may act only on Your own behalf
and on Your sole responsibility, not on behalf of any other Contributor, and
only if You agree to indemnify, defend, and hold each Contributor harmless
for any liability incurred by, or claims asserted against, such Contributor by
reason of your accepting any such warranty or additional liability. END OF
TERMS AND CONDITIONS
APPENDIX: How to apply the Apache Li-

cense to your work.
To apply the Apache License to your work, attach the following boilerplate
notice, with the fields enclosed by brackets “[]” replaced with your own identi-
fying information. (Don’t include the brackets!) The text should be enclosed
in the appropriate comment syntax for the file format. We also recommend
that a file or class name and description of purpose be included on the same
“printed page” as the copyright notice for easier identification within third-
party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the ”License”); you may
not use this file except in compliance with the License.
You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-
2.0
129
Unless required by applicable law or agreed to in writing, software distributed
under the License is distributed on an “AS IS” BASIS, WITHOUT WAR-
RANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and limita-
tions under the License.
130
G NICSLU License
131
GNU LESSER GENERAL PUBLIC
LICENSE
Version 3
29 June 2007
Copyright (C) 2007 Free Software Foundation, Inc. 〈http s ://fsf.org/〉

Everyone is permitted to copy and distribute verbatim copies of this license
document, but changing it is not allowed.
This version of the GNU Lesser General Public License incorporates the
terms and conditions of version 3 of the GNU General Public License, sup-
plemented by the additional permissions listed below.
0 Additional Definitions.
As used herein, “this License” refers to version 3 of the GNU Lesser General
Public License, and the “GNU GPL” refers to version 3 of the GNU General
Public License.
“The Library” refers to a covered work governed by this License, other than
an Application or a Combined Work as defined below.
An “Application” is any work that makes use of an interface provided by
the Library, but which is not otherwise based on the Library. Defining a
subclass of a class defined by the Library is deemed a mode of using an
interface provided by the Library.
A “Combined Work” is a work produced by combining or linking an Appli-
cation with the Library. The particular version of the Library with which
the Combined Work was made is also called the “Linked Version”.
The “Minimal Corresponding Source” for a Combined Work means the Cor-
responding Source for the Combined Work, excluding any source code for
132
portions of the Combined Work that, considered in isolation, are based on
the Application, and not on the Linked Version.
The “Corresponding Application Code” for a Combined Work means the
object code and/or source code for the Application, including any data and
utility programs needed for reproducing the Combined Work from the Ap-
plication, but excluding the System Libraries of the Combined Work.
1 Exception to Section 3 of the GNU GPL.

You may convey a covered work under sections 3 and 4 of this License without
being bound by section 3 of the GNU GPL.
2 Conveying Modified Versions.

If you modify a copy of the Library, and, in your modifications, a facility
refers to a function or data to be supplied by an Application that uses the
facility (other than as an argument passed when the facility is invoked), then
you may convey a copy of the modified version:
a) under this License, provided that you make a good faith effort to ensure
that, in the event an Application does not supply the function or data,
the facility still operates, and performs whatever part of its purpose
remains meaningful, or
b) under the GNU GPL, with none of the additional permissions of this
License applicable to that copy.
3 Object Code Incorporating Material from

Library Header Files.
The object code form of an Application may incorporate material from a
header file that is part of the Library. You may convey such object code
under terms of your choice, provided that, if the incorporated material is
not limited to numerical parameters, data structure layouts and accessors,
or small macros, inline functions and templates (ten or fewer lines in length),
you do both of the following:
a) Give prominent notice with each copy of the object code that the Li-
brary is used in it and that the Library and its use are covered by this
License.
133
b) Accompany the object code with a copy of the GNU GPL and this
license document.
4 Combined Works.
You may convey a Combined Work under terms of your choice that, taken
together, effectively do not restrict modification of the portions of the Library
contained in the Combined Work and reverse engineering for debugging such
modifications, if you also do each of the following:
a) Give prominent notice with each copy of the Combined Work that the
Library is used in it and that the Library and its use are covered by
this License.
b) Accompany the Combined Work with a copy of the GNU GPL and this
license document.
c) For a Combined Work that displays copyright notices during execution,

include the copyright notice for the Library among these notices, as well
as a reference directing the user to the copies of the GNU GPL and
this license document.
d) Do one of the following:
0) Convey the Minimal Corresponding Source under the terms of

this License, and the Corresponding Application Code in a form
suitable for, and under terms that permit, the user to recombine
or relink the Application with a modified version of the Linked
Version to produce a modified Combined Work, in the manner
specified by section 6 of the GNU GPL for conveying Correspond-
ing Source.
1) Use a suitable shared library mechanism for linking with the Li-
brary. A suitable mechanism is one that (a) uses at run time a
copy of the Library already present on the user’s computer sys-
tem, and (b) will operate properly with a modified version of the
Library that is interface-compatible with the Linked Version.
e) Provide Installation Information, but only if you would otherwise be

required to provide such information under section 6 of the GNU GPL,
and only to the extent that such information is necessary to install
and execute a modified version of the Combined Work produced by re-
combining or relinking the Application with a modified version of the
134
Linked Version. (If you use option 4d0, the Installation Information
must accompany the Minimal Corresponding Source and Correspond-
ing Application Code. If you use option 4d1, you must provide the
Installation Information in the manner specified by section 6 of the
GNU GPL for conveying Corresponding Source.)
5 Combined Libraries.
You may place library facilities that are a work based on the Library side
by side in a single library together with other library facilities that are not
Applications and are not covered by this License, and convey such a combined
library under terms of your choice, if you do both of the following:
a) Accompany the combined library with a copy of the same work based
on the Library, uncombined with any other library facilities, conveyed
under the terms of this License.
b) Give prominent notice with the combined library that part of it is a

work based on the Library, and explaining where to find the accompa-
nying uncombined form of the same work.
6 Revised Versions of the GNU Lesser Gen-

eral Public License.
The Free Software Foundation may publish revised and/or new versions of the
GNU Lesser General Public License from time to time. Such new versions
will be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the Library as
you received it specifies that a certain numbered version of the GNU Lesser
General Public License “or any later version” applies to it, you have the
option of following the terms and conditions either of that published version
or of any later version published by the Free Software Foundation. If the
Library as you received it does not specify a version number of the GNU
Lesser General Public License, you may choose any version of the GNU Lesser
General Public License ever published by the Free Software Foundation.
If the Library as you received it specifies that a proxy can decide whether
future versions of the GNU Lesser General Public License shall apply, that
135
proxy’s public statement of acceptance of any version is permanent autho-
rization for you to choose that version for the Library.
136
H jQuery MIT License
137
MIT License
Copyright (c) 2009 John Resig, http://jquery.com/
Permission is hereby granted, free of charge, to any person obtaining a copy

of this software and associated documentation files (the “Software”), to deal
in the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to
do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF

ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
OR OTHER DEALINGS IN THE SOFTWARE.
138
I jQuery GPL License
139
GNU GENERAL PUBLIC LICENSE
Version 2
June 1991
Copyright (C) 1989, 1991 Free Software Foundation, Inc.

51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 , USA
Everyone is permitted to copy and distribute verbatim copies of this license
document, but changing it is not allowed.
Preamble
The licenses for most software are designed to take away your freedom to
share and change it. By contrast, the GNU General Public License is in-
tended to guarantee your freedom to share and change free software–to make
sure the software is free for all its users. This General Public License applies
to most of the Free Software Foundation’s software and to any other program
whose authors commit to using it. (Some other Free Software Foundation
software is covered by the GNU Lesser General Public License instead.) You
can apply it to your programs, too.
When we speak of free software, we are referring to freedom, not price. Our
General Public Licenses are designed to make sure that you have the freedom
to distribute copies of free software (and charge for this service if you wish),
that you receive source code or can get it if you want it, that you can change
the software or use pieces of it in new free programs; and that you know you
can do these things.
To protect your rights, we need to make restrictions that forbid anyone to
deny you these rights or to ask you to surrender the rights. These restrictions
translate to certain responsibilities for you if you distribute copies of the
software, or if you modify it.
140
For example, if you distribute copies of such a program, whether gratis or
for a fee, you must give the recipients all the rights that you have. You must
make sure that they, too, receive or can get the source code. And you must
show them these terms so they know their rights.
We protect your rights with two steps: (1) copyright the software, and (2)
offer you this license which gives you legal permission to copy, distribute
and/or modify the software.
Also, for each author’s protection and ours, we want to make certain that
everyone understands that there is no warranty for this free software. If the
software is modified by someone else and passed on, we want its recipients to
know that what they have is not the original, so that any problems introduced
by others will not reflect on the original authors’ reputations.
Finally, any free program is threatened constantly by software patents. We
wish to avoid the danger that redistributors of a free program will individually
obtain patent licenses, in effect making the program proprietary. To prevent
this, we have made it clear that any patent must be licensed for everyone’s
free use or not licensed at all.
The precise terms and conditions for copying, distribution and modification
follow.
TERMS AND CONDITIONS FOR COPYING,

DISTRIBUTION AND MODIFICATION
0.
This License applies to any program or other work which contains a notice
placed by the copyright holder saying it may be distributed under the terms
of this General Public License. The “Program”, below, refers to any such
program or work, and a “work based on the Program” means either the
Program or any derivative work under copyright law: that is to say, a work
containing the Program or a portion of it, either verbatim or with modifi-
cations and/or translated into another language. (Hereinafter, translation
is included without limitation in the term “modification”.) Each licensee is
addressed as “you”.
Activities other than copying, distribution and modification are not covered
by this License; they are outside its scope. The act of running the Program
is not restricted, and the output from the Program is covered only if its
141
contents constitute a work based on the Program (independent of having
been made by running the Program). Whether that is true depends on what
the Program does.
1.
You may copy and distribute verbatim copies of the Program’s source code
as you receive it, in any medium, provided that you conspicuously and appro-
priately publish on each copy an appropriate copyright notice and disclaimer
of warranty; keep intact all the notices that refer to this License and to the
absence of any warranty; and give any other recipients of the Program a copy
of this License along with the Program.
You may charge a fee for the physical act of transferring a copy, and you may
at your option offer warranty protection in exchange for a fee.
2.
You may modify your copy or copies of the Program or any portion of it,
thus forming a work based on the Program, and copy and distribute such
modifications or work under the terms of Section 1 above, provided that you
also meet all of these conditions:
a) You must cause the modified files to carry prominent notices stating
that you changed the files and the date of any change.
b) You must cause any work that you distribute or publish, that in whole
or in part contains or is derived from the Program or any part thereof,
to be licensed as a whole at no charge to all third parties under the
terms of this License.
c) If the modified program normally reads commands interactively when

run, you must cause it, when started running for such interactive use in
the most ordinary way, to print or display an announcement including
an appropriate copyright notice and a notice that there is no warranty
(or else, saying that you provide a warranty) and that users may redis-
tribute the program under these conditions, and telling the user how
to view a copy of this License. (Exception: if the Program itself is
interactive but does not normally print such an announcement, your
work based on the Program is not required to print an announcement.)
142
These requirements apply to the modified work as a whole. If identifiable sec-
tions of that work are not derived from the Program, and can be reasonably
considered independent and separate works in themselves, then this License,
and its terms, do not apply to those sections when you distribute them as
separate works. But when you distribute the same sections as part of a whole
which is a work based on the Program, the distribution of the whole must be
on the terms of this License, whose permissions for other licensees extend to
the entire whole, and thus to each and every part regardless of who wrote it.
Thus, it is not the intent of this section to claim rights or contest your
rights to work written entirely by you; rather, the intent is to exercise the
right to control the distribution of derivative or collective works based on the
Program.
In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under the
scope of this License.
3.
You may copy and distribute the Program (or a work based on it, under
Section 2) in object code or executable form under the terms of Sections 1
and 2 above provided that you also do one of the following:
a) Accompany it with the complete corresponding machine-readable source

code, which must be distributed under the terms of Sections 1 and 2
above on a medium customarily used for software interchange; or,
b) Accompany it with a written offer, valid for at least three years, to

give any third party, for a charge no more than your cost of physically
performing source distribution, a complete machine-readable copy of
the corresponding source code, to be distributed under the terms of
Sections 1 and 2 above on a medium customarily used for software
interchange; or,
c) Accompany it with the information you received as to the offer to

distribute corresponding source code. (This alternative is allowed only
for noncommercial distribution and only if you received the program
in object code or executable form with such an offer, in accord with
Subsection b above.)
143
The source code for a work means the preferred form of the work for making
modifications to it. For an executable work, complete source code means
all the source code for all modules it contains, plus any associated interface
definition files, plus the scripts used to control compilation and installation of
the executable. However, as a special exception, the source code distributed
need not include anything that is normally distributed (in either source or
binary form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component itself
accompanies the executable.
If distribution of executable or object code is made by offering access to copy
from a designated place, then offering equivalent access to copy the source
code from the same place counts as distribution of the source code, even
though third parties are not compelled to copy the source along with the
object code.
4.
You may not copy, modify, sublicense, or distribute the Program except
as expressly provided under this License. Any attempt otherwise to copy,
modify, sublicense or distribute the Program is void, and will automatically
terminate your rights under this License. However, parties who have received
copies, or rights, from you under this License will not have their licenses
terminated so long as such parties remain in full compliance.
5.
You are not required to accept this License, since you have not signed it.
However, nothing else grants you permission to modify or distribute the
Program or its derivative works. These actions are prohibited by law if you do
not accept this License. Therefore, by modifying or distributing the Program
(or any work based on the Program), you indicate your acceptance of this
License to do so, and all its terms and conditions for copying, distributing or
modifying the Program or works based on it.
6.
Each time you redistribute the Program (or any work based on the Program),
the recipient automatically receives a license from the original licensor to
copy, distribute or modify the Program subject to these terms and conditions.
You may not impose any further restrictions on the recipients’ exercise of the
144
rights granted herein. You are not responsible for enforcing compliance by
third parties to this License.
7.
If, as a consequence of a court judgment or allegation of patent infringement
or for any other reason (not limited to patent issues), conditions are imposed
on you (whether by court order, agreement or otherwise) that contradict the
conditions of this License, they do not excuse you from the conditions of
this License. If you cannot distribute so as to satisfy simultaneously your
obligations under this License and any other pertinent obligations, then as
a consequence you may not distribute the Program at all. For example, if a
patent license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then the only
way you could satisfy both it and this License would be to refrain entirely
from distribution of the Program.
If any portion of this section is held invalid or unenforceable under any par-
ticular circumstance, the balance of the section is intended to apply and the
section as a whole is intended to apply in other circumstances.
It is not the purpose of this section to induce you to infringe any patents
or other property right claims or to contest validity of any such claims; this
section has the sole purpose of protecting the integrity of the free software
distribution system, which is implemented by public license practices. Many
people have made generous contributions to the wide range of software dis-
tributed through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing to dis-
tribute software through any other system and a licensee cannot impose that
choice.
This section is intended to make thoroughly clear what is believed to be a
consequence of the rest of this License.
8.
If the distribution and/or use of the Program is restricted in certain countries
either by patents or by copyrighted interfaces, the original copyright holder
who places the Program under this License may add an explicit geographi-
cal distribution limitation excluding those countries, so that distribution is
permitted only in or among countries not thus excluded. In such case, this
License incorporates the limitation as if written in the body of this License.
145
9.
The Free Software Foundation may publish revised and/or new versions of
the General Public License from time to time. Such new versions will be
similar in spirit to the present version, but may differ in detail to address
new problems or concerns.
Each version is given a distinguishing version number. If the Program spec-
ifies a version number of this License which applies to it and “any later
version”, you have the option of following the terms and conditions either of
that version or of any later version published by the Free Software Founda-
tion. If the Program does not specify a version number of this License, you
may choose any version ever published by the Free Software Foundation.
10.
If you wish to incorporate parts of the Program into other free programs
whose distribution conditions are different, write to the author to ask for
permission. For software which is copyrighted by the Free Software Founda-
tion, write to the Free Software Foundation; we sometimes make exceptions
for this. Our decision will be guided by the two goals of preserving the free
status of all derivatives of our free software and of promoting the sharing and
reuse of software generally.
NO WARRANTY
11.
BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE
IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMIT-
TED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED
IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK
AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS
WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU AS-
SUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR COR-
RECTION.
146
12.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED
TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER
PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM
AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, IN-
CLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUEN-
TIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA
OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED
BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO
OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER
OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES. END OF TERMS AND CONDITIONS
147
J ccplint License
148
CC-BY-3.0 License
cpplint.py and its corresponding unit tests are Copyright (C) 2009 Google
Inc.
• Redistributions of source code must retain the above copyright notice,

this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright

notice, this list of conditions and the following disclaimer in the docu-
mentation and/or other materials provided with the distribution.
• Neither the name of Google Inc. nor the names of its contributors may
be used to endorse or promote products derived from this software
without specific prior written permission.

LAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPY-
RIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
149
150

DynawoDocumentation PDF

Uploaded by

Copyright:

Available Formats

DynawoDocumentation PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

DynawoDocumentation PDF

Uploaded by

Copyright:

Available Formats

Dynaωo Documentation

January 31, 2019

Appendix A Dynaωo License 89

Appendix B Dynaωo Documentation License 99

Appendix C OpenModelica License 110

Appendix D SUNDIALS License 119

Appendix E SuiteSparse License 122

Appendix G NICSLU License 131

Appendix H jQuery MIT License 137

Appendix I jQuery GPL License 139

Appendix J ccplint License 148

1 Separation between modelling and solving parts in Dynaωo . . 6

3 Dynaωo results on IEEE14_DisconnectLine case . . . . . . . . 11

4 Dynaωo input and output files . . . . . . . . . . . . . . . . . . 14

5 Separation between modelling and solving parts in Dynaωo . . 36

Dynaωo is an hybrid C++/Modelica open source time domain sim-

It is an ongoing project based on previous works conducted particularly in

Figure 1: Separation between modelling and solving parts in Dynaωo

Dynaωo’s primary focus has been on RMS simulations and most of

Figure 2: Dynaωo scope in the range of dynamic phenomena

In the following sections of this document, the reader will find:

• Installation directions to be able to compile and use Dynaωo;

• Configuration directions to be able to create the needed input files in

• Detailed information about the Dynaωo simulator, its architecture,

• Advanced information on the code organization, the procedure to follow

2.1 Building Dynaωo

Command for Ubuntu:

$ > apt - get install -y git gcc g ++ gfortran autoconf pkgconf

$ > dnf install -y git gcc gcc - c ++ gcc - gfortran autoconf

export DYNAWO_LOCALE = en_GB

export NB_ PR OC ES SO RS _U SE D = $ (( $ ( nproc -- all ) / 2) )

export BUILD_TYPE = Release

$DYNAWO_HOME / util / envDynawo . sh $@ ' > myEnvDynawo . sh

Below is a description of some environment variables that might be changed

BROWSER Default browser command

$ > export http_proxy =

2.2 Launching Dynaωo

$ > ./ myEnvDynawo . sh jobs

$ > cd nrt / data / IEEE / I E E E 1 4 _ B l a c k B o x M o d e l s

It is also possible to display directly simulation results - plots - into a simple

$ > ./ myEnvDynawo . sh jobs - with - curves

2.3 Third parties

• OpenModelica [7], a Modelica [1] environment developed and main-

• SUNDIALS [11], a suite of solvers developed and maintained by the

• SuiteSparse, a suite of sparse matrix algorithms and in particular KLU

• NICSLU [2] which is another LU decomposition library. It is developed

In addition to these libraries needed for the simulation process, Dynaωo

• jQuery is used to provide a minimalistic GUI with Dynaωo that enables

• cpplint, a tool used during Dynaωo compilation process to ensure that

Figure 4: Dynaωo input and output files

3.1.1 Dynaωo inputs

• A file providing the dynamic description of the test grid to simulate:

• A file providing the needed parameters of the simulation: the parameter

• jobs.xsd for the jobs file;

• dyd.xsd for the dyd file;

• parameters.xsd for the par file;

• curvesInput.xsd for the crv file;

3.1.2 Dynaωo outputs

• A file providing the chronological list of events that happened during