DSL Tutorial

DIgSILENT
PowerFactory
Advanced Tutorial
Dynamic Modelling (DSL)
I N T E G R AT E D P O W E R S Y S T E M A N A LY S I S S O F T W A R E F O R
TRANSMISSION / DISTRIBUTION / INDUSTRY / G E N E R AT I O N / I N T E G R AT I O N O F R E N E W A B L E S
Publisher:
DIgSILENT GmbH
Heinrich-Hertz-Strae 9
72810 Gomaringen / Germany
Tel.: +49 (0) 7072-9168-0
Fax: +49 (0) 7072-9168-88
info@digsilent.de
Please visit our homepage at:

http://www.digsilent.de
Copyright 2017 DIgSILENT GmbH

All rights reserved. No part of this
publication may be reproduced or
distributed in any form without written
permission of DIgSILENT GmbH.
February 2017
Version: 1
Edition: 3
Contents
Contents
1 Introduction 1
1.1 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2 Dynamic Modelling Concepts in PowerFactory 2
2.1 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.2 General Modelling Philosophy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2.1 Flexibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2.2 Inheritance and Reuse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.3 Built-in Error Detection and Testing . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.4 Example: Generator Control System . . . . . . . . . . . . . . . . . . . . . . . . . 5
3 Creating Dynamic Models 9
3.1 General Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.2 Library Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.2.1 Composite Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.2.2 Model Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.3 Grid Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.3.1 Composite Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.3.2 Common Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4 Model Initialisation 14
4.1 How Models are Initialised in PowerFactory . . . . . . . . . . . . . . . . . . . . . 14
4.2 Initialisation of Common Primitive Blocks . . . . . . . . . . . . . . . . . . . . . . . 15
4.2.1 Integrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.2.2 First-order Lag Differentiator . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.2.3 First-order Lag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.2.4 PI Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.3 Initialisation of Composite Block Definitions . . . . . . . . . . . . . . . . . . . . . 19
4.3.1 Example: Hydro Turbine Block Initialisation . . . . . . . . . . . . . . . . . 20
4.3.2 General Procedure for Composite Block Initialisation . . . . . . . . . . . . 20
DIgSILENT PowerFactory, Advanced Tutorial i

Contents
4.4 Setting Initial Conditions in DSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.5 Iterative Setting of Initial Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.5.1 Linear Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4.5.2 Internal Division Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.5.3 Newton Iterative Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.6 Automatic Calculation of Initial Conditions . . . . . . . . . . . . . . . . . . . . . . 25
4.6.1 Example: Simple Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.6.2 Example: Wind Turbine Block . . . . . . . . . . . . . . . . . . . . . . . . . 26
5 Testing and Troubleshooting 27
5.1 Verifying Model Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.2 Viewing Model Signals and Variables during Initialisation . . . . . . . . . . . . . . 27
5.2.1 Printing Values to the Output Window . . . . . . . . . . . . . . . . . . . . 28
5.2.2 Flexible Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.2.3 Overlay of Signals in Block Diagrams . . . . . . . . . . . . . . . . . . . . 29
5.3 Testing Models in Isolation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.3.1 Initialising Disconnected Signals . . . . . . . . . . . . . . . . . . . . . . . 29
5.3.2 Step Response Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.4 Advice for Troubleshooting Models . . . . . . . . . . . . . . . . . . . . . . . . . . 31
6 Portability and Encryption 33
6.1 Portability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.1.1 Pack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.1.2 Pack to Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
6.2 Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
7 DIgSILENT Training Courses 36
A DSL Function Reference 37
A.1 DSL Standard Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
A.2 DSL Special Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
References 43
DIgSILENT PowerFactory, Advanced Tutorial ii

1 Introduction
1 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 PowerFac-
tory 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]
DIgSILENT PowerFactory, Advanced Tutorial 1

2 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 equa-
tions 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).

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 Element Remarks

Library object Grid object
Composite frame Composite model
Model definition Common model
Class Instantiated object Programming analogy
Blueprint / design Equipment in the field 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.
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 con-
troller. 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.
Figure 2.2: Two model definitions each referenced by one common model (one-to-one)

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-
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.
Figure 2.3: Hydroelectric dam, turbine and generator (Image courtesy of Wikipedia)

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, excita-
tion voltage), control objectives and feedback (i.e. frequency, terminal voltage). This can be
summarised by a block diagram as shown Figure 2.4.
Figure 2.4: Composite frame for hydroelectric generation system
This block diagram represents the composite frame for the system, showing how the syn-
chronous 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.

Figure 2.5: Model definition for a simple voltage controller
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
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
Figure 2.7: Composite model of hydro generator system in the data manager

3 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 el-
ements and common models are to be connected together. Composite frames are purely
graphical and contain no equations.
Refer to the User Manual for more details on the handling and creation of composite frames.

Figure 3.1: An example of a composite frame for a synchronous generator
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).

Figure 3.2: An example of a model definition for hydraulic turbine
Refer to the User Manual for more details on the general handling and creation of model
definitions.
Some DSL syntax guidelines to keep in mind when creating model definitions:
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 Grid Objects
3.3.1 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).
Figure 3.3: An example of a composite model with elements assigned to slots
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).

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

4 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 recom-
mended 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 steady-
state load flow solution and are known.
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.
= 0 or = 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 = .
It is implemented in DSL using a state variable as follows:

=

=
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 = 0 (i.e. since all derivatives are zero and there is nothing to integrate).

The output is the steady state value , , which can be calculated from known initial values
(e.g. load flow quantities). The state variable should therefore also be initialised to the steady
state output , .
The step response of the integrator block is shown in Figure 4.3.
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
function =
, but with a lag (and low pass filtering). It is implemented in DSL using a linear

difference approximation, plus a state variable :

=

=

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 = = 0. The state variable should
therefore be initialised to zero.
The step response of the first-order lag differentiator 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 should be initialised to the steady state output , .
The step response of the first-order lag block is shown in Figure 4.7.

Figure 4.7: Step response of first-order lag
4.2.4 PI Controller
Figure 4.8: (a) PI controller block, (b) Steady state representation
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 should be initialised to the steady
state output , .
The step response of the PI controller block (with = = 0.5) is shown in Figure 4.9.

Figure 4.9: Step response of PI controller ( = = 0.5)
4.3 Initialisation of Composite Block Definitions
As shown previously, primitive block models can be combined to form more complex block defi-
nitions. In this section, we will firstly walk through the initialisation of an example composite 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 = 0 and 0 is a constant, then = 0. Therefore:

=

=
0
= +

=

=

=

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

+
= 0
(1)
0
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 .
4.3.2 General Procedure for Composite Block Initialisation
Using the example in the preceding section as a reference, we can articulate a general proce-
dure 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 syn-
chronous 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 represen-
tation 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 for the integrator state variable.

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 condi-
tions, 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.

Figure 4.13: Wind turbine block I/O
The equations for the wind turbine model are as follows:

=

3
=
= (, )
Where the function (, ) 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 and output is known, and that we can initialise
= 0. Therefore, to complete this model we need to manually initialise . However from
inspection of the above equations, a closed form solution for cannot be found because of
the presence of the non-linear function (, ). In this case, we can use an iterative search to
calculate the initial condition for .
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 , which is directly related to a known signal .
We can use the linear search function to find the value of that will yield a value of 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 between 5 and 15 with a
3
step size of 0.01 and return the value of such that = is closest to our initial
value of = 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 interval [min, max], by succes-
sively bisecting the interval into smaller sub-intervals and selecting the sub-interval where the
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 , which is directly related to a known
signal . We can use the internal division search function to find the value of that will yield
a value of 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 such that =
3
is closest to our initial value of = 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 , which is directly related to a known
signal . Firstly, the equation for must be rearranged so that it is evaluated in terms of :
( ) 13

= (2)

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

=0 (3)

We can now use the Newton iterative search function to find the value of that will minimise
the error of the homogenous equation above given a fixed initial value for :
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 = 9.5) using an initial estimate of = 5, a maximum number of
iterations of 50 and a maximum error rate of 0.00001.
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 situations 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
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 to a known value, say
= 9.5 as before:
incfix(pw) = 9.5
We also have to give a starting estimate for the input , i.e.
inc(vw) = 7

5 Testing and Troubleshooting
5.1 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 .

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.

Figure 5.4: Using the flexible data window to view model signals and variables
5.2.3 Overlay of Signals in Block Diagrams
New feature in Version 15 (placeholder)
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 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.

Figure 5.5: Hydro turbine common model and parameters
Figure 5.6: Hydro turbine initial conditions
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.
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
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 primi-

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

6 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

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

Figure 6.3: Equations window of an encrypted block

7 DIgSILENT Training Courses
7 DIgSILENT Training Courses
DIgSILENT GmbH offers a standard 2-day training course on dynamic modelling and DSL. In-
house 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.

A DSL Function Reference
A.1 DSL Standard Functions
function description example

sin(x) sine sin(1.2)=0.93203
cos(x) cosine cos(1.2)=0.36236
tan(x) tangent tan(1.2)=2.57215
asin(x) arcsine asin(0.93203)=1.2
acos(x) arccosine acos(0.36236)=1.2
atan(x) arctangent atan(2.57215)=1.2
sinh(x) hyperbolic sine sinh(1.5708)=2.3013
cosh(x) hyperbolic cosine cosh(1.5708)=2.5092
tanh(x) hyperbolic tangent tanh(0.7616)=1.0000
exp(x) exponential value exp(1.0)=2.718281
ln(x) natural logarithm ln(2.718281)=1.0
log(x) log10 log(100)=2
sqrt(x) square root sqrt(9.5)=3.0822
sqr(x) power of 2 sqr(3.0822)=9.5
pow (x,y) power of y pow(2.5, 3.4)=22.5422
abs(x) absolute value abs(-2.34)=2.34
min(x,y) smaller value min(6.4, 1.5)=1.5
max(x,y) larger value max(6.4, 1.5)=6.4
modulo(x,y) remainder of x/y modulo(15.6,3.4)=2
trunc(x) integral part trunc(-4.58823)=-4.0000
frac(x) fractional part frac(-4.58823)=-0.58823
round(x) closest integer round(1.65)=2.000
ceil(x) smallest larger integer ceil(1.15)=2.000
floor(x) largest smaller integer floor(1.78)=1.000
time() current simulation time time()=0.1234
pi() 3.141592... pi()=3.141592...
twopi() 6.283185... twopi()=6.283185...
e() 2,718281... e()=2,718281...
Table A.1: DSL Standard Functions

A.2 DSL Special Functions
lim
lim (x, min, max)

Nonlinear limiter function:
Figure A.1
vardef
vardef(varnm)=unfitting ; hamstring
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 realised 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). Delay in
seconds and larger than 0.0. The expression Delay must evaluate to a time independent

constant and may therefore only consist of constants and parameter variables. The
expression x(t) may contain other functions.
Example:
y = delay(xe + delay(x1, 1.0), 2.0)
Resetting a DSL model initialises 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 mes-
sage.

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

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:

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 auto-
matically 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')

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.


DSL Tutorial

Uploaded by

Document Information

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

DSL Tutorial

Uploaded by

Copyright:

Available Formats

DIgSILENT

Dynamic Modelling (DSL)

Please visit our homepage at:

Copyright 2017 DIgSILENT GmbH

2 Dynamic Modelling Concepts in PowerFactory 2

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

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

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

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

3 Creating Dynamic Models 9

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

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

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

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

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

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

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

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

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

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

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

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

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

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

DIgSILENT PowerFactory, Advanced Tutorial i

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

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

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

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

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

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

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

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

5 Testing and Troubleshooting 27

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

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

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

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

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

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

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

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

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

6 Portability and Encryption 33

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

7 DIgSILENT Training Courses 36

A DSL Function Reference 37

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

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

DIgSILENT PowerFactory, Advanced Tutorial ii

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

Modern Control Engineering by K. Ogata [2]

DIgSILENT PowerFactory, Advanced Tutorial 1

2 Dynamic Modelling Concepts in PowerFactory

Network Element: is an built-in model representing a standard piece of power system

DIgSILENT PowerFactory, Advanced Tutorial 2

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.

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

2.2.2 Inheritance and Reuse

Type Element Remarks

Table 2.1: Type and element analogies

DIgSILENT PowerFactory, Advanced Tutorial 3