Introduction to DSL (DIgSILENT Simulation Language)

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.

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

• 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 Concepts in PowerFactory

1.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 don’t 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 a built-in model representing a standard piece of power system equipment, e.g.
generators, motors, transformers, converters, etc.
• DSL Model Type: is the structure of a dynamic model containing its mathematical representation in the
form of a set of equations and/or a set of graphical macros. DSL Model Types are objects that belong in
the user defined models library.
• DSL Model: is the network instance that links a model definition to an actual piece of dynamic equipment
with specific parameters. DSL models are grid elements and so must be located in the grid.
• Composite Model Frame: is a diagram establishing the connections between dynamic models and
network elements. Frames are type objects that belong in the user defined models library.
• Slot: is a block in the composite frame that represents an object location in the interconnection diagram,
e.g. network elements, measurement devices and DSL models. The user must define what type of object
the slot represents.
INTRODUCTION TO DSL

• Composite Model: is the grid instance of a composite model frame. It represents a dynamic system
(e.g. generator with prime mover control and voltage regulator). The composite model establishes the
links between actual network elements, measurement devices and DSL models.
• Block Definition: is the name of the PowerFactory object (BlkDef ) used to build both composite model
frames and DSL model types. Block definitions can be built from both equations and graphical block
diagrams.
• Primitive Block Definition: is a DSL model type containing only a set of equations with no graphical
representation.
• Composite Block Definition: is a DSL model type definition that has a graphical block diagram repre-
sentation and may be built up from primitive block definitions.
• Macro: is a block definition intended to be part of a composite block definition and contains the equation
for a specific function of a dynamic model. Macros can be used in different composite block definitions.
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).
• Measurement Device: is a PowerFactory built-in element used to obtain from a bus and/or branch
different values like bus voltages, frequency and angle, branch currents and power flows which can be
used in a Composite Model to be connected to a Common Model.
• Block Diagram: is a step-by-step diagram that represents the relation between different functions or
sub-processes of a dynamic system.

1.2 General Modelling Philosophy

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

• Flexibility: 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. composite model frame or DSL model type) with local parameter settings.
• Built-in Error Detection: detection of structural and syntax errors at model implementation time.

1.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. A very
powerful tool to build a dynamic model is the PowerFactory graphical interface. The basic building blocks for the
graphical interface are macro definitions containing mathematical functions written in 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.

1.2.2 Inheritance and Reuse

PowerFactory uses an object-oriented approach that encourages reuse by strictly enforcing the distinction be-
tween 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.

Rev.2 2
INTRODUCTION TO DSL

This same philosophy is reflected in PowerFactory ’s approach to dynamic modelling. There are type objects in
the library (i.e. composite model frames and DSL model types) that are referenced by element objects in the
grid (i.e. composite models and DSL models). These grid elements inherit the properties of the type objects
(e.g. a DSL model inherits the block structure of its linked DSL model type).

To provide a more concrete example, consider the two diagrams in Figure 1.1 and Figure 1.2. Suppose that
the composite model 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 (DSL
models 1 and 2).

Suppose that both generators use the same type of vendor A voltage controller. Instead of defining the block
diagram for each voltage controller individually, the PowerFactory philosophy is to define the vendor A voltage
controller once as a type (DSL model type) and then create two different instances (DSL models) for each of
the generators (each with their own local parameter settings). This configuration is reflected in Figure 1.1.

Figure 1.1: Single DSL model type referenced by two DSL models (one-to-many)

Now suppose that one of the vendor A voltage controllers is replaced with a vendor B voltage controller.
We can create a new DSL model based on the vendor B block diagram and replace the vendor A controller
in the composite model (all the while using the same composite model and composite model frame). This
configuration is reflected in Figure 1.2.

Rev.2 3
INTRODUCTION TO DSL

Figure 1.2: Two DSL model type each referenced by one DSL model (one-to-one)

1.3 Built-in Error Detection

To achieve ample modelling flexibility, there is no strictly defined workflow for creating dynamic models. There
are few restrictions on how a user can construct models and with this freedom, models with very complicated
structures can be created. A user could then create model structures that are unsound, but, rather than
imposing restrictions, the philosophy adopted by PowerFactory is to provide tools for error detection instead.

1.4 Example: Generator Control System

The built-in synchronous machine model (ElmSym) is provided by default without any controls. When the
synchronous machine is used “as-is” in a dynamic simulation (i.e. without controls), it will maintain a constant
turbine power “pt” and excitation voltage “ve” throughout the duration of the simulation. As a result, distur-
bances such as faults, load steps, etc may cause unstable or unrealistic system response, since the action of
control systems like speed governors and voltage regulators are omitted.

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 type 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 defining the structure of
a simplified generator control system, and how it can be implemented in PowerFactory.

Consider the hydroelectric generation system shown in Figure 1.3.

Rev.2 4
INTRODUCTION TO DSL

Figure 1.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 regulate the speed of the machine by acting on the
mechanical power intake of the generator. 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. speed, terminal voltage). This can be summarised by a block diagram as
shown Figure 1.4.

Rev.2 5
INTRODUCTION TO DSL

Figure 1.4: Connection diagram for hydroelectric generation system

This block diagram showing how the synchronous generator, governor, turbine and voltage controller are
connected through the input / output signals between them, must be implemented as the composite model
frame for the dynamic system. 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.

Let’s first define a voltage controller as shown in Figure 1.5.

Rev.2 6
INTRODUCTION TO DSL

Figure 1.5: Block diagram for a simple voltage controller

This block diagram must be implemented as the DSL model type for the voltage controller. We can perform
a similar exercise and create DSL model types for the governor and turbine (not shown here). Once we have
finished creating these model types, we will have then defined the dynamic model for the hydro generation
control system, i.e. the individual dynamic model for the governor, turbine and voltage controller, the built-in
model for the generator and how they are all connected together is defined in the composite model frame.

However at this stage, we only have general structures (which are located in the library types). 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 Graphical User Interface (GUI). Composite models
and DSL models need to be created from within the Data Manager (inside a grid folder) using the New Object
( ) icon.

We can first create a composite model and link it to the composite model frame we defined earlier (see
Figure 1.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 DSL models and link them to the relevant model definition. At the end, the complete composite model
is shown in Figure 1.6. The same composite model as seen from inside the data manager is shown in Figure
1.7.

Rev.2 7
INTRODUCTION TO DSL

Figure 1.6: Complete composite model for hydro generator system

Rev.2 8
INTRODUCTION TO DSL

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

2 Creating Dynamic Models

2.1 General Procedure

The general procedure for creating a dynamic model in PowerFactory is as follows and will be practised in the
next section of this Tutorial (see Building a User Defined Model):

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. Create each of the DSL model types and set appropriate initial conditions.
3. Construct a composite model frame showing how the slots are interconnected.
4. Create a composite model and fill the slots with the relevant grid elements, e.g. DSL models, built-in
models, measurement devices, etc.

5. Test the complete model.

2.2 Library Objects

Both composite model frames and DSL model types are created in PowerFactory using the block definition
object (BlkDef). The difference is that composite model frames can only contain slots and connectors, and
do not perform calculations, whereas DSL model types can contain mathematical functions in the form of
equations, graphical macros, summation points, multipliers, etc.

Rev.2 9
INTRODUCTION TO DSL

2.2.1 Composite Model Frame

Composite model frames are diagrams containing slots and connectors, showing how network elements and
DSL models are to be connected together. Composite model frames are purely graphical and contain no
equations. See for example Figure 1.4.

2.2.2 DSL Model Type

A DSL model type constitutes the mathematical representation of a dynamic model in the form of equations
and / or graphical macros. A DSL model type containing only equations is called a primitive block definition,
while a DSL model type 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 (PowerFac-
tory supports an arbitrary number of layers).

Figure 2.1: An example of a DSL model type for a hydraulic turbine

Some DSL syntax guidelines to keep in mind when creating model definitions:
• A variable cannot belong to more than one type (input, output, parameter, state variable).

• DSL syntax is based on assignments of variables to mathematical expressions.

• A state variable cannot be of more than one type (output, parameter, input or state variable) at the same
time.

Rev.2 10
INTRODUCTION TO DSL

• 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.
• Conditional statements (of the if-then-else type) are to be implemented using the “select” function.
• Intrinsic, logic and conditional fucntions/operators are available.
• Maximal line length is 80 characters. Longer lines can be broken by “&” sign in the first column.

• All keywords, names, functions, variables, models, macros, etc. are case sensitive.
• Complex numbers and matrix operations are not supported.
• Blanks are removed when DSL code is processed. Exception: blanks in strings are kept.
• The sequence of lines is not relevant. Instruction execution order is sorted automatically.

• Comments can be done preceded with “!”.

2.3 Grid Objects

2.3.1 Composite Model

A composite model is a grid object that represents a dynamic system (e.g. generator with prime mover and
voltage control). A composite model references a composite model frame and inherits its structure (i.e. the
interconnections between system components). The relevant system components, e.g. network elements,
DSL models, measurement devices, etc. are assigned to the relevant slots in the composite model.

Composite models are created from within the data manager, inside the active grid folder. Once a frame is
selected, the relevant system components (for example, see Figure 1.6) can be assigned to the slots. It is best
practice to store elements such as DSL models and measurement devices inside the composite model object
(for example, see Figure 1.7).

2.3.2 DSL Model

A DSL model is a grid object that represents an instance of a DSL model type. A DSL model inherits the
structure of the linked DSL model type and has its own local parameter settings.

DSL models are created from the data manager. Once a DSL model type has been selected, the parameters
of the DSL model can be entered (as an example, see Figure 2.2).

Rev.2 11
INTRODUCTION TO DSL

Figure 2.2: An example of a DSL model and its parameters

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

3.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 true
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

Rev.2 12
INTRODUCTION TO DSL

• 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 3.1 showing a frame of a governor and turbine connected to a synchronous
generator.

Figure 3.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.

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 it’s not, then an error message will be shown (“Block not correctly initialised”).

3.1.1 General Procedure for Composite Model 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 composite model frame in which the composite block is located and how it will be connected
to other 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.

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.
4. Determine expressions for the unknown signals (and variables) from the known quantities.

Rev.2 13
INTRODUCTION TO DSL

This can be applied during the practical exercise of this tutorial Building an User Defined Model.

4 Additional Documentation

The information provided in this document is just a high-level introduction to DSL. Additional information is
available, the following documents can be accessed either directly from PowerFactory or from the DIgSILENT
download area (https://www.digsilent.de/en/downloads.html).

• Advanced Tutorial: step by step description to define an user defined model. Help → Tutorial. . .
• User Manual: a dedicated chapter presents all information regarding models for dynamic simulations,
a complete list with all DSL functions including examples is also available in the User Manual. Help →
User Manual
• Technical References: description of the models implemented in PowerFactory for the different power
systems components. Help → Technical References
• Knowledge base: a database of information, based on an FAQ format, available for any users (whether
registered or not) in https://www.digsilent.de/en/faq-powerfactory.html

Apart from the mentioned documentation, DIgSILENT provides Direct Technical Support, where PowerFac-
tory experts offer direct assistance to registered users with valid guarantee/maintenance. The Support Cen-
tre is located on the website https://www.digsilent.de/en/support.html. Additionally DIgSILENT
GmbH offers a standard 2-day training course on dynamic modelling and DSL. In-house courses are normally
run twice per year; 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.