C Builder Tutorial

CBUILDER
Tutorial Manual
May 2012 rev. 02
RTDS
Technologies
User Defined Component Z

Models in C
TABLE OF CONTENTS
1 Using CBuilder to create a multiple input adder . . . . . . . . . . . . . . . 1.0

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1
Create a New Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2
Create the Required Parameters . . . . . . . . . . . . . . . . . . . . . . . . 1.3
Draw the Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.6
Add the IO points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.8
Adding the Model Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.10
Sample C Code for the Multiple Inupt Adder . . . . . . . . . . . . 1.12
2 Using CBuilder to create an integrator . . . . . . . . . . . . . . . . . . . . . . . 2.0

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1
Draw Graphics and Add Parameters . . . . . . . . . . . . . . . . . . . . . 2.2
Sample C Code for an Integrator . . . . . . . . . . . . . . . . . . . . . . 2.4
Add A Reset Input to the Integrator . . . . . . . . . . . . . . . . . . . . . 2.5
3 Using CBuilder to create a variable capacitor . . . . . . . . . . . . . . . . . 3.0

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1
Capacitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3
Adding an Optionally Monitored Variable . . . . . . . . . . . . . . . . 3.10
4 Using CBuilder to model a multimass system . . . . . . . . . . . . . . . . 4.0

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.1
Single Mass Rotating About An Axis . . . . . . . . . . . . . . . . . . . . 4.2
Two Rotating Masses Coupled By a Shaft . . . . . . . . . . . . . . . . 4.8
MultiMass Model Using Matrix Formulation . . . . . . . . . . . . . 4.12
MultiMass Model Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . 4.14
Model Development Using CBuilder . . . . . . . . . . . . . . . . . . . . 4.16
i
5 Using CBuilder to model a multithread component . . . . . . . . . . . 5.0
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1
MultiFunction Relays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2
MultiThread Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3
Model Development Using CBuilder . . . . . . . . . . . . . . . . . . . . 5.5
MultiThread Model Algorithm . . . . . . . . . . . . . . . . . . . . . . . . 5.17
MultiThread Static Section . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.18
MultiThread Ram Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.19
MultiThread Code Section . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.21
6 Using CBuilder with the PMU Shell component . . . . . . . . . . . . . . . 6.0

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.1
Phasor Measurement Unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2
Model Development Using CBuilder . . . . . . . . . . . . . . . . . . . 6.3
GTNET PMU Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.4
PMU Shell Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.5
Load PMU Shell Component into CBuilder . . . . . . . . . . . . . . 6.6
PMU Shell Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.7
C Code Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.9
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.12
7 Using CBuilder to create a generator control block . . . . . . . . . . . . . 7.0

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.2
Adding the Model code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.4
Sample C Code for the DC1 Type Exciter . . . . . . . . . . . . . . . 7.6
Data Preperation and Initialization . . . . . . . . . . . . . . . . . . . . . . 7.13
Add an Internal Slider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.16
Add Code for RealPole Function . . . . . . . . . . . . . . . . . . . . . . . 7.18
Add Code for LeadLag Function . . . . . . . . . . . . . . . . . . . . . . . 7.19
Add Code for Washout Function . . . . . . . . . . . . . . . . . . . . . . . . 7.20
Add Code for Saturation Function . . . . . . . . . . . . . . . . . . . . . . 7.21
Adding the Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.22
Add a Dial to Select Internal Variables for Monitoring . . . . . . 7.26
ii
Add a Generic Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.28
Add Monitoring Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.30
iii
1
using CBUILDER to create
a multiple input adder
June 2010 rev. 01
RTDS
Technologies
using CBuilder to create a multiple input adder
INTRODUCTION
You will be building an adder component that can add or subtract
two or three inputs. This adder will be able to accept real type
inputs.
RTDS TECHNOLOGIES INC. 1.1

CREATE A NEW COMPONENT
S Start RSCAD and Launch Component Builder

S Select New File at the welcome dialog.
S Select Control for the Component Type
S Save the component as tutorialc. You will see the following

warning. This warning means that the component is not yet
ready to be used in Draft.

CREATE THE REQUIRED PARAMETERS

The required parameters are going to be added into a new section.
Each section will appear as a seperate tab when you edit the
parameters of the icon.
S Select the Parameters tab
S Select the icon to add a new section
S You will be prompted for the new section name. Enter
addercontrol
New parameters will be added into the section that is selected.

Before adding a new parameter ensure that the section
addercontrol is selected. The selected section will be
highlighted in pink.
S Select the icon to add a new parameter.
A number of fields must be entered to define the new parameters.

Add the following parameters.
Parameter #1
Name: numInputs
Description: Number Of Inputs
Type: INTEGER
Unit/Toggle Entries: <leave blank>
Value: 2
Min: 2
Max: 3
Selecting the pin icon when adding the first parameter

will keep the Add Parameters window open. This is useful for
adding more than one parameter at a time.

Parameter #2
Name: sign1
Description: Sign of Input 1
Type: TOGGLE
Unit/Toggle Entries:
When defining a parameter as type Toggle, the toggle

entries must be entered in the box below.
Value: Add
Min: 0
Max: 1
The sign of inputs 2 and 3 must also be added as parameters.

These parameters can be added manually as above, or the existing
sign1 parameter can be copied. To copy the sign1 parameter,
highlight the parameter and select the copy/move icon . A box
will appear asking for the section to copy/move the new parameter
too. Select SECTION: addercontrol as shown below.
The copied parameters can now be modified. The parameter name

and description must be changed.

Parameter #3
Name: sign2
Type: TOGGLE
Value: Add
Min: 0
Max: 1
Parameter #4
Name: sign3
Type: TOGGLE
Value: Add
Min: 0
Max: 1
Enabled Condition: numInputs>2

DRAW THE GRAPHICS
The goal is to draw a component icon that looks similar to below.
S Start by drawing the unconditional graphics. Ensure that the

graphics are drawn near the center of the canvas (indicated by
the intersecting lines).
S Select the Graphics tab

S Add a new If graphics condition. Select the icon to add a
condition. This condition will be used to change the look of the
icon depending on the number of inputs.
S Enter the condition sign1==0 in the box provided.

S Ensure the the new condition is selected. Any graphics added

will now be placed in the If condition.
S Draw a + sign using the line tool to indicate the sign of input1.
S Ensure that the new condition is selected. Add a new Else
condition.
S Draw a sign. The graphics for the minus sign should now
appear under the Else condition.
S Highlight the GRAPHICS section in the Graphics tab and
repeat the conditional graphics above for sign2.
S Highlight the GRAPHICS section in the Graphics tab and add
a new If condition
S Enter condition numInputs>2.
S Ensure that the if (numInputs>2) condition is selected and draw
the third input line, as well as repeating the conditional graphics
for sign3.
S The icon should now appear similar to below.
S Select the Preview tab

S Select the addercontrol tab and try changing the number of
inputs from 2 to 3. Check that the graphics change accordingly.
S Return to the design tab.

ADD THE IO Points
In this example some of the IO points are conditional. Start by

making the conditions for the IO points.
S Select the IO Points tab
S Create the conditions so the IO Points table appears similar to
below.
S Select condition IO Points. Using the IO point tool, place a

new IO point where the input1 connection should be.
S You will be prompted for IO point information. Enter the
information below.
IO point fInput1
Name: fInput1
conn: SIGNAL INPUT
var: REAL
S Repeat the above process for IO point fInput2 and fOutput.
IO point fInput2
Name: fInput2
conn: SIGNAL INPUT
var: REAL
IO point fOutput
Name: fOutput
conn: SIGNAL OUTPUT
var: REAL

S Select the condition If numInputs==3 and add the fInput3 IO

point.
IO point fInput3
Name: fInput3
conn: SIGNAL OUTPUT
var: REAL

ADDING THE MODEL CODE

S Select the C File Associations tab
S Select the icon to Add New Association
S Enter a model name such as tutorialc.
S The associations should appear similar to below.
The input and output points appear under the INPUTS and
OUTPUTS sections and not the NODES section. This is a
controls component and the NODES section is reserved for power
system component electrical type nodes.

S Write the c code. Select the icon to edit the .c file.

Simple c code to add two inputs together and produce an output
might look something like below;
CODE:
fOutput = fInput1 + fInput2;
S After writing the c code, select the compile icon to

compile the code. If the compile is successful, the component
is ready to be included in a Draft circuit.
S Ensure that the component builder icon is saved.
Draft has an internal memory of the components used during

a draft session. If a component icon is modified while Draft is
open, the icons must be refreshed. Select the icon from the
Draft toolbar to refresh components.

SAMPLE C CODE FOR THE MULTIPLE INPUT ADDER

#include tutorialc.h
STATIC:
// use the mult variables to keep track of sign of input
int mult1;
int mult2;
int mult3;
RAM:
// the parameters sign1,sign2 and sign3 are toggles where
// 0 == plus and 1 == minus
// use the mult variables to keep track of sign of input
if (sign1 == 1)
mult1 = 1;
else
mult1 = 1;
if (sign2 == 1)
mult2 = 1;
else
mult2 = 1;
if (sign3 == 1)
mult3 = 1;
else
mult3 = 1;
CODE:
if (numInputs > 2)
fOutput = (mult1 * fInput1) + (mult2 * fInput2) + (mult3 * fInput3);
else
fOutput = (mult1 * fInput1) + (mult2 * fInput2);

2
an integrator
Sept 2007 rev. 00
RTDS
Technologies
INTRODUCTION
The integrator reads in one real input, integrates the input with a
user specified timeconstant (T) and writes one output. The basic
equations, based on trapezoidal rule of integration with a
simulation timestep of t, are used to compute the integral of the
input are as follows
X 1 Y
sT
1
Y(t) =
T
X(t) dt
t
1
Y(t) =
T
X(t) dt + Y(tt)
tt
1 t * [ X(tt) + x(t) ]
Y(t) =
T
{ 2 }+ Y(tt)
Y(t) =
t
2T
{ X(tt) + x(t) } + Y(tt)
Data Preparation
Initialize Xold= 0.0;

Initialize Yold= 0.0;
Compute K= dt/(2T);
Algorithm
Read X;
Y= K * (Xold + X) + Yold;
Write Y;

DRAW GRAPHICS AND ADD PARAMETERS
Draw an icon that looks similar to that below;
The component icon for the integrator includes two I/O points.
One signal input named input and one signal output named output,
both are real.
Add a parameter T to specify the time constant (type REAL).

Select the C File Associations tab

Select the icon to Add New Association
Enter the model name integrate
Left click to create new C File Association

(New Model Name popup menu appears)
Write the c code. Select the icon to edit the .c file.
Input and Output points (listed under the IO Points tab) and
user defined parameters (listed under the Parameters tab) are
automatically associated with the model and placed in the .h file.
Left clicking the View .h file button opens the .h file in an editor.
A model that includes one input, one output and a parameter would
have the following lines in the .h file
INPUTS:
double input;
OUTPUTS:
double output;
PARAMETERS:
double T;

SAMPLE C CODE FOR AN INTEGRATOR
#include integrate.h
STATIC:
/* */
/* Variables declared here may be used in both the */
/* RAM: and CODE: sections below. */
/* */
double dt;
double input_old,output_old,K;
/* E n d o f S T A T I C : S e c t i o n */
RAM:
/* */
/* Place C code here which computes constants */
/* required for the CODE: section below. The C */
/* code here is executed once, prior to the start */
/* of the simulation case. */
/* */
dt= getTimeStep();
input_old = 0.0;
output_old = 0.0;
K = dt/(2.0*T);
/* E n d o f R A M : S e c t i o n */
CODE:
/* */
/* Place C code here which runs on the RTDS. The */
/* code below is entered once each simulation */
/* step. */
/* */
output = (input + input_old) * K + output_old;
input_old = input;
output_old = output;

ADD A RESET INPUT TO THE INTEGRATOR
Add shapes to the icon to include a reset input
Add an integer I/O point named reset to the reset input.

Update the association to include the new I/O point.
Modify the C code to reset the integrator when a value other than
0 is applied to the reset input.
Recompile the new code
Save the new icon
CODE:
if (reset != 0)
{
output = 0;
input_old = 0;
output_old = 0;
}
else
{
output = (input + input_old) * K + output_old;
input_old = input;
output_old = output;
}

Draft has an internal memory of the components used during
a draft session. If a component icon is modified while Draft is
open, the icons must be refreshed. Select the icon from the
Draft toolbar to refresh components.

3
a variable capacitor
June 2010 rev. 01
RTDS
Technologies
INTRODUCTION
Control system components interact with other components using

control type input and output signals and do not interact directly
with the solution of the power system network. Power system
components, on the other hand, need to interact directly with the
solution of the power system network. The interface is usually
made by specifying an impedance at the nodes to which the
component is connected and by providing current injections into
those nodes.
v(t)
i(t)
Current Injection
The network solution expects to receive current injection values

from power system components well before the end of the
simulation timestep so that there is enough time remaining in the
timestep to compute the new node voltages. To accommodate
this, the CODE: section for power system components is divided
into two portions BeginT0 and T0T2.
The first portion, referred to as BeginT0, is used to execute the

statements required to compute current injections which the
component injects into the nodes to which it is connected.. Once
the current injections are ready, the executable code is suspended
until all of the other power system models have completed their
current injection calculations. At this point the current injections
from all of the power system models allocated to the RTDS rack
are sent to the processor dedicated to solving the power system
network. Upon completion of this T0 transfer, executable code for
the components who participated in T0 continues. The remaining
portion of the executable code, referred to as T0T2 may be used
to solve portions of the algorithm that are not needed to compute
RTDS TECHNOLOGIES
RTDS TECHNOLOGIES INC.
INC. 3.1
the current injections, for preparing variables that are written out
for monitoring and preparing for the next timestep. Once the
second portion of code is completed the executable code is again
suspended until all of the variables transferred during the T2
communication interval have been transferred between
processors. Control type variables, monitored variables and node
voltages are exchanged during the T2 communication interval.
The node voltages are computed by the processor allocated to the
network solution and transferred to other processors in the rack.
As such, new node voltage data is available once the processors
are restarted for the next simulation time step.
RTDS TECHNOLOGIES
INC. 3.2
CAPACITOR
Application of the trapezoidal rule of integration to the basic

capacitor equation is used for the numerical solution of the
capacitor.
V(t) = VN1(t)VN2(t)
C
N1 N2
i(t) = C * d V(t) i(t)

dt
1
v(t)
V(t) =
C
i(t) dt
t
1
V(t) =
C
i(t) dt + V(tt)
tt
applying trapezoidal rule of integration
i(t) = 2C * V(t) 2C * V(tt) i(tt)

t t
v(t)
R= t / 2C
i(t)
IH: Current Injection
define
IH(t) = 2C * V(tt) i(tt)
t
i(t) = 2C * V(t) + IH(t)

t
RTDS TECHNOLOGIES
INC. 3.3
Draw a capacitor icon similar to that shown below.
The component icon for the variable capacitor includes two power
system nodes and one signal input as shown below. The signal
input CVAL is used to read in variable capacitance values.
Add a parameter Cinit to specify the initial value of capacitance.
RTDS TECHNOLOGIES
INC. 3.4
Select the C File Associations tab

Select the icon to Add New Association
When a new C File Association is made for the power system
component, a menu appears in which the model name must be
entered. The menu also permits selection of which transfer zones
(T0 ... T3) are to be used for the model. At the time of writing this
document only the T0 communication may be enabled or disabled.
Any power system component which includes current injections
must check the T0 Transfer zone. The T2 transfer zone is always
enabled.
Enter the model Name

to create the model.c
and model.h files
Check the T0 box to

enable current injec-
tions for the model
Creating the C File Associations for the component automatically

generates the following associations
INPUTS: CVAL, capacitance value signal input

NODES: N1, N2 power system nodes
PARAMETERS: Cinit, initial value of capacitance
In addition to those listed above, the following additional

associations need to be made
RTDS TECHNOLOGIES
INC. 3.5
GVALUES: A conductance value (1/R) that the component places
between the nodes to which it is connected. Recall, that the
representation of the capacitor requires a resistor equal to t/(2C)
to be placed between the nodes to which the component is
connected. The equivalent conductance is equal to 1/R= 2C/t.
To add the GVALUE association select the Add Variable to .h File
button from the C File Associations Tab and select GVALUES for
the Section: value, Type: Real and enter the variable name to
which the conductance value will be assigned in the .c code.
Add Variable to .h File Button
Clicking OK on the Add Variable menu results in the GVALUES

section to be added to the Model Associations. Two lines are
added under the GVALUES section since the conductance value
is placed between two nodes. Left click the arrow to associate the
node N1 with the first GCVAL line and the N2 node with the
second GCVAL line.
RTDS TECHNOLOGIES
INC. 3.6
Left click to display pull down
Select Node name to associate the

GCVAL parameter with the node
INJECTIONS: The capacitance model injects current into node2

and out of node1. The current injection associations are made in
a similar manner as the conductance value associations described
above. Left click the Add Variable to .h File button and select
INJECTIONS from the pull down associated with the Section: and
Type: REAL. Enter the name for the current injection variable
(CINJN1). After selecting OK the INJECTIONS section is added
with the single line representing one current injection association.
Select the down arrow icon for the CINJN1 variable and select
Node N1. Add another current injection variable (CINJN2) and
associate it with Node N2.
Selecting File>Save causes the newly added GVALUES and

INJECTIONS variables to be written to the .h file so they can be
accessed in the .c file.
Write the c code. Select the icon to edit the .c file.
RTDS TECHNOLOGIES
INC. 3.7
Basic Algorithm
Read 2 node voltages v1(t), v2(t)

Compute V(t)= v1(t) v2(t)
Read Capacitance Value
Compute Gc= 2C/t
Set new Gc value for network solution
Compute branch current: i(t)= 2C/t*V + IH(tdt)
note: IH(t) from previous timestep
Compute Injection Current: IH(t)= 2C/t*V i(t)
Set injection current for node1 and node2
The RAM section initializes the history term current IH(tdt) to

0.0 and computes the constant 1/t for use in the CODE: section.
Static:
double dt, invdt, Ih, Gcap;
RAM:
dt= getTimeStep();
invdt= 1.0/dt;
Ih= 0.0;
Gcap= 2.0 * Cinit * 1.0e6 * invdt;
The CODE: section computes the branch current for the capacitor,
the new conductance for the capacitance and the current injections
into the nodes between which the component is connected. All of
the code is assigned to the BEGIN_T0 portion since it is required
to compute the injection currents. The capacitance value is read
in as microfarads (ie. 1.0 is interpreted as 1.0e6 farads) so the
CVAL variable must be multiplied by 1.0e6before it can be used.
CODE:
BEGIN_T0:
double Vbra, ib;
RTDS TECHNOLOGIES
INC. 3.8
/* Compute branch current */
Vbra= N1 N2;
ib= Gcap*Vbra + Ih;
/* Compute new value of Cfarad */

Gcap= 2.0 * CVAL * 1.0e6 * invdt;
GCVAL= Gcap;
/* Compute new History Current */

Ih= Gcap*Vbra ib;
/* Write current injections into N1, N2 */

/* +ve means current out of node */
CINJN1= Ih;
CINJN2= Ih;
RTDS TECHNOLOGIES
INC. 3.9
ADDING AN OPTIONALLY MONITORED VARIABLE
It is often desirable to permit the user to optionally monitor various

internal variables associated with a component. Monitoring of
such internal variables may be useful for debugging when the
component is part of a larger control circuit. The monitoring may
be included without adding additional output points to the
component. The following procedure is suggested to monitor the
branch current
Add a Yes/No Toggle type parameter which permits the user to

select whether the current is to be monitored in a new section
called MONITORING.
Add a Name type parameter which permits the user to enter a name
for the monitored currnet. The Name entry can be made
conditional on the monitoring being enabled in a new section
called Signal Names.
Add a new generic output variable which is active only if the
monitoring is enabled in the C File Association.
Add statements to the RTDS C code to assign the branch current to
the monitored variable.
Name parameter to specify signal name

(enabled only if MonI == Yes)
Toggle parameter to enable monitoring
RTDS TECHNOLOGIES
INC. 3.10
The new parameters MonI and Iname must be added to the .h file.
Select the Add New IO Points/Nodes/Parameters icon from
the C File Associations tab to add these new parameters.
To add the monitored variable parameter to the .h file, left click the
Add Variable to .h File button under the C File Associations tab.
Select create: Generic Outputs from the pulldown menu
associated with the Section: field and set Type: to REAL. Enter
a variable name (eg. IMON) to be used for assignment of the
monitored variable in the .c file. After selecting OK, the Edit
Output menu appears in which additional parameters for the
output variable may be specified.
Type: REAL
H File VAR: IMON
Output Name: Iname
Group: Branch Currents
Min Value: 100.0
Max Value: +100.0
Unit: kA
Condition: MonI==1
Min and Max values are used as the default limits for a meter or
plot component assigned to display the signal specified by Output
Name. The specified unit name also appears on the meter or plot
component in RSCAD/RunTime.
The create: OUTPUTS data line for the monitored output variable
appears as
Signal name available in

Parameter name for .c file RSCAD/RunTime
RTDS TECHNOLOGIES
INC. 3.11
The C code statement to write out the monitored variable is as
follows
IMON = ib;
The current monitoring should be assigned in the T0_T2

section of the CODE.
RTDS TECHNOLOGIES
INC. 3.12
4
using CBUILDER to
model a multimass system
June 2007 rev. 00
RTDS
Technologies
using CBuilder to model a multimass system
INTRODUCTION
Representation of the mechanical characteristics of turbine gen-

erator units in electromagnetic transients programs is necessary if
the interaction between the electrical system and mechanical sys-
tem is to be studied. In some situations a resonant condition may
exist between the electrical system and the mechanical system
which can lead to torsional oscillations which stress the mechani-
cal couplings between the various turbines and between the tur-
bine and generator. Perhaps the best documented case of such a
resonance was at the Navajo Project, a coal fired generation unit
located in northern Arizona U.S.A. [1]. Data from the Navajo
Project was used to develop a first and second benchmark model
for torsional oscillations [2],[3].
This document outlines how the mechanical characteristics of a

turbinegenerator system may be incorporated into a model for
use on the RTDS. Once the equations for the multimass system
have been developed, the procedure for implementing the corre-
sponding algorithm using the CBuilder feature under RSCAD is
documented.
Development of the equations representing the mechanical system

follows that presented in Kundar [4]. Firstly, the equations of mo-
tion for a single mass rotating about an axis are developed. The
analysis is then expanded to account for two masses connected by
a shaft and finally generalized to multiple masses.

SINGLE MASS ROTATING ABOUT AN AXIS
EQUATIONS OF MOTION REPRESENTING A SINGLE

MASS ROTATING ABOUT AN AXIS
Telec
Tmech
m
The basic equation of motion for a rotating mass stems from New-
tons Second Law of motion (commonly stated as F=mA) where
the Force is the difference between the mechanical torque applied
by a turbine and the electrical torque applied across the airgap of
the generator. Acceleration for the rotating mass is the rate of
change of its rotational speed (m). Instead of the mass of the ro-
tating body, the mass moment of inertia (J) is used. The moment
of inertia considers both the rotating bodys mass and its distribu-
tion around the axis of rotation.
d m
J
dt
= Tm Te (1)
J: Mass moment of Inertia in kg*m2

m: rotational speed of the mass in mech. rad/sec
Tm: Mechanical torque applied by the turbine (N*m)
Te: Electrical torque applied by the generator (N*m)
(1 N = 1 kg*m/sec2)
It is important to note that m in (1) above represents the mechani-

cal rotational speed of the machine in rad/sec. It is to be differen-

tiated from the machines electrical rotational speed. Mechanical

speed and electrical speed is the same for a machine with only one
pole pair. Machines that have more than a single pole pair will
have a slower mechanical rotational speed than one with just one
pole pair.
e = m * n (n is the number of pole pairs)
By using the perunit inertia constant, H, which is defined as the

mass kinetic energy in wattseconds at rated speed, as opposed
to the moment of inertia, equation (1) can be expressed in terms
of electrical rad/sec. H and J are related as
H = 1 J 0m
2
2 VA base
J=2 H VA base (2)
2 0m
0m: rated rotational speed of the mass

in mechanical rad/sec.
VAbase: VoltAmp base for the system
Substituting (2) into (1) yields
2H VA d m = T T (3)
base m e
2 0m dt
Noting that
m r
0m = 0 = pu (4)
VA T =T
T base = base ,
0m Tbase pu (5)
r: rotational speed of the mass in electrical rad/sec

0: rated rotational speed of the mass
in electrical rad/sec.
Tbase: base value of mechanical torque
we rearrange equation (3) such that equations (4) and (5) may be
substituted.


2H d m = m

dt 0m
T Te
VA base 0m
(6)

dt 0
T Te
2H d r = m
VA
(7)
base 0m
2H d =
T T
dt
r
0 T
m e
(8)
base
Equation 8 above relates the perunit applied torque to the per

unit rotational speed of the mass. Implementation of equation 8
into the the RTDS solution algorithm may be done by applying
trapezoidal rule to yield
pu(t) pu(t t) T a pu(t) + T a pu(t t)

2H
t
=
2
(9)
Tapu: perunit accelerating torque
Tapu= (Tm Te ) / Tbase
At the beginning of the simulation timestep all of the quantities

in (9) listed as functions of (t t) are known, as are the constants
2H and t. The most recently computed value of Tapu is used as
Tapu(t). This leaves only Wpu(t) to be computed.
To demonstrate the action of (9), we can apply a constant 1 per

unit torque with no electrical torque (ie. open circuit conditions for
a frictionless generator) and note that the mass speed linearly in-
creases. Under such conditions the rotating mass reaches 1 per
unit rotational speed after 2H seconds. 2H is referred to as the me-
chanical starting time.
r/0
1.0
2H t (sec)
Figure 1: mechanical starting time

DAMPING
In the equations for the rotating mass described above, there was
no consideration of damping. Removing the applied torque in the
example above results in the mass rotating at pu indefinitely. In
[4] a damping term proportional to r is introduced. Adding such
a term to (8) yields

dt 0
T Te
2H d r = m

T base

D r
0
(10)
Damping proportional to speed deviation (ie. [r/0]) results in

an accelerating torque when the speed of the rotating mass is less
than the rated speed. Such a representation is reasonable for small
perturbations of speed around the rated speed. However, if the
mass is to be used as part of a generator turbine model which is
required to have large deviations from synchronous speed, the
chosen representation of damping leads to unrealistic behavior.
Take for instance the case where the generator is to be started from
standstill. At zero speed the speed deviation is 1.0pu and accord-
ing to (10) the mass is subjected to an accelerating torque of +D
pu.
A physical interpretation of the damping term proportional to

speed deviation is given in the discussion to reference [5].
A damping term proportional to perunit speed, representing the

friction and windage losses, can be introduced into (8) to obtain
(11). The addition of a speed proportional damping term changes
the response of the mass to a constant mechanical torque input as
shown in Figure 2 (compare with Figure 1 which shows the re-
sponse with no damping term).

dt 0
T Te
2H d r = m

T base

D r
0
(11)

r/0
1.0 no damping
D= 1 pu
2H t (sec)
application of constant torque
r/0
no damping
with damping
t (sec)
removal of torque
Figure 2: Response with Speed Proportional Damping
Removal of the applied torque, using (11) to represent the rotating

mass, results in the mass rotational speed slowing to 0.0. Note
that equation (11) has the same form as a first order lag with a gain
of 1/D and a timeconstant of 2H/D seconds.

T 1 + E 1 W
D s(2H/D)

1
E(t) = T(t) w(t)
D
1
w(t) = E(t)
s(2H/D)
1
w(t) = [ 1/D*T(t) w(t) ]
s(2H/D)
1
w(t) =
2H
[T(t) D*w(t) ] dt
1st order lag function with Gain= 1/D and
time constant= 2H/D. Compare with
equation 11 above.

TWO ROTATING MASSES COUPLED BY A SHAFT
EQUATIONS OF MOTION FOR 2 ROTATING MASSES

COUPLED BY A SHAFT
Telec
Turbine Generator
KTG
Mass Mass
Tturb turb gen
The equations developed above are now extended to two masses

coupled by a shaft. One mass represents a turbine and the other
the rotating mass of the generator. The mass of the shaft itself is
lumped proportionally into the rotating mass inertia constants.
The shaft connecting the generator mass to the turbine mass is con-
sidered as a torsional spring. Torque transferred across the shaft
between the turbine and the generator results in twisting of the
shaft. The amount of twist depends on the torque transferred
across the shaft and on the torsional strength of the material com-
prising the shaft.
T = K m (12)
T: Torque transferred across the shaft (Nm)

m: Mechanical angle of twist across the shaft (rad)
K: Shaft Stiffness (Nm/rad)
The shaft stiffness constant (K) defines the torque required to

create an angular twist of 1 radian across the shaft. Values of K
are typically very large since the torque, in Nm, required to twist
a large turbo generator shaft by 1 radian (~57 degrees) is signifi-
cant. In order to use (12) with (11) developed above, equation 12
needs to be converted so as to relate perunit torque to perunit
angle. Using the base values for mechanical angle and torque as
shown below

mbase = 0m
VA
T base = base
0m
the base shaft stiffness may be computed as
VA base
K base =
20m
0m: rated rotational speed of the mass
in mech. rad/sec.
The torque applied by the shaft to the masses to which it is attached

is given by
T TG = K TG( T G)
T in pu if KTG, in pu
The equations of motion for the two rotating masses can now be
written
d gen
Generator Mass: 2H
dt
= T turb T e D gen gen (13)
d
Turbine Mass: 2H turb = T turb D turb turb
dt
(14)
T Te
Shaft Angle: T G = turb
K TG
(15)
all quantities in per unit
Equations (13,14) can be solved numerically using the trapezoidal

rule as
(t) (t t) (t) + (t t) (t) + (t t) T(t) + T(t t)

2H +D +K =
t 2 2 2
(16)
All of the history terms (ie. those at tt) are known at the start of
a new timestep. 2H, D, K and t are constants and the new value
of applied torque T(t) is assumed to be known. The values (t) and
(t) are unknown at the beginning of the timestep. Using the rela-

tion (17a) and applying trapezoidal rule an expression for (t) can
be derived in terms of (t).
d = (17a)
dt
(t) (t t) (t) + (t t)
dt
=
2
(17b)
(t) = t (t) + (t t) + (t t)
2
(17c)
Equation 17c can be substituted into (16) to eliminate the (t) term
and leave (t) as the only unknown.

(t) 2 2H + D + t K =
t 2

t 2

T(t) + T(t t) + (t t) 2 2H D T K 2K(t t) (18)
defineA = t2 2H + D + t2 K (19)
B= t2 2H D t2 K
solving for (t) in (18) substituting A and B as defined above

yields
(t) = A 1 T(t) + T(t t) + (t t)[B] 2K(t t) (20)
Equation 20 is solved for each mass substituting in the appropriate

parameters for H, D and T.
It is worth noting that the constants defined in (19) include terms

which are multiplied by 2/t and t/2. For a typical simulation
timestep of 50 s these multiplying factors vary by ten orders of
magnitude. Given typical values for H and K the constants can be
computed as
2 * 2H = 2.0 * 2 * 0.8688 = 69, 504.0

t 50e 6
t * K = 50e 6 * 14042.92 = 0.3511

2 2.0

Even with the typically large difference in magnitude between H

and K the elements comprising constants A and B are still different
by five orders of magnitude. As for the damping factor (D) which
is also required to compute A and B, there is little in the way of
typical data available in the literature. In many cases the damping
is set to zero.

MULTIMASS MODEL USING MATRIX FORMULATION
Representation of n masses coupled by shaft segments is straight

forward. By arranging the equations developed for 2 masses in
matrix form, the solution can be generalized to any number of
masses. For the present model, matrix sizes are dimensioned to
permit eight turbine masses, one generator mass and two rotating
exciter masses for a total of 11 coupled masses.
...
turbine turbine turbine turbine turbine generator exciters
#1 #2 #3 #4 #8 #1 & 2
Equation 20 rewritten in matrix form is
n(t) = A 1 T n(t) + T n(t t) + n(t t) [B] [2K] n(t t) (21)

where
n: mass index 1 . . . number of masses

[n(t)]: newly computed speed of mass n
[A1]: inverse of tridiagonal matrix A (full matrix)
[Tn(t)]: latest value of torque applied to mass n
[Tn(tt)]: previous value of torque applied to mass n
[n(t)]: previously computed value of speed of mass n
[B]: tridiagonal matrix of B constants
[2K]: tridiagonal matrix of 2*K spring constants
[n(tt)]: previous value of mass angle
[D]: tridiagonal damping coefficient matrix used in the
calculation of the A and B matrices.
The damping matrix includes both terms for the diagonal and off
diagonal elements. Diagonal elements represent the selfdamp-
ing factors (friction, windage) described above. Offdiagonal

terms represent the damping due to the twisting of the shaft. Under
transient conditions, when a varying torque is applied across the
shaft segments, the back and forth twisting of the shaft results in
heating and hence some damping. Data for this mutual damping
is often not available. Note that the mutual damping is across a
shaft segment so that only the n1, n and n+1 elements of the
damping matrix have nonzero terms.
X11 X12 0 0
X21 X22 X23 0
D= (22)
0 X32 X33 X34
0 0 X43 X44
Xmn: nonzero elements
Damping Matrix form for 4 mass system

MULTIMASS MODEL ALGORITHM
The algorithm for the multimass model is based on the solution

of equation 21 above. The dimension of matrices and column vec-
tors required for the solution is determined by the number of
masses that constitute the system under study. Solution of (21) re-
quires that mechanical torque applied to the turbines, electrical
torque from the generator, a number of constants and information
from the previous timestep are known.
Mechanical torque to each turbine is provided as input to the multi-

mass model from a separate component which models the speed
control and torque production. Electrical torque is provided as
output from the synchronous machine model or from the induction
motor model and passed to the multimass model. User entered
data, Hn, Kn, Dn and simulation timestep are used to compute
constants A1, B and 2K.
Solution of (21) solves for mass rotational speeds from which

mass angles and shaft torques can be computed. These quantities
are provided as output from the multimass model.
A mechanism is provided to lock all of the modelled mass speeds

to a specified speed (often synchronous speed). A lock/free switch
can be created in RSCAD/RunTime as part of the model, or the
user can provide the lock/free signal input from an external signal.
When in lock mode, all mass rotational speeds are set equal to the
specified speed. Lock mode is often used to temporarily bypass
the turbine dynamics during initialization of the power system to
which the multimass system is connected.
It is also possible operate the multimass model so as to lump all

of the masses into a single rotating mass. In this way the shaft dy-
namics can be removed. A single/multi switch can be created in
RSCAD/RunTime as part of the model, or the user can specify that
the single/multi signal come from an external source. When in
single mode, the torques applied to all of the turbine masses are
added to form a single mechanical torque input. The equivalent

mass inertia constant is equal to the sum of all modelled masses.

The sum of all the self damping terms is used for the damping.

MODEL DEVELOPMENT USING CBuilder
Development of the multimass model requires the following

steps
I) Conceptual layout of the new component

a) Which inputs should be connected using wires
b) Which outputs should be connected using wires
c) appearance of the component icon
d) options which change appearance of icon
e) What data is required to prepare the constants
f) How to group related data fields
g) What monitoring options should be available
h) control system or power system component type
II) Component Icon Creation in CBuilder (Graphics & Nodes)

a) Define component as a Control system type component
b) locate and place all of the input / output points and add
associated logic blocks
c) Draw component icon portions which do not require
conditional logic.
d) Draw component icon portions for each option which
changes the components appearance.
III) Define User Supplied Data Menus (Parameters)

a) Add all of the data sections defined under I(f) above.
b) Add logic to parameters so the parameter entry fields are
visible only when the corresponding options are selected.
IV) Write Data Preparation Portion of the C Program

a) Create C File and Declare required variables
b) Compute constants required for the executable code
c) Optionally write critical data to the .map file
V) Write C code to implement the algorithm

a) Declare required variables
b) Create variables for named output signals
c) Create variables for named input signals

VI) Test newly developed Model

a) Check data preparation to ensure constants are computed
correctly.
b) Run simulation cases to confirm basic operation
c) Run simulation cases to verify against benchmark cases

I) Conceptual Layout of the New Component
a) Torque inputs to each turbine section and the generator (Te) will
be connected to input points. The user will thus be able to inter-
connect the governor/torque production model to the multimass
model via wires. The synchronous generator models Te output
signal can also be connected to the multimass model via a wire
component.
b) The synchronous generator model requires the generator mass

speed signal as an input. Note that the speed signal may change
very little from simulation timestep to timestep. Within the
GPC processor, computations are done using double (64 bit) preci-
sion. However, when the data is sent from the multimass model
to the generator model over the rack backplane, the speed signal
is converted to a single precision number. Rather than sending the
speed signal directly from the multimass to the machine model, a
deltaomega (ie. change from synchronous speed) signal is sent
instead.
Input and output points for the multimass model are shown in the
Figure below.
T U R B I N E T O R Q U E I N P U T S Generator Mass
deltaomega Output
Tm1 Tm2 Tm3 Tm4 Tm5 Tm6 Tm7 Tm8 w
L/F
multimass component outline
Te
S/M
Multimass Input / Output Points Generator Electrical
Torque Input

c) The components appearance is shown below. Each of the tur-

bine torque inputs connects to an icon representing a single turbine
mass. Electrical torque is connected as an input to an icon repre-
senting the rotating portion of the generator. A change from syn-
chronous speed signal for the generator mass is available as an out-
put. At synchronous speed this signal is equal to 0.0. Two exciter
masses are connected on the right side of the generator mass.
L/F
LPA LPB LPC LPD
HP IPA IPB IPC
W
EXC
Te
S/M
d) There are a number of options which may be set by the user

which require the appearance of the component icon to change
Number of turbine masses (18)

Number of exciter masses (02)
Lock/Free switch input mode
Single/Multi switch input mode
The generator mass and HP turbine mass are always drawn. If the
number of turbines is set less than 8, then unused turbine icons are
replaced by extending the shaft between the generator and last tur-
bine. Exciter masses are drawn only if selected.

HP IPA IPB IPC

W
EXC
Te
MultiMass component icon

with 4 turbine masses, 1 exciter mass and
switch inputs created as part of the model
e) The following data must be supplied by the user before the

constants required for the algorithm can be computed
H: Inertia Constant for each mass (MW sec / MVA)

K: Spring Constant for each shaft (in pu)
Ds:Self Damping for each mass (in pu)
Dm: Mutual Damping for each shaft section (in pu)
Logic is included as part of the component so that only the data re-
quired for the number of selected turbines needs to be entered.
Data items not required for the selected configuration appear grey
in the menus and cannot be selected for input.
f) The following data tabs are defined for the multimass compo-
nent
CONFIGURATION: Basic configuration options

INERTIA CONSTANTS: H values for each mass
SHAFT SPRING CONSTANTS: K values for each shaft section
SELF DAMPING: Ds values for each mass
MUTUAL DAMPING: Dm values for each shaft section
MONITORING OPTION TABS: see below
g) The user is able to select the following items for monitoring.

These are named variables and as such there is no wire protruding

from the component icon for any of these outputs.
Mass Speed
Mass Angle with respect to the generator
Shaft Torque
Tabs are included in the component icon to facilitate selection of

the signals to be monitored and the name assigned to each moni-
tored variable. Logic is included as part of the component to per-
mit selection of only those variables which are computed for the
specified configuration.
h) CBuilder requires that the user specify whether the compo-

nent is a power system or control system type component. Power
system components connect to power system nodes as defined by
node icons in RSCAD/Draft and often contribute current injec-
tions into those nodes to which the component is connected. Con-
trol system components do not connect to power system nodes and
are not able to supply current injections into the power system net-
work.
The GPC processor to which a control system component is allo-

cated automatically becomes a control system processor for the
simulation case and only other control system components may be
allocated to that processor. It is not possible to allocate both con-
trol system and power system components to the same GPC proc-
essor.

II) COMPONENT ICON CREATION IN CBUILDER
The CBuilder Users Manual should be consulted for additional

details on defining the component icon. Information provided
here outlines the major steps required to complete the icon associ-
ated with the multimass model.
a) Define the Component as a Control System Component
When a new component is created the user is prompted to select

whether the component type is control or power system. For the
multimass model select control.
To change the component type after a new component has been
created, select the Tab labelled other from the control pane of the
CBuildermain window and select the radio button next the Con-
trol under Component Type.
b) Define the Input/Output points and associated conditional logic

under the IO Points Tab
Torque input for the HP Turbine, electrical Torque input to the gen-
erator and generator deltaomega output are always present. No
logic needs to be placed around these input / output points. Select
the create input/output point button from the drawing toolbar and
left click when the circle is positioned as shown below. Use the
create input/output function to create points for the HPT input, Te
input and deltaomega output signals. A popup menu asking for
the input/output point name and type (input or output, int or real)
appears. All of the torque inputs are specified as real type.

Set snap to grid when

placing input/output
points
Drawing toolbar
Create Input/Output
Point button (left
click to select, left
click again to place
input/output point)
The number of turbines included in each instance of the compo-

nent is set by the user. Torque inputs for turbines other than for the
HP turbine need to be placed inside conditional logic so that the
inputs are enabled only when dictated by the number of selected
turbines. To define a new condition, under the IO Points section,
left click the add condition button and select the if option from the
pull down. Enter the logic condition as shown below. The param-
eter nturb, defined later, holds the number of turbines selected by
the user.
Add Condition Button
Logic under which

the input point is
available

While the If (nturb>1) EndIf block is highlighted in the IO Points

section, add the input point for the IPA torque signal. The new in-
put point is created inside the highlighted IfEndIf logic.
Data under the IO Points tab should appear as shown in the Figure
below once all of the input / output points and associated logic has
been entered.

Input / Output points

outside of condition-
al logic
Conditional logic
for the input torque
signals for each tur-
bine.
Conditional logic
for the Lock/Free
and Single/Multi
optional switches
Appearance of
drawing area after
entry of input / out-
put point data

c) Draw the unconditional graphics.
The sections of the component icon shown in red below can be

drawn outside of the conditional logic.
L/F
LPA LPB LPC LPD
HP IPA IPB IPC
W
EXC
Te
S/M
d) Draw the conditional graphics.
Turbine blocks which are not enabled are replaced by a shaft sec-
tion for the components appearance in RSCAD/Draft. Exciter
masses are only drawn if enabled. L/F (Lock/Free) and S/M
(Single/Multi) input wires are only drawn if the user selects these
inputs are to come from a signal input rather than an RSCAD/Run-
Time switch.
To add a logic condition under the Graphics tab select the Add
Condition button and choose the if option from the pulldown. En-
ter the condition appropriate for the turbine section which is to be
drawn within the logic condition. Since either a shaft section or
turbine icon will be drawn, an ifelseendifstructure is required.
To add an else section, highlight the newly created ifEndIfcondi-
tion by left clicking on the If statement (the If and EndIf lines will
turn red). Left click the Add Condition button and this time select
Else from the pull down that appears.
The condition logic should appear as follows
if (nturb > 1)

Else
EndIf
To add drawing commands into a particular condition, left click

the small arrow next to the logic condition in which the drawing
commands are to be placed. The condition turns red and the arrow
should point downwards. Use the drawing commands to draw the
shapes required for the icon portion. Drawing commands are
placed within the highlighted logic condition. To draw the icon
portion in the else section left click the small arrow next to the if
line so that it again points to the right. The components drawn
within the if section disappear from the drawing canvas. Now left
click the small arrow next to the else line. The line becomes red
and the arrow points downward. Draw the shapes required for the
else portion of the icon. Repeat the above procedure for each tur-
bine section.
The multimass model permits representation of up to 2 rotating ex-

citers. No torque input is applied to these exciter masses. A vari-
able named EXCen is set to 0/1/2 by the user to indicate the
number of exciter masses to be modelled. The logic for drawing
the exciters can be arranged as follows
If (EXCen > 0)
Draw shapes to represent exciter next to generator
EndIf
If (EXCen == 2)
Draw shapes to represent 2nd exciter
EndIf
III) ADD PARAMETER ENTRY MENUS
a) Now that the component icon, including input / output points

and conditional graphics have been completed the menus for data
entry are created. These menus are defined under the Parameters
tab in the control pane area of the RSCAD/CBuilder window.

The following sections are required for the multimass component.
CONFIGURATION: basic configuration parameters including

the number of turbines to be represented (nturb) and how many ex-
citer masses are to be modelled (EXCen)
SELF DAMPING: the self damping factors for each modelled

mass.
MUTUAL DAMPING: the damping factors for the shafts con-

necting the modelled masses.
SHAFT SPRING CONSTANTS: the spring constants for the

shafts connecting the modelled masses.
INERTIA CONSTANTS: the inertia constants for each modelled

mass.
MASS SPEED MONITORING ENABLE: enable speed monitor-

ing for each modelled mass.
MASS SPEED SIGNAL NAMES: signal name for each moni-

tored mass speed signal.
MASS ANGLE MONITORING ENABLE: enable monitoring for

the angle between each modelled mass.
MASS ANGLE SIGNAL NAMES: signal name for each moni-

tored mass angle signal.
SHAFT TORQUE MONITORING ENABLE: enable shaft torque

monitoring for each modelled shaft segment.
SHAFT TORQUE SIGNAL NAMES: signal name for each moni-

tored shaft torque signal.
To create the component data entry sections listed above, left click
the add section button in the control pane area of the RSCAD/C
Builder window. Enter the Section name in the menu that appears.

None of the sections need an associated logic condition.
Once all of the data entry sections have been created, left click the
small arrow next to the section to which the parameters are to be
added. The arrow points down and the section heading is high-
lighted. Left click the add parameter button and fill in the ap-
propriate data in the menu that appears. The new parameter entry
element is added under the highlighted section.
Add Section Button Highlighted section shows where

Add Parameter Button new parameters will be placed
b) Some parameters should only permit data entry when required.

For example, if the user specifies that only 1 turbine mass is to be

modelled (nturb = 1) then data for the IPA, IPB . . . LPA turbine
masses is not necessary and the associated parameters should not
permit data entry. To facilitate this, a logic condition may be added
to each parameter.
To enable data entry for the IPA inertia constant only when the IPA
turbine is to be modelled, add the following logic condition to the
IPAH parameter entry
nturb > 1
If the nturb parameter defined under the CONFIGURATION

menu is set to 1 by the user then the IPAH parameter entry line will
be greyed out.
Names for monitored signals should only be entered if the associ-

ated turbine is modelled AND if the user has enabled that signal
for monitoring. In this case the AND function can be used in the
logic condition
nturb > 1 && HPIPATen

IV) WRITE DATA PREPARATION PORTION OF THE C

PROGRAM
a) Create C File and Declare Variables
There are two C code programs that must be written by the user
to complete the model. Firstly, a C program which computes the
constants required by the algorithm must be written. Secondly, the
program which executes the algorithm for the model must be writ-
ten. Only the second program runs on the RTDS hardware. Both
C programs are stored in the same file. A template for the C
file is created by selecting the Add Model button under the C
File Associations tab. The newly created file can be edited by se-
lecting the edit button.
Edit C File
All of the input / output signals and parameters, as well as, their
types are listed in a .h file which is automatically generated by C
Builder. The .h file is included as part of the C code using the
#include statement at the top of the C code file. As such, all of
the input / output and parameter signals may be used as part of the
C code. The simulation timestepmay be obtained by adding the
following statement into the C code
dt= getTimeStep();
The algorithm to be solved for the multimass model is essentially

defined in equation 21 above. In order to solve (21) the following
matrices must be computed as part of the data preparation code.
[H], [D], [K]

[A], [B]
[A]1

The matrices are declared as double precision and dimensioned to

the maximum number of masses (= 8 turbine masses + 1 generator
mass + 2 exciter masses = 11 masses).
RAM:
#define MAXMASS 11
double H[MAXMASS][MAXMASS];
double K[MAXMASS][MAXMASS];
double D[MAXMASS][MAXMASS];
double A[MAXMASS][MAXMASS];
double B[MAXMASS][MAXMASS];
The above matrices are declared under the RAM: section in the C
code file since they are only used for the data preparation. The ma-
trix Ainverse is required in both the data preparation and algorithm
portions of the C code and as such is declared under the STATIC:
section of the C code file.
STATIC:
double AINV[MAXMASS][MAXMASS];
b) Load Data into Variables
Data storage into the matrices and arrays is such that the lowest
indexed entry is allocated to the High Pressure turbine. The next
entry to the IP turbine and so on. Generator data is entered into the
element pointed to by nturb. Exciter #1 is entered into the element
pointed to by nturb+1. For example if the user has specified that
four turbine masses are to be modelled (nturb=4) then the follow-
ing code would be used to load the H matrix elements. Note that
the inertia constants are loaded into the diagonal elements only
and that offdiagonal elements of the H matrix are 0.0.
H[0][0]= HPH;
H[1][1]= IPAH;
. . .
H[7][7]= LPAH;
H[nturb][nturb]= GENH;
H[nturb+1][nturb+1]= EXC1H;

H[nturb+2][nturb+2]= EXC2H;
The D and K matrices are tridiagonal (see equation 22 above)

meaning that only their diagonal and diagonal +/1 elements have
nonzero values. Elements of these matrices are loaded one value
at a time
D[0][0]= HPSD + HPIPAMD;

D[0][1]= HPIPAMD;
D[1][0]= HPIPAMD;
D[1][1]= HPIPAMD + IPASD + IPAIPBMD;
D[1][2]= IPAIPBMD;
. . .
D[7][7]= LPCLPDMD + LPDSD + LPDGENMD;
D[nturb][nturb]= GENSD + LPDGENMD;
Exciter damping factors are added into nturb+1 and

nturb+2 elements.
Elements of the K matrix are filled in using the same procedure as

for the D matrix. Once the K, D and H matrix elements are filled,
the A and B matrices are computed as follows (see equation 19
above). Computations are done only for the number of masses
which are being modelled.
nmass= nturb+1+EXCen;
K1= 4/dt;
K2= dt/2;
for (row=0;row<nmass;row++)
{
for (col=0;col<nmass;col++)
{
A[row][col]= H[row][col]*k1 +
D[row][col] + K[row][col]*k2;
B[row][col]= H[row][col]*k1
D[row][col] + K[row][col]*k2;

}
}
The inverse of the A matrix is required for the algorithm (see equa-
tion 21 above). An internal matrix inversion routine is available
to generate the required inverse matrix
i= matx_invert(nmass,A,MAXMASS,AINV,MAXMASS);
where
nmass= dimension of matrix to invert
A= matrix to invert
MAXMASS= dimension of matrices A and AINV
AINV= matrix to store inverse of A
The Ainv matrix is a full matrix. In addition to the Ainv matrix,

the algorithm portion of the C code also requires the B matrix and
2 times the K matrix. However, the B and 2*K matrices are tridi-
agonal and to conserve computations they will be stored in eleven
separate arrays of dimension three. Each array holds the n1, n
and n+1 elements (where n is the diagonal element). Since these
vectors are used in both the data preparation and algorithm portion
of the C code they are declared under the STATIC: section
STATIC:
double K2TRI0[3], BTRI0[3];
. . .
The K2TRI and BTRI vectors are loaded from the K and B vectors.
for (i=0;i<3;i++)
{
BRTRI0[i]= B[0][i];
K2TRI0= 2.0 * K[0][i];
. . .
BTRI10[i]= B[10][i+8];
K2TRI10[i]= 2.0 * K[10][i+8];
}

c) Write Critical Data to the .map File
It may be useful to include an option in the components CON-

FIGURATION menu to print computed data into the .map file.
Such data may be useful for debugging purposes during the mod-
els development and testing, as well as, solving problems that
may arise if third parties begin to use the model.
Printing to the .map file may be done using the following structure
of the fprintf statement
fprintf(mapFile,\n D[%d][%d]= %lf,

row, col, D[row][col]);
V) WRITE C CODE TO IMPLEMENT THE ALGORITHM
Now that all of the constants required for the algorithm have been
computed, the C code to implement the algorithm itself can be
written. Code to execute the model algorithm is placed under the
CODE: section in the C file template. The basic structure of the
code is as follows
variable declarations
initializing
If (mode == lock)
{
set all mass speeds
}
Else if (mode = single)
{
solve one mass model
}
Else
{
compute multimass algorithm
}
write output signals

The algorithm used to solve the multimass model is based on equa-

tion 21 (repeated below) and proceeds in the following steps.
n(t) = A 1 * T n(t) + T n(t t) + [B] n(t t) [2K] n(t t)
step 1) compute [BW]= [B]*[w(tdt)]. Since only the nonzero

elements of [B] are stored the calculation is done as follows
BW0 B00 B01 0 0 Wold0

BW1 B10 B11 B12 0 Wold1
BW2 = 0 B21 B22 B23 Wold2
BW3 0 0 B32 B33 Wold3
BW[0] = BTRI0[0] * wold[0] + BTRI0[1] * wold[1];

BW[1] = BTRI1[0] * wold[0] + BTRI1[1] * wold[1] + BTRI1[2] * wold[2];
step 2) compute [K2TH]= [K2]*[THold(tdt)]. Since only the

nonzeroelements of [K2] are stored the calculation is done as fol-
lows
K2TH0 K200 K201 0 0 THold0

K2TH1 K210 K211 K212 0 THold1
K2TH2 = 0 K221 K222 K223 THold2
K2TH3 0 0 K232 K233 THold3
K2TH[0] = K2TRI0[0] * THold[0] + K2TRI0[1] * THold[1];

K2TH[1] = K2TRI1[0] * THold[0] + K2TRI1[1] * THold[1] + K2TRI1[2] * THold[2];
step 3a) compute [Bcol]= [Told] + [BW] [K2TH]. [BW] and

[K2TH] were computed in steps 1 and 2 above. [Told] are the shaft
torques computed in the previous timestep. [Told], [BW] and
[K2TH] are column vectors and can thus [Bcol] may be computed
using a for loop as shown below

for (ii=0;ii<nmass;ii++)
{
BCOL[ii]= T[ii]+BW[ii]K2TH[ii];
}
step 3b) compute [Bcol]= [Bcol] + [T]. The [T] vector is the latest
shaft torques which must first be read in from the external source.
Only those input torques associated with masses that are actually
modelled may be read in. Once read, the new shaft torques can be
added to the [BCOL] vector computed in step 3a.
T[0]= HPT;
if (nturb == 8)
{
T[1]= IPAT;
T[2]= IPBT;
T[3]= IPCT;
T[4]= LPAT;
T[5]= LPBT;
T[6]= LPCT;
T[7]= LPDT;
}
else if (nturb == 7)
{
. . .
}
. . .
else if (nturb == 2)
{
T[1]= IPAT;
}
{
BCOL[ii]= BCOL[ii] + T[ii];
}
Step 4) Compute [w]= [Ainv]*[BCOL]. Matrix [Ainv] is stored
as a full nxn matrix and as such for loops can be used to compute

the new mass speed vector [W].
{
w[ii]= 0.0
for (jj=0;jj<nmass;jj++)
{
w[ii]= w[ii] +
Ainv[ii][jj]*BCOL[jj];
}
}
Step 5) With the new speeds of each modelled mass known from
step 4, it is now possible to compute the angles of each mass. The
computed mass angles are used in step 2 during the next timestep
in the computation of speed. The vector THold is used to store the
newly computed values of mass angles.
dt2= 0.5*delt;
{
THold[ii]= THold[ii] +
dt2*(wold[ii] + w[ii]);
}
The generator mass angle is chosen as the reference (0 deg). The

computed generator mass angle is subtracted from each modelled
mass, including the generator mass itself.
for (ii=0;ii<nturb;ii++)
{
THold[ii]=
THold[ii] THold[nturb];
}
THold[nturb+1]=
THold[nturb+1]THold[nturb];
THold[nturb+2]=
THold[nturb+2]THold[nturb];

THold[nturb]= 0.0;
step 6) Now that the multimass algorithm has been solved, moni-
tored variables can be prepared. All of the computations done
within the algorithm are based on perunit quantities. Monitored
variables need to be converted to the desired units prior to being
written out. The following conversions are done
[w] speed pu * 2*PI*Base_Freq > speed in rad/sec

[THold] shaft angle in pu *360 * 2*PI*Base_Freq >
shaft angle in degrees
Shaft torques are computed using the angle across the shaft. For
example, to compute the torque across the shaft connecting the HP
and IPA masses
HPIPAT= HPIPAK * (THold[0]THold[1])

where HPIPAK is the spring
constant for the shaft
step 7) Some additional code needs to be added to the algorithm

to handle the lock/free switch. The lfm parameter under the CON-
FIGURATION menu permits the user to select whether the lock/
free switch is automatically created by the model or whether an ex-
ternal signal connected to an input point controls the lock/free
operating mode of the multimass model. To handle both input op-
tions a variable lfmode is created and assigned input from the ex-
ternal signal or from the automatically created RSCAD/RunTime
switch depending upon the selection of the lfm parameter. If the
lfm parameter is equal to 0 then an RSCAD/RunTime switch is au-
tomatically created, otherwise the lock/free signal is read from an
input point.
if (lfm > 0)
{
lfmode= lfswinp;
}
else

{
lfmode= lfsw;
}
Both the lfswinp and lfsw variables are defined in the .h file that
is created when the component is compiled.
When the lock/free signal is set to free (lfmode=0), the algorithm

as defined in steps 16 above is executed. When in lock mode
(lfmode= 1) all modelled mass speeds are fixed.
k3= 1.0;
if (rpsinit == 0) k3= rps/omo;
if (lfmode == 1)
{
{
w[ii]= k3;
}
}
The variable k3 is set to 1.0 (ie. 1.0 perunit speed represents syn-
chronous speed) if the rpsinit parameter is set to synchronous
speed (rpsinit == 1 (Yes)) by the user. If the rpsinit parameter is
set to nonsynchronous speed (rpsinit == 0 (No)) then the speci-
fied initial speed is used to compute the initial perunit speed of
the machine and this value is used for all of the modelled mass
speeds when operating in lock mode.
When in lock mode or within the first time steps, the angles of each
modelled mass can be computed based on the torque applied to
each mass and the shaft spring constant. If there is only one turbine
mass then the angle between the turbine and the generator may be
computed as
THold[0]= Te / LPDGENK;
where Te is the torque applied to the generator

LPDGENK is the shaft spring constant between the
generator and turbine.

If two turbine masses are modelled the initial mass angles are com-
puted as
THold[1]= Te / LPDGENK;
THold[2]= THold[1] + (TeIPAT)/HIPPAK;
Initial angles for the exciters are set to 0.0 since no external torque
is applied to the exciters.
If the mode switches are set so that the lock/free is free and single/
multi is set to single, then all of the modelled masses are consid-
ered as one lumped mass. The torque applied to the lumped mass
is equal to the sum of torques read in and the inertia constant of the
equivalent mass is equal to the sum of all the modelled mass inertia
constants. Self damping terms for all modelled masses are
summed to give an equivalent self damping factor for the equiva-
lent mass. Mass speed is computed as
w[0]= C2*w[0] + C1*(Ttotal Te);

w[1]= w[0];
. . .
where C1= dt / (2*totH);

C2= 1.0 ((dt*totSD)/2*totH);

VI) Test Newly Developed Model
Testing of the multimass model can start by examining the output

written to the .map file and see whether it matches hand calcula-
tions. Multiplication of the A matrix by its inverse to see whether
the unity matrix is obtained checks whether the matrix inversion
routine in the data preparation code was properly executed.
Once the basic data preparation is verified, a number of simulation

cases increasing in complexity may be run to verify the models
operation. It is useful to run the model in its simplest mode (single
mass) and compare its dynamic response to that which is expected.
As a final test, the multimass model is tested against the First

Benchmark Case as described in [2].

REFERENCES
[1] R. Farmer, A. Schwalb, Navajo Project Report on Subsyn-

chronous Resonance Analysis and Solutions, IEEE Transactions
on Power Apparatus and Systems, Vol. PAS96, No. 4, July 1977,
pp.12261232.
[2] IEEE Subsynchronous Resonance Task Force First Bench-

mark Model for Computer Simulation of Subsynchronous Reso-
nance, IEEE Transactions on Power Apparatus and Systems, Vol.
PAS96, No. 5, Sept/Oct 1977, pp.15651572.
[3] IEEE SSR Working Group Second Benchmark Model for

Simulation of Subsynchronous Resonance, IEEE Transactions
on Power Apparatus and Systems, Vol. PAS104, No. 5, May
1985, pp.10571066.
[4] P. Kundar, Power System Stability and Control,

McGrawHill, 1994.
[5] G. Gross and M.C. Hall, Synchronous Machine and Torsional

Dynamics Simulation in the Computation of Electromagnetic
Transients, IEEE Transactions on Power Apparatus and Systems,
Vol. PAS97, No. 4, July/Aug. 1978, pp10741086. (in particular
Appendix & Discussion )

5 using CBUILDER to
model a multithread
component Aug. 2008 rev. 01
21P 21G 68 79 50BF
RTDS
Technologies
using CBuilder to model a multithread component
INTRODUCTION
In real time digital power system simulation the minimum length

of time step used in the simulation is dictated by the most time
consuming algorithm which has to be completed in the time step.
Provided the resulting time step is compatible with the bandwidth
of the phenomena being investigated the simulation can run in real
time. When a smaller time step is necessary to meet the bandwidth
requirements the simulation can still run but not in real time.
If the relay algorithm can be broken down into a number of
independent blocks of code which can be evaluated sequentially
in successive time steps and subsequently organized into a
complete relay algorithm solution when all blocks have been
evaluated then the time step used in the main simulation can be
smaller than the time needed to run the complete relay algorithm.
These blocks of code running in different time steps are called
threads which are subsequently woven together to form the
complete relay solution. Any component algorithm can be
separated into individual blocks of code processed independently
of each other to create a multithreaded component running in the
main simulation. The multithreaded component requires
additional code to keep track of the multithreadedloop and adjust
delays for timers when new sampled data is available. This
additional code will ensure the individual blocks of code are
executed sequentially, and restart the sequence when new sampled
data is ready.
This document outlines how the multithreadedcomponent can be

incorporated into a model for use on the RTDS. Once the template
for the multithread component is developed, the procedure for
implementing some simple algorithms using the CBuilder feature
under RSCAD is documented.

MULTIFUNCTION RELAYS
MULTIFUNCTIONAL RELAY
21P,21G,50BF,68,79
Multi
Function
Relay
Figure1. MultiFunctional Relay
Normally a microprocessor based intelligent electronic device

(IED) will use data sampled every 8/16/32/ or 64 samples per
cycle. Relaying components are created using basic protection
theory and standard techniques for processing digitally sampled
data from the time domain. Essentially sampled data is transferred
into the phase domain using a DFT or equivalent technique. The
phasor information is then evaluated against algorithms that can
discern between normal operating conditions and fault conditions.
Control algorithms can then be processed that will isolate the
faulted portion of the power system. The same control algorithm
can then later restore the isolated portion of the power system
when the fault condition has been removed.

MULTITHREAD COMPONENT
A downsampler is used to provide data at the correct number of

samples per cycle for the algorithm. In an example case with a
nominal 60 Hz base sampling rate of 8 samples per cycle, the
control algorithm obtains and uses new data every 2.08333 ms.
If the simulation timestep is 50usec, then the main simulation
will be executed 41 times between samples. This means that it is
possible to have 41 different threads executed sequentially every
2.08333 ms. The execution time for a multifunctional relay
algorithm without using threads will require the use of a longer
simulation time step. If there are 5 threads in the multithread
cycle with an additional thread every new sample the normal delay
cycle between individual threads is 250 usec. The additional
thread every sample is normally used for the signal processing.
This means the multithread cycle would execute about 7 times
between new samples. Keep in mind that some code will be
executed each time step and must be taken into consideration for
overall execution time of each thread. The sample rate is not
always an integer value of the timestep therefore new samples
will occur with an accuracy limited to a few timesteps. This
means that the thread cycle will restart at different thread counts
changing the amount of delay between the executions of code
within a thread. This delay can be adjusted from the normal 250
usec to a temporary value whenever the new data sample
interrupts the thread cycle and restarts.

250.0
usec
0.0
5
79, timers, outputs
4
85, SAED
3
Z3, 68OOS
2
Z2, plots
1
Z1, phase selection
0
Input samples, seq components, directional 0.002083
Figure2. MultiThreaded Timestep
If a timer is used in thread 1 the time between executions of thread

1 changes when a new sample occurs indicated by the red line.
When the control algorithm is ready to read the new sample data,
the multithread was executing thread 2. Because new sample
data is ready to be read the control algorithm has to move back to
thread 0 and read in and process the new sampled data that will be
used for the other threads.
When the multithread moves back to thread 1 and starts
executing the code, only 3 main simulation timesteps have
occurred. To properly service a timer in thread 1 the amount of
delay added to the timer would have to be temporarily adjusted by
3/5 of the 250 usec (5 time steps) normally added.
The multithread component example will contain the necessary
code to temporarily change the amount of time added to timers
when a new sample occurs.

Development of the multithread model requires the following

steps


b) locate and place all of the input / output points
c) Draw component icon




correctly.

I) Conceptual Layout of the New Component
a) Typically, controls components are drawn such that input points

are on the left side and output points are on the right side of the
component.
b) The example model requires the name of an external variable

to choose which threads fractional delay is on output 7 (Frac).
c) The components appearance is shown below. IN1 IN6 start

the timers when 0 >1 transition occurs on the inputs.
IN1 IN6 starts the timers
Improve delay adjusts of the thread delay
Frac Elapsed changes the outputs from elapsed time to the
fraction delay for each thread
Analog IP is the input for the sampler and DFT
Timer1 to Timer6 is the output for each thread
Frac is the output of the monitored thread
Thread Count is the thread cycle
Info is a word variable with the staus of each timer

d) The following data tabs are defined for the multithread

component
CONFIGURATION: Basic configuration options

TIMERS: Time delay values for each timer
MONITORING OPTION TAB: see below
e) The user is able to select the following items for

monitoring. These are named variables and as such there
is no wire protruding from the component icon for any of
these outputs.
Trigger count when new sample occurs

Analog input data
Tabs are included in the component icon to facilitate

selection of the signals to be monitored and the name

assigned to each monitored variable. Logic is included as
part of the component to permit selection of only those
variables which are computed for the specified
configuration.
f) CBuilder requires that the user specify whether the

component is a power system or control system type
component. Power system components connect to power
system nodes as defined by node icons in RSCAD/Draft
and often contribute current injections into those nodes to
which the component is connected. Control system
components do not connect to power system nodes and are
not able to supply current injections into the power system
network.
The GPC processor to which a control system component

is allocated automatically becomes a control system
processor for the simulation case and only other control
system components may be allocated to that processor. It
is not possible to allocate both control system and power
system components to the same GPC processor.
II) COMPONENT ICON CREATION IN CBUILDER
The CBuilder Users Manual should be consulted for

additional details on defining the component icon.
Information provided here outlines the major steps required
to complete the icon associated with the multithread
model.
a) Define the Component as a Control System Component
When a new component is created the user is prompted to

select whether the component type is control or power
system. For the multithread model select control.
To change the component type after a new component has
been created, select the Tab labelled other from the control
pane of the CBuilder main window and select the radio

button next the Control under Component Type.
b) Define the Input/Output points and associated

conditional statements under the IO Points Tab
Inputs to start the timers are always present and require no

conditional statements to be placed around these input /
output points. Select the create input/output point button
from the drawing toolbar and left click when the circle is
positioned as shown below. Use the create input/output
function to create points for the 6 input. A popup menu
asking for the input/output point name and type (input or
output, int or real) appears. All of the timer inputs are
specified as integer type.

Set snap to grid when

placing input/output
points
Drawing toolbar
Create Input/Output
Point button (left
click to select, left
click again to place
input/output point)
Data under the IO Points tab should appear as shown in the

Figure below once all of the input / output points have been
entered.

Input / Output points

outside of logic con-
ditions

c) Draw the portions of the component icon which are outside of

conditional logic.
III) ADD PARAMETER ENTRY MENUS
a) Now that the component icon, including input / output points

and conditional graphics, has been completed the menus for data
entry are created. These menus are defined under the Parameters
tab in the control pane area of the RSCAD/CBuilder window.
The following sections are required for the multithread

component.
CONFIGURATION: basic configuration parameters including

the IED name, base frequency, variable name to choose value of
OUT7, enable monitoring.
TIMERS: pickup and dropout delay values for each timer.
MONITORING: signal name for trigger count and signal name for
analog input sampled data. Names for monitored signals should
only be entered if plotting is enabled.
plots=1
To create the component data entry sections listed above, left click
the add section button in the control pane area of the
RSCAD/CBuilder window. Enter the Section name in the menu
that appears. None of the sections need an associated logic
condition.
Once all of the data entry sections have been created, left click the
small arrow next to the section to which the parameters are to be
added. The arrow points down and the section heading is
highlighted. Left click the add parameter button and fill in the
appropriate data in the menu that appears. The new parameter
entry element is added under the highlighted
section.

Add Section Button

Add Parameter Button Highlighted section shows where
new parameters will be placed
IV) DETERMINE RAM LOADER CODE
a) Some variables must change value when the base frequency

changes. In this case the sample rate will change and the cutoff
frequency will change when the base frequency changes. To
facilitate this, a logic condition is added for each of the frequency

parameters state.
To enable parameter changes relative to base frequency, add the

following logic condition to the computations section.
If the freq parameter defined under the CONFIGURATION menu
is set to 1 (50 hz) by the user, then the SF parameter will be 0.400
and the fc variable will be 133.33. If the freq parameter is set to
0 (60 hz) then the SF parameter will be 0.480 and the fc variable
will be 160.0.
The parameter freq is added to the parameters section and used

within the C program to change the 2 variables SF and fc.

IV) WRITE DATA PREPARATION PORTION OF THE C

PROGRAM
a) Create C File and Declare Variables
There are two C code programs that must be written by the user
to complete the model. First, a C program which computes the
constants required by the algorithm must be written. Secondly, the
program which executes the algorithm for the model must be
written. Only the second program runs on the RTDS hardware.
Both C programs are stored in the same file. A template for the
C file is created by selecting the Add Model button under the
C File Associations tab. The newly created file can be edited by
selecting the edit button.
Edit C File
All of the input / output signals and parameters, as well as, their
types are listed in a .h file which is automatically generated by
CBuilder. The .h file is included as part of the C code using the
#include statement at the top of the C code file. As such, all of
the input / output and parameter signals may be used as part of the
C code. The simulation timestepmay be obtained by adding the
following statement into the C code
dt= getTimeStep();
The algorithm to be solved for the model is essentially a down

sampler, a DFT, and timers. In order to run the antialias filter the
constants must be computed as part of the data preparation code.
As well the down sampler should have a sample rate relative to the
base frequency. The RAM section will be used to perform all of
the offline section of code.

b) Load Data into Variables
The main portion DFT will use an 8 point buffer to determine the
DC, fundamental, and second harmonic content of the analog
input. The starting point of the buffer can be initialized such that
the phasor will be at angle zero.
c) Write Critical Data to the .map File
It may be useful to include an option in the components

CONFIGURATION menu to print computed data into the .map
file. Such data may be useful for debugging purposes during the
models development and testing, as well as, solving problems
that may arise if third parties begin to use the model.
Printing to the .map file may be done using the following structure
of the fprintf statement
fprintf(mapFile,\n D[%d][%d]= %lf,

row, col, D[row][col]);
V) WRITE C CODE TO IMPLEMENT THE ALGORITHM
Now that all of the constants required for the algorithm have been
computed, the C code to implement the algorithm itself can be
written. Code to execute the model algorithm is placed under the
CODE: section in the C file template. The basic structure of the
code is shown on pages 18 26.

VI) Test Newly Developed Model
Testing of the multithread model can start by examining the

output of the timers with input 7 enabled or disabled.
Once the basic data preparation is verified, a number of simulation

cases increasing in complexity may be run to verify the models
operation. It is useful to run the model with a pure sine wave at
base frequency and evaluate the plots to what is expected.

MULTITHREAD MODEL ALGORITHM
The algorithm for the multithread model is based on the above

idea. The model will contain seven threads with a timer in six of
the threads. The timers are activated when a value greater than 0
is applied to the appropriate input. The model will also contain
code for data sampling and a DFT function.
The main purpose here is not to develop a complex relay but to
introduce a template which can be used to create multifunctional
relays.
// Processing Threads are:

// 0 Antialias filter, downsampler, DFT
// 1 Timer 1, phasor rotation and plots
// 2 Timer 2
// 3 Timer 3
// 4 Timer 4
// 5 Timer 5
// 6 Timer 6

MULTITHREAD STATIC SECTION
// Include file below is generated by CBuilder

// and contains the variables declared as
// PARAMETERS, INPUTS, OUTPUTS . . .
#include PN_MT_temp.h
// time delay counters

double tdpu_ip1,tdpu_ip2,tdpu_ip3;
double tdpu_ip4,tdpu_ip5,tdpu_ip6;
double tddo_ip1,tddo_ip2,tddo_ip3;
double tddo_ip4,tddo_ip5,tddo_ip6;
// Other variables
double dt,del,fracdel,nThread,nThreadInv;
int sample_new,trig,trigcnt,trigcnt_old,nThreadInt;
int ip1,ip2,ip3,ip4,ip5,ip6,ip7,ip8,nfrac,dthalf;
int start1,start2,start3,start4,start5,start6;
double va_re,va_im,va2_re,va2_im;
double temp_re, temp_im, os1_1,os1_2;
double inv_dt,bfreq,favg;
double e_timer,f_timer,w_tan1,w_tan2,f_F13;
double f_sample_t,meas1,meas1old,hold1,tmp;
double va_buff[8];
int n_1[3], n_2[3],int idx;
double FUND_FACTOR,DC_FACTOR,_2ND_FACTOR;
double A[5], B[5], C[5],a_bre, a_bim;
/* E n d o f S T A T I C : S e c t i o n */
OUTPUTS:
intcnt_old = createOutput(nP1, strcat2(Relays|,iedName),0,100,NA,p1&&plots);
double A1RE = createOutput(nP2r, strcat2(Relays|,iedName),0,100,x,p2&&plots);
double A1IM = createOutput(nP2i, strcat2(Relays|,iedName),0,100,y,p2&&plots);
doubleA1FUND = createOutput(nP2fm, strcat2(Relays|,iedName),0,100,NA,p2&&plots);
double A12ND = createOutput(nP22nd, strcat2(Relays|,iedName),0,100,NA,p2&&plots);
double A1DC = createOutput(nP2dc, strcat2(Relays|,iedName),0,100,NA,p2&&plots);

MULTITHREAD RAM SECTION
int i,k,nsn;
double nsf,wcp,cosn,x;
if(freq==0)
{
SF = 0.480;
fc = 160.0;
} else {
SF = 0.400;
fc = 133.33;
}
dt = getTimeStep();// Simulation time step
nThreadInt = 7;
nThread = 7.0;
nThreadInv = 1.0 / nThread;
fracdel = nThread * dt;// RSCAD time step,delay is multiple # of
threads
del = fracdel;
dthalf = 0.5*del; // Pick Up Delay Calculation
tdpu_ip1 = 0.0;
tdpu_ip2 = 0.0;
tdpu_ip3 = 0.0;
tdpu_ip4 = 0.0;
tdpu_ip5 = 0.0;
tdpu_ip6 = 0.0;
tddo_ip1 = 0.0;
tddo_ip2 = 0.0;
tddo_ip3 = 0.0;
tddo_ip4 = 0.0;
tddo_ip5 = 0.0;
tddo_ip6 = 0.0;
ip1 = 0;
ip2 = 0;
ip3 = 0;
ip4 = 0;
ip5 = 0;
ip6 = 0;
ip7 = 0;

ip8 = 0;
start1 = 0;
start2 = 0;
start3 = 0;
start4 = 0;
start5 = 0;
start6 = 0;
// INPUT processing Initialization
nsn = 1;
nsf = 1.0;
inv_dt = 1.0 / dt;
f_sample_t = 0.001 / SF;
bfreq = SF * 125.0;
favg = bfreq;
idx = 6; // 6 samples to rotate by 270, normalizes Aph to 0.0 deg
e_timer= 0.0; // timer to enable freq tracking
f_timer= 10.25*dt; // adjustment to help zero the phase
// LP Filter constants calculations
for( k = 0; k < nsn; ++k )
{
wcp = sin( fc * PI * dt ) / cos( fc * PI * dt );
cosn = cos(( 2.0 * ( k + nsf + 1.0 ) 1.0 ) * PI / ( 4.0 * nsf ));
x = 1.0 / ( 1.0 + wcp * wcp 2.0 * wcp * cosn );
A[ k ] = wcp * wcp * x;
B[ k ] = 2.0 * ( wcp * wcp 1.0 ) * x;
C[ k ] = ( 1.0 + wcp * wcp + 2.0 * wcp * cosn ) * x;
}
for(i=0;i<8;i++)
{
va_buff[i]=0.0;
}
FUND_FACTOR=0.176776695; // for RMS => 0.5*(1/sqrtN)
FUND_FACTOR=FUND_FACTOR*1.009910335; // adjust for
the loss in the BW Filt at 160.0 FC
_2ND_FACTOR=FUND_FACTOR*1.135933359; // adjust for
the loss in the BW Filt
DC_FACTOR=0.125;
/* E n d o f R A M : S e c t i o n */

MULTITHREAD CODE SECTION
meas1 = IN9;
// Butterworth Filter for antialiasing 2nd order LP
// VA first stage
tmp = B[ 0 ] * os1_1 + C[ 0 ] * os1_2 + A[ 0 ] * meas1;
meas1 = tmp + 2.0 * os1_1 + os1_2;
os1_2 = os1_1;
os1_1 = tmp;
meas1old = hold1;
f_F13 = f_timer;
e_timer = e_timer + dt;
f_timer = f_timer + dt;
if(f_timer > f_sample_t)
{
// linear interpolation
tmp = ((meas1 meas1old) * inv_dt) * (f_sample_t f_F13);
meas1 = tmp + meas1old;
// 8 SAMPLE BUFFER
va_buff[idx] = meas1;
idx = idx+1;
idx = idx % 8;
// DFT FOR THE VOLTAGES AND CURRENTS
A1DC=(va_buff[0]+va_buff[1]+va_buff[2]+va_buff[3]+va_buff
[4]+va_buff[5]+va_buff[6]+va_buff[7])*DC_FACTOR;
va_re=(va_buff[0]va_buff[4]+
INV_ROOT2*(va_buff[1]va_buff[3]va_buff[5]+va_buff[7]))
*FUND_FACTOR;
va_im=(va_buff[2]+va_buff[6]+INV_ROOT2*(va_buff[1]v
a_buff[3]+va_buff[5]+va_buff[7]))*FUND_FACTOR;
va2_re=(
va_buff[0]va_buff[2]+va_buff[4]va_buff[6])*_2ND_FACTO
R;
va2_im=(va_buff[1]+va_buff[3]va_buff[5]+va_buff[7])*_2N
D_FACTOR;
trig = 1;
f_timer = f_timer f_sample_t;

trigcnt_old = trigcnt;
trigcnt = 0;
sample_new = 1;
// set the values for Inputs
ip1 = IN1;
ip2 = IN2;
ip3 = IN3;
ip4 = IN4;
ip5 = IN5;
ip6 = IN6;
ip7 = IN7;
ip8 = IN8;
}
else
{
trig = 0;
hold1 = meas1;
trigcnt = trigcnt + 1;
if (trigcnt > nThreadInt){
sample_new = 0;
trigcnt = 1; // go to Thread 1
}
///////////////////// THREAD 1 /////////////////////////////
if (trigcnt == 1){
if (sample_new==1){
if (trigcnt_old<trigcnt){
fracdel = (trigcnt + trigcnt_old + 5)*nThreadInv*del;
}
if (trigcnt_old==trigcnt){
fracdel = (trigcnt_old + 1)*nThreadInv*del;
}
if (trigcnt_old>trigcnt){
}
if (e_timer>0.1&& ip7>0){
w_tan1 = atan2(va_im,va_re);
// figure out the real and imag,then rotate the phasors
a_bre = cos(w_tan1);
a_bim = sin(w_tan1);

temp_re=(va_re * a_bre) (va_im * a_bim);

temp_im=(va_re * a_bim) + (va_im * a_bre);
va_re = temp_re;
va_im = temp_im;
}
}
else
{
fracdel = del;
}
// set the values for plots
A1RE = va_re;
A1IM = va_im;
A1FUND = sqrt((va_re * va_re) + (va_im * va_im));
A12ND = sqrt((va2_re * va2_re) + (va2_im * va2_im));
}
///////////////////// THREAD 2 /////////////////////////////
else if (trigcnt == 2){
if (sample_new==1 && ip7>0){
}
}
}
}
else
{
fracdel = del;
}
// set the outputs for Timer 1
if (ip1 > 0){
if (tdpu_ip1 < T1PU){
tdpu_ip1 = tdpu_ip1 + fracdel;
}
if (tdpu_ip1 >= T1PU){

start1 = 1;
}
}
else
{
if (start1 > 0){
tddo_ip1 = tddo_ip1 + fracdel;
}
if (tddo_ip1 >= T1DO){
start1 = 0;
tdpu_ip1 = 0.0;
tddo_ip1 = 0.0;
}
} // end of setoutputs IF statement
if (ip8 == 1){
OUT1 = fracdel;
}
else
{
if (ip1 > 0){
OUT1 = tdpu_ip1;
}
else
{
OUT1 = tddo_ip1;
}
}
}
///////////////////// THREAD 3 /////////////////////////////
}
}

}
}
else
{
fracdel = del;
} // CODE AS PER TIMER 1
}
///////////////////// THREAD 4 /////////////////////////////
}
}
}
}
else
{
fracdel = del;
}
///////////////////// THREAD 5 /////////////////////////////
}
}
}
}
else

{
fracdel = del;
}
///////////////////// THREAD 6 /////////////////////////////
}
fracdel = (trigcnt + 1)*nThreadInv*del;
}
}
else
{
fracdel = del;
}
///////////////////// THREAD 7 /////////////////////////////
if (sample_new == 1 && ip7>0){
}
}
else
{
fracdel = del;
}
cnt_old = trigcnt_old;
OUT8 = trigcnt;
OUT9 = start1+start2+start3+start4+start5+start6;

6 using CBUILDER with the
PMU shell component
August 2012 rev 02
PMU 1 PMU 2 PMU 3 ... PMU 8
RTDS
Technologies
using CBuilder with the PMU Shell component
INTRODUCTION
In real time digital power system simulation the minimum length

of time step used in the simulation is dictated by the most time
consuming algorithm which has to be completed in the time step.
Provided the resulting time step is compatible with the bandwidth
of the phenomena being investigated the simulation can run in real
time. When a smaller time step is necessary to meet the bandwidth
requirements the simulation can still run but not in real time.
This document describes the implementation of a Phasor
Measurement Unit (PMU) algorithm using techniques introduced
in tutorial chapter 5.
This document outlines how the create the PMU shell from the
source files found in the RSCAD installation directory. Typically
this is C:\RSCAD\TUTORIAL\CBuilder\CH6PMU_SHELL

Phasor Measurement Unit
TYPICAL PMU AC CONNECTION
PMU SHELL
Figure1. PMU AC Connection
PMUs are available from virtually every manufacturer of

protection and monitoring equipment. They are often
implemented as embedded functions within relays or disturbance
recorders. This document describes a PMU shell software model
for use on a Real Time Digital Simulator (RTDSR) . The
algorithms that are part of the PMU shell are developed using the
signal processing reference model from IEEE C37.118.12011
Annex C.
Development of a CBuilder model involves many steps and

generally requires weeks or months from start to finish. The next
page provides an overview of the steps typically involved to
develop a model.
RTDShas provided the source files that can be used by individuals

to start developing their own PMU signal processing algorithms
with Cbuilder and the GNETPMU firmware.

Development of the multithread model requires the following

steps


b) locate and place all of the input / output points
c) Draw component icon




correctly.

PMU SHELL COMPONENT
CBuilder is used to create models that are not part of the normal
RSCAD library. The source files are created and stored in the
RSCAD users root folder, typically this folder is
C:\RTDS_USER
The source files for the PMU SHELL component by default are
installed:
C:\RSCAD\TUTORIAL\CBuilder\CH6PMU_SHELL\RTDS_USER
There are 2 sub folders ..\CMODEL_SOURCE and ...\ULIB, the
cmodel_source folder contains the *.c and *.h files while the
ulib folder contains the component definition file.
The source files need to be copied to the RTDS_USER directory

as follows:
1 Copy the file
C:\RSCAD\TUTORIAL\CBuilder\CH6PMU_SHELL\RTDS_USER\
ULIB\_rtds_GTNET_PMU_shell.def to your ULIB folder
C:\RTDS_USER\ULIB\
2 Copy the file
CMODEL_SOURCE\PMU_m.c to your BIN folder
C:\RTDS_USER\BIN\CMODEL_SOURCE
3 Copy the file
CMODEL_SOURCE\PMU_m.h to your BIN folder
4 Copy the file
CMODEL_SOURCE\PMU_m.c to your BIN folder
5 Copy the file
CMODEL_SOURCE\PMU_m.h to your BIN folder

LOAD PMU SHELL COMPONENT into CBUILDER
StartCBuilderand open thePMUshell component definition file

_rtds_GTNET_PMU_shell.def. Once the component is loaded
into Cbuilder, the source files need to be compiled.
Follow the steps shown in figure 2 for Model: PMU_p
Repeat the steps for the Model: PMU_m
Figure2. Compiling PMU Shell source files in CBuilder

PMU SHELL ALGORITHM
ThePMU model developed to run on theRTDS includes the P class

and M class reference models from the IEEE standard C37.118.1
Annex C. Figure 3 shows the typical steps used within the
reference PMU to process the input signals [1]. A GTSYNC card
provides the absolute timereference and the simulation data is
sampled using a fixed sample rate. The quadrature oscillator
operates at nominal frequency and is used to perform complex
multiplication of the input signal. The LP filters are Finite Impulse
Response (FIR) and remove the double frequency component thus
leaving the Re and Im part of the original input signal. For P and
M class the LP filters are implemented using symmetrical FIR
filters with an odd number of stages. The P class filter
coefficients are calculated using a triangular window and the M
class filter coefficients are calculated using windowed sinc
function multiplied with a Hamming window. Each sample is
timestamped and compensated for the group delay of the LP
filter. The phasor estimate at the center of the estimation window
is unbiased by the actual system frequency and does not require
further phase correction when the timestamp at the center of the
window is used. In IEEE C37.118.12011 Annex C the P class
samples data at 15 samples per cycle and the M class samples data
at 16 samples per cycle at nominal frequency. We have modified
the P class to sample at 16 samples per cycle so we can use higher
reporting rates.
Figure3. PMU Phasor signal processing reference model

Although the block diagram in Figure 3 explains the concept of the
reference model quite well, there are some subtle changes that
need to be done for it to work on a real time digital simulator. The

simulation data must be interpolated when sampled because the

PMU sample rate may not be an integer multiple of the simulation
timestep. The quadrature oscillator must also be interpolated by
the same amount as the simulation data. The maximum reporting
latency allowed by C37.118.12011 is 2/Fs for P class and 5/Fs for
M class where Fs is the reporting rate [2]. Therefore the LP filter
order must have latency less than the maximum allowed by the
standard and also allow for other delays. The LP filter order can
be quite large at the lower reporting rates and exceed the amount
of available RAM. For example, an M class PMU operating at
nominal 50Hz with a reporting rate of 10Fs requires a filter order
of 700. The number of variables for just onePMUwould be equal
to 12,618. Because the RTDS model was designed to support 8
PMUs the amount of variables just to process the FIR filters would
equal 100,944 for a 50HzMclass PMU reporting at 10Fs. During
development of the RTDS PMU model the lowest supportable
reporting rate was found to be 10Fs at 50Hz. As the reporting rates
become lower the filter window length becomes larger to the point
that the available memory limit is exceeded. The standard
reference model does not provide filter parameters for reporting
rates higher than 100Fs or 120Fs. In order to provide reporting
rates at 200Fs and 240Fs for 50Hz and 60Hz respectively a 30 tap
FIR filter using DolphChebyshev coefficients was used.
Figure4. Magnitude Response of 240 frames/second filter

The processing of the simulation data and manipulation of the data

into the format defined by the IEEE standard is computed on one
of the PB5 processor. Because each of the eight PMUs operating
on the RTDS is independent, it is possible that all eight PMUs may
output data at the same time. Therefore a method to limit servicing
of one PMU per simulation timestepwas needed; to prevent
buffer overflows on theGTNET. When PMU data is ready to be
sent to the GTNET a service interrupt flag is set and is cleared once
the PMU data is sent to the GTNET.

C Code SECTIONS
The two *.c files have been prepared to use the parameters
specified in the PMU Shell component definition file. There are
some very specific sections that SHOULD NOT BE MODIFIED!
Before the
// !!! DO NOT CHANGE THIS !!!
STATIC:
// GTNET PHASOR ARRAY variables
// INPUT processing variables
// FIR coefficients etc...
The basic
INPUTS:
OUTPUTS:
RAM_PASS1:
RAM_PASS2:
DOWNLOAD_FILE_CODE:
// *******************************
// * CREATE THE DLOAD FILE ENTRIES
// *******************************
CODE_FUNCTIONS:
There are a number of functions called by the main CODE, each
function has some comments about what the function does. the
main function is the pmu_data function and it is used to create the
phasors and prepare the data so it can be sent to the GTNET card.
//////////////////////////////////////////////////////////
// fir_split function
// Calculates the Filtered phasor from the sampled quadrature osc. data
// Inputs:
// input1 ... Quadrature Osc sampled data
// input2 ... Quadrature Osc sampled data
// ntaps ... number of stages
// h ... FIR coefficients for PMU 07
// z ... pointer for Z delay line
// out ... pointer for phasor data

// p_state ... pointer for stage of FIR

// update ... flag to update the stage of the FIR
// Output:
//////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////
// adjust_phasor function
// Returns the corrected phasor from the array for the PMU output
// Inputs:
// pmu ... PMU number 07
// Output:
// temp_re, temp_im
//////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////
// symmetrical function
// Calculates the symmetrical components from the phasor array for the PMU output
// Inputs:
// A ... Va or Ia from #define
// B ... Vb or Ib from #define
// C ... Vc or Ic from #define
// VorI ... V1 or I1 from #define
// Output:
//////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////
// complex_division function
// Returns the corrected phasor magnitude from the array for the PMU output
// using Annex C equation C.6 correction factor
// Inputs:
// Output:
// temp_re, temp_im
//////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////
// phasor1 function
// Returns the correct type of output Re,Im or Cn,Phi
// Inputs:
// enable ... Enable
// OUTF ... Format

// Output:
//////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////
// calc_angle_diff function
// Returns the correct angle difference between 2 angles
// Inputs:
// Angle1 ...
// Angle2 ...
// Output:
// angle_diff
//////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////
// pmu_data function
// Calculates the V and I phasor from the Input data and fills the phasor array for the PMU
// output
// Implements the P CLASS reference model from Annex C of C37.118.1
// Inputs:
// IN1 ... Va
// IN2 ... Vb
// IN3 ... Vc
// IN4 ... Ia
// IN5 ... Ib
// IN6 ... Ic
// Output:
//////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////
// pmu_out function
// by Dean Ouellette/Marc Desjardine
// Send the PMU output to the GTNETPMU
// Inputs:
// Output:
// !!! DO NOT CHANGE THIS !!!
//////////////////////////////////////////////////////////
CODE:
There is not much code here in the main section and the C file
contains enough comments to be able to figure out how the
program works.

REFERENCES
[1] IEEE C37.118.12011 Annex C

[2] IEEE C37.118.12011 section 5.5.9

7 using CBUILDER to create
a generator control block
Nov 20087 rev. 00
M1 W M1 W
DC1 Type DC1 Type

Excitation Excitation
System System
Vs Vc
Ef Vpu Ef Vpu
PSS = No
PSS = Yes
LDComp = No
LDComp = Yes
RTDS
Technologies
INTRODUCTION
The DC1 type exciter requires real inputs from a generator model.
The two required inputs are the per unit generator terminal voltage
(Vpu) and the generator speed (W). An optional real stabilizer
input and load compensation input is available. The exciter model
produces the field voltage output (Ef) required by the generator.

S As a starting point, an existing generator control block can be

loaded into component builder. This eliminates the need to draw
the icon and create all the parameters.
S Upon loading the component, a popup box appears requesting the
type of component. Select Control.
The component icon for the exciter includes five I/O points. Four
signal inputs and one signal output, all are real.
S Save the component builder icon to a new file name located in the
RTDS_USER|ULIB folder.

S Select the C File Associations tab

S Select the icon to Add New Association
S Enter a model name
Left click to create new C File Association

(New Model Name popup menu appears)
Input and Output points (listed under the IO Points tab) and
user defined parameters (listed under the Parameters tab) are
automatically associated with the model and placed in the .h file.
Left clicking the View .h file button opens the .h file in an editor.
The model includes four inputs, one output and a number of
parameters

INPUTS:
double VPU;
double VS;
double Speed;
double VC;
OUTPUTS:
double OUT;
PARAMETERS:
char Gen[11];
int Mon;
int PSS;
double Vi;
double Tr;
double Ka;
double Ta;
...

SAMPLE C CODE FOR THE DC1 TYPE EXCITER
S The C code is written for the model by clicking on the edit icon to
open up the text editor window.
S The code for the DC1 type exciter is based on the block diagram
shown below.

AVR EXDC1

Vref
VSIG
wpu
VRmax
1.01
1.0 1 + sTc Ka mon6 1
+ ++ + X(t) dt
*
mon1 1 + sTr mon2 mon3 mon4 1 + sTb mon5 1 + sTa mon7 Te Efield
Vpu/Vc
VRmin
mon8
SE+KE
w > wpu mon9
wpu
W
*
sKf
0.0026526
mon10 1 + sTf1
DC1
VSIG = VS + VUEL + VOEL Excitation System
7.7
S The data preparation and code for the DC1 type exciter is shown
below.
VERSION:
3.001
#include myEXDC1.h
STATIC:
double dt,washoutG;
double Vmax, Vref, tmp;
double efldi,Verr,v_init;
double mon1,mon2,mon3,mon4,mon5,mon6,mon7,mon8,mon9,mon10;
int mon_array[10] = {1,2,3,4,5,6,7,8,9,10};
#include <builtin_gcc_generatorStructures.h>
struct realpolex realpole1;

struct realpolex realpole2;
struct integratorx integrator1;
struct washoutx washout1;
struct leadlagx leadlag1;
struct satKEx satKE1;
RAM_FUNCTIONS:
#include initTransferFunctions.inc
RAM:
dt= getTimeStep();
/* Parameter Validation */
if(Vrmax <= 0.0)
{
if(E2< E1)
{
printf(\nWarning: Vrmax is less than zero.);
printf(\n E2 must be greater than E1);
printf(\n Subsystem %d, Machine %s, exciter type ESDC1A.\n, getSubsystem(),Gen);
reportError(EXDC1,1);
}
Vrmax = (Se2 + Ke)*E2;

Vrmin = 1*Vrmax;
}
if (Vrmax < Vrmin)

{
tmp = Vrmin;
Vrmin = Vrmax;
Vrmax = tmp;
printf(\nWarning: Vrmax is less than Vrmin.);
printf(\n Vrmin set to Vrmax and Vrmax set to Vrmin);

printf(\n Subsystem %d, Machine %s, exciter type EXDC1.\n, getSubsystem(),Gen);
reportError(EXDC1,1);
}
/* read initial field voltage */

efldi = get_data(Gen,Efldi);
/* Compute initial Vref value */

if (Vi < 0.0 || LFInit==1)
{
Vi= get_data(Gen,Vpu);
if (LDComp == 1)
{
Vi = computeInitVcomp(Gen);
}
}
/* Compute initial Se + KE */
if (Ke == 0.0)
{
v_init = 0.0;
printf(\nWarning: Ke entered as 0.0. Calculation of Ke such that the);
printf(\n initial condition of Vc is zero is not supported.);
printf(\n Subsystem %d, Machine %s, exciter type EXDC1.\n, getSubsystem(),Gen);
reportError(EXDC1x,1);
}
else
{
v_init = initSatKE(E1,Se1,E2,Se2,efldi,Ke,&satKE1);
}
printf(The value of v_init is %f\n,v_init);
Verr = v_init/Ka;
Vref = Verr + Vi;
Vmax= 1.2;
if (Vref > Vmax) Vmax= 1.2*Vref;
/* the create_slider function is in the .h file in the INPUTS section */
/* Initialize variables for real pole #1 */
initRealPole(1.0,Tr,Vi,Vi,&realpole1);
/* Initialize variables for lead lag */
initLeadLag(Tb,Tc,Verr,Verr,&leadlag1);
initRealPole(Ka,Ta,Verr,v_init,&realpole2);
/* Initialize variables for wash out */

washoutG = Kf/Tf1;
initWashout(washoutG,Tf1,efldi,&washout1);

/* Initialize variables for integrator */
initIntegrator(Te,0.0,efldi,&integrator1);
/* Check initial output values are within Vrmax and Vrmin limits */
if (v_init > Vrmax || v_init < Vrmin)
{
printf(\nWarning: Initial value of mon6 is not within the entered limits.);
printf(\n VRmax = %f, VRmin = %f, mon6 initial value = %f.,Vrmax,Vrmin,v_init);
printf(\n Subsystem %d, Machine %s, exciter type EXDC1x.\n, getSubsystem(),Gen);
reportError(EXDC1x,1);
}
/* Initialize all monitoring variables that are going to be referenced in the code section before
they are assigned a value */
mon9 = v_init;
mon10 = 0.0;
CODE:
double puSpeed;
/* Include load compensation */

if (LDComp==1)
{
mon1 = VC;
}
else
{
mon1 = VPU;
}
/* realpole #1*/
mon2 = realPole(mon1, 1.0, 0, 0.0, 0.0,0,0,0.0, &realpole1);
/* Summing junction */
mon3 = Vref1 mon2;
/* Optionally include stabilizer input */

if (PSS == 1)
{
mon3 = mon3 + VS;
}
mon4 = mon3 mon10;
/* leadlag */
mon5 = leadLag(mon4,1.0,0,0.0,0.0,0,0,0.0,&leadlag1);
/* realpole #2 */
mon6 = realPole(mon5,Ka,1,Vrmin,Vrmax,0,0,0.0,&realpole2);
/* Summing Junction */
mon7 = mon6 mon9;
/* Integrator */
mon8 = integrator(mon7,0,0.0,0.0,0,0,0.0,&integrator1);

/* Saturation Function */
mon9 = satKE(mon8, &satKE1);
/* Washout */
mon10 = washOut(mon8,washoutG,0,0.0,0.0,0,0,0.0,&washout1);
/* Efd */
OUT = mon8;
if (spdMult == 1)
{
puSpeed = Speed/wBase;
OUT = mon8 * puSpeed;
}
/*check if monitoring is enabled, if so assign the output based on the dial position*/
if (Mon ==1)
{
if (dial1 == 2)
{
internalV = mon2;
}
else if (dial1 == 3)
{
internalV = mon3;
}
{
internalV = mon4;
}
{
internalV = mon5;
}
{
internalV = mon6;
}
{
internalV = mon7;
}
{
internalV = mon8;
}
else if (dial1==9)
{
internalV = mon9;
}
else if (dial1==10)
{
internalV = mon10;
}
else

{
internalV = mon1;
}
}

DATA PREPARATION AND INITIALIZATION
Generic generator control models include the capability to

initialize their internal variables and to configure setpointsliders.
Given the initial field voltage, the initial terminal voltage and
various gains of the exciter components, it is possible to compute
the initial inputs and output associated with each block of the DC1
controller. The initial terminal voltage and gains of the exciter
components are entered to the component as parameters. The
initial field voltage is computed by the generator model code and
can be accessed using the get_data function. The get_data
function locates and returns data from another component. In the
RAM section the initial field voltage is determined using the code
below;
efldi = get_data(Gen,Efldi);
The get data function requires two arguments. The first argument
is the name of the component, the second argument is the
parameter name.
The name of the generator to which the exciter model is connected
is required as a parameter named Gen.
The generator model precalculates the field voltage required to
provide the desired real and reactive power output. This data is
written to the .map file and given the variable Efldi. To extract
the initial field voltage from the generator model, the parameter
name Efldi must be passed to the get_data function. The parameter
name is case sensitive.
The error is calculated as the initial output of the saturation block
v_init divided by the gain Ka.
Verr= v_init/Ka;
The initial value for Vref slider is computed as

Vref= Vi+Verr;
Vmax= 1.2;
if (Vref > Vmax) Vmax= 1.2*(Vref);
The initial value Vref and the maximum value Vmax are used
to initialize the slider in the following section ADD AN
INTERNAL SLIDER.

Commonly used control functions are available as function calls
in CBuilder. In this case, the realPole, leadLag, washOut and
Integrator functions are used. To use these function in the CODE
section, the history terms must first be initialized in the RAM
section. The calculated history terms are then stored in a structure
for use within the CODE section. The initialization functions are
stored in a file named initTransferFunctions.inc. This include
statement must appear in the RAM_FUNCTIONS section.
Optionally, the initialization functions could appear directly in the
RAM_FUNCTIONS section and not in an include file. Please see
APPENDIX E of the CBuilder Users Manual for complete details
on initialization of the transfer functions.
RAM_FUNCTIONS:
#include initTransferFunctions.inc
The functions in the initTransferFunctions.inc file can be called

from the RAM section.
/* Initialize variables for saturation function */

if (Ke <= 0.0)
{
v_init= initSatKE0(E1,Se1,E2,Se2,efldi,Vrmax,Cal,&satKE1);
}
else
{
v_init =
initSatKE(E1,Se1,E2,Se2,efldi,Ke,Cal,&satKE1);
}
initRealPole(1.0,Tr,Vi,Vi,&realpole1);
/* Initialize variables for lead lag */
initLeadLag(Tb,Tc,Verr,Verr,&leadlag1);
initRealPole(Ka,Ta,Verr,v_init,&realpole2);
/* Initialize variables for wash out */

washoutG = Kf/Tf1;
initWashout(washoutG,Tf1,efldi,&washout1);
/* Initialize variables for integrator */

initIntegrator(Te,0.0,efldi,&integrator1);
For example, to initialize the first realpole, the gain, time constant,
initial input, initial output and realpole structure are passed as
parameters. The initial input and output of the realpole are set to
initial p.u voltage of the generator. The leadLag is initialized next,
the precalculated Verr value is passed as the initial input and
output of the leadlag.

ADD AN INTERNAL SLIDER
Referring to the block diagram, a slider Vref is required as input

to the control block. The slider is an internal input to the
component meaning that a physical input connection does not
exist on the component.
S Add an internal slider.
Left click to add a variable

to the .h file.
Select section create:

SLIDERS to add a slider
S Assign a variable name to the slider so it can be referenced in the

Code section. In this example Vref1 is used.
S Select OK
An Edit Slider box appears as below requesting information to
initialize the slider.

A slider name is required. This is the name of the slider as it will
appear in RunTime. To duplicate existing generic generator
control models the Vref slider is located under the CTLs|Inputs
group and named V_generator name. To concatenate two strings
together, the strcat2 function can be used to create the slider name.
The initial value of the slider has been calculated in the RAM
section and assigned to variable Vref. The maximum value of the
slider has also been calculated in the RAM section and assigned
to variable Vmax. The variables Vref and Vmax are entered as
Initial Value and Max Value above.
S Save the CBuilder component
After saving the component, a create_slider function appears in
the INPUTS: section of the .h file. The slider name Vref1 can be
used within the CODE section of the .c file.

ADD CODE FOR REALPOLE FUNCTION
The function realPole implements the transfer function below

Y(s) = G / (1 + sT) * X(s)
In the code section, the realPole function is called as follows
/* realpole */
out=realPole(Input, Gain, Limit, minLim, maxLim,RST,RSTSIG,RVAL, &realpole1);
The realPole function requires nine arguments. For a complete

description of the arguments please see APPENDIX E of the
CBuilder Users Manual. The function returns the output Y(s) of
the realpole transfer function.

ADD CODE FOR LEADLAG FUNCTION
The function leadLag implements the transfer function

Y(s) = G (1 + sT1) /(1 + sT2)* X(s)
In the code section, the leadLag function is called as follows
/* leadLag */
out=leadLag(Input, Gain, Limit, minLim, maxLim,RST,RSTSIG,RVAL, &leadlag1);
The leadLag function requires nine arguments. For a complete

the leadlag transfer function.

ADD CODE FOR WASHOUT FUNCTION
The function washOut implements the transfer function

Y(s) = G sT /(1 + sT)* X(s)
In the code section, the washOut function is called as follows
/* washOut*/
out=washOut(Input, Gain, Limit, minLim, maxLim,RST,RSTSIG,RVAL,
&washout1);
The washOut function requires nine arguments. For a complete

the washOut transfer function.

ADD CODE FOR SATURATION FUNCTION
The saturation function satKE implements the saturation curve

Se
Se(E2)
Se(E1)
E1 E2 Ef
In the code section, the satKE function is called as follows.

/* saturation */
out=satKE(Input, &satKE1);

ADDING THE CODE
S Read in the p.u. voltage and check for load compensation
if (LDComp==1)
{
mon1 = VC;
}
else
{
mon1 = VPU}
S Add function call for the first realpole function

mon2 = realPole(VPU, 1.0, 0, 0.0, 0.0,0,0,0.0, &realpole1);
The realpole function requires nine arguments. The first argument
is the input. Input to the first realpole block is the p.u. voltage from
the generator model. This input is an I/O point on the component
and declared in the .h file as VPU.
The second argument is the gain. The gain is fixed at 1.0.
The third, fourth and fifth arguments are for limits. Limits are not
included in this block and therefore set to 0.
The sixth, seven and eigth arguments are for reset. Reset is not
The ninth argument is the realpole structure. The variables within
the structure were initialized in the RAM section.
The output from the realpole is assigned the variable name mon2
according to the block diagram.
S Add code for the summing junction.
/* Summing junction */
mon3 = Vref1 mon2;
/* Optionally include stabilizer input */

if (PSS == 1)
{
mon3 = mon3 + VS;
}
The summing junction subtracts the output from the realpole

mon2 from the Vref slider. An optional third input can exist to
the summing junction. If the parameter PSS is set to YES in the
component, a stabilizer input signal input is available and added
to the above. The output from the summing junction is assigned
the variable name mon3.

S Add code for the summing junction
mon4 = mon3 mon10;
The output from the washout block (mon10) is subtracted from
the output of the previous summing junction according to the
block diagram.
S Add function call for the leadlag function.
mon5 = leadLag(mon4,1.0,0,0.0,0.0,0,0,0.0,&leadlag1);
The leadLag function requires nine arguments. The first argument
is the input. Input to the leadLag function is the output from the
previous summing junction (mon4).
The second argument is the gain. The gain is fixed at 1.0. The
third, fourth and fifth arguments are for limits. Limits are not
The ninth argument is the leadlag structure. The variables within
The output from the leadlag is assigned the variable name mon5
S Add function call for the second realpole function.
mon6 = realPole(mon5,Ka,1,Vrmin,Vrmax,0,0,0.0,&realpole2);
Input to the second realPole function is the output from the leadlag
(mon5).
The second argument is the gain. The gain Ka is entered as a
parameter.
Limits are included in the second realPole, therefore the third
argument is set to 1.
The fourth and fifth arguments are the minimum and maximum
limits Vrmin and Vrmax. Vrmin and Vrmax are parameters
entered by the user.
The ninth argument is the realpole#2 structure. The variables
within the structure were initialized in the RAM section.
The output from the realpole is assigned the variable name mon6

S Add code for summing junction.
mon7 = mon6 mon9;
The output from the saturation block (mon9) is subtracted from the
output of realpole#2 (mon6).
S Add function call for the integrator function.
mon8 = integrator(mon7,0,0.0,0.0,0,0,0.0,&integrator1);
The first argument in the integrator function call is the input. Input
to the integrator function is the output from the previous summing
junction (mon7).
The second, third and fourth arguments are for limits. Limits are
not included in this block and therefore set to 0.
The fifth, sixth and seven arguments are for reset. Reset is not
The eighth argument is the integrator structure. The variables
The output from the integrator is assigned the variable name
mon8 according to the block diagram.
S Add function call for the saturation function.
mon9 = satKE(mon8,&satKE1);
The first argument in the satKE function call is the input. Input to
the satKE function is the output from the previous integrator
(mon8).
The second argument is the saturation structure. The variables
S Add function call for the washout function.
mon10 = washOut(mon8,washoutG,0.0,0.0,0,0,0.0,&integrator1);
The first argument in the washOut function call is the input. Input
to the washOut function is the output from the integrator (mon8).
The second argument is the gain. The gain is computed as Kf/Tf1.

The third, fourth and fifth arguments are for limits. Limits are not
The sixth, seventh and eighth arguments are for reset. Reset is not

The ninth argument is the washout structure. The variables within
The output from the washout is assigned the variable name
mon10 according to the block diagram.
S Add multiplier and compute the output field voltage

if (spdMult == 1){
puSpeed = Speed/wBase;
OUT = mon8 * puSpeed; }
The p.u speed is determined by dividing the machine speed by the

base value (wBase). wBase is a parameter entered by the user and
Speed is an I/O point on the component and declared in the .h file
as Speed.
The output from the integrator (mon8) is multiplied by the p.u.
speed of the machine to produce the field voltage (OUT). The
signal OUT is an I/O point on the component and declared in the
.h file as OUT.

ADD A DIAL TO SELECT INTERNAL VARIABLES FOR MONITORING
Internal variables are displayed on the block diagram of the DC1

controller and are identified with a mon# wire label. To maintain
similar operation to existing generator controls, only one internal
variable may be monitored at one time in RunTime. The position
of a dial indicates which internal variable is displayed in RunTime.
S Add an internal dial.

to the .h file.

DIALS to add a dial
S Assign a variable name to the dial so it can be referenced in the

Code section. In this example dial1 is used.
S Select OK
An Edit Dial box appears as below requesting information to
initialize the dial.

A dial name is required. This is the name of the dial as it will
appear in RunTime. To duplicate existing generic generator
control models the dial is named exc_mon and is located under
the Machines|generatorname group To concatenate two strings
together, the strcat2 function can be used to create the Group
name. The number of internal monitoring variables is 10,
therefore the number of positions available on the dial has been set
to 10. The initial position of the dial is set to 1. The dial values
are stored in an array with name mon_array. This array must be
declared in the static section of the .c file. Creation of the dial is
conditional. If the parameter Mon (Monitor internal variable) is
toggled to Yes, then the dial is created.
S Save the CBuilder component
After saving the component, a create_dial function appears in the
INPUTS: section of the .h file. The dial name dial1 can be used
within the CODE section of the .c file.

ADD A GENERIC OUTPUT
An output signal must be added to display the monitored internal

variable in RunTime.
S Add a generic output.

to the .h file.

GENERIC OUTPUTS
S Assign a variable name to the generic output so it can be

referenced in the Code section. In this example internalV is used.
S Select OK
An Edit Output box appears as below requesting information to
initialize the generic output signal.

A generic output is required to display internal variables in
RunTime. An output name is required, this is the name of the
signal as it will appear in RunTime. The variable name ivName
is entered. ivName is a parameter. Therefore, the signal name
entered as parameter ivName is used as the output name. To
duplicate existing generic generator control models the signal
name is located under the Machines|generatorname group. To
concatenate two strings together, the strcat2 function can be used
to create the Group name. Creation of the generic output is
conditional. If the parameter Mon (Monitor internal variable) is
toggled to Yes, then the output signal is created.

ADD MONITORING CODE
The internal variables named mon# can be plotted in RunTime.

The signal to monitor is based on the dial position.
S Add monitoring code for internal variables.
if (Mon == 1)
{
if (dial1 == 2)
{
internalV = mon2;
}
{
internalV = mon3;
}
{
internalV = mon4;
}
{
internalV = mon5;
}
else if (dial1== 6)
{
internalV = mon6;
}
{
internalV = mon7;
}
{
internalV = mon8;
}
else if (dial1==9)
{
internalV = mon9;
}
else if (dial1==10)
{
internalV = mon10;
}
else
{
internalV = mon1;
}
}

Monitoring is enabled if the parameter Mon is toggled to Yes in the
component. If the dial position is 2, then the generic output signal
exc_mon1 is assigned internal variable mon2. If the dial position
is 3, then the generic output signal exc_mon1 is assigned internal
variable mon3 etc. This code continues until all 9 dial positions
have been associated with an output. Note: the variable name of
the dial declared in the .h file is dial1. The dial name in RunTime
will appear as exc_dial. The variable name of the generic output
declared in the .h file is exc_mon1. The name of the generic output
will appear in RunTime as exc_mon.

C Builder Tutorial

Încărcat de

Informații document

Descriere originală:

Titlu original

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

C Builder Tutorial

Încărcat de

Drepturi de autor:

Formate disponibile

CBUILDER

User Defined Component Z

1 Using CBuilder to create a multiple input adder . . . . . . . . . . . . . . . 1.0

2 Using CBuilder to create an integrator . . . . . . . . . . . . . . . . . . . . . . . 2.0

3 Using CBuilder to create a variable capacitor . . . . . . . . . . . . . . . . . 3.0

4 Using CBuilder to model a multimass system . . . . . . . . . . . . . . . . 4.0

6 Using CBuilder with the PMU Shell component . . . . . . . . . . . . . . . 6.0

7 Using CBuilder to create a generator control block . . . . . . . . . . . . . 7.0

RTDS TECHNOLOGIES INC. 1.1

CREATE A NEW COMPONENT

S Start RSCAD and Launch Component Builder

S Save the component as tutorialc. You will see the following

RTDS TECHNOLOGIES INC. 1.2

CREATE THE REQUIRED PARAMETERS

New parameters will be added into the section that is selected.

A number of fields must be entered to define the new parameters.

Selecting the pin icon when adding the first parameter

RTDS TECHNOLOGIES INC. 1.3

When defining a parameter as type Toggle, the toggle

The sign of inputs 2 and 3 must also be added as parameters.

The copied parameters can now be modified. The parameter name

RTDS TECHNOLOGIES INC. 1.4

RTDS TECHNOLOGIES INC. 1.5

DRAW THE GRAPHICS

The goal is to draw a component icon that looks similar to below.

S Start by drawing the unconditional graphics. Ensure that the

S Select the Graphics tab

S Enter the condition sign1==0 in the box provided.

RTDS TECHNOLOGIES INC. 1.6

S Ensure the the new condition is selected. Any graphics added

S Select the Preview tab

RTDS TECHNOLOGIES INC. 1.7

ADD THE IO Points

In this example some of the IO points are conditional. Start by

S Select condition IO Points. Using the IO point tool, place a

S Repeat the above process for IO point fInput2 and fOutput.

RTDS TECHNOLOGIES INC. 1.8

S Select the condition If numInputs==3 and add the fInput3 IO

RTDS TECHNOLOGIES INC. 1.9

ADDING THE MODEL CODE

RTDS TECHNOLOGIES INC. 1.10

S Write the c code. Select the icon to edit the .c file.

fOutput = fInput1 + fInput2;

S After writing the c code, select the compile icon to

Draft has an internal memory of the components used during

RTDS TECHNOLOGIES INC. 1.11

SAMPLE C CODE FOR THE MULTIPLE INPUT ADDER

RTDS TECHNOLOGIES INC. 1.12

Initialize Xold= 0.0;

RTDS TECHNOLOGIES INC. 2.1

Draw an icon that looks similar to that below;

RTDS TECHNOLOGIES INC. 2.2

Select the C File Associations tab

Left click to create new C File Association

Write the c code. Select the icon to edit the .c file.

RTDS TECHNOLOGIES INC. 2.3

output = (input + input_old) * K + output_old;

RTDS TECHNOLOGIES INC. 2.4

Add shapes to the icon to include a reset input

Add an integer I/O point named reset to the reset input.

RTDS TECHNOLOGIES INC. 2.5

RTDS TECHNOLOGIES INC. 2.6