Building a User Defined Model

In this part of the tutorial a practical exercise is presented, in which the step-by-step procedure for creating a
dynamic controller and integrating it into a network model is explained. The dynamic controller will be created
using existing macros from the PowerFactory global library.

1 Import Project

• Click on the icon to import and activate the project for this exercise.
• Look at the network, execute a load flow and verify that it runs without errors.

Figure 1.1: Single line diagram and load flow results

The goal of the exercise is to build an automatic voltage regulator (AVR) and exciter model for the generator
G1 in Figure 1.1. A composite model frame to establish the connections between the dynamic model and the
generator will also be created. The active grid elements (composite model and DSL model) will be created to
integrate the regulator model to the generator. We will also see in detail how the initialisation of the models is
done.

The AVR/exciter model structure is given in the form of a block diagram as shown in Figure 1.2, where the
controlled signal is the generator terminal voltage Vt and the control signal is the generator field voltage Efd.
The controller description indicates that Vs is the control signal from an optional power system stabiliser.
DSL USER DEFINED MODEL

Figure 1.2: AVR block diagram

2 Building the DSL Model Type

By means of the DSL Graphical User Interface (GUI), the above structure will be implemented in a DSL model
type using macros from the DIgSILENT library.

• Insert a new page using the icon, select Dynamic Model → DSL Model type and assign a name to
the new created object (“Simplified AVR”).

• All the required transfer functions are available as macros in the DIgSILENT library and can be accessed
via the Drawing Tools bar.
• To insert a macro in the graphical page, make sure the Graphical Freeze Mode is deactivated; then
select from the Drawing Tools the desired macro, move to the graphical page and insert it. Repeat for all
macros. Note the macros are grouped according to classes.
• Relocate the macro blocks according to the layout from Figure 1.2.

• Place the summation points by using the icon from the Drawing Tools bar on the right-hand side of
the graphical page.

• Connect the inputs and outputs of the blocks and of the summation points by using the icon from the
Drawing Tools.

Rev.2 2
DSL USER DEFINED MODEL

• Draw the input and output signals of the model by using the same signal icon ( ). Input signals are
drawn starting at the left-hand margin of the page, output signals are drawn ending at the right-hand
margin of the graphical page.
• Right-click → Edit each block in the graphical page: in the opened dialog window, rename the parameters
according to the names in Figure 1.2 (e.g. Tr, Kp, Ki...). The state variables can also be renamed, but
this is not essential.

• Right-click → Edit each signal and rename them according to the names in Figure 1.2.
• Right-click → Edit the summation point and invert the inputs corresponding to the “-” operators in Figure
1.2.

Note: The macros used in the model definition are linked using a “Block Reference” object. In the block
reference the parameters, state variables and internal variables can be renamed such that they are
unambiguously identified without modifying the macro; this implies that the number of parameters and
variables in the block reference should be the same as in the macro type.

Note: All macros available in the DIgSILENT Library are also described in the corresponding technical refer-
ence available from the Help menu Technical References → DSL Macros.

3 Initialising the Model

The model is not completed until the initialisation statements have been defined and included in the model. A
procedure analogous the one explained in the introduction of this tutorial Model Initialisation will be used. The
simulation should begin at a steady-state operating point. PowerFactory automatically initialises the values of
all signals that are unambiguously known from the load flow initialisation. However, the initial values of other
signals need to be defined by the user:

• The signals Efd and Vt will be initialised by PowerFactory in the built-in synchronous machine element
according to the initial load flow calculation; therefore, the unknown signals to be initialised will be Vref
and Vs.
• The model has 5 state variables that need to be initialised (named here xr, xi, xd, xa, xe).

The steady state block diagram for this controller will be as indicated in Figure 3.1; where we applied the
general rule to reflect the steady state of the system, which is to consider all derivates to be zero, i.e. 𝑑𝑥
𝑑𝑡 = 0
or 𝑠 = 0:

Rev.2 3
DSL USER DEFINED MODEL

Figure 3.1: Steady state representation for the AVR block diagram

In Figure 3.1, the unknown signals and the state variables are indicated in red and the known signals are shown
in blue. Notice that the signal Vs (unknown signal) corresponds to the control signal from a power system
stabiliser, and as such, knowing that a power system stabiliser has no influence on steady state operation,
allows to initialise such signal Vs to a value of zero, whether the corresponding model will be in use or not.

From the steady state signal flow shown in Figure 3.1, it can be derived that:

𝑉 𝑟𝑒𝑓 − 𝑉 𝑡 + 𝑉 𝑠 = 0

since

𝑉𝑠=0

therefore

𝑉 𝑟𝑒𝑓 = 𝑉 𝑡

By inspecting the equation of the blocks (macros) that relate the state variables and their derivatives to the
inputs and outputs of the blocks, and equating the expressions for the derivative to zero, we can find the
expressions for the initial conditions of the state variables as functions of parameters and known signals:

𝑥𝑖 = 𝐾𝑒 * 𝐸𝑓 𝑑/𝐾𝑎
𝑥𝑑 = 0
𝑥𝑎 = 𝐾𝑒 * 𝐸𝑓 𝑑
𝑥𝑒 = 𝐸𝑓 𝑑
𝑥𝑟 = 𝑉 𝑡

Once the initial conditions have been identified, they have to be entered in the equations page of the DSL
model type that defines the AVR/exciter:
• Double click somewhere on an empty space on the graphical page of the “Simplified AVR” under con-
struction to edit it, and go to the “Equations” page.

• Write the assignments for the obtained initial conditions using the inc(varname) = expression statement
as shown in Figure 3.2:

Rev.2 4
DSL USER DEFINED MODEL

Figure 3.2: AVR initial conditions

Note: Internal variables can, but do not need to, be initialised. They can be initialised, for example, in order to
simplify the expression for the mandatory initialisation expression:
inc(Vr) = Ke*Efd
inc(Va) = Vr/Ka
inc(xi) = Va

4 Building the Composite Model Frame

A composite model frame is needed to define the connection between the AVR/Exciter and the generator. In
order to improve the flexibility of the frame, and allow for the possibility of a future expansion of the frame to
include a power system stabiliser and/or the replacement of the AVR by a more detailed model, the field current
should be considered as an additional signal.

The frame will then comprise two slots, one for the AVR/Exciter and another for the generator. The slot for the
AVR/Exciter will have three input signals: one for the generator terminal voltage, one for the generator field
current, and one for the power system stabiliser control signal. It will have one output signal to control the
generator field voltage. The generator slot will have one input, the field voltage, and two outputs, the terminal
voltage and the field current.

The signal names to be entered in the slots must match the local names of the required variables in the DSL
model and in the generator. Inspecting the list of variables of the synchronous machine object (class name
ElmSym), the local names of the signals are:
• field voltage: ve
• field current: ie

• terminal voltage: ut
The local names for the AVR/Exciter model (class name ElmDsl) have been defined by the user when creating
the DSL model type, therefore:
• generator terminal voltage: Vt

• stabiliser control signal: Vs

• field voltage: Efd
For the “spare” signal corresponding to the generator field current input, the default name Ifd can be used. All
in all, the frame will look as depicted in Figure 4.1.

Rev.2 5
DSL USER DEFINED MODEL

Figure 4.1: Composite Model Frame

To define the composite model frame diagram we shall proceed as follows:

• Create a new page using the icon which is located with the page tab of the graphic window, select
Dynamic Model → Composite Model Frame and assign a name to the new created object (“Generator
Control Frame”).

• Insert two slots in the newly created page using the slot icon ( ) located at the Drawing Tools bar. For
that select , then move to the empty graphic window and right-click to insert one slot, repeat to add the
second slot. The slots can be moved and rearranged after placed to better organise the diagram (click
over one of them and drag it to the desired position on the page) as shown in Figure 4.1.
• Edit each slots and enter the slot name (see Figure 4.1). Define the local names of the output and input
signals for each slot and optionally, the class name in the Filter for → Class Name field, as summarised
in the table below.

Slot Name Voltage Control Generator

Outputs Efd ut,ie
Inputs Vt,Vs,Ifd ve
Class Name ElmDsl* ElmSym*

• Now connect the signals using the signal icon ( ) from the Drawing Tools. To connect the signal, click
on the output of the slot first and then click on the input of the destination slot; observe that the output
signals are shown in red and input signals in green.

Rev.2 6
DSL USER DEFINED MODEL

Note: PowerFactory assigns a default name to the signals according to the input name to which they are
connected. You can edit the signals by double clicking on them and changing the signal name.

Note: ElmDsl is the generic class name of a DSL model. A specific class name to a given model definition
is ElmXxx, where “Xxx” indicates the first letters of the name of the DSL model type (first letter in upper
case).

5 Defining the DSL model and the Composite model

The grid elements that represent the generator’s controller will be defined in the data manager using the frame
and block diagram previously built. There is no specific order in which the composite and DSL model has to
be created. It is advised to create first the composite model and use it as a grid folder to store the DSL models
(and eventually other elements) that will be linked in it.

Defining the Composite Model:

– Open the data manager and navigate to the active grid of the project, then click the new object icon
( ) and type in the filter text field Composite Model oder ElmComp, to filter the elements and find
the composite model. Once found select it and press OK.
– In the dialog window, enter a composite model name “G1 Controls”, using the icon choose Select
Type → Composite Model Frame (BllkDef), then select from the project library the frame diagram
(“Generator Control Frame”) created in the previous steps.

We have just created the composite model which shows now the different slots where later the control elements
will be linked together; for that, first the AVR DSL model has to be defined.
Defining the DSL Model:
– In the data manager, locate the recently defined composite model, then click the icon and type
in the filter text field DSL Model oder ElmDsl, to filter the elements and find the DSL model. Once
found select it and press OK.
– Select the model definition “Simplified AVR” created previously from the project library.
– Enter the name “Voltage Controller” for the DSL model and then assign the following values to the
model parameters:

Tr 0.02
Te 1.2
Ke 1
Ka 1
Ta 0.01
Kp 50
Ki 5
Kd 20
Td 0.1
Ve_min 0
Ve_max 10
Vr_min 0
Vr_max 10
Vpid_min -100
Vpid_max 100

Rev.2 7
DSL USER DEFINED MODEL

The final step we still have to do is link all elements in the composite model:

• Open the data manager and locate inside the active grid the “G1 Controls” composite model. Edit it.
• Double-click on the corresponding Generator’s “Net Elements” field and select the “G1” grid element.
• Double-click on the corresponding Voltage Control’s “Net Elements” field and select the “Simplified AVR”
DSL model.

Figure 5.1: “G1 Controls” composite model

6 Summary

This concludes the exercise. Now it should be clear how to carry out the following tasks:

□ Build block diagrams for the composite model frame and DSL model type.
□ Identify and apply macros from the global library.
□ Create the grid elements that define a dynamic system.
□ Differentiate between a composite and DSL model.

□ Define the initial conditions.