DIgSILENT PowerFactory

Application Guide

Dynamic Modelling Tutorial

DIgSILENT Technical Documentation

DIgSILENT GmbH
Heinrich-Hertz-Str. 9
72810 - Gomaringen
Germany
T: +49 7072 9168 00
F: +49 7072 9168 88
http://www.digsilent.de
[email protected]
r887

Copyright 2013, DIgSILENT GmbH. Copyright of this document belongs to DIgSILENT GmbH.
No part of this document may be reproduced, copied, or transmitted in any form, by any means
electronic or mechanical, without the prior written permission of DIgSILENT GmbH.
Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

Contents

Contents
1 Introduction
1.1 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2 Dynamic Modelling Concepts in PowerFactory

4
4
5

2.1 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.2 General Modelling Philosophy . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.2.1 Flexibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.2.2 Inheritance and Reuse . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.3 Built-in Error Detection and Testing . . . . . . . . . . . . . . . . . . . . . . . . . .

2.4 Example: Generator Control System . . . . . . . . . . . . . . . . . . . . . . . . .

3 Creating Dynamic Models

12

3.1 General Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

12

3.2 Library Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

12

3.2.1 Composite Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

12

3.2.2 Model Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

12

3.3 Grid Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

14

3.3.1 Composite Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

14

3.3.2 Common Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

14

4 Model Initialisation

16

4.1 How Models are Initialised in PowerFactory . . . . . . . . . . . . . . . . . . . . .

16

4.2 Initialisation of Common Primitive Blocks . . . . . . . . . . . . . . . . . . . . . . .

17

4.2.1 Integrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

17

4.2.2 First-order Lag Differentiator . . . . . . . . . . . . . . . . . . . . . . . . .

18

4.2.3 First-order Lag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

19

4.2.4 PI Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

19

4.3 Initialisation of Composite Block Definitions . . . . . . . . . . . . . . . . . . . . .

19

4.3.1 Example: Hydro Turbine Block Initialisation . . . . . . . . . . . . . . . . .

21

4.3.2 General Procedure for Composite Block Initialisation . . . . . . . . . . . .

22

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

Contents

4.4 Setting Initial Conditions in DSL . . . . . . . . . . . . . . . . . . . . . . . . . . . .

23

4.5 Iterative Setting of Initial Conditions . . . . . . . . . . . . . . . . . . . . . . . . . .

23

4.5.1 Linear Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

24

4.5.2 Internal Division Search . . . . . . . . . . . . . . . . . . . . . . . . . . . .

24

4.5.3 Newton Iterative Search . . . . . . . . . . . . . . . . . . . . . . . . . . . .

25

4.6 Automatic Calculation of Initial Conditions . . . . . . . . . . . . . . . . . . . . . .

26

4.6.1 Example: Simple Block . . . . . . . . . . . . . . . . . . . . . . . . . . . .

26

4.6.2 Example: Wind Turbine Block . . . . . . . . . . . . . . . . . . . . . . . . .

27

5 Testing and Troubleshooting

28

5.1 Verifying Model Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

28

5.2 Viewing Model Signals and Variables during Initialisation . . . . . . . . . . . . . .

28

5.2.1 Printing Values to the Output Window . . . . . . . . . . . . . . . . . . . .

29

5.2.2 Flexible Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

29

5.2.3 Overlay of Signals in Block Diagrams . . . . . . . . . . . . . . . . . . . .

29

5.3 Testing Models in Isolation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

30

5.3.1 Initialising Disconnected Signals . . . . . . . . . . . . . . . . . . . . . . .

30

5.3.2 Step Response Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

30

5.4 Advice for Troubleshooting Models . . . . . . . . . . . . . . . . . . . . . . . . . .

33

6 Portability and Encryption

34

6.1 Portability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

34

6.1.1 Pack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

34

6.1.2 Pack to Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

35

6.2 Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

35

7 DIgSILENT Training Courses

37

A DSL Function Reference

38

A.1 DSL Standard Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

38

A.2 DSL Special Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

39

References

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

44

Introduction

Introduction

This guide is intended to be an introduction to dynamic modelling in PowerFactory . It will cover

the philosophy, creation, initialisation and testing of dynamic models for use in time-domain
power systems simulations.

1.1

Prerequisites

A basic knowledge of electrical engineering, linear systems and control theory and PowerFactory handling is assumed. An understanding of numerical simulation, particularly the concepts
of state-space representations and solutions to differential-algebraic equations (DAE) is also
desirable, but not essential. The following references are useful for the interested reader:
Modern Control Engineering by K. Ogata [2]
Power System Stability and Control by P. Kundur - Section 13 of this book has a good
treatment on the formulation of DAE equations for power systems applications and how to
solve them with numerical integration methods [1]

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

Dynamic Modelling Concepts in PowerFactory

Dynamic Modelling Concepts in PowerFactory

2.1

Terminology

In this section, a number of dynamic modelling terms that are specific to PowerFactory are
defined. If this is your first exposure to dynamic modelling in PowerFactory , then dont worry
about trying to understand all of these terms right now (as they are quite abstract and can take
some time to get used to!). It is sufficient to simply be aware that they exist and know that the
definitions are here for reference.
Network Element: is an built-in model representing a standard piece of power system
equipment, e.g. generators, motors, transformers, converters, etc.
Composite Frame: an overview diagram showing the interconnections between slots. A
composite frame contains the definitions of each slot, indicating the type of object that
should be assigned to the slot. Frames are type objects that belong in the equipment type
library.
Slot: is a block in the composite frame that represents an object in the grid, e.g. network
elements, measurement devices and DSL common models. The user must define what
type of object the slot represents.
Composite Model: is a grid object that represents a complete dynamic system (e.g.
generator with prime mover and voltage control). It links the composite frame (which
contains slots) to the actual network elements, measurement devices and DSL common
models in the grid.
Model Definition: defines the transfer function of a dynamic model, in the form of equations and / or graphical block diagrams. It can be seen as the design or blueprint for a
piece of equipment (e.g. design for a model XYZ controller). Model definitions are type
objects that belong in the equipment type library.
Common Model: links a model definition to an actual piece of equipment with specific
parameter settings. Whereas the block definition could be seen as the design or model
for a piece of equipment, the common model can be seen as a specific physical instance
of the equipment item itself (e.g. the physical controller unit). Common models are grid
elements that belong in the grid.
Block Definition: is the name of the PowerFactory object (BlkDef) used to build both
composite frames and model definitions. Block definitions can be built from both equations
and graphical block diagrams.
Primitive Block Definition: is a model definition containing only a set of equations with
no graphical representation. Primitive blocks are often re-used in other (composite) model
definitions.
Composite Block Definition: is a model definition that has a graphical block diagram
representation and may be built up from primitive block definitions.
Macro: is a model definition that is designed to be used only in other composite block
definitions. A block definition can be assigned as a macro by ticking the macro checkbox in
the block definition dialog. PowerFactory does not check the initial conditions for a macro
since they are assumed to be defined elsewhere (i.e. in a higher-level block definition).

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

Dynamic Modelling Concepts in PowerFactory

2.2

General Modelling Philosophy

The underlying philosophy for dynamic modelling in PowerFactory is as follows:

Flexibility: structure that allows any arbitrary dynamic model to be created.
Inheritance and Reuse: object-oriented approach where multiple grid objects can use
the same library object (i.e. frame or model definition) with local parameter settings.
Built-in Error Detection and Testing: there are built-in tools to detect structural and
syntax errors and to test models individually

2.2.1

Flexibility

The dynamic modelling approach in PowerFactory was specifically designed to be flexible, so

that any model, from simple time delays to complex controller structures, can be constructed
using the same set of tools. The basic building blocks are the model equations that are written
in the DIgSILENT Simulation Language (DSL). Higher-level representations such as graphical block diagrams and nested block structures are automatically converted to a set of DSL
equations, which are then parsed and interpreted during the simulation.

2.2.2

Inheritance and Reuse

PowerFactory uses an object-oriented approach that encourages reuse by strictly enforcing the
distinction between library (type) and grid (element) objects. For example, when creating a
transformer, the user must create both a transformer type (e.g. 2MVA, 11/0.4kV, Z=6%) and the
transformer element itself. Multiple transformer elements can use the same type, and changing
the type parameters will affect all of the transformers that inherit or reference this type.
This same philosophy is reflected in PowerFactory s approach to dynamic modelling. There are
type objects in the library (i.e. composite frames and model definitions) that are referenced by
element objects in the grid (i.e. composite models and common models). These grid elements
inherit the properties of the type objects (e.g. a common model inherits the block structure of its
linked model definition). A table of type versus element analogies are shown in Table 2.1 below:
Type
Library object
Composite frame
Model definition
Class
Blueprint / design

Element
Grid object
Composite model
Common model
Instantiated object
Equipment in the field

Remarks

Programming analogy
Physical analogy

Table 2.1: Type and element analogies

To provide a more concrete example, consider the two diagrams in Figure 2.1 and Figure 2.2.
Suppose that the frame represents the connections of a generator (Slot A) to a voltage controller
(Slot B). Both diagrams depict two generators (network elements 1 and 2), each connected to
a voltage controller (common models 1 and 2).
Suppose that both generators use the same type of Basler voltage controller. Instead of defining the block diagram for each voltage controller individually, the PowerFactory philosophy is to
define the Basler voltage controller once as a type (model definition) and then create two different instances (common models) for each of the generators (each with their own local parameter
settings). This configuration is reflected in Figure 2.1.
Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

Dynamic Modelling Concepts in PowerFactory

Figure 2.1: Single model definition referenced by two common models (one-to-many)
Now suppose that one of the Basler voltage controllers is replaced with an AVK voltage controller. We can create a new common model based on the AVK block diagram and replace the
Basler controller in the composite model (all the while using the same composite model and
frame). This configuration is reflected in Figure 2.2.

2.3

Built-in Error Detection and Testing

Modelling flexibility comes at the expense of a strictly defined workflow for creating dynamic
models. There are few restrictions on how a user can construct models and with this freedom, a
user can create models with very complicated structures. This has an obvious drawback in that
some model structures are fundamentally unsound, but can be created nevertheless. Rather
than impose restrictions, the philosophy adopted by PowerFactory is to provide tools for error
detection and testing instead.

2.4

Example: Generator Control System

The built-in synchronous machine model (ElmSym) is shipped by default without any controls.
When the synchronous machine is used as-is in a dynamic simulation (i.e. without controls),
it will output a constant turbine power pt and excitation voltage ve throughout the duration of
the simulation. As a result, disturbances such as faults, load steps, etc will likely cause unstable
frequency and voltage excursions since there are no governor or AVR actions to control these
quantities.
It is therefore necessary to specifically define the generator controls and their dynamic response
to system disturbances. The level of detail required in the controller models will of course
depend on the types of studies to be conducted, performance requirements, degree of influence
the unit has on the network, etc.
In this example, we will illustrate the dynamic modelling concepts discussed so far by defin-

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

Dynamic Modelling Concepts in PowerFactory

Figure 2.2: Two model definitions each referenced by one common model (one-to-one)
ing the structure of a simplified generator control system, and how it can be implemented in
PowerFactory .
Consider the hydroelectric generation system shown in Figure 2.3.
In this system, the amount of water flowing into the penstock is controlled by a control gate
at the intake. The water in the penstock flows through the turbine and rotates it, before being
discharged through the draft tube. The turbine is coupled to a synchronous generator, which
is then connected to the network. The gate position is controlled by a governor system, which
tries to keep the output of the generator at a constant frequency. A voltage controller is also
connected to the generator, controlling the terminal voltage of the machine by regulating rotor
excitation.
We can see from this stylised system that there are control signals (i.e. gate position, excitation voltage), control objectives and feedback (i.e. frequency, terminal voltage). This can be
summarised by a block diagram as shown Figure 2.4.
This block diagram represents the composite frame for the system, showing how the synchronous generator, governor, turbine and voltage controller are connected together and the
input / output signals between them. The blocks that represent the generator, governor, etc are
called slots and are placeholders for the models that describe their dynamic behaviour.
At this stage, we have just seen an overview for how the hydro generation control system is
structured (i.e. a frame). We still have to define the individual dynamic models for the governor,
turbine and voltage controller. Note that as mentioned earlier, there is already a built-in model
for the synchronous generator element and therefore does not require an additional definition.
Lets first define a voltage controller based on a simple PID controller as shown in Figure 2.5.
This block diagram represents the model definition for the voltage controller. We can perform
a similar exercise and define model definitions for the governor and turbine (not shown here).
Once we have finished creating these model definitions, we will have then defined complete
blueprints for the hydro generation control system, i.e. the individual dynamic model definitions

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

Dynamic Modelling Concepts in PowerFactory

Figure 2.3: Hydroelectric dam, turbine and generator (Image courtesy of Wikipedia)

Figure 2.4: Composite frame for hydroelectric generation system

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

Dynamic Modelling Concepts in PowerFactory

Figure 2.5: Model definition for a simple voltage controller

for the governor, turbine and voltage controller, the built-in model for the generator and how they
are all connected together (the composite frame).
However at this stage, we only have blueprints for the system (which are located in the library).
We still need to create actual instances of the equipment inside the grid. Built-in grid elements
such as synchronous generators can be created by the drawing tools in the PowerFactory GUI.
However, composite models and common models need to be created from within the Data
Manager (inside a grid folder) using the New Object function.
We can first create a composite model and link it to the composite frame we defined earlier
(see Figure 2.4). The slots for the generator, governor, turbine and voltage controller now
need to be filled. For the generator slot, we can select the relevant generator element in the
grid. For the other slots, we will have to create common models and link them to the relevant
model definition. In the end, the complete composite model is shown in Figure 2.6. The same
composite model as seen from inside the data manager is shown in Figure 2.7.

Figure 2.6: Complete composite model for hydro generator system

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

10

Dynamic Modelling Concepts in PowerFactory

Figure 2.7: Composite model of hydro generator system in the data manager

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

11

Creating Dynamic Models

Creating Dynamic Models

3.1

General Procedure

The general procedure for creating a dynamic model in PowerFactory is as follows:

1. Consider the structure of the system to be modelled and how it can be broken down into
discrete blocks that can be modelled separately
2. Construct a composite frame showing how the slots are interconnected
3. Create each of the model definitions and set appropriate initial conditions (see Section 4
4. Create a composite model and fill the slots with the relevant grid elements, e.g. common
models, built-in models, measurement devices, etc
5. Test the complete model (see Section 5).

3.2

Library Objects

Both composite frames and model definitions are created in PowerFactory using the block definition object (BlkDef). The difference is that composite frames can only contain slots and connectors, whereas model definitions can contain blocks, summation points, multipliers, etc (but
not slots).
PowerFactory recognises whether the block definition is a composite frame or a model definition
based on the first block or slot that is drawn in the diagram. If a block is drawn, the slot icon
is automatically deactivated so that slots and blocks cannot be mixed up in the same diagram
(and vice versa if a slot is drawn first).

3.2.1

Composite Frames

Composite frames are diagrams containing slots and connectors, showing how network elements and common models are to be connectd together. Composite frames are purely graphical
and contain no equations.
Refer to Chapters 25.9.2 and 25.10 of the user manual (v15.0) for more details on the handling
and creation of composite frames.

3.2.2

Model Definitions

A model definition describes the mathematical transfer function of a dynamic model in the form
of equations and / or graphical block diagrams. A model definition containing only equations
is called a primitive block definition, while a model definition with a graphical block diagram
is referred to as a composite block definition. Both primitive and composite block definitions
can be reused inside other higher-level model definitions (PowerFactory supports an arbitrary
number of layers).
Refer to Chapters 25.10 of the user manual (v15.0) for more details on the general handling and
creation of model definitions.
Some DSL syntax guidelines to keep in mind when creating model definitions:
Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

12

Creating Dynamic Models

Figure 3.1: An example of a composite frame for a synchronous generator

Figure 3.2: An example of a model definition for hydraulic turbine

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

13

Creating Dynamic Models

A state variable cannot be defined as an output to a model definition.

Derivatives may only appear on the left-hand side of equations.
Algebraic loops and recursion (e.g. for and while loops) are not supported in DSL.
If-then-else statements are not supported in DSL (use the select function instead).
The maximum line length is 80 characters.
Complex numbers are not supported.
Variable names are case sensitive.
Comments can be added to DSL code using an exclamation mark (!) as a prefix, e.g.
!This is a comment.
DSL statements are executed in an iterative manner so the order of statements is not
important
Refer also to the DSL function reference in Appendix A.

3.3
3.3.1

Grid Objects
Composite Models

A composite model is a grid object that represents a complete dynamic system (e.g. generator
with prime mover and voltage control). A composite model references a composite frame and
inherits its structure (i.e. the interconnections between system components). The relevant
system components, e.g. network elements, common models, measurement devices, etc. are
assigned to the relevant slots in the composite model.
Composite models are created from within a data manager (e.g. by the New Object button
or from the context menu New Others), inside the active grid folder. Once a frame is
selected, the relevant system components (for example, see Figure 3.3) can be assigned to the
slots. It is best practice to store elements such as common models and measurement devices
inside the composite model object (for example, see Figure 2.7).

3.3.2

Common Models

A common model is a grid object that represents a physical instance of a model definition. A
common model inherits the block diagram of the linked model definition, but has its own local
parameter settings.
Common models are created from within a data manager (e.g. by the New Object button or
from the context menu New Others). Once a model definition has been selected, the
parameters of the common model can be entered (for example, see Figure 3.4).

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

14

Creating Dynamic Models

Figure 3.3: An example of a composite model with elements assigned to slots

Figure 3.4: An example of a common model and its parameters

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

15

Model Initialisation

Model Initialisation

In PowerFactory , all dynamic models are initialised according to a load flow calculation. In other
words, prior to the start of a time-domain simulation, the system is operating in a steady state
condition and network voltages, active and reactive power flows, loadings, etc. are defined by
the load flow solution. This also means that the operational configuration defined for the load
flow calculation (e.g. generator active / reactive power dispatch, settings for station controllers,
etc.) is used as the steady-state starting point for the time-domain simulation. It is recommended that the steady-state load flow is configured correctly before running a time-domain
simulation.

4.1

How Models are Initialised in PowerFactory

The initialisation process is generally performed in the opposite direction from normal operation,
i.e. from right-to-left or output-to-input (although this is not always the case). This is because
the outputs of the model are usually known (e.g. from the steady-state load flow calculation) and
the inputs are unknown and need to be initialised. Model initialisation typically starts at the grid
elements and then works backward through the other blocks, initialising each block completely
one at a time.
In most models, a number of variables (or signals) will need to be manually initialised. This is
generally for variables or signals that cannot be determined directly from the load flow solution.
Note that not all of the variables and signals in a model need to be manually initialised. When
a variable or signal is not known or manually initialised, PowerFactory will try to use the model
equations to compute its initial value. An error will be thrown if the model equations have
undefined variables or signals (e.g. an unknown input). Undefined variables or signals need to
be manually initialised, for example:
All state variables
All unknown input (and output) signals
Elaborating on the concept of known and unknown signals, known signals are those that are
connected to built-in models (e.g. grid elements such as synchronous machines, transformers,
etc) or other DSL models that have already been initialised.
For example, consider Figure 4.1 showing a frame of a governor and turbine connected to a
synchronous generator.

Figure 4.1: Frame showing a governor and turbine connected to a synchronous generator
The initialisation process starts at the synchronous generator element, a grid element with a
built-in model. The signals (pt and speed) are calculated automatically based on the steadystate load flow solution and are known.
Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

16

Model Initialisation

The turbine block is the next block initialised. The output signal pt is known from the generator
element, but the input signal g is unknown, and must be manually initialised. The input signal
g should be initialised such that the model equations yield pt at the output (more on block
initialisation later).
Lastly, the governor block is initialised. Since the output signal g has already been initialised in
the turbine block and the speed input is known from the generator element, no manual initialisation of the input / output signals for this block are required. However, any internal state variables
in the block need to be manually initialised.
Note that it may also be possible for the output signal g to be calculated using the model equations from the speed input. If this is possible, then the calculated g should be the same as the
g initialised in the turbine block. If its not, then an error message will be shown (Block not
correctly initialised).

4.2

Initialisation of Common Primitive Blocks

Before looking at the initialisation of complicated block diagrams, we will first examine the initialisation of primitive blocks such as integrators, differentiators, first-order lags, etc. The general
rule is that in the steady state, all derivates are zero, i.e. dx
dt = 0 or s = 0.
4.2.1

Integrator

Figure 4.2: (a) Integrator block, (b) Steady state representation

The standard integrator block is shown in Figure 4.2(a) and describes the function yo =
It is implemented in DSL using a state variable x as follows:

yi dt.

dx
= yi
dt
yo = x
The DSL code representation for the above equations is:
x.

= yi

yo = x
Figure 4.2(b) shows the equivalent steady state representation of the integrator block. In the
steady state, the input yi = 0 (i.e. since all derivatives are zero and there is nothing to integrate).
The output yo is the steady state value yo,ss , which can be calculated from known initial values
(e.g. load flow quantities). The state variable x should therefore also be initialised to the steady
state output yo,ss .
The step response of the integrator block is shown in Figure 4.3.
Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

17

Model Initialisation

Figure 4.3: Step response of integrator

4.2.2

First-order Lag Differentiator

Figure 4.4: (a) First-order lag differentiator block, (b) Steady state representation
The basic first-order lag differentiator block is shown in Figure 4.4(a) and loosely describes the
i
function yo = dy
dt , but with a lag (and low pass filtering). It is implemented in DSL using a linear
difference approximation, plus a state variable x:

dx
yi x
=
dt
T
dx
yo =
dt
The DSL code representation for the above equations is:
limits(T)=(0,)
dx=(yi-x)/T
x.

= dx

yo = dx
Figure 4.4(b) shows the equivalent steady state representation of the differentiator block. In the
steady state, the output is not fluctuating and thus yi = yo = 0. The state variable x should
therefore be initialised to zero.
Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

18

Model Initialisation

The step response of the first-order lag diferentiator block is shown in Figure 4.5.

Figure 4.5: Step response of first-order lag differentiator

4.2.3

First-order Lag

Figure 4.6: (a) First order lag block, (b) Steady state representation
The first-order lag block is shown in Figure 4.6(a) and its steady-state representation is shown
in Figure 4.6(b). The state variable x should be initialised to the steady state output yo,ss .
The step response of the first-order lag block is shown in Figure 4.7.

4.2.4

PI Controller

The PI controller block is shown in Figure 4.8(a) and its steady-state representation is shown in
Figure 4.8(b). Like the integrator block, the state variable x should be initialised to the steady
state output yo,ss .
The step response of the PI controller block (with ki = kp = 0.5) is shown in Figure 4.9.

4.3

Initialisation of Composite Block Definitions

As shown previously, primitive block models can be combined to form more complex block definitions. In this section, we will firstly walk through the initialisation of an example composite

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

19

Model Initialisation

Figure 4.7: Step response of first-order lag

Figure 4.8: (a) PI controller block, (b) Steady state representation

Figure 4.9: Step response of PI controller (ki = kp = 0.5)

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

20

Model Initialisation

block definition. Afterwards, some more general rules are articulated for composite block initialisation.

Figure 4.10: Block definition for a hydro turbine

Figure 4.11: Steady state representation of hydro turbine block diagram

4.3.1

Example: Hydro Turbine Block Initialisation

Consider the hydro turbine block definition in Figure 4.10. Suppose that this turbine block will be
connected in the frame shown in Figure 4.1. The output pt is therefore known and we need to
manually initialise the input g. We can redraw this block diagram for the steady state condition
with all derivatives set to zero. This steady state representation is shown in Figure 4.11. From
this steady-state representation, we can work backwards from the known output pt and calculate
an initial value for the input g:
Since we know that dH = 0 and H0 is a constant, then H = H0. Therefore:
pt
K
Pm
dU =
H0
U = U nl + dU

UG = H
U
G=
UG
G
g=
At
Pm =

If we put these equations together, we can derive a single expression for g:

Pt
+ U nl

g = KH0
H0 At

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

(1)

21

Model Initialisation

Note that it isnt necessary to initialise g with a single expression. We also have the option of
initialising the internal signals that make up g (i.e. Pm, dU, U, etc). The state variable for the
integrator block also needs to be initialised, and it will have the steady state value U .

4.3.2

General Procedure for Composite Block Initialisation

Using the example in the preceding section as a reference, we can articulate a general procedure for calculating the initial conditions for a composite block:
1. Consider the frame in which the composite block is located and how it will be connected
to other slots.
In the hydro turbine example, we saw that the turbine slot was connected to the synchronous machine and governor slots.
2. Determine which signals (and variables) are known and unknown
This follows on from step one - once the signal relationships of the slot is known in the
context of the frame, then we can identify a) the signals that will be known from a load flow
initialisation, and b) the signals that we need to initialise manually. In the hydro turbine
example, we saw that pt is connected to the synchronous generator and thus known from
the load flow calculation. The input g, however, is unknown and needs to be initialised
manually. We also look inside the block definition and identify all the state variables (which
all require manual initialisation).
3. Construct a steady-state representation of the block diagram
Set all derivatives to zero and redraw the block to show its steady-state configuration. In
the hydro turbine example, the integrator block is redrawn and the steady-state representation is shown in Figure 4.11.
4. Calculate the unknown signals (and variables) from the known quantities
In the hydro turbine example, we worked backwards from the known output pt to calculate
the unknown steady-state input g, as well as the quantity U for the integrator state variable.

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

22

Model Initialisation

4.4

Setting Initial Conditions in DSL

Once the initial conditions have been identified, they have to be set in the composite block DSL
equations. Manual initialisations must be entered in code form inside the equations window of
the block definition dialog (see Figure 4.12 below).

Figure 4.12: Equations window of the block definition dialog box

There are three statements available for setting initial conditions:
inc (variable) = expression
inc0 (variable) = expression
incfix (variable) = expression
The inc statement is the standard statement for initialisation. The inc0 statement is only executed if the signal is not connected and is typically used to test models in isolation or when the
signal is not used, but needs to be initialised (more on the use of inc0 in Section 5.3). Lastly,
the incfix statement is only used for automatic calculation of initial conditions (see Section 4.6).
The use of the inc statement is straightforward and can be illustrated by example. In the previous hydro turbine example, we can initialise g as follows:
inc(g) = (pt / (K * H0) + Unl) / (sqrt(H0) * At)

4.5

Iterative Setting of Initial Conditions

Occasionally, it is impossible to determine closed form algebraic equations for the initial conditions, especially when there are non-linearities involved. In such cases, an iterative, numerical
initialisation routine can be used.
For example, consider a wind turbine model with inputs and outputs as shown in Figure 4.13.
The equations for the wind turbine model are as follows:
kb speed
vw
3
pw = ar Cp vw
=

Cp = f (, )

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

23

Model Initialisation

Figure 4.13: Wind turbine block I/O

Where the function f (, ) is a non-linear function of power coefficients without a closed form
and is represented by a two-dimensional matrix (i.e. a lookup table).
Suppose that in this model, the input speed and output pw is known, and that we can initialise
= 0. Therefore, to complete this model we need to manually initialise vw . However from
inspection of the above equations, a closed form solution for vw cannot be found because of
the presence of the non-linear function f (, ). In this case, we can use an iterative search to
calculate the initial condition for vw .
There are three iterative search algorithms available in PowerFactory : 1) Linear search, 2)
Internal division search, and 3) Newton iterative search. Well look at each one in turn and use
them to initialise the wind turbine example above.

4.5.1

Linear Search

The linear search function (loopinc) has the following usage:

inc(varp) = loopinc (varnm, min, max, step, error)
This function performs a line search from a minimum value (min) to a maximum value (max)
with stepsize step and tries to find the parameter value (varp) that yields an output closest to
known parameter varnm. A warning message is shown if the smallest deviation is larger than
the parameter error.
To illustrate how to use the linear search function, we can apply it to the wind turbine example
above. We want to initialise the parameter vw , which is directly related to a known signal pw .
We can use the linear search function to find the value of vw that will yield a value of pw closest
to its initial value:
inc(pw) = 9.5
inc(vw) = loopinc (pw, 5, 15, 0.01, 0.01)
In the above snippet, the function will search through all values of vw between 5 and 15 with a
3
step size of 0.01 and return the value of vw such that pw = ar Cp vw
is closest to our initial
value of pw = 9.5.

4.5.2

Internal Division Search

The internal division search function (intervalinc) has the following usage:
inc(varp) = intervalinc (varnm, min, max, iter, error)
This function performs an internal division search over the inteval [min, max], by successively
bisecting the interval into smaller sub-intervals and selecting the sub-interval where the the

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

24

Model Initialisation

parameter value (varp) yields an output closest to known parameter varnm. The function
continues for iter iterations. A warning message is shown if the smallest deviation is larger
than the parameter error.
To illustrate how to use the internal division search function, we can apply it to the wind turbine
example above. We want to initialise the parameter vw , which is directly related to a known
signal pw . We can use the internal division search function to find the value of vw that will yield
a value of pw closest to its initial value:
inc(pw) = 9.5
inc(vw) = intervalinc (pw, 5, 15, 50, 0.01)
In the above snippet, the function will bisect the interval [5,15] a total of 50 times. At each
iteration, the next sub-interval to bisect is chosen by finding the value of vw such that pw =
3
ar Cp vw
is closest to our initial value of pw = 9.5.
4.5.3

Newton Iterative Search

The Newton iterative search function (newtoninc) has the following usage:
inc(varp) = intervalinc (expr, start, iter, error)
This function performs a Newton algorithm to find the parameter value varp such that it equals
expr, using an initial estimate start and running for iter iterations or until the absolute error
is less than error.
To illustrate how to use the Newton iterative search function, we can apply it to the wind turbine
example above. We want to initialise the parameter vw , which is directly related to a known
signal pw . Firstly, the equation for pw must be rearranged so that it is evaluated in terms of vw :

vw =

pw
ar Cp

 13
(2)

The above equation can then be further rearranged so that it is in homogenous form:

vw

pw
ar Cp

 31
=0

(3)

We can now use the Newton iterative search function to find the value of vw that will minimise
the error of the homogenous equation above given a fixed initial value for pw :
inc(pw) = 9.5
inc(vw) = newtoninc (pow(pwind/rhoAr/Cp,1/3), 5, 50, 0.00001)
In the above snippet, the function performs a Newton iterative search on the homogenous equation (with fixed pw = 9.5) using an initial estimate of vw = 5, a maximum number of iterations of
50 and a maximum error rate of 0.00001.

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

25

Model Initialisation

4.6

Automatic Calculation of Initial Conditions

PowerFactory offers an automatic calculation of initial conditions feature that internally uses an
iterative method to determine the unknown initial conditions (refer to the previous Section 4.5
for more details on the iterative methods available).

Figure 4.14: Automatic calculation of initial conditions option in block definition

The feature is located in the block definition dialog (see Figure 4.14). Ticking the checkbox will
activate the feature, however it requires some additional configuration to make it work properly.
The variables to be initialised should be configured with either fixed (known) initial conditions or
estimates. This can typically be done with the inc and incfix statements.
In the context of automatic initialisation, the inc statement simply initialises the variable with an
estimated starting value (which may or may not be right). The iterative algorithm will determine
the correct initial condition for the variable. The incfix statement, on the other hand, defines a
fixed initial condition for the variable. This is normally used in ambiguous sitations where the
value of one or more variables needs to be fixed.

4.6.1

Example: Simple Block

As a simple example, suppose a block has two inputs (x1, x2) that will be automatically initialised
to a known output (yo), say a basic equation such as yo = x1 + x2. If we knew that yo = 5 and
we didnt fix x1 or x2, then there would be an infinite number of solutions for (x1, x2), e.g. (3,2),
(2,3), (1,4), (5,0), etc.
In this case, we can initialise one of the variables x1 or x2 with incfix to a fixed value, and put
an arbitrary starting estimate for the other variable, i.e.:
incfix(x1) = 3

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

26

Model Initialisation

inc(x2) = 0
The iterative algorithm will then calculate (x1, x2) = (3, 2) as the correct set of initial conditions.
If incfix is not used, then PowerFactory will output the warning message Unnecessary inputs
have been left unchanged (arbitrary choice)! and solve for the initial conditions with one of the
starting estimates arbitrarily fixed.

4.6.2

Example: Wind Turbine Block

Let us revisit the wind turbine example in Section 4.5 and evaluate the initial conditions with
the automatic initialisation feature. In this case, we want to fix output pw to a known value, say
pw = 9.5 as before:
incfix(pw) = 9.5
We also have to give a starting estimate for the input vw , i.e.
inc(vw) = 7

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

27

Testing and Troubleshooting

5
5.1

Testing and Troubleshooting

Verifying Model Equations

After creating a block definition and setting up the diagram, equations and initialisation, the
first step in testing the model should be to check for syntax and typing errors using the built-in
Check and Check Inc. functions (see Figure 5.1).

Figure 5.1: Check and Check Inc. functions in the block definition dialog
The Check function looks for syntax and typographical errors, for instance, built-in function
names that are misspelled (e.g. sqrut(4) instead of sqrt(4)), mathematical syntax errors
(e.g. 2 ++ 3 instead of 2 + 3), variable or signal names that dont exist or are misspelled, etc.
Actual numerical checks are not performed (i.e. it does not check for the evaluation of undefined
calculations such as divide by zero conditions).
Check Inc. function simply checks that all the state variables are initialised (for non-macro
blocks) and also prints out the complete set of model equations and initial conditions.

5.2

Viewing Model Signals and Variables during Initialisation

When testing models and troubleshooting initialisation issues, it is useful to be able to examine
the input / output signals connecting the common models, as well as any internal and state
variables from inside the common models. The following subsections describe the three ways
to see model signals and variables that are available in PowerFactory .

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

28

Testing and Troubleshooting

5.2.1

Printing Values to the Output Window

Firstly, run the Calculate Initial Conditions command. Next, create a variable set for the DSL
common model object of interest. From the variable set dialog, select the signals (or variables)
of interest and press the Print Values button to show the calculated initial values of the selected
signals or variables (see Figures 5.2 and 5.3).
Note that signals and state variables are located in the Signals menu, and internal variables
are located in the Calculation Parameter menu.

Figure 5.2: Printing initial values from the variable set dialog

Figure 5.3: Result of Print Values button in output window

5.2.2

Flexible Data

The flexible data window can also be used to view model signals and variables. Find the DSL
common model of interest in the data manager, select Detail Mode (the eyeglasses icon) and
then select the Flexible Data tab at the bottom of the window. Clicking on the Define Flexible
Data icon brings up a variable set dialog where the signals and variables of interests can be
selected. These signals and variables will then be displayed in the data manager as shown in
Figure 5.4.

5.2.3

Overlay of Signals in Block Diagrams

New feature in Version 15 (placeholder)

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

29

Testing and Troubleshooting

Figure 5.4: Using the flexible data window to view model signals and variables

5.3

Testing Models in Isolation

For a large composite model with many individual common models inside, it may be useful to
test each common model in isolation.

5.3.1

Initialising Disconnected Signals

When testing a model in isolation, there may be known signals that are normally connected to
other models (e.g. the hydro turbine output pt in Figure 4.10) that are now not connected to
anything. In such cases, these signals need to be initialised to dummy values for the purposes
of model testing.
This can be done using the inc0 statement, which allows us to initialise a disconnected signal.
Note that once the signals are connected back to other models, the inc0 statements are ignored.
As an example, lets revisit the hydro turbine model in Figure 4.10. In Section 4.3, we found that
the input g and state variable x needed to be initialised as follows:
inc(g) = (pt / (K * H0) + Unl) / (sqrt(H0) * At)
inc(x) = (pt / (K * H0) + Unl)
Recall from the frame in Figure 4.1 that the turbine block is connected to a synchronous machine
block, and thus the output pt is known from the load-flow initialisation of the synchronous
machine. If we want to test the the turbine block in isolation, we will need to initialise pt with
the inc0 statement, say to a value of pt = 0.95:
inc0(pt) = 0.95
We now create a common model object using the hydro turbine block definition and the model
parameters as shown in Figure 5.5. Running the Calculate initial conditions command yields
the initial conditions in Figure 5.6.

5.3.2

Step Response Tests

Once the model is initialised to run in isolation, we can test the step response of inputs to the
model by using parameter events. A parameter event allows us to change the value of any
signal (or variable) in an element or DSL model during a time-domain simulation.

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

30

Testing and Troubleshooting

Figure 5.5: Hydro turbine common model and parameters

Figure 5.6: Hydro turbine initial conditions

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

31

Testing and Troubleshooting

A parameter event can be defined by right clicking on the DSL common model object Define
Parameter Event. For example, Figure 5.7 shows a parameter event defined on the common
model Hydro Turbine. From this figure, we can see that at time t = 1s, we are changing the
input signal g to a new value of 1.05.

Figure 5.7: Parameter event on hydro turbine input signal g

Figure 5.8 shows the simulation result depicting the step change of the input signal g (the
black dashed line) and the response of the output pt (the blue line).

Figure 5.8: Hydro turbine step response

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

32

Testing and Troubleshooting

5.4

Advice for Troubleshooting Models

The following guidelines are provided to help find and resolve any issues encountered when
creating dynamic models in PowerFactory :
Add the initialisation equations to the composite block definitions, rather than to the primitive blocks.
Make sure that block definitions are set up so that each model can be initialised completely
one at a time.
Dont forget to initialise all state variables.
Signal and variable names are sensitive to context and whitespaces. For example, the
signals pt, Pt and pt (space at the end) are not the same. In particular, watch out for
spaces at the beginning or end of signal (or variable) names as problems may arise that
can be difficult to find.
When using inc0 statements, make sure that the signal names in the frame are the same
as the signal names in the model definition. Normally, when standard inc statements
are used, there will be an error during initialisation if the names dont match. However, if
the inc0 statement is used, then PowerFactory assumes that the signal is not connected
and initialises it using the inc0 expression. The model will initialise, but will not function
correctly. This can be a difficult bug to find, so take care of the naming in model definitions
and frames.
If one composite model is causing problems, put all the other models out of service and
try to solve the problem in isolation. The other models can be re-instated and tested again
once the problem has been solved.
The previous point also applies to a single composite model with many block definitions
(DSL common models). If there is a problem with one common model, try to put the
common models that are not directly connected or related to the problem model out of
service. Some dummy initialisation values (i.e. with the inc0 statement) may need to be
added.
Use the Verify Initial Conditions option in the Calculation of Initial Conditions command
object (ComInc).
Use the Display internal DSL-events in output window option in the Run Simulation
command object (ComSim).

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

33

Portability and Encryption

Portability and Encryption

6.1

Portability

When creating a composite block definition, it is common to use standard macros and primitive
blocks from the global library (e.g. integrators, time delays, PI controllers, etc.), or perhaps even
primitive blocks from other projects or libraries. In the block definition, there will consequently
be external references and links to the global library or other projects / libraries.
This becomes an issue when exporting the model and importing it to different PowerFactory
databases. Only the references are exported and if the other databases do not contain the
same reference macros or primitive blocks (or they have been modified), then the model will not
function as intended.
PowerFactory offers two functions to make DSL models more portable for reuse:
1. Pack
2. Pack Macro
Both of these functions can be found in the block definition dialog (see Figure 6.1 below).

Figure 6.1: Block definition packing and encryption functions

6.1.1

Pack

The Pack function takes all of the external macros used in a block definition and creates local
copies of them in a folder called Used Macros, located inside the block definition object itself
(see Figure 6.2 below). All of the references in the block definition are then linked to the local
Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

34

Portability and Encryption

macros in the Used Macros folder. The Pack function therefore creates a self-contained block
definition object without any external references.
It is important to note that if a macro needs to be altered after packing, the modifications must
be done to the local macro inside this folder (and not to the macro in the global library, other
project, etc).

Figure 6.2: Used macros folder created by Pack function

6.1.2

Pack to Macro

The Pack Macro function takes the Pack function one step further and reduces the entire
block definition into a set of equations. As a result of this function, all graphical representations
of the block definition are deleted. This function is irreversible and it is advised that a copy of
the block definition be made before attempting to use the Pack Macro function.

6.2

Encryption

Important Note: The DSL model encryption feature requires an additional license option and is
not included in the basic RMS or EMT simulation packages. Please contact DIgSILENT GmbH
if you require this feature.
Models that contain highly sensitive data (e.g. trade secrets, proprietary algorithms, etc) can be
encrypted so that the internal equations of the model are not visible to others. The Encrypt
function can be found in the block definition dialog (see Figure 6.1).
Note that the Encrypt function will only be enabled for block definitions without any graphical
representations (i.e. a macro or an equation block). If a block definition has a graphic, it must be
reduced to a set of equations using the Pack Macro function before the Encrypt function
can be utilised.
Figure 6.3 shows an example of the equations window when a block definition has been encrypted.

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

35

Portability and Encryption

Figure 6.3: Equations window of an encrypted block

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

36

DIgSILENT Training Courses

DIgSILENT Training Courses

DIgSILENT GmbH offers a standard 2-day training course on dynamic modelling and DSL. Inhouse courses are normally run twice per year at DIgSILENT s head office in Gomaringen,
Germany. However, special courses can be provided upon request. Please contact DIgSILENT
or consult the website (www.digsilent.de) for details on course dates and schedules.

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

37

DSL Function Reference

A
A.1

DSL Function Reference

DSL Standard Functions
function
sin(x)
cos(x)
tan(x)
asin(x)
acos(x)
atan(x)
sinh(x)
cosh(x)
tanh(x)
exp(x)
ln(x)
log(x)
sqrt(x)
sqr(x)
pow (x,y)
abs(x)
min(x,y)
max(x,y)
modulo(x,y)
trunc(x)
frac(x)
round(x)
ceil(x)
floor(x)
time()
pi()
twopi()
e()

description
sine
cosine
tangent
arcsine
arccosine
arctangent
hyperbolic sine
hyperbolic cosine
hyperbolic tangent
exponential value
natural logarithm
log10
square root
power of 2
power of y
absolute value
smaller value
larger value
remainder of x/y
integral part
fractional part
closest integer
smallest larger integer
largest smaller integer
current simulation time
3.141592...
6.283185...
2,718281...

example
sin(1.2)=0.93203
cos(1.2)=0.36236
tan(1.2)=2.57215
asin(0.93203)=1.2
acos(0.36236)=1.2
atan(2.57215)=1.2
sinh(1.5708)=2.3013
cosh(1.5708)=2.5092
tanh(0.7616)=1.0000
exp(1.0)=2.718281
ln(2.718281)=1.0
log(100)=2
sqrt(9.5)=3.0822
sqr(3.0822)=9.5
pow(2.5, 3.4)=22.5422
abs(-2.34)=2.34
min(6.4, 1.5)=1.5
max(6.4, 1.5)=6.4
modulo(15.6,3.4)=2
trunc(-4.58823)=-4.0000
frac(-4.58823)=-0.58823
round(1.65)=2.000
ceil(1.15)=2.000
floor(1.78)=1.000
time()=0.1234
pi()=3.141592...
twopi()=6.283185...
e()=2,718281...

Table A.1: DSL Standard Functions

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

38

DSL Function Reference

A.2

DSL Special Functions

lim
lim (x, min, max)
Nonlinear limiter function:

Figure A.1
vardef
vardef(varnm)=unitstring ; namestring
Defines the unit and name for variable varnm. It can be used for model parameters as well as
internal signals.
Examples:
vardef(Ton) = 's' ; 'Pick up time for restart' ! defines unit and name
vardef(Ton) = ; 'Pick up time for restart' ! defines name only vardef(Ton)
= 's' ; ! defines unit only
limits
limits(param)=(min, max)
Limiter function used to print a warning message to the Output Window if a parameter is
outside the specified limits. Brackets [ and ] are used to indicate the inclusion of the end
points in the range, ( and ) are used to indicate the exclusion of the end points from the
range.
Example:
limits(K)=(0,1]
limstate
limstate (x1, min, max)
Nonlinear limiter function for creating limited integrators. Works only with fixed limits, i.e.
min and max are parameters.
Example:

x1. = xe/Ti;
y = limstate(x1,min,max);
This was previously realized by using select and lim functions:
x1. = select( x1>=max.and.xe>0
& .or.x1<=min.and.xe<0, 0, xe/Ti);
y = lim(x1,min,max);
delay
delay (x, Tdelay)
Delay function. Stores the value x(Tnow) and returns the value x(Tnow-Tdelay). Tdelay
in seconds and larger than 0.0. The expression Tdelay must evaluate to a time independent constant and may therefore only consist of constants and parameter variables. The

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

39

DSL Function Reference

expression x(t) may contain other functions.

Example:
y = delay(xe + delay(x1, 1.0), 2.0)
Resetting a DSL model initializes its delay functions with x(Treset).
select
select (boolexpr, x, y)
Returns x if boolexpr is true, else y. Example:
x1.=select(T1>0, xe/T1, 0.0) !to avoid division by zero
time
time ()
Returns the current simulation time. Example:
t=time()
y = sin(t) or
y = sin(time())

file
file (ascii-parm, expr)
!OBSOLETE! Please use an ElmFile object in the composite model in stead.
picdro
picdro (boolexpr, Tpick, Tdrop)
Logical pick-up-drop-off function useful for relays. Returns the internal logical state: 0 or
1.
Return value:
The internal state:
changes from 0 to 1, if boolexpr=1, for a duration of at least Tpick seconds
changes from 1 to 0, if boolexpr=0, after Tdrop seconds
remains unaltered in other situations.
flipflop
flipflop (boolset, boolreset)
Logical flip-flop function. Returns the internal logical state: 0 or 1.
Return value:
The internal state:
changes from 0 to 1, if boolset=1 and boolreset=0 (SET)
changes from 1 to 0, if boolset=0 and boolreset=1 (RESET)
remains unaltered in other situations. (HOLD)
Initial value: boolset. The initial condition boolset=boolreset=1 will cause an error message.

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

40

DSL Function Reference

aflipflop
aflipflop (x, boolset, boolreset)
Analog flip-flop function. Returns the (old) value for x at SET-time if internal state=1, else
returns the current value of x.
Return value:
The internal state:
changes from 0 to 1, if boolset=1 and boolreset=0 (SET)
changes from 1 to 0, if boolset=0 and boolreset=1 (RESET)
remains unaltered in other situations. (HOLD)
lapprox
lapprox (x, array iiii)
Returns the linear approximation y=f(x), where f is defined by the array iiii. Please consider that the array has to be sorted in ascending order.
Example:
y = lapprox(1.8, array valve)
invlapprox
invlapprox (y, array iiii)
Inverse lapprox with array.
lapprox2
lapprox2 (xl, xc, matrix iiii)
Returns the linear approximation y=f(xl,xc) of a two-dimensional array, where f is defined
by the matrix iiii. xl represents the line value and xc the column of the matrix. Please
consider that the array has to be sorted in ascending order.
Example:
y = lapprox2(2.5, 3.7, matrix cp)
sapprox
sapprox (x, array iiii)
Returns the spline approximation y=f(x), where f is defined by the array iiii. Please consider that the array has to be sorted in ascending order.
Example:
y = sapprox(1.8, array valve)
sapprox2
sapprox2 (xl, xc, matrix iiii)
Returns the spline approximation y=f(xl,xc) of a two-dimensional array, where f is defined
by the matrix iiii. xl represents the line value and xc the column of the matrix.
Example:
y = sapprox2(2.5, 3.7, matrix cp)
event

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

41

DSL Function Reference

Option 1: calling a predefined event in the DSL element

event( Condition, trigger, 'name=ThisEvent dtime=delay value=val variable=var')
Option 2: target specification, no create parameter
event( Condition, trigger, 'target=ThisSlot name=ThisEvent dtime=delay value=val
variable=var')
Option 3: create and target specification
event( Condition, trigger, 'create=ThisEvtType target=ThisSlot name=ThisEvent dtime=delay
value=val variable=var')
This function can create or call any kind of event for the DSL model itself or elements
inside the network. The event is executed, if the input signal trigger changes sign from to + with a time delay of dtime.
Hint: the event command has changed from DSL level 3 to level 4!
Arguments:
int Condition (obligatory)
Boolean expression to activate (=1) or deactivate (=0) the event handling; if Condition is
set to 1, the event can be executed, depending on the trigger signal.
double trigger (obligatory)
The trigger signal, which will enable the execution of the event.
The string format determines the details of the event call, and which of the three options
above applies:
string ThisEvtType (mandatory, only option 3)
Type of event to be created. To specify the type use e.g. EvtParam for parameter event
or EvtSwitch for switch event, etc.
string ThisSlot (mandatory, only options 2 and 3)
If target=this is defined, the event is applied to a signal of the present DSL model. If any
other name is given, the DSL interpreter checks the composite model where the present
DSL model (common model) is used and searches for a slot with the given name. The
event is then applied to the element assigned to that slot.
string ThisEvent (obligatory)
Name of the event created (option 3) or the external event to be started (option 1/2). The
external event must be stored locally in the DSL model. If name=this is set, a parameter
event will be created and executed automatically with the DSL element itself as the target.
double delay (obligatory)
Delay time of the event after triggering.
double val (optional)
Value of the parameter event (only when name=this is set or when a parameter event is
created).
double var (optional)
Parameter to which the value is set (only when name=this is set or when a parameter
event is created).
Return value:
void (no return value)
Remark:

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

42

DSL Function Reference

If the event()-definition according to options 2/3 is used, the create and target parameters
must be the first parameters that are listed.
Examples:
The example shows a clock made with DSL using event( , ,'name=this ...') which automatically creates and configures a parameter event. The variable named xclock will be
reset to value val=0 within dtime=0, if the integrator output xclock is larger than 1. The
input signal is a clock signal with the time period Tclock.
inc(xclock)=0
inc(clockout)=0
xclock.=1/Tclock
reset clock=select(xclock>1,1,-1)
event(enable,reset clock,'name=this value=0 variable=xclock')
clockout=xclock
The following event calls an external event called OpenBreaker, which is stored and
defined inside the DSL element, if yo changes sign from - to +. The delay time is 0.2s.
event(1,yo,'name=OpenBreaker dtime=0.2')
The following event is a simple undervoltage load-shedding relay. The element in the
slot Load will be disconnected with a switch event EvtSwitch, when the signal u-umin
becomes positive. The event in the event list will be called TripLoad.
event(1,umin-u,'create=EvtSwitch name=TripLoad target=Load')

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

43

References

References
[1] Prabha Kundur. Power System Stability and Control. McGraw-Hill, Inc, 1994.
[2] K. Ogata. Modern Control Engineering. Prentice Hall, fifth edition, 2010.

Dynamic Modelling Tutorial (DIgSILENT Technical Documentation)

44