DSL Tutorial

(1)

DIgSILENT PowerFactory

Application Guide

Dynamic Modelling Tutorial

(2)

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

Copyright ©2013, DIgSILENT GmbH. Copyright of this document belongs to DIgSILENT GmbH. No part of this document may be reproduced, copied, or transmitted in any form, by any means electronic or mechanical, without the prior written permission of DIgSILENT GmbH.

(3)

Contents

3 Creating Dynamic Models 12 3.1 General Procedure . . . 12 3.2 Library Objects . . . 12 3.2.1 Composite Frames . . . 12 3.2.2 Model Definitions . . . 12 3.3 Grid Objects . . . 14 3.3.1 Composite Models . . . 14 3.3.2 Common Models . . . 14 4 Model Initialisation 16 4.1 How Models are Initialised in PowerFactory . . . 16

4.2 Initialisation of Common Primitive Blocks . . . 17

4.2.1 Integrator . . . 17

4.2.2 First-order Lag Differentiator . . . 18

4.2.3 First-order Lag . . . 19

4.2.4 PI Controller . . . 19

4.3 Initialisation of Composite Block Definitions . . . 19

4.3.1 Example: Hydro Turbine Block Initialisation . . . 21

(4)

Contents

4.4 Setting Initial Conditions in DSL . . . 23

4.5 Iterative Setting of Initial Conditions . . . 23

4.5.1 Linear Search . . . 24

4.5.2 Internal Division Search . . . 24

4.5.3 Newton Iterative Search . . . 25

4.6 Automatic Calculation of Initial Conditions . . . 26

4.6.1 Example: Simple Block . . . 26

4.6.2 Example: Wind Turbine Block . . . 27

5 Testing and Troubleshooting 28 5.1 Verifying Model Equations . . . 28

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

5.2.1 Printing Values to the Output Window . . . 29

5.2.2 Flexible Data . . . 29

5.2.3 Overlay of Signals in Block Diagrams . . . 29

5.3 Testing Models in Isolation . . . 30

5.3.1 Initialising Disconnected Signals . . . 30

5.3.2 Step Response Tests . . . 30

5.4 Advice for Troubleshooting Models . . . 33

6 Portability and Encryption 34 6.1 Portability . . . 34

6.1.1 Pack . . . 34

6.1.2 Pack to Macro . . . 35

6.2 Encryption . . . 35

7 DIgSILENT Training Courses 37 A DSL Function Reference 38 A.1 DSL Standard Functions . . . 38

A.2 DSL Special Functions . . . 39

(5)

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]

(6)

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

(7)

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 theDIgSILENT Simulation Language (DSL). Higher-level representations such as

graph-ical block diagrams and nested block structures are automatgraph-ically 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 defin-ing 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 differ-ent instances (common models) for each of the generators (each with their own local parameter settings). This configuration is reflected in Figure 2.1.

(8)

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.

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.

(9)

defin-2 Dynamic Modelling Concepts in PowerFactory

Figure 2.2: Two model definitions each referenced by one common model (one-to-one)

ing the structure of a simplified generator control system, and how it can be implemented in PowerFactory .

Consider the hydroelectric generation system shown in Figure 2.3.

In this system, the amount of water flowing into the penstock is controlled by a control gate at the intake. The water in the penstock flows through the turbine and rotates it, before being discharged through the draft tube. The turbine is coupled to a synchronous generator, which is then connected to the network. The gate position is controlled by a governor system, which tries to keep the output of the generator at a constant frequency. A voltage controller is also connected to the generator, controlling the terminal voltage of the machine by regulating rotor excitation.

We can see from this stylised system that there are control signals (i.e. gate position, 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.

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. Let’s first define a voltage controller based on a simple PID controller as shown in Figure 2.5. This block diagram represents themodel 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

(10)

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

(11)

Figure 2.5: Model definition for a simple voltage controller

for the governor, turbine and voltage controller, the built-in model for the generator and how they are all connected together (the composite frame).

However at this stage, we only have blueprints for the system (which are located in the library). We still need to create actual instances of the equipment inside the grid. Built-in grid elements such as synchronous generators can be created by the drawing tools in the PowerFactory GUI. However, composite models and common models need to be created from within the Data Manager (inside a grid folder) using the “New Object” function.

We can first create acomposite 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 createcommon 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.

(12)

(13)

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 def-inition object (BlkDef). The difference is that composite frames can only contain slots and con-nectors, 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 ele-ments and common models are to be connectd together. Composite frames are purely graphical and contain no equations.

Refer to Chapters 25.9.2 and 25.10 of the user manual (v15.0) for more details on the handling and creation of composite frames.

3.2.2 Model Definitions

A model definition describes the mathematical transfer function of a dynamic model in the form of equations and / or graphical block diagrams. A model definition containing only equations is called aprimitive block definition, while a model definition with a graphical block diagram

is referred to as acomposite block definition. Both primitive and composite block definitions

can be reused inside other higher-level model definitions (PowerFactory supports an arbitrary number of layers).

Refer to Chapters 25.10 of the user manual (v15.0) for more details on the general handling and creation of model definitions.

(14)

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

(15)

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

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

(16)

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

(17)

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

(18)

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 initialisa-tion 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 equa-tions 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”).

4.2 Initialisation of Common Primitive Blocks

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

dt = 0or s = 0.

4.2.1 Integrator

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

The standard integrator block is shown in Figure 4.2(a) and describes the function yo =R yidt.

It is implemented in DSL using a state variable x as follows:

dx dt = yi

yo= x

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

yo = x

Figure 4.2(b) shows the equivalent steady state representation of the integrator block. In the steady state, the input yi= 0(i.e. since all derivatives are zero and there is nothing to integrate).

The output yo is the steady state value yo,ss, which can be calculated from known initial values

(e.g. load flow quantities). The state variable x should therefore also be initialised to the steady state output yo,ss.

(19)

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 yo=dy_dti, but with a lag (and low pass filtering). It is implemented in DSL using a linear

difference approximation, plus a state variable x:

dx dt = yi− x T yo= dx dt

The DSL code representation for the above equations is: limits(T)=(0,)

dx=(yi-x)/T

x. = dx

yo = dx

Figure 4.4(b) shows the equivalent steady state representation of the differentiator block. In the steady state, the output is not fluctuating and thus yi = yo = 0. The state variable x should

(20)

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

Figure 4.5: Step response of first-order lag differentiator

4.2.3 First-order Lag

Figure 4.6: (a) First order lag block, (b) Steady state representation

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

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

4.2.4 PI Controller

The PI controller block is shown in Figure 4.8(a) and its steady-state representation is shown in Figure 4.8(b). Like the integrator block, the state variable x should be initialised to the steady state output yo,ss.

The step response of the PI controller block (with ki= kp= 0.5) is shown in Figure 4.9.

4.3 Initialisation of Composite Block Definitions

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

(21)

Figure 4.7: Step response of first-order lag

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

(22)

block definition. Afterwards, some more general rules are articulated for composite block initial-isation.

Figure 4.10: Block definition for a hydro turbine

Figure 4.11: Steady state representation of hydro turbine block diagram

4.3.1 Example: Hydro Turbine Block Initialisation

Consider the hydro turbine block definition in Figure 4.10. Suppose that this turbine block will be connected in the frame shown in Figure 4.1. The output pt is therefore known and we need to manually initialise the input g. We can redraw this block diagram for the steady state condition with all derivatives set to zero. This steady state representation is shown in Figure 4.11. From this steady-state representation, we can work backwards from the known output pt and calculate an initial value for the input g:

Since we know that dH = 0 and H0 is a constant, then H = H0. Therefore: P m = pt K dU = P m H0 U = U nl + dU U G =√H G = U U G g = G At

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

g =

P t

K×H0+ U nl

√

(23)

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

4.3.2 General Procedure for Composite Block Initialisation

Using the example in the preceding section as a reference, we can articulate a general 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 U for the integrator state variable.

(24)

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

Theinc statement is the standard statement for initialisation. The inc0 statement is only

exe-cuted 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 ofinc0 in Section 5.3). Lastly,

theincfix statement is only used for automatic calculation of initial conditions (see Section 4.6).

The use of theinc statement is straightforward and can be illustrated by example. In the

previ-ous 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. The equations for the wind turbine model are as follows:

λ = kb× speed vw

pw= ρar× Cp× vw3

(25)

Figure 4.13: Wind turbine block I/O

Where the function f (β, λ) is a non-linear function of power coefficients without a closed form and is represented by a two-dimensional matrix (i.e. a lookup table).

Suppose that in this model, the input speed and output pwis known, and that we can initialise

β = 0. Therefore, to complete this model we need to manually initialise vw. However from

inspection of the above equations, a closed form solution for vw cannot be found because of

the presence of the non-linear function f (β, λ). In this case, we can use an iterative search to calculate the initial condition for vw.

There are three iterative search algorithms available in PowerFactory : 1) Linear search, 2) Internal division search, and 3) Newton iterative search. We’ll look at each one in turn and use them to initialise the wind turbine example above.

4.5.1 Linear Search

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

inc(varp) = loopinc (varnm, min, max, step, error)

This function performs a line search from a minimum value (“min”) to a maximum value (“max”) with stepsize “step” and tries to find the parameter value (“varp”) that yields an output closest to known parameter “varnm”. A warning message is shown if the smallest deviation is larger than the parameter “error”.

To illustrate how to use the linear search function, we can apply it to the wind turbine example above. We want to initialise the parameter vw, which is directly related to a known signal pw.

We can use the linear search function to find the value of vwthat will yield a value of pwclosest

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 vwbetween 5 and 15 with a

step size of 0.01 and return the value of vwsuch that pw= ρar× Cp× v3wis closest to our initial

value of pw= 9.5.

4.5.2 Internal Division Search

The internal division search function (intervalinc) has the following usage:

inc(varp) = intervalinc (varnm, min, max, iter, error)

This function performs an internal division search over the inteval [“min”, “max”], by successively bisecting the interval into smaller sub-intervals and selecting the sub-interval where the the

(26)

parameter value (“varp”) yields an output closest to known parameter “varnm”. The function continues for “iter” iterations. A warning message is shown if the smallest deviation is larger than the parameter “error”.

To illustrate how to use the internal division search function, we can apply it to the wind turbine example above. We want to initialise the parameter vw, which is directly related to a known

signal pw. We can use the internal division search function to find the value of vwthat will yield

a value of pwclosest to its initial value:

inc(pw) = 9.5

inc(vw) = intervalinc (pw, 5, 15, 50, 0.01)

In the above snippet, the function will bisect the interval [5,15] a total of 50 times. At each iteration, the next sub-interval to bisect is chosen by finding the value of vw such that pw =

ρar× Cp× vw3 is closest to our initial value of pw= 9.5.

4.5.3 Newton Iterative Search

The Newton iterative search function (newtoninc) has the following usage:

inc(varp) = intervalinc (expr, start, iter, error)

This function performs a Newton algorithm to find the parameter value “varp” such that it equals “expr”, using an initial estimate “start” and running for “iter” iterations or until the absolute error is less than “error”.

To illustrate how to use the Newton iterative search function, we can apply it to the wind turbine example above. We want to initialise the parameter vw, which is directly related to a known

signal pw. Firstly, the equation for pwmust be rearranged so that it is evaluated in terms of vw:

vw= _p w ρar× Cp 13 (2)

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

vw− _p w ρar× Cp 13 = 0 (3)

We can now use the Newton iterative search function to find the value of vw that will minimise

the error of the homogenous equation above given a fixed initial value for pw:

inc(pw) = 9.5

inc(vw) = newtoninc (pow(pwind/rhoAr/Cp,1/3), 5, 50, 0.00001) In the above snippet, the function performs a Newton iterative search on the homogenous equa-tion (with fixed pw= 9.5) using an initial estimate of vw= 5, a maximum number of iterations of

(27)

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 theinc and incfix statements.

In the context of automatic initialisation, theinc 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. Theincfix statement, on the other hand, defines a

fixed initial condition for the variable. This is normally used in ambiguous sitations where the value of one or more variables needs to be fixed.

4.6.1 Example: Simple Block

As a simple example, suppose a block has two inputs (x1, x2) that will be automatically initialised to a known output (yo), say a basic equation such as yo = x1 + x2. If we knew that yo = 5 and we didn’t 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 withincfix to a fixed value, and put

an arbitrary starting estimate for the other variable, i.e.:

(28)

inc(x2) = 0

The iterative algorithm will then calculate (x1, x2) = (3, 2) as the correct set of initial conditions. Ifincfix 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 pwto a known value, say

pw= 9.5as before:

incfix(pw) = 9.5

We also have to give a starting estimate for the input vw, i.e.

(29)

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 don’t 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 .

(30)

5.2.1 Printing Values to the Output Window

Firstly, run the “Calculate Initial Conditions” command. Next, create a variable set for the DSL common model object of interest. From the variable set dialog, select the signals (or variables) of interest and press the “Print Values” button to show the calculated initial values of the selected signals or variables (see Figures 5.2 and 5.3).

Note that signals and state variables are located in the “Signals” menu, and internal variables are located in the “Calculation Parameter” menu.

Figure 5.2: Printing initial values from the variable set dialog

Figure 5.3: Result of “Print Values” button in output window

5.2.2 Flexible Data

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

5.2.3 Overlay of Signals in Block Diagrams

(31)

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

5.3 Testing Models in Isolation

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

5.3.1 Initialising Disconnected Signals

When testing a model in isolation, there may be known signals that are normally connected to other models (e.g. the hydro turbine output “pt” in Figure 4.10) that are now not connected to anything. In such cases, these signals need to be initialised to dummy values for the purposes of model testing.

This can be done using theinc0 statement, which allows us to initialise a disconnected signal.

Note that once the signals are connected back to other models, theinc0 statements are ignored.

As an example, let’s revisit the hydro turbine model in Figure 4.10. In Section 4.3, we found that the input “g” and state variable “x” needed to be initialised as follows:

inc_{(g) = (pt / (K * H0) + Unl) / (sqrt(H0) * At)} inc_{(x) = (pt / (K * H0) + Unl)}

Recall from the frame in Figure 4.1 that the turbine block is connected to a synchronous machine block, and thus the output “pt” is known from the load-flow initialisation of the synchronous machine. If we want to test the the turbine block in isolation, we will need to initialise “pt” with theinc0 statement, say to a value of pt = 0.95:

inc0(pt) = 0.95

We now create a common model object using the hydro turbine block definition and the model parameters as shown in Figure 5.5. Running the “Calculate initial conditions” command yields the initial conditions in Figure 5.6.

5.3.2 Step Response Tests

Once the model is initialised to run in isolation, we can test the step response of inputs to the model by usingparameter events. A parameter event allows us to change the value of any

(32)

Figure 5.5: Hydro turbine common model and parameters

(33)

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

(34)

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.

• Don’t 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 usinginc0 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 don’t match. However, if theinc0 statement is used, then PowerFactory assumes that the signal is not connected

and initialises it using theinc0 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 theinc0 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).

(35)

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

(36)

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.

(37)

(38)

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.

(39)

A DSL Function Reference

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

(40)

A.2 DSL Special Functions

lim

lim (x, min, max)

Nonlinear limiter function:

Figure A.1

vardef

vardef(varnm)=unitstring ; namestring

Defines the unit and name for variable varnm. It can be used for model parameters as well as internal signals.

Examples:

vardef(Ton) = 's' ; 'Pick up time for restart' ! defines unit and name vardef(Ton) = ; 'Pick up time for restart' ! defines name only vardef(Ton) = 's' ; ! defines unit only

limits

limits(param)=(min, max)

Limiter function used to print a warning message to the Output Window if a parameter is outside the specified limits. Brackets [ and ] are used to indicate the inclusion of the end points in the range, ( and ) are used to indicate the exclusion of the end points from the range.

Example:

limits(K)=(0,1]

limstate

limstate (x1, min, max)

Nonlinear limiter function for creating limited integrators. Works only withfixed limits, i.e.

min and max are parameters. Example:

x1. = xe/Ti;

y = limstate(x1,min,max);

This was previously realized by using “select” and “lim” functions: x1. = select( x1>=max.and.xe>0

& .or.x1<=min.and.xe<0, 0, xe/Ti); y = lim(x1,min,max);

delay

delay (x, Tdelay)

Delay function. Stores the value x(Tnow) and returns the value x(Tnow-Tdelay). Tdelay in seconds and larger than 0.0. The expression Tdelay must evaluate to a time indepen-dent constant and may therefore only consist of constants and parameter variables. The

(41)

expression x(t) may contain other functions. Example:

y = delay(xe + delay(x1, 1.0), 2.0)

Resetting a DSL model initializes its delay functions with x(Treset).

select

select (boolexpr, x, y)

Returns x if boolexpr is true, else y. Example:

x1.=select(T1>0, xe/T1, 0.0) !to avoid division by zero

time

time ()

Returns the current simulation time. Example: t=time()

y = sin(t) or y = sin(time())

file

file (ascii-parm, expr)

!OBSOLETE! Please use an ElmFile object in the composite model in stead. picdro

picdro (boolexpr, Tpick, Tdrop)

Logical pick-up-drop-off function useful for relays. Returns the internal logical state: 0 or 1.

Return value:

The internal state:

• changes from 0 to 1, if boolexpr=1, for a duration of at least Tpick seconds • changes from 1 to 0, if boolexpr=0, after Tdrop seconds

• remains unaltered in other situations.

flipflop

flipflop (boolset, boolreset)

Logical flip-flop function. Returns the internal logical state: 0 or 1.

Return value:

The internal state:

• changes from 0 to 1, if boolset=1 and boolreset=0 (SET) • changes from 1 to 0, if boolset=0 and boolreset=1 (RESET) • remains unaltered in other situations. (HOLD)

Initial value: boolset. The initial condition boolset=boolreset=1 will cause an error mes-sage.

(42)

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 con-sider that the array has to be sorted in ascending order.

Example:

y = lapprox(1.8, array valve)

invlapprox

invlapprox (y, array iiii)

Inverse lapprox with array.

lapprox2

lapprox2 (xl, xc, matrix iiii)

Returns the linear approximation y=f(xl,xc) of a two-dimensional array, where f is defined by the matrix iiii. xl represents the line value and xc the column of the matrix. Please consider that the array has to be sorted in ascending order.

Example:

y = lapprox2(2.5, 3.7, matrix cp)

sapprox

sapprox (x, array iiii)

Returns the spline approximation y=f(x), where f is defined by the array iiii. Please con-sider that the array has to be sorted in ascending order.

Example:

y = sapprox(1.8, array valve)

sapprox2

sapprox2 (xl, xc, matrix iiii)

Returns the spline approximation y=f(xl,xc) of a two-dimensional array, where f is defined by the matrix iiii. xl represents the line value and xc the column of the matrix.

Example:

y = sapprox2(2.5, 3.7, matrix cp)

(43)

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)

(44)

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

(45)

References

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