04 appendix

DIgSILENT PowerFactory

Appendix A: Glossary

B: Hotkeys References

D: Types Reference

C: Elements Reference

E: Reference to the use of Symbols in PowerFactory

F: Interfaces with Other Programs

G: The DIgSILENT Programming Language - DPL

H: DPL Reference

I: DSL Reference

Appendix A Glossary

Appliance

Base Case

Block Definition

Block Diagram

Branch Elements

Busbars

Class

Composite Frame

Composite Model

Cubicle

DAQ

Device

DGS

DOLE

DPL

Drag&Drop

DSL

DSL primitive

Edge Elements

Element

Graphics Board Window

Grid

Node

Object

Page Tab

Project

Result Object

Slot

Study Case

System Stage

Type

Virtual Instrument

Virtual Instrument Panel

Appliance

A specific physical, installed, power system component: a specific generator, transformer, busbar, etc. Example: a piece of NKBA 0.6/1kV 4 x 35sm cable, 12.4 meters long.

Base Case

A base case is the highest level in a tree of hierarchical system stage designs. It is the basic power system design, for which one or more alternative designs may be created and analyzed. The base case is always stored in a grid folder.

Block Definition

A block definition is a mathematical model which may be used in other block definitions or in a composite model. Examples are all default controllers (i.e. VCO's, PSS's, MDM's), and all additional user-defined DSL models. A block definition is called "primitive'' when it is directly written in DSL, or "complex'' when it is build from other block definitions, by drawing a block diagram.

Block Diagram

A block diagram is a graphical representation of a DSL model, i.e. a voltage controller, a motor driven machine model or a water turbine model. Block diagrams combine DSL primitive elements and block definitions created by drawing other block diagram.

The block models thus created may (again) be used in other block diagrams or to create a Composite Frame.

See also: DSL primitive , Composite Frame

Branch Elements

A one port element connected to a node, such as a load or a machine. See also nodes, edge elements.

Busbars

Busbars are particular representations of nodes. Busbars are housed in a Station folder and several busbars may be part of a station.

Class

DIgSILENT GmbH www.digsilent.de Tel: +49 (0)7072 9168-50 Fax: +49 (0)7072 [email protected]

of 150DIgSILENT PowerFactory

07/10/2011file://C:\Documents and Settings\sesa157733\Configuración local\Temp\~hh3EFB.htm

A class is a template for an element, type or other kind of objects like controller block diagrams, object filters, calculation settings, etc. Examples:

� The 'TypLne' class is the type model for all lines and cables

� The 'ElmLne' class is an element model for a specific line or cable

� The 'ComLdf' class is a load-flow command

� The 'EvtSwitch' class is an event for a switch to open or close during simulation

Composite Frame

A composite frame is a special block diagram which defines a new stand-alone model, mostly without in- or outputs. A composite frame is principally a circuit in which one or more slots are connected to each other.

A composite frame is used to create composite models by filling the slots with appropriate objects. The composite frame thus acts as template for a specific kind of composite models.

See also: Block Diagram , Slot

Composite Model

A composite model is a specific combination of mathematical models.These models may be power system elements such as synchronous generators, or block definitions, such as voltage controllers, primary mover models or power system stabilizers.

Composite models may be used to create new objects, such as protection devices, to 'dress-up' power system elements such as synchronous machines with controllers, prime movers models, etc., or for the identification of model parameters on the basis of measurements.

Cubicle

A cubicle is the connection point between a edge or branch element and a node (represented by a busbar or terminal). It may be visualized as a bay in a switch yard or a panel in a switchgear board. Elements such as CT's, protection equipment, breakers and so forth, are housed in the cubicle, as one would expect to find in reality.

DAQ

Abbreviation for "Data Acquisition''.

Device

A certain kind of physical power system components: certain synchronous machines, two-winding transformers, busbars, or other kinds of equipment. Example: a NKBA 0.6/1kV 4 x 35sm cable.

DGS

Abbreviation for "DIgSILENT Interface for Geographical Informations Systems''.

DOLE

Abbreviation for "DIgSILENT Object Language for Data Exchange''. DOLE was used in previous PowerFactory versions, but replaced by DGS meanwhile. Now, use DGS instead, please.

The DOLE import uses a header line with the parameter name. This header must have the following structure:

� The first header must be the class name of the listed objects.

� The following headers must state a correct parameter name.

DPL

Abbreviation for "DIgSILENT Programming Language''. For further information, please refer to Chapter G The DIgSILENT Programming Language - DPL .

Drag&Drop

"Drag&Drop'' is a method for moving an object by left clicking it and subsequently moving the mouse while holding the mouse button down ("dragging''). Releasing the mouse button when the new location is reached is called "dropping''. This will move the object to the new location.

DSL

Abbreviation for "DIgSILENT Simulation Language''. For further information, please refer to Chapter 25.9 The DIgSILENT Simulation Language (DSL) .

DSL primitive

A DSL primitive is the same as a primitive block definition. A DSL primitive is written directly in DSL without the use of a block diagram.

Examples are PID controllers, time lags, simple signal filters, integrators, limiters, etc. DSL primitives are normally used to build more complex block definitions.

See also: Block Definition , Block Diagram

Edge Elements

The elements between two nodes. May also be termed 'two port element.' Source, topological studies; picture a 3 dimensional box, the corners of the box would be called the nodes, and the edges between corners are hence 'edges.' See also nodes, branch elements.

Element

A mathematical model for specific appliances. Most element models only hold the appliance-specific data while the more general type-specific data comes from a type-reference. Example: a model of a piece of NKBA 0.6/1kV 4 x 35sm cable, 12.4 meters long, named "FC 1023.ElmLne".

Graphics Board Window

The graphics board window is a multi document window which contains one or more graphical pages. These pages may be single line graphics, virtual instrument pages, block diagrams etc.

The graphics board shows page tabs when more than one page is present. These tabs may be used to change the visible page or to change the page order by drag&drop on the page tab.

See also: Virtual Instrument , Block Diagram , Page Tab , Drag&Drop

Grid

A Grid is a collection of power system elements which are all stored in one so-called "Grid Folder'' in the database. Normally, a grid forms a logical part of a power system design, like a the MV distribution system in a province, or the HV transport system in a state.

Object

An object is a specific item stored in the database. Examples are specific type or element models which have been edited to model specific devices or appliances. Examples: the element "FC 1023.ElmLne", the type "NKBA_4x35.TypLne", the load-flow command "3Phase.ComLdf"

Node

The mathematical or generic description for what are commonly known as busbars in the electrical world. In PowerFactory nodes may be represented by "Busbars" or "Terminals" of various kinds. These are treated in the same manner in mathematical terms but treated slightly differently in the database. As far as possible the user should use terminals as Busbars can be somewhat inflexible. See also Busbars, Edge Elements, Branch Elements.

Page Tab

Page tabs are small indexes at the edge (mostly on the top or bottom) of a multi-page window. The tabs show the titles of the pages. Left-clicking the page tab opens the corresponding page. Page tabs are used in object dialogues, which often have different pages for different calculation functions, and in the Graphics Board Window, when more than one graphical page is present.

Project

All power system definitions and calculations are stored and activated in a project. The project folder therefore is a basic folder in the user's database tree. All grids that make out the power system design, with all design variants, study cases, commands, results, etc. are stored together in a single project folder.

Result Object

A result object keeps one or more lists of parameters which are to be monitored during a calculation. Results objects are used for building calculation result reports and for defining a virtual instrument.



See also: Virtual Instrument

Slot

A slot is a place-holder for a block definition in a composite frame. A composite model is created from a composite frame by filling one or more slots with an appropriate object.

See also: Block Definition , Composite Frame .

Study Case

A study case is a folder which stores a list of references or shortcuts to grid or system stage folders. These folders are (de)activated when the calculation case folder is (de)activated.

Elements in the grid folders that are referenced by the study case form the 'calculation target' for all calculation functions. Elements in all other, non-active, grid folders are not considered for calculation.

Besides the list of active folders, the calculation case also stores all calculations commands, results, events, and other objects which are, or have been, used to analyze the active power system.

See also: Grid , System Stage

System Stage

A system stage is an alternative design or variation for a particular grid. A system stage is stored in a system stage folder, which keeps track of all differences from the design in the higher hierarchical level. The highest level is formed by the base grid folder. It is possible to have system stages of system stages.

See also: Grid , Base Case

Type

A mathematical model for devices: general models for two-winding transformers, two-winding transformers, busbars, etc. A type model only contains the non-specific data valid for whole groups of power system elements. Example: a NKBA 0.6/1kV 4 x 35sm cable type, named "NKBA_4x35.TypLne"

See also: System Stage , Grid

Virtual Instrument

A virtual instrument is a graphical representation of calculation results. It may be a line or bar graph, a gauge, a vector diagram, etc. A virtual instrument gets its values from a result object.

See also: Result Object .

Virtual Instrument Panel

Virtual instrument panels are one of the possible types of pages in a graphics board window. Virtual instrument panels are used to create and show virtual instruments. Each virtual instrument panel may contain one or more virtual instruments.

See also: Graphics Board Window , Virtual Instrument

Appendix B Hotkeys References

Graphic Windows Hotkeys

Data Manager Hotkeys

Dialogue Hotkeys

Output Window Hotkeys

B.1 Graphic Windows Hotkeys



Combination Where/When Description

Alt + - Single Line Graphic, Block Diagrams, Vi's Zoom out

Alt + + Single Line Graphic, Block Diagrams, Vi's Zoom in

Alt + Rubberband Only textboxes inside the rubber band are marked, no parent objects

Alt + Left-click Textbox Textbox und Parent-Object are marked

Alt + Left-click Element All the connected elements will be marked

Ctrl + A All elements are marked

Ctrl + Alt + Shift + P Element Dialogue Save a screenshot of the complete monitor as bitmap under C:\Digsi\snapshots

Ctrl + Alt + Scrolling Marked Object Single Objects from a Busbar system can be moved

Ctrl + Alt + Scrolling Marked Busbar Single objects from a Busbar System can be increased or reduced (size)

Ctrl + Alt + Scrolling Block The stub length of blocks in block diagrams remains when shifting

Ctrl + Alt + Scrolling Marked Terminal Line-Routes will move to the terminal, instead of terminal to the line

Ctrl + Alt + Scrolling Marked Node Symbol of the connected branch element will not be centered

Ctrl + C Marked Element

Ctrl + L Single Line Graphic, Block Diagrams Will open the Define Layer dialogue to create a new layer

Ctrl +Left-click Element

Ctrl + Left-click Inserting Loads/Generators Rotate element 90°

Ctrl + Left-click Inserting Busbars/Terminals Rotate element 180°

Ctrl + M Element Dialogue Mark Element in the graphic

Ctrl + Q Single Line Graphic, Block Diagrams Open Graphic Layer dialogue

Ctrl + X Marked Element Cut

Esc Connecting Mode Interrupt the mode

Esc Inserting Symbol Interrupt and change to graphic cursor

Esc Animation Mode Interrupt mode

S + Left-click Element Mark only the symbol of the element

S + Scrolling Marked Element Move only the symbol of the element

Shift + Scrolling Marked Element Element can only be moved in the direction of axes

Shift + Scrolling Marked Textbox After rotation, textbox can be aligned in the direction of axes

Tab Inserting Symbol Jump to next connection



B.2 Data Manager Hotkeys

B.3 Dialogue Hotkeys

B.4 Output Window Hotkeys



Alt + F4 Close data manager

Alt + Return Right; Link Open the edit dialogue of the element

Backspace Jump one directory up

Pag ? Right Scroll a page up

Pag ? Right Scroll a page down

Ctrl + ? Edit dialogue open Call the edit dialogue of the next object from the list and closes the current dialogue

Ctrl + ? Edit dialogue open Call the edit dialogue of the previous object from the list and closes the current dialogue

Ctrl + A Right Mark all

Ctrl + Alt + P Save screenshot of the data manager as bitmap under C:\Digsi\snapshots

Ctrl + Alt + S Right; Project Open the share dialogue

Ctrl + Alt + Shift +

P Save screenshot of the complete monitor as bitmap under C:\Digsi\snapshots

Ctrl + B Detail-Modus Change to next tab

Ctrl + C Marked object, marked symbol Copy marked object

Ctrl + C Marked cell Copy the value of the marked cell

Ctrl + D Change between normal and detail mode

Ctrl + F Call the Filter dialogue

Ctrl + F7 Like Ctrl + R

Ctrl + G Right Go to line

Ctrl + I Right Call the dialogue Select Element, in order to insert a new object. The object class depends on the current position

Ctrl + Left-click Select the object

Ctrl + M Move the object

Ctrl + O Change between the display of out of service and no relevant objects for calculation

Ctrl + Q Right; station, Busbar or element with a connection

Close the station graphic

Ctrl + Q Right, element with more than one connection Call the dialogue Select Station, which lists all the connected stations

Ctrl + R Project Activate the project

Ctrl + R Study case Activate study case

Ctrl + R Grid Add the grid to the study case

Ctrl + R Variant Insert the variant to the current study case, if the corresponding grid is not in the study case

Ctrl + S Left

Ctrl + Shift + P

Ctrl + Tab Detail-Modus Change to next tab

Ctrl + V Insert the content of the clipboard

Ctrl + W Change the focus between right and left side

Ctrl + X Marked object, marked symbol Cut object

Ctrl + X Marked cell Cut cell content

End Right Jump to the last column of the current row

Del Right, symbol Delete marked object

Del Right, cell Delete the content of the cell

Esc Right; after change in the line Undo the change

F2 Right; cell Change to edit mode

F3 Close all opened dialogues to select an element

F4 Activate/Deactivate Drag&Drop-Mode

F5 Update

F8 Right, Graphic-Object Open the graphic

Pos1 Right Jump to the first column of the current row

Return Right Call the edit dialogue of the marked object

Return links Display or close the content of the marked object

Return Right; after change in the line Confirm changes

Return Right; link Call the edit dialogue of the original object

Shift + Left-click Select all the objects between the last marked object and the clicked row



Ctrl + A Input field Mark the content

Ctrl + Alt + P Save screenshot of the dialogue as bitmap under C:\Digsi\snapshots

Ctrl + Alt + Shift + P Save screenshot of the complete monitor as bitmap under C:\Digsi\snapshots

F1 Online help



Pag (up arrow) Page up

Pag (down arrow) Page down



Appendix C Elements Reference

2-Winding Transformers (ElmTr2/ElmTr2n)

3-Winding Transformer (ElmTr3)

Asynchronous Machine (ElmAsm)

Booster Transformer (ElmTrb)

Cable System (ElmCabsys)

Common Impedance (ElmZpu)

DC/DC Converter (ElmDcdc)

Doubly Fed Induction Machine (ElmAsmsc)

External Network (ElmXnet)

Line (ElmLne)

Line Sub-Section (ElmLnesec)

Load General (ElmLod)

Load Low Voltage (ElmLodlv)

Load Partial (ElmLodlvp)

Motor Driven Machine (ElmMdm__X )

Neutral Earthing Element (ElmNec)

PWM AC/DC Converter - 1 DC Connection (ElmVscmono)

PWM AC/DC Converter - 2 DC Connections (ElmVsc)

Rectifier/Inverter 1-DC Connection (ElmRecmono)

Rectifier/Inverter 2-DC Connection (ElmRec)

Series Capacitances (ElmScap)

Series Reactance (ElmSind)

Shunt/Filter Element (ElmShnt)

Soft Starter (ElmVar)

Static Generator (ElmGenstat)

Static Var System (ElmSvs)

Station Controller (ElmStactrl)

Synchronous Machine (ElmSym)

Tower Line Coupling (ElmTow)

AC Voltage Source (ElmVac)

DC Voltage Source (ElmVdc)

Current Measurement (StaImea)

Power Measurement (StaPqmea)

Voltage Measurement (StaVmea)

Digital Clock (ElmClock)

Fast Fourier Transform (ElmFft)

File Object (ElmFile)

Ctrl + A Mark the content of the output window

Ctrl + Alt + home

Ctrl + Pag (up arrow) Like Ctrl + Pos1

Ctrl + Pag (down arrow) Like Ctrl + End

Ctrl + C Copy the market report to the clipboard

Ctrl + E Open a new empty editor

Ctrl + End Set the cursor in the last position of the last row

Ctrl + F Open the Search and Replace dialogue

Ctrl + F3 Cursor in a Word Jump to previous same word

Ctrl + home

Ctrl + O Call the Open dialogue

Ctrl + P Call the Print dialogue

Ctrl + Arrow (up arrow) Page up

Ctrl + Arrow (down arrow) Page down

Ctrl + Pos1 Set the cursor in the first position of first row

Ctrl + Shift + End Set the cursor in the last position and marks the report in between

Ctrl + Shift + Pos1 Set the cursor in the first position and marks the report in between

End Set the cursor in the last position of the row

F3 Marked word Jump to next same word

F4 Debug-Mode

G Debug-Mode

H Debug-Mode

home

Arrow (up arrow) Set the cursor one line above

Arrow (right arrow) Set the cursor one position after

Arrow (down arrow) Set the cursor one line below

Arrow (left arrow) Set the cursor one position before

Pos1 Set the cursor to the first position of the row

Shift + Pag ? Set the cursor one page up and select the in between content

Shift + Pag ? Set the cursor one page down and select the in between content

Shift + F3 Cursor in a Word Jump to the next same word




Fourier Source (ElmFsrc)

Phase Measurement Device (Phase Locked Loop, ElmPhi__pll)

Digital Register (ElmReg)

Sample and Hold Model (ElmSamp)

Trigger Model (ElmTrigger)

C.1 2-Winding Transformers (ElmTr2/ElmTr2n)

Objects used to represent 2-winding, three or single phase transformers (autotransformers), require a reference to a TypTr2 object. If the option Auto Transformer is enabled, autotransformer winding connection instead of galvanic separation is used.

Input parameters

Table C.1 shows the input parameters for the ElmTr2 object, Table C.2 for the ElmTr2n. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the two winding transformers, presenting the relations among the input parameters is given in the attached technical referece papers: TechRef_2-W-Transformer_SinglePhase.pdf and TechRef_2-W-Transformer_3Phase.pdf.

Note: The name of the parameter is displayed in the Object edit dialogue, by placing the cursor in the input field of the parameter. Certain parameters are relevant to more than one calculation, therefore they can be found and edited in different tabs. The availability of some parameters is conditioned to the current value of the selection parameters (iopt_...); therefore not all the listed parameters would be visualized at once in a dialogue.


Table C.1: ElmTr2 Parameters Name Description Unit Range Default

loc_name Name _NameValid

root_id Original Location

fold_id In Folder

charact Charact.

chr_name Characteristic Name

for_name Foreign Key _ForKeyValid

dat_src Data source

outserv Out of Service x>=0&x<=1 0

typ_id Type

iZoneBus Zone 0

ntnum parallel Transformers x>0&x<100 0

nntap Tap Position 0

t2ldc Controlled Node x=0|x=1|x=2 0

ilcph Phase x>=0&x<=6 0

imldc Control Mode x[0]='V'|x[0]='P'|x[0]='Q '

ldcct Current Transformer Rating A 1.

ldcpt Voltage Transformer Ratio 1.

ldcrs Rset V 0.

ldcxs Xset V 0.

ntrcn Automatic Tap Changing x=1|x=0 0

ildc Line Drop Compensation (LDC) x>=0&x<=2 0

strf1 Load Current 0.

ratfac Rating Factor x>0 1.

ifrqft Frequent Fault ( >10(5)/lifetime, Category II(III) ) x=1|x=0 0

usetp Voltage Setpoint p.u. x>=0 1.

psetp Active Power Setpoint MW 0.

qsetp Reactive Power Setpoint Mvar 0.

i_cont Tap Changer x>=0&x<=1 0

usp_up Upper Voltage Bound p.u. 01. Jan

usp_low Lower Voltage Bound p.u. 0.99

psp_up Upper Active Power Bound MW 0.

psp_low Lower Active Power Bound MW 0.

qsp_up Upper Reactive Power Bound Mvar 0.

qsp_low Lower Reactive Power Bound Mvar 0.

tapctrl Tap Controller

re0tr_h Re Ohm x>=0 0.

xe0tr_h Xe Ohm x>=0 0.

re0tr_l Re Ohm 0.

xe0tr_l Xe Ohm x>=0 0.

iopt_hf Consider HF-Parameter x=0|x=1 0

Cg_h Capacitance HV-Ground uF x>=0 0.

Cg_l Capacitance LV-Ground uF x>=0 0.

Cc1_hl Capacitance HV-LV, 1-Sequence uF x>=0 0.


ifc Forced Cooling Enabled x=1|x=0 0

i_rem Remote Control x=0|x=1 0

p_rem Controlled Node

p_cub Controlled Branch (Cubicle)

i_auto Auto Transformer x=0|x=1 0

i_eahv HV-side, phase 2 internally grounded x>=0|x<=2 0

i_ealv LV-side, phase 2 internally grounded x>=0|x<=2 0

ignd_h Star Point x>=0|x<=2 0



ignd_l Star Point x>=0|x<=2 0

iintgnd External Star Point x=0|x=1 0

i_hvcon HV-side, phase 2 connected x=0|x=1 0

i_lvcon LV-side, phase 2 connected x=0|x=1 0

sernum Serial Number

constr Year of Construction 0

doc_id Additional Data

desc Description

pStoch Element model

iperfect Ideal component 0

iTaps According to Measurement Report x=0|x=1 0

iMeasLoc Measured at x=0|x=1 0

mTaps Measurement Report

i_uopt Tap Position 0

i_uoptCont Control Mode x=0|x=1 0

maxload Max. Loading % x>=0 100.

iOPFCload Max. Loading x=0|x=1 0

iblock Unit Transformer x=0|x=1 0

ilt_op Long-term operating conditions before short-circuit are known x=0|x=1 0

Ub_lv Highest Operating Voltage kV 0.

Ib_lv Highest Operating Current kA 0.

cosphib_lv Power factor 0.9

Ubqmin_hv Minimum Operating Voltage kV 0.

Tctrl Controller Time Constant s x>0 0.5

Kqctrl Controller Sensitivity dv/dQ %/Mvar x<0|x>0 0.1

Kpctrl Controller Sensitivity dv/dP %/MW x<0|x>0 0.1

pldc External LDC

i_tapini Estimate Tap Position 0

iIntTapCtrl Use Integrated Tap Controller x=0|x=1 0

dpl1 dpl1 0.

dpl2 dpl2 0.

dpl3 dpl3 0.

dpl4 dpl4 0.

dpl5 dpl5 0.

Table C.2: ElmTr2n Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


typ_id Type

iZoneBus Zone 0


nntap Tap Position 0

t2ldc Controlled Node x=0|x=1|x=2 0



ldcct Current Transformer Rating A 1.

ldcpt Voltage Transformer Ratio 1.

ldcrs Rset V 0.

ldcxs Xset V 0.



ratfac Rating Factor x>0 1.

ifrqft Frequent Fault ( >10(5)/lifetime, Category II(III) ) x=1|x=0 0




i_cont Tap Changer x>=0&x<=1 0

usp_up Upper Voltage Bound p.u. 01. Jan

usp_low Lower Voltage Bound p.u. 0.99






iopt_hf Consider HF-Parameter x=0|x=1 0

Cg_h Capacitance HV-Ground uF x>=0 0.

Cg_l Capacitance LV-Ground uF x>=0 0.




C.2 3-Winding Transformer (ElmTr3)

Object used to represent 3-phase, 3-winding transformers (or autotransformers), requires a reference to a TypTr3 object.

Input parameters

Table C.3 shows the input parameters for the ElmTr3 object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the 3-winding transformers, presenting the relations among the input parameters is given in the attached Technical Reference Paper.







i_auto Auto Transformer x=0|x=1 0

i_eahv HV-side, phase 2 internally grounded x>=0|x<=2 0

i_ealv LV-side, phase 2 internally grounded x>=0|x<=2 0




desc Description




iMeasLoc Measured at x=0|x=1 0


i_uopt Tap Position 0

i_popt Optimize Active Power Setpoint 0

i_qopt Optimize Reactive Power Setpoint 0


iblock Unit Transformer x=0|x=1 0

ilt_op Long-term operating conditions before short-circuit are known x=0|x=1 0

Ub_lv Highest Operating Voltage kV 0.

Ib_lv Highest Operating Current kA 0.

cosphib_lv Power factor 0.9

Ubqmin_hv Minimum Operating Voltage kV 0.




pldc External LDC


dpl1 dpl1 0.

dpl2 dpl2 0.

dpl3 dpl3 0.

dpl4 dpl4 0.

dpl5 dpl5 0.


Table C.3: ElmTr3 Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


typ_id Type

iZoneBus Zone 0

nt3nm parallel Transformers x>0&x<100 0





ictrlside for Tap at x>=0&x<=2 0



t3ldc Controlled Node x>=0|x<=3 0

n3tap_h Act. Position 0

n3tap_m Act. Position 0

n3tap_l Act. Position 0



n3rcn_h Automatic Tap Changing x=0|x=1 0

n3rcn_m Automatic Tap Changing x=0|x=1 0

n3rcn_l Automatic Tap Changing x=0|x=1 0

lodt3 Type Load

nt3rl Pointer to relais 0

usetp_h Voltage Setpoint p.u. x>=0 1.

usetp_m Voltage Setpoint p.u. x>=0 1.

usetp_l Voltage Setpoint p.u. x>=0 1.

psetp_h Active Power Setpoint p.u. 0.

psetp_m Active Power Setpoint p.u. 0.

psetp_l Active Power Setpoint p.u. 0.

qsetp_h Reactive Power Setpoint p.u. 0.

qsetp_m Reactive Power Setpoint p.u. 0.

qsetp_l Reactive Power Setpoint p.u. 0.

imldc_h Control Mode x[0]='V'|x[0]='P'|x[0]='Q '

imldc_m Control Mode x[0]='V'|x[0]='P'|x[0]='Q '

imldc_l Control Mode x[0]='V'|x[0]='P'|x[0]='Q '

t3ldc_h Controlled Node x>=0|x<=3 0

t3ldc_l Controlled Node x>=0|x<=3 0

t3ldc_m Controlled Node x>=0|x<=3 0

ratfac_h HV-Side x>0 1.

ratfac_m MV-Side x>0 1.

ratfac_l LV-Side x>0 1.








i_cont Tap Changer x=0|x=1 0

usp_up Upper Voltage Bound p.u. x>=0 01. Jan

usp_low Lower Voltage Bound p.u. x>=0 0.99





ignd_h Star Point x>=0|x<=2 0

ignd_m Star Point x>=0|x<=2 0

ignd_l Star Point x>=0|x<=2 0

i_auto_hl Auto Transformer x=0|x=1|x=2 0


i_cont_h Tap Changer x=0|x=1 0

i_cont_m Tap Changer x=0|x=1 0

i_cont_l Tap Changer x=0|x=1 0

re0h Re Ohm 0.

re0m Re Ohm 0.

re0l Re Ohm 0.

xe0h Xe Ohm 0.

xe0m Xe Ohm 0.

xe0l Xe Ohm 0.





desc Description



i_tapopt_l Tap Position LV-Side x=0|x=1 0

i_tapopt_h Tap Position HV-Side x=0|x=1 0

i_tapopt_m Tap Position MV-Side x=0|x=1 0

i_tapoptCont_l Control Mode LV-Side x=0|x=1 0

i_tapoptCont_h Control Mode HV-Side x=0|x=1 0

i_tapoptCont_m Control Mode MV-Side x=0|x=1 0




pldc External LDC

i_tapini_h Estimate Tap Position HV-Side 0

i_tapini_m Estimate Tap Position MV-Side 0

i_tapini_l Estimate Tap Position LV-Side 0



iMeasTap for Tap at x>=0&x<=2 0



C.3 Asynchronous Machine (ElmAsm)

Object used to represent asynchronous machine models, requires a reference to a TypAsmo or TypAsm (obsolete) object.

Input parameters

Table C.4 shows the input parameters of the ElmAsm object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the asynchronous machine model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.


C.4 Booster Transformer (ElmTrb)

Object used to represent booster transformers (3-phase), requires a reference to a TypTrb object.

Input parameters

Table C.5 shows the input parameters for the ElmTrb object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

iMeasLoc Measured at x>=0&x<=2 0


dpl1 dpl1 0.

dpl2 dpl2 0.

dpl3 dpl3 0.

dpl4 dpl4 0.

dpl5 dpl5 0.


Table C.4: ElmAsm Parameters Name Description Unit Range Default

loc_name Name NameValid


fold_id In Folder

charact Charact.


for_name Foreign Key ForKeyValid

dat_src Data source


typ_id Type

monof Operation Mode x=0|x=1 0

ngnum parallel Machines x>0&x<100 0

pgini Active Power MW x>=0 0.

qgini Reactive Power Mvar 0.

bustp Bus Type

i_mot Generator/Motor 0

mdmex Exponent x>=0 2.

mdmlp Proportional Factor p.u. x>=0&x<=100 1.

tstart Starting Time s x>=0 0.

iconfed Static converter-fed drive x=0|x=1 0



i_pset Estimate Active Power x=0|x=1 0




desc Description

iAstabint A-stable integration algorithm x=0|x=1 0

ignd Star Point x=0|x=2 0


Xe Xearth Ohm x>=0 0.

Re Rearth Ohm x>=0 0.

iUseStart Use Motor Starting Method x=0|x=1 0

iStartMethod Motor Starting Method x>=0&x<=2 0

Tyd Switch to 'D' after s x>=0 0.5

mdTradd Variable Rotor Resistance

idfig Doubly Fed Induction Machine x=0|x=1 0

dpl1 dpl1 0.

dpl2 dpl2 0.

dpl3 dpl3 0.

dpl4 dpl4 0.

dpl5 dpl5 0.




The description of the booster transformers, presenting the relations among the input parameters is given in the attached Technical Reference Paper.


C.5 Cable System (ElmCabsys)

Object used to represent a system of electromagneticaly coupled cables.

Input parameters

Table C.6 shows the input parameters for the ElmCabsys object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the cable system, presenting the relations among the input parameters and the required types is given in the attached Technical Reference Paper.


C.6 Common Impedance (ElmZpu)

The Common Impedance is a per unit impedance model including an ideal transformer. The main usage is for branches used for network reduction.

Input parameters

Table C.7 shows the input parameters for the ElmZpu object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the common impedance model, presenting the relations among the input parameters is given in the attached Technical Reference Paper..

Note: The name of the parameter is displayed in the object edit dialogue, by placing the cursor in the input field of the parameter. Certain parameters are relevant to more than one calculation, therefore they can be found and edited in different tabs. The availability of some parameters is conditioned to the current value of the selection parameters (iopt_...); therefore not all the listed parameters would be visualized at once in a dialogue

Table C.5: ElmTrb Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


typ_id Type

iZoneBus Zone 0




desc Description


re0tr_l Re Ohm 0.

xe0tr_l Xe Ohm x>=0 0.


Table C.6: ElmCabsys Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


typ_id Cable Definition

desc Description

plines Circuit ElmLne,ElmLneroute

dpolar Polarity

i_dist Line Model x=0|x=1 0

c_dist Distributed Parameter 0

c_lumped Lumped Parameter (PI) 0

tmat Transformation Matrix Tv

pzs Surge Impedance Ohm

pa Wave Propagation

pTa Travel Time s

ftau Frequency for Parameter Approximation Hz x>0 100000.


Table C.7: ElmZpu Parameters Name Description Unit Range Default

name Name _NameValid


fold_id In Folder



C.7 DC/DC Converter (ElmDcdc)

The description of the DC/DC converter model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.

C.8 Doubly Fed Induction Machine (ElmAsmsc)

Object used to represent doubly fed induction generators, requires a reference to a TypAsmo object.

Input parameters

Table C.8 shows the input parameters of the ElmAsm object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the double feed asynchronous machine model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.


charact Charact.



dat_src Data source


iZoneBus Zone 0

Sn Nominal Power MVA x>=0 1.

nphases Phases x=1|x=3 0

iequalz Use equal Impedances (zij = zji) x=0|x=1 0

iz2eqz1 Use Impedance z2 = z1 x=0|x=1 0

r_pu Real Part p.u. 0.

x_pu Imaginary Part p.u. 0.

r_pu_ji Real Part p.u. 0.

x_pu_ji Imaginary Part p.u. 0.

r0_pu Real Part p.u. 0.

x0_pu Imaginary Part p.u. 0.

r0_pu_ji Real Part p.u. 0.

x0_pu_ji Imaginary Part p.u. 0.

r2_pu Real Part p.u. 0.

x2_pu Imaginary Part p.u. 0.

r2_pu_ji Real Part p.u. 0.

x2_pu_ji Imaginary Part p.u. 0.

iZshc Use same impedance as for loadflow x=0|x=1 0

rs_pu Real Part p.u. 0.

xs_pu Imaginary Part p.u. 0.

rs_pu_ji Real Part p.u. 0.

xs_pu_ji Imaginary Part p.u. 0.

r0s_pu Real Part p.u. 0.

x0s_pu Imaginary Part p.u. 0.

r0s_pu_ji Real Part p.u. 0.

x0s_pu_ji Imaginary Part p.u. 0.

r2s_pu Real Part p.u. 0.

x2s_pu Imaginary Part p.u. 0.

r2s_pu_ji Real Part p.u. 0.

x2s_pu_ji Imaginary Part p.u. 0.


manuf Manufacturer



desc Description

dpl1 dpl1 0.

dpl2 dpl2 0.

dpl3 dpl3 0.

dpl4 dpl4 0.

dpl5 dpl5 0.



Table C.8: ElmAsmsc Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source



C.9 External Network (ElmXnet)

Object used to represent external networks.

Input parameters

Table C.9 shows the input parameters for the ElmXnet object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the external network model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.



typ_id Type

monof Operation Mode x=0|x=1 0

ngnum parallel Machines x>0&x<100 0

pgini Active Power MW x>=0 0.



mdmex Exponent x>=0 2.

mdmlp Proportional Factor p.u. x>=0&x<=100 1.

tstart Starting Time s x>=0 0.




desc Description

slipset Slip % x>-100&x<100 0.5

Urot Rated Slip Ring Voltage V x>0 1.

rcrow Crow-Bar Resistance p.u. x>=0 0.

xcrow Crow-Bar Reactance p.u. x>=0 0.

i_conv Use Integrated PWM Converter x=0|x=1 0

i_ctrl Use Built-In Current Controller x=0|x=1 0

i_feedback Rotor Flux Feed-Back x=0|x=1 0

cv Cv x>=0 0.

Pmmax Max Pulse Width Modulation Index x>0 1.

Kd Kd 0.1

Kq Kq 0.1

Td Td s 0.01

Tq Tq s 0.01

p_pctrl Controlled Flow



Xe Xearth Ohm x>=0 0.

Re Rearth Ohm x>=0 0.


Table C.9: ElmXnet Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


bustp Bus Type

pgini Active Power MW 0.


sgini Apparent Power MVA x>=0 0.

cosgini Power Factor x>=-1&x<=1 0.

snss Short-Circuit Power Sk''max MVA x>0 10000.

rntxn R/X Ratio (max.) x>=0 0.1

xntrn X/R Ratio (max.) x>=0 10.

cmax c-Factor (max.) x>0 01. Jan

cmin c-Factor (min.) x>0 1.

cused Use for calculation x=0|x=1 0

z2tz1 Z2/Z1 max. x>=0 1.

z0tz1 Z0/Z1 max. x>=0 1.

x0tx1 X0/X1 max. x>=0 1.

r0tx0 R0/X0 max. x>=0 0.1


ignd Star Point x>=0|x<=2 0

Re Grounding Resistance



C.10 Line (ElmLne)

The ElmLne is used to represent transmission lines/cables, it requires a reference to a TypLne or a TypTow object. The ElmLne can contain line sections as presented in Section 10.1.9 Defining and Working with Transmission Lines .

Input parameters

Table C.10 shows the input parameters for the ElmLne object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the line model, presenting the relations among the input parameters and the posible types is given in the attached Technical Reference Paper.


Ohm 0.

Xe Grounding Reactance Ohm 0.

fdsymr Resistance R=R(freq) [A-Z] _FrqDepValid

fdsyml Reactance L=L(freq) [A-Z] _FrqDepValid


ip_ctrl Secondary Controller (Slack) x=0|x=1 0

iv_mode Voltage Controller Mode x=0|x=1 0

phiini Angle deg x>=-180&x<=180 0.

tag Acceleration Time Constant s x>0 99.

K Secondary Frequency Bias MW/Hz x>=0 0.

desc Description

snssmin Short-Circuit Power Sk''min MVA x>0 8000.

rntxnmin R/X Ratio (min.) x>=0 0.1

xntrnmin X/R Ratio (min.) x>=0 10.

z2tz1min Z2/Z1 min. x>=0 1.

z0tz1min Z0/Z1 min. x>=0 1.

x0tx1min X0/X1 min. x>=0 1.

r0tx0min R0/X0 min. x>=0 0.1

MaxS Max. Power MW x>=0 100000.

ecost Energy Cost $/kWh x>0 0.05

p_uctrl Reference Busbar

cmonth No load costs (monthly) $/M 0.

cpower From MW

ccost Costs $/MWh

ictpg Active Power x=0|x=1 0

ictqg Reactive Power x=0|x=1 0

iOPFCPmin Min. x=0|x=1 0

iOPFCPmax Max. x=0|x=1 0

iOPFCQmin Min. x=0|x=1 0

iOPFCQmax Max. x=0|x=1 0

q_min Min. Mvar 0.

q_max Max. Mvar 100.

Pmin_uc Minimum Power MW 0.

round Smoothing of Cost Function % x>=0.0&x<=100.0 5.

Kpf Primary Frequency Bias MW/Hz 0.

dpl1 dpl1 0.

dpl2 dpl2 0.

dpl3 dpl3 0.

dpl4 dpl4 0.

dpl5 dpl5 0.

Pctrl Active power steps 0

i_prty Priority x>=0 0

mode_inp Input Mode


Table C.10: ElmLne Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


typ_id Type

iZoneBus Zone 0

nlnum parallel Lines x>=1 0

dline Length of Line km x>=0 1.

fline Derating Factor x>=0 1.

Top Operating Temperature degC 20.

inAir Laying x=0|x=1 0



C.11 Line Sub-Section (ElmLnesec)

Object used to represent sections of lines or cables. It can refer to any of the types defined for transmission lines or cables (TypLne, TypTow, TypGeo).

Input parameters

Table C.11 shows the input parameters for the ElmLnesec object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the line route model, presenting the relations among the input parameters and the required types is given in the attached Technical Reference Paper.


nlsim Enable for Contingency Analysis x=0|x=1 0

ishclne Available x=0|x=1 0

fshcloc Short-Circuit Location % x>=0&x<=100 50.

lodln Type of Load

lprot Protection Devices

slin1 Load Current/Nom.Current p.u. x>=0 0.


pCondCir Type of Phase Conductors

pCondGnd Type of Earth Conductors

pCondN Type of Neutral Conductors

sagCir Max.Sag, Phase Conductors m x>=0 0.

sagGnd Max.Sag, Ground Wires m x>=0 0.

ktrto Transposition x=0|x=1 0

rearth Earth Resistivity Ohmm x>=0 100.

i_model Line Model x=0|x=1 0

kz1 Surge Impedance, HF, Mode 1. Ohm x>0 50.

pz1 Poles,Mode 1 Hz

zz1 Zeros, Z1 Hz

kz0 Surge Impedance, HF, Mode 0 Ohm x>0 50.

pz0 Poles, Mode 0 Hz

zz0 Zeros, Zl0 Hz

kz2 Surge Impedance, HF, Mode 2. Ohm x>0 50.

pz2 Poles,Mode 2 Hz

zz2 Zeros, Z2 Hz

ka1 Wave Propagation Constant. p.u. x>0 1.

a1dc Wave Propagation, DC, Mode 1 p.u. x>0 1.

Ta1 Travel Time, Mode 1 s x>0 0.001

pa1 Poles, A1 Hz

za1 Zeros, A1 Hz

ka0 Wave Propagation Constant p.u. x>0 1.



pa0 Poles, A0 Hz

za0 Zeros, A0 Hz

ka2 Wave Propagation Constant. p.u. x>0 1.



pa2 Poles, A2 Hz

za2 Zeros, A2 Hz

fmin Min. Frequency of Parameter Fitting Hz x>0 0.001

fmax Max. Frequency of Parameter Fitting Hz x>0 1000000.

ftau Frequency for Travel-Time Estimation Hz x>0 100000.

tolBode Tolerance for Bode Approximation % x>0 5.

tmat Transformation Matrix

cubsecs Routes/Cubicles/Sections




desc Description

NrCust Number of connected customers x>=0 0

i_ldlv Line Load x=0|x=1 0





dpl1 dpl1 0.

dpl2 dpl2 0.

dpl3 dpl3 0.

dpl4 dpl4 0.

dpl5 dpl5 0.


Table C.11: ElmLnesec



C.12 Load General (ElmLod)

Object used to represent load models. Requires a reference to a TypLod object for general loads and a TypLodind object for complex loads.

Input parameters

Table C.12 shows the input parameters of the ElmLod object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the general load model, presenting the relations among the input parameters, is given in the attached Technical Reference Paper of TypLod. The description of the complex load model is given in the Technical Reference Paper of TypLodind.


Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


typ_id Type

dline Length km x>=0 0.

fline Derating Factor x>=0 1.

inAir Laying x=0|x=1 0

index Index 0.




desc Description




Table C.12: ElmLod Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


typ_id Type

plini Active Power MW 0.

qlini Reactive Power Mvar 0.

plinir Active Power MW 0.

qlinir Reactive Power Mvar 0.

plinis Active Power MW 0.

qlinis Reactive Power Mvar 0.

plinit Active Power MW 0.

qlinit Reactive Power Mvar 0.

scale0 Scaling Factor 1.

i_sym Balanced/Unbalanced x=0|x=1 0

mode_inp Input Mode




desc Description

u0 Voltage p.u. x>0 1.

phmc Harmonic Currents

pSCDF Time dependent rate

fSCDF Scaling factor 1.

OptCost Unit 0

NrCust Number of connected customers x>0 0

i_prty Load priority 0

shed Shedding steps 0

trans Transferable % x>=0.0&x<=100.0 0.

pTrans Alternative Supply (Load)

i_scale Adjusted by Feeder Load Scaling x=0|x=1 0

i_pini Estimate Active Power x=0|x=1 0

i_qini Estimate Reactive Power x=0|x=1 0




C.13 Load Low Voltage (ElmLodlv)

Object used to represent loads at low voltage level.

Input parameters

Table C.13 shows the input parameters for the ElmLodlv object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the low voltage load model, presenting the relations among the input parameters and the required types is given in the attached Technical Reference Paper.


C.14 Load Partial (ElmLodlvp)

Object used to represent partial loads.

Input parameters


i_scaleini Estimate Scaling Factor x=0|x=1 0

iShedding Allow load shedding x=0|x=1 0

shedcost Costs for load shedding $/MVA 1.

shedmax Max. load shedding % x>=0.0&x<=100.0 100.

shedmin Min. load shedding % x>=0.0&x<=100.0 0.

dpl1 dpl1 0.

dpl2 dpl2 0.

dpl3 dpl3 0.

dpl4 dpl4 0.

dpl5 dpl5 0.


Table C.13: ElmLodlv Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


typ_id Type

lodparts Add. Loads

plini Active Power, P kW x>=0 0.

slini Apparent Power, S kVA x>=0 0.

coslini Power Factor, cos(phi) x>=0&x<=1 0.

ulini Voltage, U(L-L) kV x>0 0.4

ilini Current, I A x>=0 0.

pf_recap Power Factor x=0|x=1 0

pnight P kW x>=0 0.

NrCust Number of Customers x>=0 0

iopt_inp Load Type x>=0&x<=3 0

scale0 Scaling Factor 1.

i_scale Adjusted by Load Scaling x=0|x=1 0

nphase No. of Phases x>=1|x<=3 0





desc Description

pSCDF Time dependent rate

fSCDF Scaling factor 1.

OptCost Unit 0

i_prty Load priority 0

shed Shedding steps 0

trans Transferable % x>=0.0&x<=100.0 0.

pTrans Alternative Supply (Load)

dpl1 dpl1 0.

dpl2 dpl2 0.

dpl3 dpl3 0.

dpl4 dpl4 0.

dpl5 dpl5 0.




Table C.14 shows the input parameters for the ElmLodlvp object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the partial load model, presenting the relations among the input parameters and the required types is given in the attached Technical Reference Paper.


C.15 Motor Driven Machine (ElmMdm__X )

Objects used to represent motor driven machines. Three types of driven machine models are defined in PowerFactory: ElmMdm__1 (Type 1), ElmMdm__3 (Type 3) and ElmMdm__5 (Type 5). All types of motor driven machine models may be used in connection with a synchronous or an asynchronous motor.

Input parameters

Tables C.15, C.16 and C.17 show the input parameters for the defined motor driven machine types. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the motor driven machine models, presenting the relations among the parameters and the connection to a motor, are given in the attached Technical Reference Paper..

Note: The name of the parameter is displayed in the Object edit dialogue, by placing the cursor in the input field of the parameter. Certain parameters are relevant to more than one calculation, therefore they can be found and edited in different tabs. The availability of some parameters is conditioned to the current value of the selection parameters (iopt_...); therefore not all the listed parameters would be visualized at once in a dialogue

Table C.14: ElmLodlvp Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


typ_id Type

plini Active Power, P kW x>=0 0.

slini Apparent Power, S kVA x>=0 0.

coslini Power Factor, cos(phi) x>=0&x<=1 0.

ulini Voltage, U kV x>0 0.4

ilini Current, I A x>=0 0.

pf_recap Power Factor x=0|x=1 0

pnight P kW x>=0 0.

NrCust Number of Customers x>=0 0

iopt_inp Load Type x>=0&x<=3 0

lnepos Position on Line % x>=0&x<=100 50.




desc Description


Table C.15: ElmMdm__1 Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


typ_id Type

mdmex mdmex;Exponential factor 0.

mdmlp mdmlp;Proportional factor p.u. 0.




fold_id In Folder

charact Charact.



dat_src Data source

outserv Out of Service x>=0&x<=1 0.

typ_id Type

alf1 alf1;Torque at synchronous speed p.u. 0.

slipm slipm;Slip at min. torque p.u. 0.

exp1 exp1;Exponent of first polynom. function 0.

alf2 alf2;Torque at standstill p.u. 0.

exp2 exp2;Exponent of second polynom. function 0.

xkmm xkmm;Torque at slip = Slipm (min. torque) p.u. 0.



C.16 Neutral Earthing Element (ElmNec)

The NEC/NER (Neutral Earthing Conductor/Neutral Earthing Reactor) is the grounding element in PowerFactory, does not require any type.

Input parameters

Table C.18 shows the input parameters for the ElmNec object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the NEC/NER model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.





fold_id In Folder

charact Charact.



dat_src Data source


typ_id Type

speed Speed p.u.

torque Torque p.u.

load Load p.u. x>=0 1.

nkoor nkoor;Number of used coordinates (speed) 0.

x1 x1;X-axis coordinates (speed) p.u. 0.

y1 y1;Y-axis coordinates (torque) p.u. 0.






























Table C.18: ElmNec Parameters DisplayName Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


Unom Rated Voltage kV x>0 1.

Curn Rated Current (Ie=3*I0) kA x>0 0.1

Ithlim Rated Short-Time Thermal Current (3*I0) kA x>0 1.

Tkr Rated Short-Circuit Duration s x>0 1.

ignd Star Point x>=0|x<=1 0

R0 Zero Sequence Resistance Ohm 0.



C.17 PWM AC/DC Converter - 1 DC Connection (ElmVscmono)

Object used for a PWM converter model. Represents a self-commutated, voltage sourced AC/DC converter (capacitive DCcircuit).

Input parameters

Table C.19 shows the input parameters of the ElmVscmono object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the PWM converter model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.


X0 Zero Sequence Reactance Ohm 0.

Re Grounding Resistance Ohm 0.

Xe Grounding Reactance Ohm 0.

fcharR0 Frequency Dependency R0

fcharL0 Frequency Dependency L0

fcharRe Frequency Dependency Re

fcharLe Frequency Dependency Le


manuf Manufacturer



desc Description


Table C.19: ElmVscmono Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


Unom Rated AC-Voltage kV x>0 1.

Unomdc Rated DC-Voltage (DC) kV x>0 1.

Snom Rated Power MVA x>0 1.

usetp AC Voltage Setpoint p.u. x>0.0 1.

usetpdc DC Voltage Setpoint p.u. x>0.0 1.

phisetp Phase Setpoint deg 0.



p_phictrl Controlled Node

p_uctrl Controlled Node (AC)

p_uctrldc Controlled Node (DC)


p_qctrl Controlled Flow

i_acdc Control Mode x>=0&x<=6 0

pmsetp PWM Factor p.u. 0<=x 1.

pmd_max Upper Limit of Pmd p.u. 0<=x&x<=1 1.

pmd_min Lower Limit of Pmd p.u. 0<=x&x<=1 0.

pmq_max Upper Limit of Pmq p.u. 0<=x&x<=1 1.

pmq_min Lower Limit of Pmq p.u. 0<=x&x<=1 0.

phmc Harmonic Injections

i_mod Modulation x=0|x=1|x=2 0

fmod Modulation Frequency Hz 10000.

Ron Transistor/Diode On-Resistance Ohm x>0 0.0001

Goff Transistor/Diode Off-Conductance uS x>=0 0.001

Cvalve Snubber Capacitance uF x>0 0.1

Gvalve Snubber Conductance S x>=0 0.

i_det Model x=0|x=1 0

i_ctrl Use Integrated Current Controller x=0|x=1 0

uk Short Circuit Impedance % x>=0 0.

Pcu Copper Losses kW x>=0 0.

Pnold No-Load Losses kW x>=0 0.

Cdc DC-Capacitance (not in use) uF x>=0 0.

Kd Kd 0.1

Kq Kq 0.1

Td Td s 0.01

Tq Tq s 0.01

q_max Max. p.u. 1.

q_min Min. p.u. -1.



C.18 PWM AC/DC Converter - 2 DC Connections (ElmVsc)

Object used for a PWM converter model. Voltage sourced AC/DC converter with 2-DC connections.

Input parameters

Table C.20 shows the input parameters of the ElmVsc object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the converter model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.


C.19 Rectifier/Inverter 1-DC Connection (ElmRecmono)

Rectifier model with a sigle DC connection, requires a reference to a TypRec object.

Input parameters

Table C.21 shows the input parameters for the ElmRecmono object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the rectifier model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.



manuf Manufacturer



desc Description


ictrltp Model x>=0&x<=2 0



Table C.20: ElmVsc Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


Unom Nominal Voltage (AC) kV x>0 1.

Unomdc Nominal Voltage (DC) kV x>0 1.

Snom Nominal Power MVA x>0 1.

usetp Voltage Setpoint p.u. x>0.0 1.

phisetp Phase Setpoint deg 0.



p_phictrl Controlled Node

p_uctrl Controlled Node


p_qctrl Controlled Flow

i_acdc Control Mode x>=0&x<=5 0

pmsetp PWM Factor p.u. 0<=x 1.

pmd_max Upper Limit of Pmd p.u. 0<=x&x<=1 1.

pmd_min Lower Limit of Pmd p.u. 0<=x&x<=1 0.

pmq_max Upper Limit of Pmq p.u. 0<=x&x<=1 1.

pmq_min Lower Limit of Pmq p.u. 0<=x&x<=1 0.

phmc Harmonic Voltages

i_mod Modulation x=0|x=1|x=2 0

fmod Modulation Frequency 10000.

Ron Transistor/Diode On-Resistance Ohm x>0 0.0001

Goff Transistor/Diode Off-Conductance myS x>=0 0.001

i_det Model x=0|x=1 0


manuf Manufacturer



desc Description


ictrltp Model x>=0&x<=2 0





C.20 Rectifier/Inverter 2-DC Connection (ElmRec)

Rectifier model with 2-DC connections, requires a reference to a TypRec object.

Input parameters

Table C.22 shows the input parameters for the ElmRec object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).



Table C.21: ElmRecmono Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


typ_id Type




desc Description

uset Voltage Setpoint p.u. 1.

pset Power-Setpoint p.u. 1.

Pset Power-Setpoint MW 1.

Qset Reactive Power-Setpoint Mvar 1.

Iset Current Setpoint kA x>0 1.

Xd Commutation Reactance Ohm x>=0 0.

mode Orientation (Rectifier/Inverter) *x='R'|*x='I '

bstp Control-Characteristic *x='V'|*x='I'|*x='P'|*x='Q'|*x='E'|*x='G '

alpha_set Actual Firing-Angle deg 0<=x&x<=180 15.

gamma_set Extinction Angle (gamma) Setpoint deg 0<=x&x<=180 15.

ntrcn Tap-Changer x=0|x=1|x=2 0

nntap Actual Winding Ratio p.u. x>0 1.

alphacn Automatic Firing Angle Control x=0|x=1 0

pctrl Controller


i_int Ideal Rectifier x=0|x=1 0

maxorder Maximum Harmonic Order x>0 0

i_cv Current/Voltage-Source Converter x=0|x=1 0

alphamin Minimum Firing Angle deg 0<=x&x<=180 0.

alphamax Maximum Firing Angle deg 0<=x&x<=180 180.

gammamin Minimum Extinction Angle deg 0<=x&x<=180 0.

gammamax Maximum Extinction Angle deg 0<=x&x<=180 180.

nt2ag Phase Shift *30deg x>=0&x<12 0




Table C.22: ElmRec Parameters Name Description Unit Default

loc_name Name


fold_id In Folder

charact Charact.


for_name Foreign Key

dat_src Data source

outserv Out of Service 0

typ_id Type




desc Description

uset Voltage Setpoint p.u. 1.

pset Power-Setpoint p.u. 1.

Pset Power-Setpoint MW 1.

Qset Reactive Power-Setpoint Mvar 1.

Iset Current Setpoint kA 1.

Xd Commutation Reactance Ohm 0.

mode Orientation (Rectifier/Inverter)

bstp Control-Characteristic



C.21 Series Capacitances (ElmScap)

The ElmScap object represents series capacitances in PowerFactory. It can be used for various applications, e.g.

� Series compensation of transmission lines

� Filter capacitance

Input parameters

Table C.23 shows the input parameters of the ElmScap object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the Series Capacitance model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.


alpha_set Actual Firing-Angle deg 15.

gamma_set Extinction Angle (gamma) Setpoint deg 15.

ntrcn Tap-Changer 0

nntap Actual Winding Ratio p.u. 1.

alphacn Automatic Firing Angle Control 0

pctrl Controller


i_int Ideal Rectifier 0

maxorder Maximum Harmonic Order 0

i_cv Current/Voltage-Source Converter 0

alphamin Minimum Firing Angle deg 0.

alphamax Maximum Firing Angle deg 180.

gammamin Minimum Extinction Angle deg 0.

gammamax Maximum Extinction Angle deg 180.

nt2ag Phase Shift *30deg 0

iAstabint A-stable integration algorithm 0

iconfed Static converter-fed drive 0


Table C.23: ElmScap Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


iZoneBus Zone 0

ucn Rated Voltage kV x>=0 1.


xcap Reactance 1/B Ohm x>=0 0.

bcap Susceptance, B S x>=0 0.

ccap Capacitance, C F x>=0 0.

Imov1 MOV Current 1 kA x>=0 0.

Vmov1 MOV Voltage 1 kV x>=0 0.

Imov2 MOV Current 2 kA x>=0 0.

Vmov2 MOV Voltage 2 kV x>=0 0.

Curn Rated Current kA x>0 1.

Sn Rated Power MVA x>0 173.205

i_enter Metal Oxid Varistor x=0|x=1 0

Im Current kA

Vm Voltage kV


manuf Manufacturer



desc Description

systp System Type x=0|x=1 0


iInterPol Interpolation x=0|x=1 0

smoothfac Smoothing Factor % x>=0.0&x<=100.0 10.




C.22 Series Reactance (ElmSind)

The ElmSind object represents series reactances in PowerFactory.

Input parameters

Table C.24 shows the input parameters for the ElmSind object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the series reactance model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.


C.23 Shunt/Filter Element (ElmShnt)

The ElmShnt object is used to represent different shunt connection types.

Input parameters

Table C.25 shows the input parameters for the ElmShnt object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the shunt/filter model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.


Table C.24: ElmSind Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


iZoneBus Zone 0

ucn Rated Voltage kV x>0 6.


Curn Rated Current kA x>0 0.096225

Sn Rated Power MVA x>0 1.

uk Short-Circuit Voltage uk % x>=0 0.

ukr Short-Circuit Voltage (Re(uk)) ukr % x>=0 0.

Pcu Copper Losses kW x>=0 0.

Zd Impedance (absolute) Zd Ohm x>=0 0.

xrea Reactance, X Ohm x>=0 0.

lrea Inductance, L mH x>=0 0.

rrea Resistance, R Ohm x>=0 0.


manuf Manufacturer



desc Description




Table C.25: ElmShnt Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source

outserv Out of Service x>=0&x<=1 0,00

ushnm Nominal Voltage kV x>0 6.

nshph Phases x>=1&x<=3 0,00

iintgnd External Star Point x=0|x=1 0,00

ignd Star Point x>=0|x<=2 0,00

nbsph of Phase

imldc Control Mode x[0]='V'|x[0]='Q'|x[0]='P '

ilcph Phase x>=0&x<=6 0,00

iQorient Orientation x=0|x=1 0,00

ncapx Max. No. of Steps x>0 0,00

ncapa Act.No. of Step x>=0 0,00

shtype Shunt Type x=0|x=1|x=2|x=3|x=4 0,00

capsa Vector Group

qcapn Rated Reactive Power, C Mvar x>=0 0.96

qtotn Rated Reactive Power, L-C Mvar x>=0 1.

cucap Rated Current, C A x>=0 0.



C.24 Soft Starter (ElmVar)

The ElmVar object is used to represent voltage control, soft starter devises for induction motors. The ElmVar does not require a type object.

Input parameters

Table C.26 shows the input parameters for the ElmVar object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the soft starter model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.


cutot Rated Current, L-C A x>=0 96224998,00

bcap Susceptance uS x>=0 26666699219,00

ccap Capacitance uF x>=0 84882599,00

c1 Capacitance C1 uF x>=0 0.

c2 Capacitance C2 uF x>=0 84882599,00

pgrad Degree % x>=0&x<=100 4.

fres Resonance Frequency Hz x>=0 250.

nres Tuning Order x>=0 5.

qrean Rated Reactive Power, L Mvar x>=0 24.

curea Rated Current, L A x>=0 2309399902,00

xrea Reactance Ohm x>=0 39203,00

rlrea Inductance mH x>=0 477465,00

grea Quality Factor (at fn) x>=0 0.

greaf0 Quality Factor (at fr) x>=0 0.

rrea Resistance Ohm x>=0 0.

rpara Parallel Resistance Ohm x>=0 0.

tandc Loss Factor, tan(delta) x>=0 0.

gparac Parallel Conductance uS x>=0 0.

fcharL L(f)

fcharR R(f)

fcharC C(f)

shuz0 Z0/Z1 x>=0 0.

i_opt Use Controller for OPF optimization x=0|x=1 0,00

i_optCont Control Mode x=0|x=1 0,00

systp System Type x=0|x=1 0,00

Bg Susceptance to Ground nS x>=0 0.

Xe Reactance, Xe Ohm x>=0 0.

Re Resistance, Re Ohm x>=0 0.

acost Annual Cost $/year x>=0 0.

iswitch Switchable x>=0&x<=1 0,00


manuf Manufacturer

constr Year of Construction 0,00


desc Description

i_rem Remote Control x=0|x=1 0,00




Kctrl Controller Sensitivity dq/dv p.u./% x>0&x<1 0.1

usetp_mx Upper Voltage Limit p.u. x>0 39203,00

usetp_mn Lower Voltage Limit p.u. x>0 0.95

qsetp_mx Upper Reactive Power Limit Mvar 0.

qsetp_mn Lower Reactive Power Limit Mvar 0.

pfsetp_mx Upper Power Factor Limit x<=1&x>=-1 1.

pfsetp_mn Lower Power Factor Limit x<=1&x>=-1 0.95

pf_recap_mx Power Factor x=0|x=1 0,00

pf_recap_mn Power Factor x=0|x=1 0,00

iIntTapCtrl Use Integrated Tap Controller x=0|x=1 0,00

mode_inp Input Mode


Table C.26: ElmVar Parameters DisplayName Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


iZoneBus Zone 0

Unom Nominal Voltage kV x>0 6.



C.25 Static Generator (ElmGenstat)

The Static Generator (ElmGenstat, ) is an easy to use model of any kind of generator, which is not rotating but static. Applications are:

� Photovoltaic Generators

� Fuel Cells

� Storage devices

� HVDC Terminals

� Reactive Power Compensations

Wind generators, which are connected with a full-size converter to the grid, can be modelled as a static generator as well, because the behaviour of the plant (from the view of the grid side) is determined by the converter:

� Wind Generators

Basic Data

Load Flow Data

VDE/IEC Short-Circuit Data

Full Short-Circuit Data

Optimization Data

RMS- / EMT-Simulation Data

C.25.1 Basic Data

On the basic date tab of the Static Generator you can choose the category of the element, enter the number of parallel generators and the ratings of one generator.

Fig. C.1: Static Generator - Basic Data

C.25.2 Load Flow Data

On the load flow tab you can define the power output: active and reactive power, or active power and voltage magnitude, or even a droop. Additionally you can specify a capability curve, which may be the whole range of the converter or a curve with the shape of a V for a min. and max. power factor for example.

Inom Nominal Current kA x>0 1.

K Amplification x>=0&x<=1 0.

i_onoff Bypass x=0|x=1 0


manuf Manufacturer



desc Description






Fig. C.2: Static Generator - Load Flow Data

C.25.3 VDE/IEC Short-Circuit Data

For short circuit analysis according to IEC 60909 (VDE 0102), you can specify, whether the Static Generator shall have a contribution to the short circuit or not. In order to let the Static Generators fed into the short circuit, enable the option 'Static converter-fed drive'. With this option enabled, a Static Generator will have a contribution like a Static converter-fed drive according to IEC 60909:

� It has a contribution to I''k and to ip.

� It has no contribution to Ib or Ik .

In IEC 60909 the contribution of a Static converter-fed drive to I''k is defined by:

�

� X = 0.995 Z

� R/X = 0.1

� with

The index 'rM' specifies the rating of the static converter transformer on the network side, or the rating of the static converter, if no transformer is present.

C.25.4 Full Short-Circuit Data

If you want to define a user-specific level for the subtransient and a transient short circuit, you can do so using the Complete Method. For short circuit calculations by the Complete Method you can enter a subtransient and a transient short circuit level, either as short circuit power or as short circuit current, and the R/X ratio (alternatively the X/R ratio). Additionally it is possible to enter values for the zero sequence impedance, for example if the Static Generator includes a transformer with earthed star point.

C.25.5 Optimization Data

On the optimization tab you can add the Static Generator to a Virtual Power Plant.

C.25.6 RMS- / EMT-Simulation Data

In time-domain-simulations the Static Generator has to be controlled via a DSL model. It behaves either as a controlled voltage source (input signale u1r_in and u1i_in) or as a controlled current source (input signale id_ref and iq_ref, assuming the current controller of the real converter would be ideally fast).








C.26 Static Var System (ElmSvs)

The static var compensator system (ElmSvc) is a combination of a shunt capacitor bank and a thyristor controlled shunt reactance.

Input parameters

Table C.27 shows the input parameters for the ElmSvs object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the static var compensator, presenting the relations among the input parameters is given in the attached Technical Reference Paper.


C.27 Station Controller (ElmStactrl)

The desciption of the Station Controller is given in the attached Technical Reference Paper.

The Station Controller is used for steady-state analysis. For time-domain simulation please use Common Models as described in Section 25.7 Models for Stability Analysis .

C.28 Synchronous Machine (ElmSym)

Object used to represent synchronous machine models, requires a reference to a TypSym object.

Input parameters

Table C.28 shows the input parameters of the ElmSym object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the synchronous machine model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.


Table C.27: ElmSvs Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


nxcap Max. Number of Capacitors x>=0 0

nncap Act. Number of Capacitors x>=0 0

qmax Q Reactance (>0) Mvar x>=0 0.

qmin Q per Capacitor Unit (<0) Mvar x<=0 0.

tcrmax TCR, Max. Limit Mvar x>=0 0.

ibvco Remote Bus

usetp Voltage Setpoint p.u. x>0 1.

tcrqact Act. Value of TCR Mvar x>=0 0.

qsetp Q Setpoint Mvar 0.

ictsv Use for OPF Control x=0|x=1 0

ivcop Controlled Phase x>=0&x<=4 0

i_ctrl Load Flow Control x>=0&x<=2 0

i_sctrl Balanced/Unbalanced Control x=0|x=1 0




iconn Connection mode of Capacitors x=0|x=1|x=2 0

pcu Maximum Copper Losses kW x>=0 0.

i_det TCR Model x=0|x=1 0

q0 Reactive Power Mvar 0.

Re Resistance, Re Ohm 0.

Xe Reactance, Xe Ohm 0.

R0 Resistance, R0 Ohm 0.

X0 Reactance, X0 Ohm 0.


manuf Manufacturer



desc Description

phmc Harmonic Currents (TCR)

i_int Ideal SVS x=0|x=1 0

maxorder Maximum Harmonic Order x>0 0


i_qini Estimate Reactive Power x=0|x=1 0





Table C.28: ElmSym Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


typ_id Type

ngnum parallel Machines x>0 0

pgini Active Power MW 0.


sgini Apparent Power MVA x>=0 0.

cosgini Power Factor 0.

ictpg Active Power x=0|x=1 0

ictqg Reactive Power x=0|x=1 0

costp Costs per MW $/MW 0.

iestp Estimate Active Power x=0|x=1 0

iestq Estimate Reactive Power x=0|x=1 0

bustp Corresponding Bus Type

usetp Voltage p.u. x>0 1.


xesy Xearth Ohm x>=0 0.

resy Rearth Ohm x>=0 0.

ip_ctrl Reference Machine x=0|x=1 0

iv_mode Mode of Local Voltage Controller x=0|x=1 0

i_spin Spinning in isolated operation x=0|x=1 0

phiini Angle deg x>=-180&x<=180 0.




desc Description

pStoch Stochastic model

Pctrl Active power steps 0

i_prty Priority x>=0 0

iOPFCPmin Min. x=0|x=1 0

iOPFCPmax Max. x=0|x=1 0

Pmax_uc Max. MW 0.8

Pmin_uc Min. MW 0.

tmin_up Minimum up-time h 0.

tmin_down Minimum down-time h 0.

cost_up Startup $ 0.

cost_down Shutdown $ 0.

cpower Power MW

ccost Costs $/h

dsecres Reserve 0.

iqtype Use limits specified in type 0

iOPFCQmin Min. x=0|x=1 0

iOPFCQmax Max. x=0|x=1 0

q_min Min. p.u. -1.

q_max Max. p.u. 1.

i_cap User defined Capability Curve 0

cap_P Act.Power MW

cap_Qmn Min. Mvar

cap_Qmx Max. Mvar

iunitcom Optimized in unit commitment 0

t_on Initial Condition h 0.

t_off Initial Condition h 0.

P_min Min. MW 0.

pmaxratf Rating Factor x>=0 1.

pG Range of Voltage Regulation (+/-) % x>=0&x<=100 0.

Kpf Prim. Frequency Bias MW/Hz x>=0 0.




mode_inp Input Mode

dpl1 dpl1 0.

dpl2 dpl2 0.

dpl3 dpl3 0.

dpl4 dpl4 0.

dpl5 dpl5 0.



C.29 Tower Line Coupling (ElmTow)

The ElmTow is used to represent electromagnetic coupling between transmission lines. In order to define the line coupling, a TypTow/TypGeo object determining the geometrical characteristics and the conductor type of the structure where the coupled lines are located, is required.

Input parameters

Table C.29 shows the input parameters for the ElmTow object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the line coupling model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.


C.30 AC Voltage Source (ElmVac)

The ElmVac is used to represent AC Voltage sources (single phase or three phase).

Input parameters

Table C.30 shows the input parameters for the ElmVac object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the AC voltage source model, presenting the relations among the input parameters and the posible types is given in the attached Technical Reference Paper.



Table C.29: ElmTow Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


typ_id Tower Type

desc Description

line1 Circuit 1

line2 Circuit 2

line3 Circuit 3

line4 Circuit 4

line5 Circuit 5

line6 Circuit 6

rearth Earth Resistivity Ohmm x>0 100.

pGeo Type TypTow,TypGeo

towdist Distance m

pCon_e Type TypCon

sag_e Max.Sag m

plines Circuit ElmLne,ElmLneroute

dpolar Polarity

pCon_c Type TypCon

sag_c Max.Sag m

transp Transposition

dtow Length 0.

iusecoup Use Coupling Length x=0|x=1 0

pos1 Position 1 km

pos2 Position 2 km

couplen Coupling Length km


c_dist Distributed Parameter 0

c_lumped Lumped Parameter (PI) 0

tmat Transformation Matrix Tv

pzs Surge Impedance Ohm

pa Wave Propagation

pTa Travel Time s

ftau Frequency for Parameter Approximation Hz x>0 100000.


Table C.30: ElmVac Parameters Name Description Unit Range Default


Under preparation...



C.31 DC Voltage Source (ElmVdc)

The ElmVdc is used to represent DC Voltage sources (single phase or three phase).

Input parameters

Table C.31 shows the input parameters for the ElmVdc object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the AC voltage source model, presenting the relations among the input parameters and the posible types is given in the attached Technical Reference Paper.


C.32 Current Measurement (StaImea)

The description of the current measurement model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.

C.33 Power Measurement (StaPqmea)

The description of the power measurement model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.

C.34 Voltage Measurement (StaVmea)

The description of the voltage measurement model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.

C.35 Digital Clock (ElmClock)

Object used to represent clock inputs.

Input parameters

Table C.32 shows the input parameters of the ElmClock object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the clock model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.



Table C.31: ElmVdc Parameters Name Description Unit Range Default


Under preparation...





Table C.32: ElmClock Parameters Name Description Unit Range Default





C.36 Fast Fourier Transform (ElmFft)

Object used to represent fast Fourier transforms.

Input parameters

Table C.33 shows the input parameters of the ElmFft object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the fast Fourier transform model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.


C.37 File Object (ElmFile)

Object used to read data from a file during calculations.

Input parameters

Table C.34 shows the input parameters of the ElmFile object. Parameters are presented in the same order of the object dialogue (starting from the 'Basic Data' tab).

The description of the measurement file element, presenting the functionality of the input parameters is given in the attached Technical Reference Paper.

Note: The name of the parameter is displayed in the Element edit dialogue, by placing the cursor in the input field of the parameter. Certain parameters are relevant to more than one calculation, therefore they can be found and edited in different tabs. The availability of some parameters is conditioned to the current value of the selection parameters (iopt_...); therefore not all the listed parameters would be visualized at once in a dialogue.

fold_id In Folder

charact Charact.



dat_src Data source


typ_id Type

Tp Period ms x>0 1.

tonTp Ratio Ton/Tp x>0&x<1 0.5

iopt_meas Use Measurement Frequency x=0|x=1 0

ctrlsim Control Simulation Step Size x=0|x=1 0


Table C.33: ElmFft Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


typ_id Type

nsamp Number of Points x>0 256.

nphase No. of Phases x=1|x=3 0

i_win Window x>=0 0


Table C.34: ElmFile Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


iopt_imp Import from x>=0&x<=1 0

f_name Filename

icol Column j 0

afac Factor a 1.

bfac Factor b 0.

prim P or S

tini Time Index 0.

desc Description




C.38 Fourier Source (ElmFsrc)

Fourier source element, used to generate periodical signals in the frequency domain.

Input parameters

Table C.35 shows the input parameters of the ElmFsrc object. Parameters are presented in the same order of the element dialogue (starting from the 'Basic Data' tab).

The description of the Fourier source model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.

Note: The name of the parameter is displayed in the Element edit dialogue, by placing the cursor in the input field of the parameter. Certain parameters are relevant to more than one calculation, therefore they can be found and edited in different tabs. The availability of some parameters is conditioned to the current value of the selection parameters (iopt_...); therefore not all the listed parameters would be visualized at once in a dialogue

C.39 Phase Measurement Device (Phase Locked Loop, ElmPhi__pll)

The description of the phase measurement device model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.

C.40 Digital Register (ElmReg)

The `Register' (ElmReg) model in PowerFactory is a digital shifting register. With every rising edge of the clock signal the values are shifted by one, then the output is set and the input is read and stored in the register.

Input parameters

Table C.36 shows the input parameters of the ElmReg object. Parameters are presented in the same order of the element dialogue (starting from the 'Basic Bata' tab).

The complete description of the Register model is given in the attached Technical Reference Paper.


C.41 Sample and Hold Model (ElmSamp)

The `Sample and Hold' model of PowerFactory (ElmSamp) samples a signal, setting the output at the rising edge of a clock. The output value is constant up to the next clock pulse.

Input parameters

Table C.37 shows the input parameters of the ElmSamp object. Parameters are presented in the same order of the element dialogue (starting from the 'Basic Data' tab).

The complete description of the Sample and Hold model is given in the attached Technical Reference Paper.


Table C.35: ElmFscr Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


dc_com DC Component 0.

f_min Minimum Frequency Hz x>0 10.

delta_f Frequency Step Hz x>0 10.

overspl Oversampling Factor x>=10 10.

ampl_ Amplitude

phase_ Phase deg

rb_proc Calculate with



Table C.36: ElmReg Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


typ_id Type

nsamp Size x>0 0





C.42 Trigger Model (ElmTrigger)

The trigger model (ElmTrigger) is used to monitor the value of a signal. If certain trigger conditions are met the model will start a trigger event.

Input parameters

Table C.38 shows the input parameters of the ElmTrigger object. Parameters are presented in the same order of the element dialogue (starting from the 'Basic Data' tab).

The complete description of the Trigger model is given in the attached Technical Reference Paper.


Appendix D Types Reference

2-Winding Transformer Type (TypTr2)

3-Winding Transformer Type (TypTr3)

Asynchronous Machine (TypAsmo)

Booster Transformer Type (TypTrb)

Cable Type (TypCab)

Conductor Type (TypCon)

General Load (TypLod)

Line Type (TypLne)

Rectifier Type (TypRec)

Synchronous Machine Type (TypSym)

Tower Types (TypTow/TypGeo)

Table C.37: ElmSamp Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


typ_id Type



Table C.38: ElmTrigger Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source


typ_id Type


i_max On x=0|x=1 0

i_min On x=0|x=1 0

i_grd On x=0|x=1 0

valmax Threshold 1.

valmin Threshold -1.

valgrd Threshold 1/s 1.

npickmax Set after... 0

npickmin Set after... 0

npickgrd Set after... 0

ndropmax Reset after... 0

ndropmin Reset after... 0

ndropgrd Reset after... 0

npts Number of Points for Calculation of Gradient x>=0 0

sleep Number of measured values after Start until Trigger gets active x>=0 0

res Acquire Data x=0|x=1 0

iopt_res Writing of RMS Results 0

iopt_sys Trigger Type 0


DIgSILENT GmbH www.digsilent.de



D.1 2-Winding Transformer Type (TypTr2)

Type used to define two winding transformers/autotransformers (ElmTr2 and ElmTr2n).

Input parameters

Table D.1 shows the input parameters for the TypTr2 object. Parameters are presented in the same order of the element dialogue (starting from the 'Basic Data' tab).

The description of the 2-winding transformer model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.


Tel: +49 (0)7072 9168-50 Fax: +49 (0)7072 [email protected]

Table D.1: TypTr2 Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source

strn Rated Power MVA x>0 1.

utrn_h HV-Side kV x>0 6.

utrn_l LV-Side kV x>0 6.

uktr Short-Circuit Voltage uk % 3.

pcutr Copper Losses kW 0.

curmg No Load Current % x>=0 0.

dutap Additional Voltage per Tap % 0.

phitr Phase of du deg 0.

ntpmx Maximum Position 0

ntpmn Minimum Position 0

nntap0 Neutral Position 0

fdtr2r Resistance R=R(freq) [A-Z]

fdtr2l Reactance L=L(freq) [A-Z]

uk0tr Absolute uk0 % 3.

ur0tr Resistive Part ukr0 % 0.

tr2cn_h HV-Side _IsVecGrpValid

tr2cn_l LV-Side _IsVecGrpValid

nt2ag Phase Shift *30deg x>=0&x<=12 0

nt2ph Technology x=1|x=2|x=3 0

itrdl x,Pos.Seq. HV-Side x>=0&x<=1 0.5

itrdr r,Pos.Seq. HV-Side x>=0&x<=1 0.5

itrmt Type 0

it0mt Type 0

cknee Knee Current p.u. 0.

psi0 Knee Flux p.u. x>=0 01. Jan

xmlin Linear Reactance p.u. x>=0 0.

xmair Saturated Reactance p.u. x>=0 0.

ksat Saturation Exponent x>1 0

iLimb Core x=3|x=5 0

iInterPol Interpolation x=0|x=1 0

smoothfac Smoothing Factor % x>=0.0&x<=100.0 10.

zx0hl_h z, Zero Sequ. HV-Side x>=0&x<=1 0.9

zx0hl_n Mag. reac. / uk0 x>=0 100.

pict2 Ratio Ip/In p.u. 0.

pitt2 Max. Time s 0.

twct2 Ratio It/In p.u. 0.

twtt2 Max. Time s 0.

ansiclass Class

tap_side at Side x=0|x=1 0

frnom Nominal Frequency Hz x>=0 50.

pfe No Load Losses kW x>=0 0.

strnfc Rated Power (forced cooling) MVA x>=0 0.

oltc On-load Tap Changer x=0|x=1 0

itapzdep Tap dependent impedance x=0|x=1 0

uktmn uk (min. tap) % 0.

pcutmn Pcu (min. tap) kW 0.

uktmx uk (max. tap) % 0.

pcutmx Pcu (max. tap) kW 0.

uk0tmn uk0 (min. tap) % 0.

uk0rtmn Re(uk0) (min. tap) % 0.

uk0tmx uk0 (max. tap) % 0.

uk0rtmx Re(uk0) (max. tap) % 0.

manuf Manufacturer




D.2 3-Winding Transformer Type (TypTr3)

Type used to define three winding transformers/autotransformers (ElmTr3).

Input parameters

Table D.2 shows the input parameters for the TypTr3 object. Parameters are presented in the same order of the element dialogue (starting from the 'Basic Data' tab).

The description of the 3-winding transformer model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.


desc Description


satcur Current (peak) p.u.

satflux Flux (peak) p.u.


Table D.2: TypTr3 Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source

strn3_h HV-Side MVA x>0 1.

strn3_m MV-Side MVA x>0 1.

strn3_l LV-Side MVA x>0 1.

utrn3_h HV-Side kV x>=0 0.

utrn3_m MV-Side kV x>=0 0.

utrn3_l LV-Side kV x>=0 0.

uktr3_h HV-MV % x>=0 3.

uktr3_m MV-LV % x>=0 3.

uktr3_l LV-HV % x>=0 3.

pcut3_h HV-MV kW x>=0 0.

pcut3_m MV-LV kW x>=0 0.

pcut3_l LV-HV kW x>=0 0.

curm3 No Load Current % x>=0 0.

cr0m3 No Load Current % 0.

n3tmn_h Min. Position 0

n3tmn_m Min. Position 0

n3tmn_l Min. Position 0

n3tmx_h Max. Position 0

n3tmx_m Max. Position 0

n3tmx_l Max. Position 0

n3tp0_h Neutral Position 0

n3tp0_m Neutral Position 0

n3tp0_l Neutral Position 0

du3tp_h Add. Voltage per Tap % x>=0 0.

du3tp_m Add. Voltage per Tap % x>=0 0.

du3tp_l Add. Voltage per Tap % x>=0 0.

ph3tr_h Phase of du deg x>=0&x<=360 0.

ph3tr_m Phase of du deg x>=0&x<=360 0.

ph3tr_l Phase of du deg x>=0&x<=360 0.

uk0hm HV-MV % x>=0 3.

uk0ml MV-LV % x>=0 3.

uk0hl LV-HV % x>=0 3.

ur0hm HV-MV % x>=0 0.

ur0ml MV-LV % x>=0 0.

ur0hl LV-HV % x>=0 0.

fdtr3r Resistance R=R(freq) [A-Z] _FrqDepValid

fdtr3l Reactance L=L(freq) [A-Z] _FrqDepValid

tr3cn_h HV-Side _IsVecGrpValid

tr3cn_m MV-Side _IsVecGrpValid

tr3cn_l LV-Side _IsVecGrpValid

nt3ag_h Phase Shift *30deg x>=0&x<=12 0

nt3ag_m Phase Shift *30deg x>=0&x<=12 0

i3loc Position 0

i30lc Position 0

itrmt Type 0

it0mt Type Zero Sequence 0

c3nee Knee Current p.u. 0.



D.3 Asynchronous Machine (TypAsmo)

Type object defined for asynchronous machine elements (ElmAsm) and double feed induction machines (ElmAsmsc).

Input parameters

Table D.3 shows the input parameters of the TypAsmo object. Parameters are presented in the same order of the Type dialogue (starting from the 'Basic Data' tab).

The description of the asynchronous machine model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.

Note: The name of the parameter is displayed in the Type edit dialogue, by placing the cursor in the input field of the parameter. Certain parameters are relevant to more than one calculation, therefore they can be found and edited in different tabs. The availability of some parameters is conditioned to the current value of the selection parameters (iopt_...); therefore not all the listed parameters would be visualized at once in a dialogue.

psi0 Saturation Flux p.u. 01. Jan

x3lin Linear Part p.u. 0.

x3air Saturated p.u. 0.

pict3 Ratio Ip/In 0.

pitt3 Max. Time s 0.

twct3 Ratio It/In 0.

twtt3 Max. Time s 0.

pfe No Load Losses kW x>=0 0.

t3nam transformer name (only for compatib.)

bname1 bus name 1 (only for compatib.)



elemnm Element Name (only for compatib.)

ansiclass Class

nt3ag_l Phase Shift *30deg x>=0&x<=12 0

itapos Tap Modeled at x=0|x=1 0

snfc_h HV-Side MVA x>=0 0.

snfc_m MV-Side MVA x>=0 0.

snfc_l LV-Side MVA x>=0 0.

oltc_h HV-Side x=0|x=1 0

oltc_m MV-Side x=0|x=1 0

oltc_l LV-Side x=0|x=1 0

itapzdep Tap dependent impedance x=0|x=1 0

itapzside for Tap at x>=0&x<=2 0

uktr3mn_h uk(HV-MV)(min. tap) % x>=0 0.

uktr3mn_m uk(MV-LV)(min. tap) % x>=0 0.

uktr3mn_l uk(LV-HV)(min. tap) % x>=0 0.

pcut3mn_h Pcu(HV-MV)(min. tap) kW x>=0 0.

pcut3mn_m Pcu(MV-LV)(min. tap) kW x>=0 0.

pcut3mn_l Pcu(LV-HV)(min. tap) kW x>=0 0.

uktr3mx_h uk(HV-MV)(max. tap) % x>=0 0.

uktr3mx_m uk(MV-LV)(max. tap) % x>=0 0.

uktr3mx_l uk(LV-HV)(max. tap) % x>=0 0.

pcut3mx_h Pcu(HV-MV)(max. tap) kW x>=0 0.

pcut3mx_m Pcu(MV-LV)(max. tap) kW x>=0 0.

pcut3mx_l Pcu(LV-HV)(max. tap) kW x>=0 0.

uk0mnhm uk0(HV-MV)(min. tap) % x>=0 0.

uk0mnml uk0(MV-LV)(min. tap) % x>=0 0.

uk0mnhl uk0(LV-HV)(min. tap) % x>=0 0.

ur0mnhm Re(uk0)(HV-MV)(min. tap) % x>=0 0.

ur0mnml Re(uk0)(MV-LV)(min. tap) % x>=0 0.

ur0mnhl Re(uk0)(LV-HV)(min. tap) % x>=0 0.

uk0mxhm uk0(HV-MV)(max. tap) % x>=0 0.

uk0mxml uk0(MV-LV)(max. tap) % x>=0 0.

uk0mxhl uk0(LV-HV)(max. tap) % x>=0 0.

ur0mxhm Re(uk0)(HV-MV)(max. tap) % x>=0 0.

ur0mxml Re(uk0)(MV-LV)(max. tap) % x>=0 0.

ur0mxhl Re(uk0)(LV-HV)(max. tap) % x>=0 0.

manuf Manufacturer


desc Description



Table D.3: TypAsmo Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source



sgn Rated Apparent Power kVA x>0 500.

ugn Rated Voltage kV x>0 6.

cosn Rated Power Factor x>0&x<=1 0.8

nppol No of Pole Pairs x>0 0

aiazn Locked Rotor Current (Ilr/In) p.u. x>0 5.

tag Acceleration Time Constant s x>0 2.

xm Mag. Reactance Xm p.u. x>0 4.

rtox R/X Locked Rotor x>=0 0.1

rstr Stator Resistance Rs p.u. x>=0 0.

rrtrA Rotor Resistance RrA p.u. x>0 0.01

rrtrB Rotor Resistance RrB p.u. x>0 0.1

xstr Stator Reactance Xs p.u. x>=0 0.01

xrtrA Rotor Reactance XrA p.u. x>0 0.1

xrtrB Rotor Reactance XrB p.u. 0.1

xmrtr Rotor Leakage Reac. Xrm p.u. x>=0 0.

frequ Nominal Frequency Hz x>0 50.

istt Status of ESB Calculation 0

nslty Connection 0

pgn Rated Mechanical Power kW x>=0 400.

anend Nominal Speed rpm x>=0 0.

aslkp Slip at Stalling Point x>=0 0.

asstl Slip at Saddle Point x>=0 0.

amazn Locked Rotor Torque p.u. x>=0 0.

amkzn Torque at Stalling Point p.u. x>=0 0.

amstl Torque at Saddle Point p.u. x>=0 0.

coazn cos(phi) Locked Rotor p.u. x>=0 0.

slp Slip % x>=0 0.

mslp Torque p.u. x>=0 0.

islp Current p.u. x>=0 0.

fdasmr Resistance R=R(freq) [A-Z] FrqDepValid

fdasml Reactance L=L(freq) [A-Z] FrqDepValid

i_mode Input Mode x=0|x=1 0

effic Efficiency at nominal Operation % 100.

i_trans Consider Transient Parameter 0

fcharrstr Stator Resistance Rs(f)

fcharlss Inductance L''(f)

iinrush Ratio Ip/In p.u. x>0 10.

Tinrush Max. Time s x>0 0.02

Tcold Cold s x>0 20.

Thot Hot s x>0 10.

i_cdisp Consider Current Displacement (Squirrel Cage Rotor) x=0|x=1 0

n_cdisp Order of R-L Approximation 0

rrsn Slip dependent part of RrA at nominal slip 0.

xrsn Slip dependent part of XrA at nominal slip 0.

rrs1 Slip dependent part of RrA at slip=1 0.

xrs1 Slip dependent part of XrA at slip=1 0.

rrtrA0 Slip indep. Resistance RrA0 0.

xrtrA0 Slip indep. Reactance XrA0 0.

r0 Resistance RrA1 0.1

x0 Reactance XrA1 0.1

r1 Resistance RrA2 0.1

x1 Reactance XrA2 0.1

i_cage Rotor 0

i_optpn Power Rating 0

rtoxshc R/X Locked Rotor x>=0 0.1

aiaznshc Locked Rotor Current (Ilr/In) p.u. x>0 5.

xtorshc X/R Locked Rotor x>=0 10.

xdssshc Locked Rotor Reactance p.u. x>0 0.199007

iansitp ANSI Type x>=0&x<=6 0

manuf Manufacturer


desc Description

J Inertia kgm^2 x>0 08. Feb

rzero Resistance p.u. 0.01

xzero Reactance p.u. 0.1




D.4 Booster Transformer Type (TypTrb)

Type used to define booster transformers (ElmTrb).

Input parameters

Table D.4 shows the input parameters for the TypTrb object. Parameters are presented in the same order of the element dialogue (starting from the 'Basic Data' tab).

The description of the booster transformer model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.


D.5 Cable Type (TypCab)

Type used to define cable objects.

Input parameters

Table D.5 shows the input parameters for the TypCab object. Parameters are presented in the same order of the element dialogue (starting from the 'Basic Data' tab).

The description of the cable type model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.


Table D.4: TypTrb Parameters DisplayName Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source

manuf Manufacturer


desc Description

strn Rated Power MVA x>0 1.

utrn_h HV-Side kV x>0 6.

utrn_l LV-Side kV x>0 6.

uktr Short-Circuit Voltage uk % x>=0 3.

pcutr Copper Losses kW x>=0 0.

curmg No Load Current % x>=0&x<=100 0.

uk0tr Absolute uk0 % x>=0&x<=100 3.

ur0tr Resistive Part ukr0 % x>=0&x<=100 0.

tr2cn_l LV-Side _IsVecGrpValidB

nt2ag Phase Shift *30deg x>=0&x<=12 0

itrdz z,Pos.Seq. HV-Side x>=0&x<=1 0.5

itrdz_lv z,Pos.Seq. LV-Side x>=0&x<=1 0.5

zx0hl_h z, Zero Sequ. HV-Side 0.9

zx0hl_l z, Zero Sequ. LV-Side 0.1

zx0hl_n Mag. reac. / uk0 x>=0 100.


Table D.5: TypCab Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source

typCon Shape

diaTube Inner Diameter mm x>=0 0.

diaCon Outer Diameter mm x>=0 5.

thSht Thickness of Sheath mm x>=0 1.

thArm Thickness Armour mm x>=0 1.

thIns Thickness mm x>=0 1.

rho Resistivity uOhm*cm x>0 Jan 68

my Relative Permeability 1.

epsr Relative Permittivity 3.

tand Dielectric Loss Factor 0.02

has_ins3 Has Insulation 3 (Serving) x=0|x=1 0

has_ins2 Has Insulation 2 (Over Sheath) x=0|x=1 0

has_arm Has Armour x=0|x=1 0

has_sht Has Sheath x=0|x=1 0

manuf Manufacturer


desc Description



D.6 Conductor Type (TypCon)

Type used to define conductor objects. A reference to a conductor type is required in the tower types: TypTow/TypGeo, to define the conductors of the transmission line.

Input parameters

Table D.6 shows the input parameters for the TypCon object. Parameters are presented in the same order of the element dialogue (starting from the 'Basic Data' tab).

The description of the conductor type model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.


D.7 General Load (TypLod)

Type object defined for general load elements (ElmLod).

Input parameters

Table D.7 shows the input parameters of the TypLod object. Parameters are presented in the same order of the Type dialogue (starting from the 'Basic Data' tab).

The description of the general load model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.

Note: The name of the parameter is displayed in the Type edit dialogue, by placing the cursor in the input field of the parameter. Certain parameters are relevant to more than one calculation, therefore they can be found and edited in different tabs. The availability of some parameters is conditioned to the current value of the selection parameters (iopt_...); therefore not all the listed parameters would be visualized at once in a dialogue.

uline Rated Voltage kV x>=0 0.

rtemp Max. End Temperature degC x>0 80.

Ithr Rated Short-Time (1s) Current kA x>=0 0.


Table D.6: TypCon Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source

ncsub Number of Subconductors x>0&x<100 0

dsubc Bundle Spacing m 0.1

diaco Diameter mm x>0 30.

radco Radius mm x>0 15.

erpha GMR (Equivalent Radius) mm x>0 11.682

Lint Internal Inductance mH/km x>0 0.05

my_r Relative Permeability x>0 1.

iskin Skin effect x=0|x=1 0

gline Line Conductivity uS/km x>=0 0.

rpha DC-Resistance Ohm/km x>0 0.05

uline Nominal Voltage kV x>0 6.

sline Nominal Current kA x>=0 1.


Ithr Rated Short-Time (1s) Current kA x>=0 0.

manuf Manufacturer


desc Description


Table D.7: TypLod Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source

lodst Static (const Z) % x>=0&x<=100 0

loddy Dynamic % x>=0&x<=100 0

lodsp Special % x>=0&x<=100 0

kpf Frequ. Dependence on P 0.

kpu Volt. Dependence on P 01. Jun

tpf Transient Frequency Dependence s x>=0 0.

tpu Transient Voltage Dependence s x>=0 0.

kqf Frequ. Dependence on Q 0.

kqu Volt. Dependence on Q 01. Aug



D.8 Line Type (TypLne)

Type used to define transmission lines/cables (ElmLne), whose line impedances have been already calculated (no electromagnetic coupling between conductors is calculated in this type).

Input parameters

Table D.8 shows the input parameters for the TypLne object. Parameters are presented in the same order of the element dialogue (starting from the 'Basic Data' tab).

The description of the line type model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.


tqf Transient Frequency Dependence s x>=0 0.

tqu Transient Voltage Dependence s x>=0 0.

t1 Dynamic Load Time Constant s x>=0 0.1

pgrd QL/QC % x>=0 200.

qcq QC/Q % 100.

cnm Connection (*x)='Y'|(*x)='D '

spfilnm Measurement File

fdlodr Resistance R=R(freq) [A-Z] FrqDepValid

fdlodl Reactance L=L(freq) [A-Z] FrqDepValid


nlnph Phases x>=1&x<=3 0


manuf Manufacturer


desc Description

i_nln Nonlinear Model x=1|x=0 0

i_pure Load model x=0|x=1 0

i_csrc Current Source/Impedance x=0|x=1 0

udmax Upper Voltage Limit p.u. x>1 01. Feb

udmin Lower Voltage Limit p.u. x<1&x>0 0.8

Prp Power of parallel Resistance/Total Active Power % x>=0&x<=100 0.

xt Transformer Short Circuit Reactance % x>=0 0.


Table D.8: TypLne Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source

nlnph Phases x>=1&x<=3 0

uline Rated Voltage kV x>=0 0.

sline Rated Current kA x>=0 1.

slin1 Rated Current (1.) kA x>=0 0.

slin2 Load Current (*In) *In x>=0 0.

lodln Type of Load

picln Ratio Ip/In p.u. 0.

pitln Maximum Time s 0.

twcln Ratio It/In p.u. 0.

twtln Maximum Time s 0.

rline Resistance R 'Ohm/km x>=0 0.

xline Reactance X 'Ohm/km 0.

rlin1 Loop Resistance (sev) Ohm/km x>=0 0.

xlin1 Loop Reactance (sev) Ohm/km x>=0 0.


bline Susceptance B 'uS/km 0.

lline Inductance L 'mH/km x>=0 0.

cline Capacitance C 'uF/km 0.

gline Conductance G 'uS/km 0.

tline Ins. Factor 0.

fdlinr Resistance R=R(freq) [A-Z] _FrqDepValid

fdlinl Reactance L=L(freq) [A-Z] _FrqDepValid

fdlinc Capacitance C=C(freq) [A-Z] _FrqDepValid

rline0 Resistance R0 'Ohm/km x>=0 0.

xline0 Reactance X0 'Ohm/km x>=0 0.

lline0 Inductance L0 'mH/km x>=0 0.

bline0 Susceptance B0 'uS/km 0.

cline0 Capacitance C0 'uF/km 0.



D.9 Rectifier Type (TypRec)

Type used to define a 6 pulse bridge rectifier/inverter elements (ElmRecmono and ElmRec).

Input parameters

Table D.9 shows the input parameters for the TypRec object. Parameters are presented in the same order of the element dialogue (starting from the 'Basic Data' tab).



gline0 Conductance G0 'uS/km 0.

tline0 Ins. Factor 0.

Ices Earth-Fault Current A/km 0.

miso Insulation Material

mlei Conductor Material

qurs Nominal Cross Section mm*2 0.

bett Operating Temp. degC 0.

crosect Cross Section


aohl_ Cable / OHL _AohlValid

InomAir Rated Current (in air) kA x>=0 1.

Ithr Rated Short-Time (1s) Current (Conductor) kA x>=0 0.

rtheta Resistance R'(theta) Ohm/km x>=0 0.

theta Temperature theta degC x!=20 0.

manuf Manufacturer


desc Description

frnom Nominal Frequency Hz x>=0 50.

fcharL1 L1'(f)

fcharR1 R1'(f)

fcharC1 C1'(f)

fcharL0 L0'(f)

fcharR0 R0'(f)

fcharC0 C0'(f)


cabdiam Outer Diameter mm 0.

ncond No. of Conductors 3.

iopt_cnd Cable is

iopt_ord Conductors

cmeth Installation Method (IEC 364)

iopt_dir Arrangement

lcost Line Cost $/km x>=0 0.

nneutral No. of Neutrals x=0|x=1 0

rnline Resistance Rn 'Ohm/km x>=0 0.

xnline Reactance Xn 'Ohm/km x>=0 0.

bnline Susceptance Bn 'uS/km x>=0 0.

rpnline Resistance Rpn 'Ohm/km x>=0 0.

xpnline Reactance Xpn 'Ohm/km x>=0 0.

bpnline Susceptance Bpn 'uS/km x>=0 0.


Table D.9: TypRec Parameters DisplayName Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source

manuf Manufacturer


desc Description

Unom Rated AC Voltage kV x>0 1.

Pnom Rated Active Power MW x>0 1.

Rthy Thyristor-Resistance (at On) Ohm x>0 0.0001

alphamin Minimum Firing Angle deg 0.

alphamax Maximum Firing Angle deg 180.

gammamin Minimum Extinction Angle deg 0.

gammamax Maximum Extinction Angle deg 180.

Imax Rated DC-Current kA x>0 1.

Unomdc Rated DC-Voltage (DC) kV x>0 1.

tapmin Minimum Turns-Ratio p.u. x>0.5|x<1.5 0.9



D.10 Synchronous Machine Type (TypSym)

Type used to define synchronous machine elements (ElmSym)

Input parameters

Table D.10 shows the input parameters for the TypSym object. Parameters are presented in the same order of the element dialogue (starting from the 'Basic Data' tab).

The description of the synchronous machine model, presenting the relations among the input parameters is given in the attached Technical Reference Paper.


tapmax Maximum Turns-Ratio p.u. x>0.5|x<1.5 01. Jan

i_diode Diode-/Thyristor Converter x=0|x=1 0

Goff Thyristor-Conductance (at Off) S x>=0 0.

Gs Snubber-Conductance S x>=0 0.

Cs Snubber-Capacity uF x>0 0.1

i_trf Built-In Transformer x=0|x=1 0

alphanom Nominal Firing Angle deg 15.

tapnom Nominal Turns-Ratio (t2/t1) x>0 1.


Table D.10: TypSym Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source

sgn Nominal Apparent Power MVA x>0 1.

ugn Nominal Voltage kV x>0 6.

cosn Power Factor x>0&x<=1 0.8

tag Acceleration Time Const. (rated to Pgn) s x>0 10.

tds Td 's x>0 1.

tqs Tq 's x>=0 1.

tdss Td ''s x>0 0.05

tqss Tq ''s x>0 0.05

xd xd p.u. x>0 2.

xds xd 'p.u. x>0 0.3

xdss xd ''p.u. x>0 0.2

xq xq p.u. x>0 2.

xqs xq 'p.u. x>=0 0.3

xqss xq ''p.u. x>0 0.2

xdsat short-circuit ratio p.u. x>=0 01. Feb

xdsss saturated value xd''sat p.u. x>0 0.2

xtor Ratio X/R x>=0 10000000.

rstr rstr p.u. 0.

xpot Potier reactance p.u. x>=0 0.

sg10 1.0 p.u. x>=0 0.

sg12 01. Feb p.u. x>=0 0.

x2sy Reactance x2 p.u. x>0 0.2

r2sy Resistance r2 p.u. x>=0 0.

x0sy Reactance x0 p.u. x>=0 0.1

r0sy Resistance r0 p.u. x>=0 0.

iamort with amortisseur windings x=0|x=1 0

iusesat Use saturated value x=0|x=1 0

satur Machine Type IEC909 x>=0&x<=3 0

fdsymr Resistance R=R(freq) [A-Z] _FrqDepValid

fdsyml Reactance L=L(freq) [A-Z] _FrqDepValid

bname bus name (only for compatib.)

q_min Minimum Value p.u. -1.

q_max Maximum Value p.u. 1.

Q_min Minimum Value Mvar -1.

Q_max Maximum Value Mvar 1.

iturbo Rotor Type x=0|x=1 0

isat Main Flux Saturation x=0|x=1 0

iuseXdk Ik instead of Reactances x=0|x=1 0

curk 3-Phase Ik3p kA x>=0 0.

curk1p 1-Phase Ik1p kA x>=0 0.

curk2p 2-Phase Ik2p kA x>=0 0.

nslty Connection x>=0&x<=2 0

tags Acceleration Time Const. (rated to Sgn) s x>0 8.



D.11 Tower Types (TypTow/TypGeo)

Both types are used to define the tower structure of a transmission line. If TypTow or TypGeo are referred in an ElmLne, the coupling impedances of the line are calculated according to the given geometrical distribution of the conductors. The tower types require a reference to conductors types (TypCon).

Input parameters

Tables D.11 and D.12 show the input parameters for the TypTow and TypGeo objects. Parameters are presented in the same order of the element dialogue (starting from the 'Basic Data' tab).

The description of the tower models, presenting the relations among the input parameters is given in the attached Technical Reference Paper.


h Inertia Time Constant (rated to Sgn) H s x>0 4.

tds0 Td0 's x>0 666.667

tqs0 Tq0 's x>=0 666.667

tdss0 Td0 ''s x>0 0.075

tqss0 Tq0 ''s x>0 0.075

lss l ''p.u. x>0 0.2

i_trans Consider Transient Parameter x=0|x=1 0

fcharrstr rs(f)

fcharlss l''(f)

i_v12 Model x=0|x=1 0

xl xl p.u. x>=0 0.1

xrl xrl p.u. x>=0 0.

kcanay Canay Factor p.u. x>=0 0.

manuf Manufacturer


desc Description

dpu Mechanical Damping p.u. x>=0 0.

hpn Inertia Time Constant (rated to Pgn) H s x>=0 5.


Table D.11: TypTow Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source

nlcir Number of Line Circuits x>=1 0

nlear Number of Earth Wires x>=0 0

gearth Earth Conductivity uS/cm x>0 100.

rearth Earth Resistivity Ohmm x>0 100.

ktrto Transposition

nphas Num. of Phases

pcond_e Conductor Types TypCon

pcond_c Conductor Types TypCon

xy_e Coordinate of Earth Conductors m

xy_c Coordinate of Line Circuits m

ktrto_c1 t x=0|x=1 0






nphas_1 x=1|x=2|x=3 0

nphas_2 x=1|x=2|x=3 0

nphas_3 x=1|x=2|x=3 0

nphas_4 x=1|x=2|x=3 0

nphas_5 x=1|x=2|x=3 0

nphas_6 x=1|x=2|x=3 0

cond_e1 1

cond_e2 2

cond_c1 1

cond_c2 2

cond_c3 3

cond_c4 4

cond_c5 5

cond_c6 6

xy_e1 1 m 0.

xy_e2 2 m 0.

xy_c1 1 m 0.



Appendix E Reference to the use of Symbols in PowerFactory

The symbols used in the graphic windows of PowerFactory are defined by the so called 'Symbol' objects (IntSym). DIgSILENT provides a complete set of symbols to represent any of the defined network components; additionally the users have the possibility to define their own symbols and use them in the graphical windows of their projects.

In the proceeding sections the variables used to define symbol objects are presented.

The Symbol General Definitions

Geometrical Description

E.1 The Symbol General Definitions

The general definitions of the symbols are given in the 'General' page of the object's dialogue.

Symbol Description The description of a symbol is shown in the list of symbols when "Show Layer..." is used and a symbol has to be selected on the page "Configuration"

Object Type Class name of the element which shall be represented.

Type of Representation Branch or node object

ID The icon ID of the icons from the graphic toolbar. If this value is set the symbol will be used when a new element is inserted. In case of '0' the symbol will not be used as default.

Width/Height The width and height is defines the range of the fang. The marking of an element in the graphic makes this range visible.

Visible

xy_c2 2 m 0.

xy_c3 3 m 0.

xy_c4 4 m 0.

xy_c5 5 m 0.

xy_c6 6 m 0.

R_c Matrix of Resistances R_ij Ohm/km

X_c Matrix of Reactances X_ij Ohm/km

R_c0 Matrix of 0-Sequence-Resistances R_ij_0 Ohm/km

X_c0 Matrix of 0-Sequence-Reactances X_ij_0 Ohm/km

R_c1 Matrix of 1-Sequence-Resistances R_ij_1 Ohm/km

X_c1 Matrix of 1-Sequence-Reactances X_ij_1 Ohm/km

frnom Nominal Frequency Hz 50.

L_c Matrix of Inductances L_ij H/km

L_c0 Matrix of 0-Sequence-Inductances L_ij_0 H/km

L_c1 Matrix of 1-Sequence-Inductances L_ij_1 H/km

G_c Matrix of Conductances G_ij uS/km

B_c Matrix of Susceptances B_ij uS/km

G_c0 Matrix of 0-Sequence-Conductances G_ij_0 uS/km

B_c0 Matrix of 0-Sequence-Susceptances B_ij_0 uS/km

G_c1 Matrix of 1-Sequence-Conductances G_ij_1 uS/km

B_c1 Matrix of 1-Sequence-Susceptances B_ij_1 uS/km

C_c Matrix of Capacitances C_ij uF/km

C_c0 Matrix of 0-Sequence-Capacitances C_ij_0 uF/km

C_c1 Matrix of 1-Sequence-Capacitances C_ij_1 uF/km

sline Nominal Current kA x>=0 1.


i_mode Input Mode x=0|x=1 0

manuf Manufacturer


desc Description


Table D.12: TypGeo Parameters Name Description Unit Range Default



fold_id In Folder

charact Charact.



dat_src Data source

xy_e Coordinates Earth Wires m

xy_c Coordinates Phase Circuits m

manuf Manufacturer


desc Description





Visibility of the symbol

Mirror Defines if the symbol can be mirror (right mouse button entry)

Allow Moving Allows moving in graphic

Show Connection Attributes Shows the square (resulting state of composite switches) at the end of connection lines

Insertion Reference Defines the insertion point of an element (e.g. rectangular terminal = 4 -> top left).The following matrix describes the relation between the insertion points and the insertion numbers: 4 3 2 5 0 1 6 7 8

Additional Attributes Only used for elements whose representation shall be able to alter via specific changes of the element parameters (e.g. shunts, couplers)

Connection Points Defines the position on the symbol where the connection lines start. The number of connection points is defined by the number of lines unequal (-9999,-9999). The points should be located on the grid, i.e. they should be a multiple of 4.375 (mm)

Contents Containing objects of type "SetVitxt" defining the layout of the text boxes. The names must be unique. Labels beginning with "Label..." and result boxes beginning with "Res...". The name of symbol must also be part of the name of the SetVitxt.

E.2 Geometrical Description

The geometrical description of the symbol is given in the 'Geometry' page of the dialogue. The geometry can be specified by means of geometrical primitives in the 'Geometrical Components and Attributes' field or can be defined using an external bit map or WMF file.

E.2.1 Geometrical Primitives

Circle (C,iStyle,rWidth,iFill,iColor,iRsz,nPts,rMx,rMy,rPx,rPy) Defines a Circle by the center (rMx, rMy) and a point on the edge (rPx,rPy). Parameter nPts must be 2.

Arc (A,iStyle,rWidth,iFill,iColor,iRsz,nPts,rMx,rMy,rPx1,rPy1,rPx2,rPy2) Defines an arc by the center (rMx,rMy) and 2 points (rPx1,rPy1) (rPx2,rPy2) on the edge, drawn clockwise. nPts must be set to 3.

Polyline (L, iStyle,rWidth,iFill,iColor,iRsz,iRot,nPts,rPx,rPy) Defines an open polygonal line with nPts points. rPx andrPy are the coordinates of peg points. iRot can be defined as: n -> random y -> only rotatable to the bottom and the right (used in symbols)

Polygon (G, iStyle,rWidth,iFill,iColor,iRsz,nPts {,rPx,rPy}) Defines a closed polygonal line with nPts points. rPx and rPy are coordinates of peg points

Text (T, iColor,iRsz,iFont,iAlign,rHeight,iOri,iRot,sString,rPx,rPy) Defines a text with the following attributes:

iFont font number ( > 0)

iAlign insertion point (0 = left top, 2 = center)

rHeight height ( > 0 )

iOri orientation ( 0 = horizontal , 1 = vertical )

iRot rotate text with object ( 0 = no, 1 = yes, 2 = vert./ horiz.,3 = only to the bottom and right, -- used in symbols only --)

sString text (max. 80 characters)

rPx,rPy coordinates of insertion point

iRsz resize_Mode (0=not possible, 1=shift only, 2=keep ratio, 3=any (RS_NONE,RS_SHIFTONLY,RS_KEEPXY, RS_FREE)

All geometrical elements have the following attributes in common:

iStyle (Line style) 1 = normal line 2 = dotted 3 = dashed 4 = dotted and dashed

rWidth (Line widht in mm ( > 0))

iFill (Fill style) 0 = not filled 1 = filled 100% 2 = horiz. stripes 3 = vertical stripes 4 = horizontal and vertical stripes 5 = diagonal from left bottom to right top 6 = diagonal from right bottom to left top 7 = diagonal grid of stripes 8 = filled 25% 9 = filled 50%10 = filled 75%

iColor (Colour) -1 = colour of object 0 = white 1 = black 2 = bright red 3 = bright blue 4 = bright green 5 = yellow 6 = cyan 7 = magenta 8 = dark grey 9 = grey 10 = red 11 = dark rot 12 = dark green 13 = green 14 = dark blue 15 = blue 16 = white 17 = bright grey

iRsz (Resize mode) 0 = not resizable 1 = shift only 2 = keep ratio 3 = resizable in any direction





In version 13.0 additional parameters were added:

iSB No. of area (1..32, can only be used if set in source code, e.g. vector groups

iLay No. of graphic layer

iSN Connection number (0..4)

iIP Object is used for calculation of intersections (=1 only for node objects)

xOff, yOff Offset used when object is inserted (optional)

E.2.2 Showing self defined pictures in symbols

WMF and bitmaps can be selected as "Symbol File". The definitions of the geometrical primitives are not used if a "Symbol File" is defined.The picture will be adapted to the size of symbol in the single line diagram.After selection of a WMF file in the top entry field for the Symbol File (not rotated) a button "Create all other files" appears which allows to create automatically WMF files in the same folder with a rotation of 90, 180 and 270 degrees. Additionally pictures for open devices with the same angles can be entered in the bottom lines.

Appendix F Interfaces with Other Programs

DGS Interface

Converting PSS/E Files

StationWare Interface

F.1 DGS Interface

With its DGS interface DIgSILENT PowerFactory offers sophisticated data import and export possibilities for the use of other programs and for dynamic data exchange. For example the DGS interface can be used for the conversion of system data from SCADA (Supervisory Control And Data Acquisition) and GIS (Graphical Information System). The dialogue of this interface is opened by selecting Import... -> DGS Format... or Export... -> DGS Format... resp. in the main File menu.

DGS files can be either in ASCII format, in Access format, or in Excel format.

The GIS conversion uses millimeter units with respect to the bottom-left origin and a limit up A0 paper format (1188 x 840 mm). It could therefore be necessary to transform the GIS coordinates before creation of the ".DGS'' file.

For more detailed information, please find the documentation and examples in the DGS folder inside the PowerFactory installation folder, or contact the DIgSILENT Support team.

F.2 Converting PSS/E Files

The import function for PSS/E files is an integrated command of PowerFactory . It supports versions of PSS/E from 23 to 29 and can be found in the main menu under File −> Import... −> PSS/E . Both import of PSS/E files as a PowerFactory project and export of PowerFactory -projects as PSS/E files are supported. To export a project in PSS/E format select File −> Export... −> PSS/E from the main menu.

Importing PSS/E Steady-State Data

Import of PSS/E file (Dynamic Data)

Exporting a project to a PSS/E file

F.2.1 Importing PSS/E Steady-State Data

PowerFactory is able to convert both steady-state data (for load-flow and short-circuit analyses) and dynamic data files. It is good practise to first import the steady-state data (described in this section), then to add the dynamic models (described in Section F.2.2 Import of PSS/E file (Dynamic Data) .

Before starting the next steps for importing a PSS/E file, all projects should be de-activated. Then please select from the main menu File -> Import... -> PSS/E. Afterwards the window of the import command will pop-up, asking the user to specify various options.

General Settings Tab Page

Import Options Tab Page

Import Graphical Options Tab Page

General Settings Tab Page








Fig. F.1: PSS/E Import - General Settings

Nominal Frequency Nominal frequency of the file to be Converted/Imported.

PSS/E Raw data Location on the hard disk of the PSS/E raw data file. By default the program searches for *.raw extensions. The user may consider all types of files by typing *.*.

Add Graphic Files Location of the PSS/E drw files on the file system. Again by default the programs searches for files with extension *.drw. The user may consider all types of files by typing *.*.

Note After the Conversion/Importing has finished, the resulting project will contain a graphics folder where all of the PSS/E drw converted graphics will be stored. The user must therefore relocate each one of them to the corresponding grids.

Save converted data in:

Project The project name that will be assigned to the converted/imported file.

in Location in the data manager tree where the imported file will be stored.

Sequence Data Location of the PSS/E sequence data file. By default the program searches for *.seq extensions. The user may consider all types of files by typing *.*.

The following topics

Dyn Models Data

Parameter Mapping

Composite Frame Path

DSL - Model Path

are not used for the import of steady-state data and will be explained in the dynamic import Section F.2.2.

Import Options Tab Page

Fig. F.2: PSS/E Import - Options

Convert only sequence data file With this option enabled, the converter will only add the sequence data to an existing project.

Convert only dynamic models file With this option enabled, the converter will only add the dynamic data file to an existing project (only for dynamic data import).

Convert only graphic file With this option enabled, the converter will add only a single-line diagram to an existing project.

Only convert file (no DB action) Internal option used for syntax check and error messages during conversion. Normally this box should be left unchecked.



Output only used dynamic models Displays a list of used dynamic models (only for dynamic data import).

Unit of 'LEN' for lines in miles instead of km With this option enabled, all lengths will be interpreted in miles in the PSS/E raw files.

Consider transformer phase shift With this option enabled, transformer phase shifts will be considered. This option is recommended and activated by default.

Convert Induction Machines (P<0) With this option enabled, all generators in the raw data file that have negative active power will be converted to asynchronous machines. For transmission grids the option should be disabled for proper modeling of phase shift generators.

Automatic 3-W. Transformer detection/conversion The older versions of PSS/E do not know 3-winding transformers. Therefore the converter will try to detect the existence of three 2-Winding Transformers connected to a busbar. If any candidates are available, PowerFactory will replace them by a 3-Winding Transformer. The detection is using the impedances and the voltage control of the transformers.

Convert capacitive line shunts to line susceptance B' If a line has line shunts the converter adds automatically the line shunt capacitance to the C1' (B1') in the PowerFactory line type.

Convert Common Impedance as Transformer The Common Impedance in PSS/E may be converted to a PowerFactory common impedance or to a transformer. This is selected here.

Convert Series Capacitance as Common Impedance Older versions of PSS/E do not know series capacitances as a dedicated model. These elements therefore are represented by lines with negative reactances. During the conversion PowerFactory detects these branches and converts them to series capacitances (by default) or to common impedances (when this option is active).

Convert off-nominal turn ratio to transformer tap Transformer ratios different from the rated ratio are automatically converted to a transformer type using taps, including the correct tap position.

Busbar naming: 'PSSE_NAME' With this option enabled, the busbars are named similar to the PSS/E raw data file (without bus number).

Branch naming: 'BUSNAME1_BUSNAME2_ID' With this option enabled, the branches are named as the name of the busbars + ID.

Import Graphical Options Tab Page

Fig. F.3: PSS/E Import - Graphical Options

Rotate with respect to busbar The converter will rotate the graphical layout in case of the majority of busbars being in vertical or horizontal position.

Snap coordinates to grid The converter will snap to grid all objects in the single line graphics.

Transformer Symbol according to IEC This options lets the user to choose the transformer symbol as IEEE (default) or IEC representation.

Scaling factor The graphic files are scaled according to the scaling factor shown.

F.2.2 Import of PSS/E file (Dynamic Data)

As explained in Section F.2.1 it is good practise first to import the steady-state data and then to add the dynamic model data.

Before converting dynamic data, it is recommended to copy the IEEE library folder located in the global library into the user directory. The IEEE dynamic data library folder can be found under Library\Models\IEEE . This folder has the structure as shown in Figure F.4.




Fig. F.4: IEEE Library

The following subdirectories are of importance in the conversion/importing.

Frames This folder contains the composite frames which are basically wired diagrams.

Macros All models are described in the DIgSILENT simulation language DSL. These DSL models may use functional primitives, the so-called DSL macros. The standard macros are stored in this folder.

Models This folder contains the models for most typical models, e.g. automatic voltage regulators (AVRs), power system stabilizers (PSS), primary controllers (PCO) and others. The models are described in DIgSILENT Simulation Language (DSL). The folders also may contain user-defined models.

An important condition for successful file conversion is that all DSL models used during the conversion process should be stored in the same model library folder. By default, this is the case in the global PowerFactory library. If the original library should use specific folders for the different types of controllers (AVR,PCO,PSS,..), the user should copy all of the models into the same library folder. After the conversion, the user may re-arrange the models.

The procedure to start the import of dynamic network data is very similar to the import of steady-state data. Some parameter adjustments have to be made.

General Settings Tab Page - Dynamic Model Import

Import Options Tab Page - Dynamic Model Import

General Settings Tab Page - Dynamic Model Import

In the dialogue of General Settings in Figure F.1 the following topics have to be specified:

Dyn Models Data Location of the PSS/E Dynamic Models data file. By default the program searches for *.dyn and *dyr extensions. The user may consider all types of files by typing *.*.

Parameter Mapping Location of the PowerFactory mapping file. This is an option that normally will not have to be touched by the user. By default PowerFactory will automatically set up its own internal mapping file. This file defines how to translate the PSS/E internal models into PowerFactory models, including the mapping of controller parameters. For automated conversion of user-defined PSS/E controllers the mapping file may be customized. Please contact our support if you wish to do so.

Composite Frame Path Location in the PowerFactory data base where the composite frames are stored (IEEE/Frames...).

DSL - Model Path Location in the PowerFactory data base where the DSL models are stored (IEEE/Models....).

Import Options Tab Page - Dynamic Model Import

In the dialogue of Import Options in Figure F.1 the following options should be considered:

Convert only dynamic models file With this option enabled, the converter will only add the dynamic data file to an existing project.

Output only used dynamic models Displays a list of used dynamic models.

F.2.3 Exporting a project to a PSS/E file

This function allows the export of the network model in PSS/E format. The export comprises both steady-state and dynamic data sets. The correct conversion of dynamic models is only possible for the standard IEEE models. Models which the user implemented in PowerFactory DSL can not automatically be translated but must be modeled as user-defined controller types separately in PSS/E.

To export a project in PSS/E format select File −> Export... −> PSS/E from the main menu.

Export General Settings Tab Page

Export Options Tab Page

Export General Settings Tab Page




Fig. F.5: PSS/E Export - General settings

RAW Conversion File Path and file name for the PSS/E RAW file, containing the symmetrical description of the model.

SEQ Conversion File Path and file name for the PSS/E SEQ file, containing the additional description of the model necessary for unbalanced conditions.

DYN Conversion File Path and file name for the PSS/E DYN file, containing the dynamic models of the project.

Export Options Tab Page

Fig. F.6: PSS/E Export - Options

Convert Motors to Generators if P<0 With this option enabled, all asynchronous machines in generator mode will be converted to synchronous machines.

Base Apparent Power Base for the power values given in per-unit system.

Min (Zero) Impedance Branch Minimum impedance for ideal connections.

PSS/E Version Version of PSS/E target files.

The section of developers' options contains additional options used for debugging. Please use these options only when requested to do so by the PowerFactory support.

Extra Precision Activates the output of values in extended precision.

F.3 StationWare Interface

This chapter describes the StationWare interface. An introduction into StationWare's general philosophy is given in Section F.3.1.

The following two sections describe the overall StationWare architecture (Section F.3.2) and the conceptual differences between PowerFactory and StationWare (Section F.3.3).

Both PowerFactory and StationWare have to be configured before they can be used together (Section F.3.4).

The Getting Started section (Section F.3.5) provides a gentle introduction into the most important features. The complete documentation can be found in the Reference section (Section F.3.6).

The final Technical Reference (Section F.3.7) provides some deeper knowledge how PowerFactory data is converted to StationWare data and vice versa.

The terms StationWare and PSMS are used as synonyms throughout the whole chapter. PSMS stands for Protection Settings Management System, and stresses the more internal and technical part of StationWare.

About StationWare

Component Architecture

Fundamental Concepts

Configuration

Getting Started

Reference

Technical Reference

F.3.1 About StationWare

DIgSILENT StationWare provides a reliable central protection settings database and management system for the complete power system substation data, both to manage the various control parameters and to centrally store substation related information and data, based on latest .NET technology.

StationWare stores and records all settings in a central database, allows modeling of all relevant work flow sequences, provides quick access to relay manuals, interfaces with manufacturer specific relay settings software, and integrates with PowerFactory software, allowing for powerful and easy-to-use settings co-ordination studies.

Modern numerical relays have a large number of settings that are determined, stored and communicated by proprietary software solutions (these may even be suitable for only a particular manufacturer or even a series or type of relay). This results in a fragmented and distributed settings "database." DIgSILENT StationWare provides a single system that incorporates all such different device protocols, thereby providing one manageable software data storage system, based on modern IT techniques, facilitating data interfacing and exchange in a transparent and hassle free manner.





PowerFactory's data exchange facility allows it to access the settings stored inStationWare, such that these may be used as input for the powerful PowerFactory system simulation and protection setting tools. Settings that are calculated by using these tools may then be transferred back to StationWare.

F.3.2 Component Architecture

DIgSILENT StationWare is a so-called Client-Server Application: the functionality is distributed on at least two computers: client and server. Figure F.7 gives an overview on the components.

Fig. F.7: Architecture overview

Usually there are several clients. One main advantage of this architecture is the fact that the data is stored in one central database on the server. One client connects to the server and fetches the data from there, modifies them, and afterward stores them back to the server. On other clients these changes are visible.

DIgSILENT StationWare server provides two interfaces to access from client machines:

� Visualization by means of a standard web browser. The HTML interface can be used with an usual web browser (e.g. Microsoft Internet Explorer or Mozilla Firefox) as shown in Figure F.8. The browser displays HTML pages which are created by StationWare's HTML front end. The HTML pages are transferred using the HTTP protocol on top of the TCP/IP internet protocol. HTML allows to present all kind of data e.g. plain text, tables or images. Additionally HTML provides concepts to achieve interactivity: by submitting HTML forms or pressing on hyperlinks data is sent to the server. The server interpretssuch requests and creates new HTML pages which are displayed by the browser again.

� The web service interface, similar to the HTML interface uses the HTTP protocol to communicate with the web service frontend, though no HTML pages are transferred but lower-level data (SOAP/XML encoded). The web service client application is responsible to present this data conveniently. PowerFactory is able to play the role of a web service client. It integrates parts of StationWare's data and concepts smoothly into its own world.

The functionality of the HTML interface is covered in the StationWare manual. The remainder of this chapter focuses on PowerFactory as client.




Fig. F.8: HTML interface

F.3.3 Fundamental Concepts

Though both in StationWare and in PowerFactory the settings and data associated with protective devices, such as relays, CTs, VTs and circuit breakers are stored, the systems provide a different set of concepts how to deal with this data.

In StationWare it is possible to model a location hierarchy and associate the devices to nodes in this hierarchy (e.g. substations). This has no equivalent on the PowerFactory side where the devices are stored inside the parent grid (ElmNet) object.

On the other side PowerFactory allows to create a topological representation of networks which is not supported in StationWare.

This section describes the concept mismatch between PowerFactory and StationWare. In order to use the StationWare interface it's important to know about the differences between both applications.

Location

Device

Device State

Life Cycle Phase

Location

In StationWare each device belongs to exactly one location. There are different location types e.g. Region, Area, Substation, or Bay. The locations are organized in a hierarchy tree as shown in Figure F.9.




Fig. F.9: StationWare locations

In PowerFactory the data is organized in projects (IntPrj). A project may have one or more grids (ElmNet) which in turn contain net elements e.g. terminals, cubicles, and relays (ElmRelay). See Figure F.10 for a typical PowerFactory project.

Fig. F.10: PowerFactory project

StationWare's location concept and PowerFactory's pr oject/grid concept hardly fit together. That's the reason why the data mapping between PowerFactory and StationWare begins at the device level which is the subject of the next sections.

Device

StationWare manages a set of devices e.g. relays, CTs, VTs, or Circuit breakers. Each device is associated to a device type e.g. ABB DPU2000R or SEL421 003. Additionally each device has an unique ID: the device ID.

In PowerFactory a relay is represented by an ElmRelay object which references exactly one TypRelay object. The ElmRelay object contains several sub-components e.g. the I> component (a RelToc object), the Logic component (RelLogic), or the Ios component (RelMeasure). See Figure F.11 for an example. The device ID is used to link one StationWare device to one PowerFactory device. The PowerFactory device e.g. an ElmRelay object stores the StationWare device ID as foreign key.



Fig. F.11: PowerFactory relay

Device State

A device's state is in StationWare called setting. A setting is a list of attributes, and describes the state of one device completely. An attribute is a tuple of

� attribute name,

� attribute type which can be an arbitrary integer or floating point number, optionally with a range restriction, or a string, or a enumeration type.,

� a default value,

� an optional unit.

A complex relay may have thousands of attributes. In StationWare the setting attributes are organized in so-called setting groups. A setting group groups the attributes together which belong somehow together. It's often defined by the device manufacturer. Each attribute belongs to exactly one setting group. Inside a group the attribute name is unique.

The device type defines which attributes and groups characterize a device. Table F.1 shows an example of a possible device type. There are two setting groups G and H. Group G has the attributes a, b, and c, group H has the attributes d and e.

Table F.1: Settings Definition

According to this attribute definition a device can have settings as shown in tables F.2 or F.3.

Table F.2: Settings Example 1

Table F.3: Settings Example 2

On the PowerFactory side there are neither setting nor group nor attribute. There is the ElmRelay object and its sub-objects. These objects can have parameters. See table F.4 for a definition and table F.5 for an example. The TypRelay type defines components and parameters.

StationWare attributes are somehow mapped to PowerFactory parameters and vice versa. How this actually is accomplished, is described in Section F.3.7 Technical Reference . The mapping is non-trivial since only a small subset of the attributes (the calculation-relevant data) is modeled in PowerFactory and vice versa. Additionally there is no one-to-one relationship between attributes, and parameters and a parameter could get calculated out of several attributes.

.

Table F.4: Parameter Definition

Some relays support multiple setting groups (MSG) also called parameter sets. Such relays have the same group many times (c.f. table F.5). The groups H1, H 2, and H 3 have the same set of attributes (c and d). Some relay models in PowerFactory do not support this concept fully. Instead of modeling all MSGs, only one instance of the H groups is provided.

In this case a group index parameter defines which of the MSGs actually is transferred from StationWare to PowerFactory.

Life Cycle Phase

In StationWare each setting has one life cycle phase e.g. Planning or Applied. At each point in time a device can have a set of settings e.g. three Planning settings, one Applied setting and 12 Historic settings.

Group Name Type Default Unit

G a b c

integer in [0,10] float float in [0.03,1.65]

0 -0.32 1.0

A I/s

H d e

string enum 'yes','no','maybe'

'DEFAULT' 'yes'

Group, Name Value

G,a G,b G,c H,d H,e

7 23.43 1.1 'abc' 'maybe'

Group, Name Value

G,a G,b G,c H,d H,e

8 0 1.1 'abcdef' 'yes'

Component Parameter Type

i> o integer

Logic p q

string enum 'enabled','disabled'

Ios r s

float float

Component Parameter Value

i>:o Logic:p Logic:q Ios:r

8 'HIGH' 'enabled' 18.5



Table F.5: Parameter Example

.

Table F.6: Multiple Setting Group Definition

In PowerFactory a device has exactly one state (or setting). Therefore when data is transferred between PowerFactory and StationWare, always a concrete device setting in StationWare must be specified.

For PowerFactory purposes a special PowerFactory planning phase is introduced. The transfer directions are specified as follows:

� Imports from StationWare into PowerFactory are restricted to Applied and PowerFactory settings. Applied denotes the current applied setting (Applied ) or a previous applied (Historic ) setting.

� Exports from PowerFactory to StationWare are restricted to the PowerFactory setting. (Applied and Historic settings are read-only and can never be changed).

(Actually PowerFactory's sophisticated variant management is similar to the phase concept, but there is no obvious way how to bring them together.)

F.3.4 Configuration

In order to transfer data between PowerFactory and StationWare both systems must be configured.

StationWare Server

PowerFactory Client

StationWare Server

An arbitrary StationWare user account can be used for the StationWare interface in PowerFactory. The user must have enough access rights to perform operations e.g. for the export from PowerFactory to StationWare write-rights must be granted.

The bi-directional transfer of settings is restricted to lifecycle phases with

1. status PLANNING or REVIEW and

2. with a cardinality constraint of 1 i.e. there may exist one or no such setting for one device.

Please ensure that at least one phase fullfills these requirements, and there exists a setting of this phase.

PowerFactory Client

The client operating system must allow connections to the server (network and firewall settings etc.).

Nothing has to be done in the PowerFactory configuration itself. The TypRelays in the Library must of course support StationWare/PowerFactory mapping.

F.3.5 Getting Started

This section is a simple walkthrough and covers the most essential StationWare interface functionality. By using a simple PowerFactory project and simple StationWare substation, it describes

1. how relays in StationWare and PowerFactory are created,

2. how these relays are linked,

3. how settings can be exported from PowerFactory to StationWare,

4. how settings can be imported again into PowerFactory.

All (especially the more advanced) options and features are described in the reference section (see Section F.3.6 Reference ).

Prepare substation in StationWare

Prepare project in PowerFactory

Link Relays and establish a Connection

Export and Import Settings

Prepare substation in StationWare

We begin with the StationWare side. We create a substation and two relays within:

� start the web browser,

� log on to the StationWare system,

� create a new substation titled Getting Started,

� create two relays named Getting Started Relay 1 and Getting Started Relay 2 in the Getting Started substation

In the HTML interface the station detail page should look as shown in Figure F.12.

� Go to the detail page of the Getting Started Relay 1 (Figure F.13).

Since we have just created the device it has no settings, yet. Later it will contain a PowerFactory setting which reflects the relay state on the PowerFactory side.

Ios:s 19.5

Group Name Type Default Unit

G a b

integer in [0,10] float

0 -0.32

A I/s

H1 c d

string float in [0.03,1.65]

'DEFAULT' 1.0

H2 c d


'DEFAULT' 1.0

H3 c d


'DEFAULT' 1.0





Fig. F.12: Substation

Fig. F.13: Device

Prepare project in PowerFactory

Create a new PowerFactory project and create a simple grid within

� start PowerFactory,

� create a new project titled GettingStarted,

� draw a simple grid with two terminals (ElmTerm) connected by a line (ElmLne) as shown in Figure F.14.



Fig. F.14: Grid

Now add a relay to the upper terminal

� right-click the cubicle quadrangle with the mouse. A context menu pops up.

� select New Devices.../Relay Model... as shown in Figure F.15.

A dialogue pops up that allows you to specify the settings of the new relay (ElmRelay).

� insert Getting Started Relay 1 as Name

� select an appropriate Relay Type which supports StationWare import/export (see Figure F.16).

� press OK

� in the same way add a relay Getting Started Relay 2 to the second terminal.

PowerFactory's object filter mechanism gives an overview over all devices inside the current project.



Fig. F.15: Cubicle context menu

� Press the icon (Edit Relevant Objects for calculation) in the toolbar and select the icon (ElmRelay) to filter out all non-relay objects as shown in Figure F.17.

All calculation relevant relays (actually there only the two we created above) are displayed in a table (see Figure F.18).

Link Relays and establish a Connection

Now the PowerFactory relays must get linked to the StationWare relays.

� mark both relay icons with the mouse,

� press the right mouse button.

A context menu pops up as shown in Figure F.19.

� select the StationWare menu item,

� select the Select Device ID item.

A Log on to StationWare server dialogue pops up. Since this is the first time PowerFactory connects to the StationWare server some connection settings must be entered.



Fig. F.16: Relay dialogue

Fig. F.17: Relay object filter

� enter the Server Endpoint URL of the StationWare server. The URL should have a format similar to

http://192.168.1.53/psmsws/psmsws.asmx

� enter Username and Password of a valid StationWare user account.

Fig. F.18: Relay display



Fig. F.19: Device context menu

Figure F.20 shows the dialogue settings.

Fig. F.20: Log on dialogue

� press OK.

The connection procedure may take some seconds. If the server could be accessed and the user could be authenticated a success message is printed into the output window

DIgSI/info - Established connection

to StationWare server 'http://192.168.1.53/psmsws/p smsws.asmx'

as user'pf00002'

Otherwise an error dialogue pops up. Correct the connection settings until the connection is successfully created. The reference section (Section 1.6.2) explains the connection options in detail.

Having established a connection to the server, a browser dialogue pops up which displays the location hierarchy as known from the StationWare HTML interface. The dialogue is shown in Figure F.21.

� navigate to the Getting Started substation,

� select the Getting Started Relay 1 device,

� press OK.

Fig. F.21: Browser dialogue

Now the PowerFactory relay is "connected" to the StationWare device.

� in the same way select Getting Started Relay 2 for the second PowerFactory relay.

Export and Import Settings

Having linked PowerFactory to StationWare devices, the transfer between both systems can be started.

� mark the relays with the mouse and right-click to get the relay context menu as shown in Figure F.19.

� select the Export... item in the StationWare menu entry.

A ComStationware dialogue is shown which allows to specify the export options (c.f. Fig. 1.16). See Section Export and Import Settings in the Reference section for all export options.



Fig. F.22: ComStationware dialogue

� select PowerFactory as Life cycle Phase,

� press Execute.

After a few seconds the relay settings are transferred to the server, and the output window contains the message

DIgSI/info - Exported 2 of 2 device settings succes sfully

The result can now be observed in the StationWare HTML interface.

Fig. F.23: Device detail page

� navigate to the relay detail view of the Getting Started Relay 1 relay (c.f. Fig. F.23)

Observe the new created PF setting. The phase of this setting is PowerFactory .

� switch to the settings detail page of the new PF setting (c.f.Fig. F.24).



Fig. F.24: Setting detail page

The setting values should correspond to the relay state in PowerFactory. In the same way the Getting Started Relay 2 relay has a new PF setting.

Now try the opposite direction and import a setting from StationWare into PowerFactory.

� modify the PF settings in StationWare by entering some other values

� in PowerFactory mark the relays with the mouse and right-click to get the relay context menu as shown in Figure F.19.

� select the Import... item in the StationWare menu entry.

Again the ComStationware dialogue (see Figure F.22) pops up as known from the export.

� leave the default settings,

� press Execute.

Again the result of the settings transfer is reflected in the output window:

DIgSI/info - Imported 2 of 2 device settings succes sfully

� find ElmRelay object parameters changed according to the changes on the StationWare side

All import options are described in detail in the reference section Export and Import Settings .

F.3.6 Reference

This section describes all options and features concerning the StationWare interface.

The Device Context Menu

Connection

The Browser Dialogue

The ComStationware Object

Import Options

Export Options

The Device Context Menu

Almost all functionality can be accessed by the device context menu. Mark one ore more objects which supports the StationWare transfer e.g. ElmRelay

� in the object filter (Figure F.19)

� in the data manager as shown in Figure F.25.




Fig. F.25: Device context menu

The StationWare submenu contains the entries as follows:

Import... opens the ComStationware dialogue and sets the device selection according to the above selected device objects. The ComStationware dialogue settings are explained in detail in section The ComStationware Object .

Export... does the same for the export direction.

Select Device ID... starts the Browser dialogue (Figure F.29) to link this device to a StationWare device. The dialogue is subject of section The Browser Dialogue .

Reset Device ID resets the device ID.

Connect... terminates the current StationWare session if it's already existing. Shows a Log On dialogue. The connection settings are covered by Section 1.6.2. This may be useful when you are using several StationWare accounts and want to switch between them.

Disconnect terminates the StationWare session

Connection

Similar to the HTML interface the StationWare interface in PowerFactory is session-oriented: when a user logs on to the system by specifying a valid StationWare account (username and password) a new session is created. Only inside such a session StationWare can be used. The account privileges restrict the application functionality e.g. an administrator account is more powerful than a usual user account.

Fig. F.26: Log on dialogue

Working with PowerFactory the first time the StationWare server is required the Logon dialogue is shown as shown in Figure F.26.

The StationWare connection options are stored in the user settings (Figure F.27). After each successful logon the user settings are updated.

Fig. F.27: User settings

As mentioned in the Architecture section (Section 1.2) StationWare is a client-server application. The StationWare server component is located on a server machine in the internet. The client component is the PowerFactory application which is running on a client machine.

The technology PowerFactory and StationWare use to communicate is called web services and is standardized like many other internet technologies (HTML, HTTP). The server computer (or more exactly the StationWare service application on the server computer) has a 'name' by which it can be accessed. This 'name' is called service endpoint and resembles a web page URL:

http://the.server.name/psmsws/psmsws.asmx

or

http://192.168.1.53/psmsws/psmsws.asmx

http denotes the protocol, the.server.name is the computer name (or DNS) of the server computer and psmsws/psmsws.asmx is the name of the StationWare application.

The connection options are as follows:

Service Endpoint The Service Endpoint denotes the StationWare server 'name' as described above

Username/Password Username and Password have to be valid user account in StationWare. A StationWare user account has nothing to do with the PowerFactory user account.

The very same StationWare account can be used by two different PowerFactory users. The privileges of the StationWare account actually restrict the functionality. For device import the user requires read-access rights. For exporting additionally write-access rights are required.

The Browser Dialogue

As mentioned in the Concept description (see Section Device ) the StationWare device ID is stored as Foreign Key in the ElmRelay object dialogue (Description page) as shown in Figure F.28.



Fig. F.28: ElmRelay dialogue

A more convenient way is to use the Browser dialogue shown in Figure F.29. The dialogue allows to browse through the StationWare location hierarchy and select a device. The hierarchy data is cached to minimize network accesses. Due this caching it's possible that there may exist newly created locations or devices which are not displayed in the browser dialogue. The Refresh button empties the cache and enforces PowerFactory to re-fetch the correct data from the server.

The ComStationware Object

In PowerFactory almost everything is an object: relays are ElmRelay objects, users are IntUser objects, and grids are ElmNet objects.

What may be on the first sight confusing is the fact that actions are objects as well: for a short-circuit calculation a ComShc object is created. The calculation can be performed with several options e.g. 3-Phase, single phase, or 3 Phase to Neutral.

Fig. F.29: Browser dialogue

You can even specify the fault location. All these calculation options are stored in the ComShc object. Every action object has an Execute button which starts the action. In fact there is a large number of parametrized actions like load flow calculation (ComLdf), simulation (ComSim), there is even a ComExit object that shuts down PowerFactory. All objects which can 'do' something have the Com prefix.

Since the StationWare interface is actually 'doing' something (it does import data, it does export data) it is implemented as a ComStationware object.

The ComStationware object is used both for the import (Section 1.6.4.1) and the export (Section 1.6.4.2). It is located in the project's study case according to PowerFactory conventions. The actual Getting Started project (Section 1.5) is shown in Figure F.30.

By default the study case of a new project contains no ComStationWare object. It is automatically created when it is first needed, as well as the ComShc object is instantiated at the time when the first short-circuit calculation is performed.

Import Options

The ComStationware dialogue provides import options as follows (Figure F.31):

Transfer Mode select Import from StationWare as Transfer Mode

Check only Plausibility if the Check only Plausibility flag is enabled the import is only simulated but not really executed.

Life cycle Phase/Time stamp A list of available life cycle phases is shown.

Fig. F.30: Project study case



Fig. F.31: ComStationware import options

� PowerFactory selects the current setting with PowerFactory phase as source setting.

� if Applied is selected the current Applied setting is transferred. If additionally a Timestamp value is entered the setting that was applied at this time is transferred which may either be Applied or Historic.

The Timestamp format is in ISO format: e.g. 2005-02-28 22:27:16

The time part may be omitted. Then 00:00:00 AM is assumed.

All Devices If All Devices is enabled, all calculation-relevant devices are imported. Devices not supported by StationWare are ignored.

Device Selection Unless All Devices is enabled, the Device Selection provides a more subtle way to specify which devices are to be transferred. The Device Selection parameter can be

� an ElmRelay object: this and only this relay is imported

� a SetSelect object: a SetSelect is a container that may hold several objects. All of them are transferred, except the ones not supported by StationWare

� a SetFilt object: the SetFilt is the most flexible way to specify the device selection e.g. you can select all devices in the project of type ElmRelay and whose name begin with PW....

Devices outside the activated project are ignored.

The Device Selection is automatically set if the Device Context Menu mechanism (Section The Device Context Menu ) is used.

All Settings Groups/Group Index This parameter specifies how multiple settings groups (MSG) are handled (c.f. Section 1.3).

� If the relay in StationWare has MSGs and the PowerFactory relay model supports MSGs and - All Settings Groups is enabled: then all groups are transfered. - All Settings Groups is disabled: then only the Group Index -th group is transferred.

� � If the relay in StationWare has MSGs and the PowerFactory relay model doesn't support MSGs: then the Group Index-th group is imported.

These parameters are ignored completely if the relay has no MSGs.

The import transfer is started by pressing Execute.

Fig. F.32: ComStationware export options

Export Options

The export options are almost identical to the import options (Figure F.32):

Transfer Mode Select Export as Transfer Mode



Life cycle Phase A list of possible life cycle targets is shown. Please have in mind that a setting of the life cycle is available. Applied settings can never be changed.

Click Execute to start the data transfer. Then the PowerFactory -relevant parameters are copied upon the existing target setting.

F.3.7 Technical Reference

The purpose of this section is to describe what happens internally inside PowerFactory when device settings are exported or imported.

This section also explains how new device types are integrated. PowerFactory is delivered with a library of relay models. This library cannot contain all relays of all manufacturers. A way how to enhance the library for new device types is shown in this section as well. The StationWare interface is heavily based on DPL (DIgSILENT Programming Language) which is documented in a separate DPL Manual.

Overview

Import Scripts

Export Scripts

How to create a new Device Type conversion

Overview

For each device type (TypRelay) and each transfer direction a separate DPL script is required.

The import DPL script takes the StationWare attributes and a ElmRelay object as input and fills somehow the ElmRelay object's and its subobjects' parameters.

The export DPL script takes a ElmRelay object as input parameter and calculates some output parameters which are the StationWare attributes.

Note: DPL's most important benefit is: you can do everything. That's exactly DPL's most important disadvantage as well. Be sure that your DPL scripts do what they should do and not more. An import script should only set the parameters in the ElmRelay object and its subcomponents. An export script shouldn't change anything at all (at least within PowerFactory).

The scripts have to be named PsmsImport .ComDpl and PsmsExport.ComDpl and must be located in the same folder as the TypRelay object.

Type data like TypRelay objects should be located in a library folder e.g. in the project library. If it is referenced from several projects, it belongs into a global library. See Figure F.33 for an example database structure.

Import Scripts

The algorithm used for the import from StationWare to PowerFactory is as follows. Let d be the device whose setting is to be imported:

1. let t be d's device type

2. let dpl be the PsmsImport.ComDpl object near t

3. initialize dpl's input parameter with the device attributes from StationWare

4. initialize dpl's external object parameter Relay with d

5. execute dpl

Fig. F.33: Database structure

The execution step actually sets the relay parameters.

We use the StationWare device type example shown in table F.1 from the Concept section (Section 1.3) and the PowerFactory device type as shown in table F.3.

The StationWare attributes are G.a, G.b, G.c, H.d, and H.e, the PowerFactory parameters are I>:o , Logic:p , Logic:q , Ios:r , and Ios:s .

Only the attributes G.a, G.c, and H.d and the parameters I>:o , Logic:p , and Ios:r are mapped. The others are ignored since there is no equivalent concept on the other system.

Figure F.34 shows the Basic options. The PsmsImport.ComDpl must meet the requirements as follows:

Name must be PsmsImport

General Selection must be empty

Input Parameters this table holds the StationWare attributes. The Name has the format [group name]__[attribute name]

The Type may either be int (for integer numbers), double (for floating point numbers), or string (for string and enum values).

The Value field must be empty. The attribute unit has to inserted in the Unit field if appropriate. A Description may be inserted, too.

External Object this table contains exactly one entry: an object with the Name Relay. The object column must be empty.




Fig. F.34: DPL import script: Basic options

The Input parameters get initialized with the StationWare attribute values and the External Object with the current relay.

The second page of the ComDpl script holds the output parameters. They have the meaning as follows (Figure F.35 shows the Advanced options). Remote Script this parameter must be unset

Result Parameters the table must have one entry with Name Result of Type String . The DPL script should set this parameter to OK if the import procedure was successful. Otherwise it may hold an error message which is displayed in the output window.

Figure F.36 shows the Script page which contains the DPL code. The code must be a valid DPL program. It should set the relay parameters according to the input parameters.

Fig. F.35: DPL import script: Advanced options



Fig. F.36: DPL import script: Script

Export Scripts

The export direction is almost symmetric to the import process. Be d the device whose setting is to exported:

1. let t be d's device type

2. let dpl be the PsmsExport.ComDpl object near t

3. initialize dpl's external object parameter Relay with d

4. execute dpl

5. transfer dpl's output parameter to the setting in StationWare

The export DPL script must also meet some requirements: Figure F.37 shows the Basic options.

Fig. F.37: DPL export script: Basic options

Name ComDpl.Name must be PsmsExport.

General Selection must be empty

Input Parameters this table must be empty

External Object this table contains exactly one entry: an object with the Name Relay . The object column must be empty.

The second page of the ComDpl script holds the output parameters. They have the meaning as follows (Figure F.38 shows the Advanced options).

Remote Script this parameter must be unset

Result Parameters the table must have the first entry with Name Result of Type String . The DPL script should set this parameter to OK if the import procedure was successful. Otherwise it may hold an error message which is displayed in the output window. Below the Result parameter are the StationWare attributes.



Figure F.39 shows the Script page which contains the DPL code. The code must be a valid DPL program. It should not change the database.

Fig. F.38: DPL export script: Advanced options

Fig. F.39: DPL export script: Script

How to create a new Device Type conversion

This section gives some practical guidelines how to create the conversion scripts for new types. First create a test environment:

� create in StationWare a new substation with one device of the desired device type. Create a default PowerFactory setting for this device.

� create a simple PowerFactory project which contains a device of the desired type

� link the PowerFactory device to the StationWare device by setting the foreign key to the device ID.

Then write the import script:

� create an empty PsmsImport.ComDpl near the TypRelay object.

� define the input and output parameters of the ComDpl object

� write the DPL code

� test the script by importing the PowerFactory setting

Iterate these steps until there are no error messages. Change the setting in StationWare and re-try the import. In quite the same way create and verify a PsmsExport.ComDpl script.




Appendix G The DIgSILENT Programming Language - DPL

The DIgSILENT Programming Language DPL serves the purpose of offering an interface for automating tasks in the PowerFactory program. The DPL method distinguishes itself from the command batch method in several aspects:

� DPL offers decision and flow commands

� DPL offers the definition and use of user-defined variables

� DPL has a flexible interface for input-output and for accessing objects

� DPL offers mathematical expressions

The DPL adds a new dimension to the DIgSILENT PowerFactory program by allowing the creation of new calculation functions. Such user-defined calculation commands can be used in all areas of power system analysis, such as

� Network optimizing

� Cable-sizing

� Protection coordination

� Stability analysis

� Parametric sweep analysis

� Contingency analysis

� etc.

Such new calculation functions are written as program scripts which may use

� Flow commands like 'if-then-else´ and 'do-while'

� PowerFactory commands (i.e. load-flow or short-circuit commands)

� Input and output routines

� Mathematical expressions

� PowerFactory object procedure calls

� Subroutine calls

The Principle Structure of a DPL Command

The DPL Command Object

The DPL Script Editor

The DPL Script Language

Access to Other Objects

Access to Locally Stored Objects

Accessing the General Selection

Accessing External Objects

Remote Scripts and DPL Command Libraries

DPL Functions and Subroutines

G.1 The Principle Structure of a DPL Command

The principle Structure of a DPL script is shown in Figure G.1.

Fig. G.1: Principle of a DPL command

The DPL command object ComDpl is the central element, which is connecting different parameter, variables or objects to various functions or internal elements and then puts out results or changes parameters.

As the input to the script can be predefined input parameters, single objects from the single line diagram or the database or a set of objects/elements, which are then stored inside a so called "General Selection''.

These input information can then be evaluated using functions and internal variables inside the script. Also internal objects can be used and executed, like

� a calculation command, i.e. ComLdf, ComSim, etc., especially defined with certain calculation options

� subscripts also released in DPL

� filter sets, which can be executed during the operation of the script

Thus the DPL script will run a series of operation and start calculation or other function inside the script. It will always communicate with the database and will store changed settings, parameters or results directly in the database objects. There is nearly no object inside the active project, which can not be accessed or altered.

During or at the end of the execution of the DPL script, the results can be outputted or parameters of elements my be changed. There is the possibility to execute a predefined output command ComSh or to define own outputs with the DPL commands available.





G.2 The DPL Command Object

The DPL command object ComDpl holds a reference to a remote DPL command when it is not a root command. The example depicted in Figure G.2 is apparently a referring command, since its "DPL script'' reference is set to the remote command \ Library\ DPL Commands\ CheckVLoading.

Fig. G.2: A DPL command

� A root command has its own script on the "script'' page of the dialogue.

� A referring command uses the script of the remote DPL command.

G.2.1 Creating a new DPL Command

A DPL Command ComDpl can be created by using the "New Object'' ( ) icon in the toolbar of the data manager and selecting DPL Command and more. Then press OK and a new DPL command is created. The dialogue is now shown and the parameters, objects and the script can now be specified.

This dialogue is also opened by double-clicking a DPL script, by selecting Edit from the context sensitive menu or by selecting the script from the list when pressing the icon

.

G.2.2 Defining a DPL Commands Set

The DPL command holds a reference to a selection of objects (General Selection). At first this general selection is empty, but there are several ways to define a special set of object used in the DPL command. This "DPL Commands Set'' (SetSelect) can be specified through:

� Select one or more elements in the single line diagram. Then right-click the selection (one of the selected elements) and choose the option Define...−> DPL Commands Set... from the context sensitive menu.

� It is also possible to select several elements in the data manager. Right-click the selection and choose the option Define...−> DPL Commands Set... from the context sensitive menu.

G.2.3 Executing a DPL Command

To execute a DPL command or to access the dialogue of a script, the icon can be activated. This will pop up a list of available DPL scripts from the global and local library.

The easiest way to start a DPL command AND define a selection for it is

� To select one or more elements in the single line diagram or in the data manager and then right-click the selection.

� Choose the option Execute DPL Scripts from the context sensitive menu.

� Then select a DPL script from the list. This list will show DPL scripts from the global as well as from the local library.

� Select a DPL script, insert/change the variables and then press the button Execute

In this way the selection is combined into a DPL Commands Set and the set is automatically selected for the script chosen.

Only one single DPL command set is valid at a time for all DPL scripts. This means that setting the DPL command set in one DPL command dialogue, will change the DPL command set for all DPL commands in the database.







Note To choose different sets for various DPL scripts you can either use different selection object SetSelect like the "General Set''. Or new DPL command

sets can be created and selected inside the active study case. This is done by pressing , selecting "other'' and the element "Set (SetSelect)'' and then selecting the set type.

The interface section Input Parameters is used to define variables that are accessible from outside the DPL command itself. DPL commands that call other DPL commands as subroutines, may use and change the values of the interface variables of these DPL subroutines.

The list of External Objects is used to execute the DPL command for specific objects. A DPL command that, for example, searches the set of lines for which a short-circuit causes too deep a voltage dip at a specific busbar, would access that specific busbar as an external object. Performing the same command for another busbar would then only require setting the external object to the other busbar.

G.2.4 DPL Advanced Options

On the Advanced Options page a Remote script can be selected, which is then used by this script instead of a local defined script on the next page Script. This is a so called "referring command''. The "root command'' as described above in the example uses the local defined script.

Also there can be Result parameters defined. These parameters are results from the script and they are stored inside the result object. Hence it is possible to access them through the variable monitor and display them in a plot.

G.2.5 DPL Script Page

The most important part of a DPL root command is of course the actual DPL program script. That script is written on the Script page of a DPL root command dialogue, if no Remote script is selected.

On this page the DPL code of a already defined script is shown and/or new command lines can be inserted for modifying this script or writing a new script. The available commands and the DPL language are described in the following sections.

The edited program code also features a highlighting specially suited for handling DPL scripts.

G.3 The DPL Script Editor

There is also an own editor available for conveniently writing a DPL script. To activate this editor press the icon on the bottom side of the Script page of a DPL command dialogue.

Now a new window will be opened in PowerFactory. Here the script can be written in a very convenient way similar to the programming language C++. The highlighting will be activated automatically.

There are several tools which can be used in this editor:

With this icon "Edit Object'' the edit dialogue of the script is opened and the user can Check the modified script for errors or one can Execute it.

The script inside the editor and in the dialogue are synchronized each time the script is saved or edited in the dialogue. If this "Disconnect'' icon is pressed, the scripts will not be synchronized anymore.

With the "search'' icon the user can activate a Find, a Replace or also a Go To function inside the editor.

With the "search next'' icon find/replace/go to the next matching word.

With the "search previous'' icon find/replace/go to the previous matching word.

With the these icons bookmarks can be set in the editor. Also jump from one bookmark to the next or previous as well as clear all bookmarks.

When finished editing, press the icon and the script will be synchronized with the main dialogue. One can also jump to the main graphics board by selecting the option Window −> Graphic... from the main menu.

G.4 The DPL Script Language

The DPL script language uses a syntax quite similar to the C++ programming language. This type of language is intuitive, easy to read, and easy to learn. The basic command set has been kept as small as possible.

The syntax can be divided into the following parts:

� variable definitions

� assignments and expressions

� program flow instructions

� method calls

The statements in a DPL script are separated by semicolons. Statements are grouped together by braces.

Example:

statement1; statement2; if (condition) { groupstatement1; groupstatement2; }





DIgSILENT GmbH www.digsilent.de Tel: +49 (0)7072 9168-50 Fax: +49 (0)7072 9168-88



G.4.1 Variable Definitions

DPL uses the following internal parameter types

� double, a 15 digits real number

� int, an integer number

� string, a string

� object, a reference to a PowerFactory object

� set, a container of objects

Vectors and Matrices are available as external objects.

The syntax for defining variables is as follows: [VARDEF] = [TYPE] varname, varname, ..., varname; [TYPE] = double | int | object | set

All parameter declarations must be given together in the top first lines of the DPL script. The semicolon is obligatory.

Examples: double Losses, Length, Pgen; int NrOfBreakers, i, j; string txt1, nm1, nm2; object O1, O2, BestSwitchToOpen; set AllSwitches, AllBars;

G.4.2 Constant parameters

DPL uses constant parameters which cannot be changed. It is therefore not accepted to assign a value to these variables. Doing so will lead to an error message.

The following constants variables are defined in the DPL syntax:

SEL is the general DPL selection

NULL is the 'null' object

this is the DPL command itself

Besides these global constants, all internal and external objects are constant too.

G.4.3 Assignments and Expressions

The following syntax is used to assign a value to a variable: variable = expression variable += expression variable -= expression

The add-assignment "+='' adds the right side value to the variable and the subtract-assignment "-='' subtracts the right-side value.

Examples:

double x,y;x = 0.5*pi(); ! x now equals 1.5708 y = sin(x); ! y now equals 1.0 x += y; ! x now equals 2.5708 y -= x; ! y now equals -1.5708

G.4.4 Standard Functions

The following operators and functions are available:

� Arithmetic operators: +, -, *, /

� Standard functions ( all trigonometric functions based on radians (RAD)):

[email protected]




function description example

sin(x) sine sin(1.2)=0.93203

cos(x) cosine cos(1.2)=0.36236

tan(x) tangent tan(1.2)=2.57215

asin(x) arcsine asin(0.93203)=1.2

acos(x) arccosine acos(0.36236)=1.2

atan(x) arctangent atan(2.57215)=1.2

sinh(x) hyperbolic sine sinh(1.5708)=2.3013

cosh(x) hyperbolic cosine cosh(1.5708)=2.5092

tanh(x) hyperbolic tangent tanh(0.7616)=1.0000

exp(x) exponential value exp(1.0)=2.718281

ln(x) natural logarithm ln(2.718281)=1.0

log(x) log10 log(100)=2

sqrt(x) square root sqrt(9.5)=3.0822

sqr(x) power of 2 sqr(3.0822)=9.5

pow (x,y) power of y pow(2.5, 3.4)=22.5422

abs(x) absolute value abs(-2.34)=2.34

min(x,y) smaller value min(6.4, 1.5)=1.5

max(x,y) larger value max(6.4, 1.5)=6.4

modulo(x,y) remainder of x/y modulo(15.6,3.4)=2

trunc(x) integral part trunc(-4.58823)=-4.0000

frac(x) fractional part frac(-4.58823)=-0.58823

round(x) closest integer round(1.65)=2.000

ceil(x) smallest larger integer ceil(1.15)=2.000



Table. G.1: DPL Standard Functions

� Constants:

Table. G.2: DPL Internal Constants

G.4.5 Program Flow Instructions

The following flow commands are available. if ( [boolexpr] ) [statlist] if ( [boolexpr] ) [statlist] else [statlist] do [statlist] while ( [boolexpr] ) while ( [boolexpr] ) [statlist] for ( statement ; [boolexpr] ; statement ) [statlis t]

in which [boolexpr] = expression [boolcomp] expression [boolcomp] = "<" | ">" | "=" | ">=" | ">=" | "<>" [statlist] = statement; | { statement; [statlist] }

� Unary operators: ".not."

� Binary operators: ".and." | ".or." | ".nand." | ".nor." | ".eor."

� Parentheses: {logical expression}

Examples: if (a<3) { b = a*2; } else { b = a/2; } while (sin(a)>=b*c) { a = O:dline; c = c + delta; } if ({.not.a}.and.{b<>3}) { err = Ldf.Execute(); if (err) { Ldf:iopt_lev = 1; err = Ldf.Execute(); Ldf:iopt_lev = 0; } } for (i = 0; i < 10; i = i+1){ x = x + i; } for (o=s.First(); o; o=s.Next()) { o.ShowFullName(); }

Break and Continue

The loop statements 'do-while' and 'while-do' may contain 'break' and 'continue' commands. The 'break' and 'continue' commands may not appear outside a loop statement.

The 'break' command terminates the smallest enclosing 'do-while' or 'while-do' statement. The execution of the DPL script will continue with the first command following the loop statement.

The 'continue' command skips the execution of the following statements in the smallest enclosing 'do-while' or 'while-do' statement. The execution of the DPL script is continued with the evaluation of the boolean expression of the loop statement. The loop statement list will be executed again when the expression evaluates to TRUE. Otherwise the loop statement is ended and the execution will continue with the first command following the loop statement.

Example: O1 = S1.First(); while (O1) { O1.Open(); err = Ldf.Execute(); if (err) { ! skip this one O1 = S1.Next; continue; } O2 = S2.First(); AllOk = 1; DoReport(0); !reset while (O2) { err = Ldf.Execute(); if (err) { ! do not continue AllOk = 0; break; } else { DoReport(1); ! add } O2 = S2.Next(); } if (AllOk) { DoReport(2); ! report } O1 = S1.Next();}

G.4.6 Input and Output

The "input'' command asks the user to enter a value. input(var, string);

The input command will pop up a window with the string and an input line on which the user may enter a value. The value will be assigned to the variable "var''.

The "output'' command writes a line of text to the output window. output(string);

The string may contain "=''-signs, followed by a variable name. The variable name will then be replaced by the variable's value.

Example: input(diameter, 'enter diameter'); output('the entered value=diameter');

The example results in the pop up of a window as depicted in Figure G.3.

floor(x) largest smaller integer floor(1.78)=1.000

pi() pi

twopi() 2 pi

e() e





Fig. G.3: The input window

The following text will appear in the output window: DIgSI/dpl - the entered value=12.3400

The output command is considered obsolete and has been replaced by the more versatile "printf'' and "sprintf'' functions. Please see the DPL reference for detailed information.

G.5 Access to Other Objects

With the syntax for the parameter definitions, program flow and the input and output, it is already possible to create a small program. However, such a script would not be able to use or manipulate variables of 'external' objects. It would not be possible, for instance, to write a script that replaces a specific line by possibly better alternatives, in order to select the best line type. Such a script must be able to access specific objects (the specific line) and specific sets of objects (the set of alternative line types).

The DPL language has several methods with which the database objects and their parameters become available in the DPL script:

� The most direct method is to create an object, or a reference to an object, in the DPL command folder itself. Such an object is directly available as "object'' variable in the script. The variable name is the name of the object in the database.

� The DPL command set may be used. This method is only useful when the order in which the objects are accessed is not important. The DPL command set is automatically filled when a selection of elements is right-clicked in either the single line graphic or the data manager and the option Execute DPL Script is selected.

� The list of external objects is mainly used when a script should be executed for specific objects or selections. The list of external objects is nothing more than a list of 'aliases'. The external object list is used to select specific objects for each alias, prior to the execution of the script.

G.5.1 Object Variables and Methods

If a database object is known to the DPL command, then all its methods may be called, and all its variables are available. For example, if we want to change a load-flow command in order to force an asymmetrical load-flow calculation, we may alter the parameter "iopt_net''. This is done by using an assignment:

Ldf:iopt_net = 1; ! force unbalanced

In this example, the load-flow objects is known as the objects variable "Ldf''.

The general syntax for a parameter of a database object is objectname:parametername

In the same way, it is possible to get a value from a database object, for instance a result from the load-flow calculations. One of such a result is the loading of a line object, which is stored in the variable "c:loading''. The following example performs the unbalanced load-flow and reports the line loading.

Example 00. int error; 01. double loading; 02. Ldf:iopt_net = 1; ! force unbalanced 03. error = Ldf.Execute(); ! execute load-flow 04. if (error) { 05. exit(); 06. } else { 07. loading = Line:c:loading; ! get line loading 08. output('loading=loading'); ! report line load ing 09. }

This examples is very primitive but it shows the basic methods for accessing database objects and their parameters.

G.6 Access to Locally Stored Objects

Locally stored objects (also called 'internal objects') can be accessed directly. They are known in the DPL script under their own name, which therefore must be a valid DPL variable name. It will not be possible to access an internal object which name is "My Load-flow\~{}1*'', for instance.

Internal objects may also be references to objects which are stored elsewhere. The DPL command des not distinguish between internal objects and internal references to objects.

An example is shown in Figure G.4, where a DPL script is shown on the left which has a load-flow command and a reference to a line in its contents folder on the right.

Fig. G.4: DPL contents

The example DPL script may now access these objects directly, as the objects "Ldf'' and "Line''. In the following example, the object "Ldf'', which is a load-flow command, is used in line 01 to perform a load-flow.

00. int error; 01. error = Ldf.Execute(); 02. if (error) { 03. output('Load-flow command returns an error'); 04. exit(); 05. }

In line 01, a load-flow is calculated by calling the method "Execute()'' of the load-flow command. The details of the load-flow command, such as the choice between a balanced single phase or an unbalanced three phase load-flow calculation, is made by editing the object "Ldf'' in the database. Many other objects in the database have methods which can be called from a DPL script. The DPL contents are also used to include DPL scripts into other scripts and thus to create DPL "subroutines''.

G.7 Accessing the General Selection







Accessing database objects by storing them or a reference to them in the DPL command would create a problem if many objects have to be accessed, for instance if the line with the highest loading is to be found. It would be impractical to create a reference to each and every line.

A more elegant way would be to use the DPL global selection and fill it with all lines. The data manager offers several ways in which to fill this object DPL Command Set with little effort. The selection may then be used to access each line indirectly by a DPL "object'' variable. In this way, a loop is created which is performing the search for the highest loading. This is shown in the following example.

Example 00. int error; 01. double max; 02. object O, Omax; 03. set S; 04. 05. error = Ldf.Execute(); ! execute a load-flow 06. if (error) exit(); ! exit on error 07. 08. S = SEL.AllLines(); ! get all selected li nes 09. Omax = S.First(); ! get first line 10. if (Omax) { 11. max = Omax:c:loading; ! initialize maximum 12. } else { 13. output('No lines found in selection'); 14. exit(); ! no lines: exit 15. } 16. O = S.Next(); ! get next line 17. while (O) { ! while more lines 18. if (O:c:loading>max) { 19. max = O:c:loading; ! update maximum 20. Omax = O; ! update max loaded l ine 21. } 22. O = S.Next(); 23. } 24. output('max loading=max for line'); !output res ults 25. Omax.ShowFullName();

The object SEL used in line 08 is the reserved object variable which equals the General Selection in the DPL command dialogue. The SEL object is available in all DPL scripts at all times and only one single "General Selection'' object is valid at a time for all DPL scripts. This means that setting the General Selection in the one DPL command dialogue, will change it for all other DPL commands too.

The method "AllLines()'' in line 08 will return a set of all lines found in the general selection. This set is assigned to the variable "S''. The lines are now accessed one by one by using the set methods "First()'' and "Next()'' in line 09, 16 and 22.

The line with the highest loading is kept in the variable "Omax''. The name and database location of this line is written to the output window at the end of the script by calling "ShowFullName()''.

G.8 Accessing External Objects

The DPL contents make it possible to access external object in the DPL script. The special general selection object ("SEL'') is used to give all DPL functions and their subroutines access to a central selection of objects. i.e. the DPL Command Set.

Although flexible, this method would create problems if more than one specific object should be accessed in the script. By creating references to those objects in the DPL command itself, the DPL command would become specific to the current calculation case. Gathering the objects in the general selection would create the problem of selecting the correct object.

To prevent the creation of calculation-specific DPL commands, it is recommended practice to reserve the DPL contents for all objects that really 'belong' to the DPL script and which are thus independent on where and how the script is used. Good examples are load-flow and short-circuit commands, or the vector and matrix objects that the DPL command uses for its computations.

If a DPL script must access a database object dependent on where and how the DPL script is used, an "External Object'' must be added to the external object list in the DPL root command. Such an external object is a named reference to an external database object. The external object is referred to by that name. Changing the object is then a matter of selecting another object.

In Figure G.5, an example of an external object is given. This external object may be referred to in the DPL script by the name "Bar1'', as is shown in the example.

Fig. G.5: DPL external object table

Example: sagdepth = Bar1:u;

G.9 Remote Scripts and DPL Command Libraries

To understand the DPL philosophy and the resulting hierarchical structure of DPL scripts, the following is important to understand:

� A DPL command either executes its own script or the script of another, remote, DPL command. In the first case, the DPL command is called a 'root command' and the script is called a 'local script' . In the second case, the DPL command is called a 'referring' command and the script is called a 'remote script' .

� A root command may define interface variables that are accessible from outside the script and which are used to define default values.

� Each root command may define one or more external objects . External object are used to make a DPL command run with specific power system objects, selections, commands, etc.

� A referring command may overrule all default interface values and all selected external objects of the remote command.

� Each DPL command can be called as a subroutine by other DPL commands.

The use of remote scripts, external objects and interface variables makes it possible to create generic DPL commands, which may be used with different settings in many different projects and study cases.

The easiest way to develop a new DPL command is to create a new ComDpl in the currently active study case and to write the script directly in that DPL object. In such a way, a DPL "root command'' is made. If this root command needs DPL subroutines, then one or more DPL command objects may be created in its contents. Each of these subroutines will normally also be written as root functions.

The newly written DPL command with its subroutines may be tested and used in the currently active study case. However, it cannot be executed when another study case is active. In order to use the DPL command in other study cases, or even in other projects, one would have to copy the DPL command and its contents. This, however, would make it impossible to alter the DPL command without having to alter all its copies.

The solution is in the use of 'remote scripts'. The procedure to create and use remote scripts is described as follows.

Suppose a new DPL command has been created and tested in the currently active study case. This DPL command can now be stored in a save place making it possible to use it in other study cases and projects.

This is done by the following steps:

� Copy the DPL command to a library folder. This will also copy the contents of the DPL command, i.e. with all it's DPL subroutines and other locally stored objects.





� "Generalize'' the copied DPL command by resetting all project specific external objects. Set all interface variable values to their default values. To avoid deleting a part of the DPL command, make sure that if any of the DPL (sub)commands refers to a remote script, all those remote scripts are also stored in the library folder.

� Activate another study case.

� Create a new DPL command object (ComDPL) in the active study case.

� Set the "DPL script'' reference to the copied DPL command.

� Select the required external objects.

� Optionally change the default values of the interface variables

� Press the Check button to check the DPL script

The Check or Execute button will copy all parts of the remote script in the library that are needed for execution. This includes all subroutines, which will also refer to remote scripts, all command objects, and all other objects. Some classes objects are copied as reference, other classes are copied completely.

The new DPL command does not contain a script, but executes the remote script. For the execution itself, this does not make a change. However, more than one DPL command may now refer to the same remote script. Changing the remote script, or any of its local objects or sub-commands, will now change the execution of all DPL commands that refer to it.

G.9.1 Subroutines and Calling Conventions

A DPL command object may be included in the contents of another DPL command. In that case, the included DPL "subroutine'' may be called in the script of the enclosing DPL command. In principle, this is not different from calling, for example, a load-flow command from a DPL script.

As with most other command objects, the DPL command only has one method:

int Execute() ; executes the DPL script.

The difference is that each DPL subroutine has different interface parameters, which may be changed by the calling command. These interface parameters can also be set directly at calling time, by providing one or more calling arguments. These calling arguments are assigned to the interface parameters in order of appearance. The following example illustrates this.

Suppose we have a DPL sub-command "Sub1'' with the interface section as depicted in Figure G.6.

Fig. G.6: Interface section of subroutine

The calling command may then use, for example: ! set the parameters: Sub1:step = 5.0; Sub1:Line = MyLine; Sub1:Outages = MySelection; ! execute the subroutine: error = Sub1.Execute();

However, using calling arguments, we may also write: ! execute the subroutine: error = Sub1.Execute(5.0, MyLine, MySelection);

G.10 DPL Functions and Subroutines

The DPL syntax is very small because it mainly serves the purpose of basic operations like simple calculations, if-then-else selections, do-while loops, etc..

The strength of the DPL language is the possibility to call functions and to create subroutines. A function which can be called by a DPL command is called a "method''. Four types of methods are distinguished:

Internal methods These are the build-in methods of the DPL command. They can always be called.

Set methods These methods are available for the DPL 'set' variables.

Object methods These methods are available for the DPL 'object' variables.

External methods These are the methods which are available for certain external PowerFactory objects, such as the load-flow command, the line object, the asynchronous machine, etc.

Please see the DPL Reference for a description of these functions including implementation examples.

Appendix H DPL Reference

General Functions

Input / Output Functions and Methods

String Functions

Project Functions and Methods

Study Case Functions and Methods

General Object Functions and Methods

Set Functions and Methods

Analysis Command Functions and Methods

Specialized Methods for Elements and Types

Methods for Virtual Instruments

Methods for Additional Objects (Int*)

DDE Functions




DIgSILENT GmbH www.digsilent.de Tel: +49 (0)7072 9168-50 Fax: +49 (0)7072 9168-88



H.1 General Functions

exit Terminates a DPL script immediately.

GetTime Returns current processor time.

GetLanguage Returns the current language.

GetGlobalLib Returns a global library folder.

Random Returns a random number.

SetRandSeed Initializes the random number generator.

fRand Returns stochastic numbers according to a probability distribution.

exit

exit ()

The exit() command terminates a DPL script immediately. If called within a subscript, only the subscript itself will be terminated. In this case, execution will continue in the calling parent script.

Arguments:

The exit() command has no arguments.

Return value:

The exit() command has no return value.

Example: int in; int sum; !sums up all entered numbers while(1){ input(in, 'Enter a number please (<0 to stop)'); if (in < 0){ !negative number entered, so calc su m and stop printf('Sum: %d', sum); exit(); !terminate script here } sum += in; }

GetTime

int GetTime (int iN)

Returns current processor time.

Arguments:

int iN (obligatory) : precision after decimal point

Return value:

Current processor time in seconds

GetLanguage

int GetLanguage ()

Returns the current program language setting.

Arguments:

none

Return value:

0 = English, 1 = German

Example:

The following example displays a different message, depending on the language. int err, lng; lng = GetLanguage(); err = Ldf.Execute(); if (err) { if (lng) { output('Load-flow command returned an error') ; } else { output('Fehler im Lastfluss Kommando'); } exit(); }

GetGlobalLib

object GetGlobalLib ([string ClassName])

Returns the global library for object-types of class "ClassName''. ClassName may be omitted, in which case the complete global library folder is returned.

Arguments:

string ClassName (optional) : The classname of the objects for which the library folder is sought

Return value:

The library folder

Example:

The following example shows the contents of the global library for line types. object Lib, O; set S; Lib = GetGlobalLib('TypLne'); S = lib.GetContents(); O = S.First(); while (O) { O.ShowFullName(); O = S.Next(); }

Also see "GetLocalLib'' .

Random

double Random ([double x1 [,double x2]])

Returns a pseudo random value. If x1 and x2 are omitted, a value in the range of [0 ... 1] is returned. If only x1 is given, the possible range is [0 ... x1] and with both x1 and x2, [x1 ... x2].

Arguments:

double x1 (optional) : upper/lower limit

double x2 (optional) : upper limit

Return value:

A pseudo-random number

Example:

The following example sets a load to a random active power prior to calculating a load-flow. double P; Load:plini = Random(1.2, 2.3); Ldf.Execute();

SetRandSeed

void SetRandSeed (int N)

Initializes the random number generator. One out of 10 predefined initialization seeds can be selected.

Arguments:

[email protected]



int N (obligatory) : seed 0..10

Example:

See fRand()

fRand

double fRand (int mode | double p1 | double p2)

Returns a stochastic number according to a specific probability distribution.

Arguments:

int mode (obligatory) :

double p1 (obligatory) :

double p1 (obligatory) :

Return value:

void

Example:

The following example prints random numbers for the following distributions: uni0 : an uniform distribution in [0..1] uni1 : an uniform distribution in [0..50] uni2 : an uniform distribution in [-8, 21]; norm : a normal distribution with mean=30 and sta ndard variance=5 weib : a Weibull distribution with lambda=5 and b eta=30 int n; double uni0,uni1,uni2,norm,weib; SetRandSeed(2); for (n=0; n<10; n+=1) { uni0 = fRand(0); uni1 = fRand(0, 50); uni2 = fRand(0, -8, 21); norm = fRand(1, 30, 5); weib = fRand(2, 5, 30); printf('%f %f %f %f %f', uni0, uni1, uni2, norm, weib);}

Results Output: 0.232422 20.225048 20.364702 32.294429 15.165993

0.877555 31.371372 11.501229 28.380458 26.404837

0.901226 15.313008 14.782988 23.883499 34.911052

0.598748 17.908476 -6.831869 28.314934 20.706127

0.588662 35.265549 6.403110 25.233148 16.437912

0.474393 44.846884 20.024787 35.297444 22.190684

0.122955 24.725714 -6.099016 28.535867 27.149573

0.554570 17.020344 13.658290 32.858903 30.625329

0.920789 47.127992 0.749566 28.616229 21.187893

0.609307 11.819403 -6.716297 37.955694 29.645523

H.2 Input / Output Functions and Methods

Writing into the Output Window

Additional Functions related to input/output

Writing to Files

SetDesktop Methods

See also: String Functions

H.2.1 Writing into the Output Window

ClearOutput Clears the output window.

printf Outputs a formatted string.

Write Writes a report.

Error Outputs a formatted error.

Warn Outputs a formatted warning.

Info Outputs a formatted information.

SetLineFeed Sets the automatic line feed for "printf()''.

ClearOutput

void ClearOutput ()

Clears the output window.

Arguments:

none

Return value:

void (no return value)

Example:

The following command clears the output window. ClearOutput();

printf

void printf (String Format, String T | double X | int I, ...)

Table H.1:

0: uniform distribution

1: normal distribution

2: weibull distribution

else: returns 0.0

Table H.2:

uniform normal weibull

p1 min mean shape

p2 max stdvar scale





Outputs a formatted string. The printf() command uses the C++ printf() formatting syntax.

Arguments:

String Format (obligatory): The format string

String T (optional): string argument

double X (optional): double argument

int I (optional): int argument

Return value:

void

Example:

See the format string syntax for examples and more information.

The output format is defined by the format string. The passed arguments and the passed format string must match. An error message will be produced when, for instance, a format string for two strings is used together with three doubles.

The 'printf' will automatically insert a line-break after printing by default. This means that the next 'printf' will start on the next line. The automatic line-break can be disabled by using the "SetLineFeed''-function.

See "SetLineFeed'' for more information.

Also see "sprintf'' .

Also see "fprintf'' .

Also see "Error'' .

Also see "Warn'' .

Also see "Info'' .

Also see "Write'' .

Write

int Write (string Format, [object aObj | set aSet], ...)

Writes out a line of formatted text, using the DIgSILENT output language.

Arguments:

string Format (obligatory): The format string

object aObj (optional): An object which is used to get data from

set aSet (optional): A set which is used to get objects from

Return value:

0 on success, 1 on error

The "Write'' command is used to quickly output a line of formatted output, using the same formatting language as is used for defining reports and result-boxes. See Section 20.2.3 for more information.

Because data or parameters of more than object is often written out, the DIgSILENT output language has the special macro "ACC(x)'' to distinguish between these objects. Prior to execution, all given objects and all objects in the given sets are listed together in a single list. The "ACC(x)'' macro returns the object with the index "x'' in that list. The ACC ("acc''="access'') macro can be used more than once for the same object.

Interface variables of the DPL script can also be used in the format string by the "DEF'' macro. If the DPL script has "ResX'' as an interface double, then "DEF:ResX'' will access that variable.

Example:

In the following example, two lines of output are written out. The first line only contains normal text. The second line writes the name and loading of two lines. In this example, "ACC(1)'' refers to the object "LineA', and "ACC(2)'' to "LineB''

Write('The following results are found'); Write('# : #.## # , # : #.## # $N, ACC(1):loc_name,ACC(1):c:loading,[ACC(1):c:loading, ACC(2):loc_name,ACC(2):c:loading,[ACC(2):c:loadi ng', LineA, LineB);

Also see "printf'' .



Also see "Error'' .

Also see "Warn'' .

Also see "Info'' .

Error

string Error (String Format,String T | double X | int I, ...)

Writes a formatted string as error message to the output window. The DPL execution will continue, but a pop-up error message box will appear at the end of execution.

Arguments:





Return value:

The formatted string

Example:

The following example writes an error to the output window. Error('Index could not be calculated.');


See the format string syntax for more information.




Also see "Warn'' .

Also see "Info'' .

Also see "Write'' .

Warn

string Warn(String Format, String T | double X | int I, ...)

Writes a formatted string as warning to the output window.

Arguments:







Return value:


Example:

The following example writes a warning message to the output window. Warn('No loads attached: using approximation.');






Also see "Error'' .

Also see "Info'' .

Also see "Write'' .

Info

string Info (String Format, String T | double X | int I, ...)

Writes a formatted string as information message to the output window.

Arguments:

String Format (obligatory) : The format string

String T (optional) : string argument

double X (optional) : double argument

int I (optional) : int argument

Return value:


Example:

The following example writes an info message to the output window. Info('Trying to calculate first index...');






Also see "Error'' .

Also see "Warn'' .

Also see "Write'' .

SetLineFeed

void SetLineFeed (int i)

Sets or resets the automatic line feed for printf().

Arguments:

int i (obligatory) : use '0' to disable the automatic line feed, use '1' to enable it again.

Return value:

void

Example:

The following example disables the automatic line feed prior to printing a matrix of numbers. The special character '\n' is used to force a line feed. int i,j; SetLineFeed(0); ! disable line-feed for (i=0; i<3; i+=1) { printf('%2d', i); for (j=1; j<5; j+=1) { printf('\t%2d', i+j); } printf('\n'); ! insert a line-feed }


H.2.2 Additional Functions related to input/output

EchoOn Re-activates the user interface

EchoOff Freezes (de-activates) the user-interface.

NoFinalUpdate Prevents "EchoOn()'' at end of execution.

GetPageLen Returns the number of lines per page.

EchoOn

void EchoOn ()

Re-activates the user interface.

Arguments:

none

Return value:

void

Example:

The following example de-activates the user-interface to speed up the calculations, after which the user-interface is re-activated again. EchoOff(); .. do some calculation ... EchoOn();

Also see "EchoOff()'' .

Also see "NoFinalUpdate()'' .

EchoOff




void EchoOff ()

Freezes (de-activates) the user-interface. For each EchoOff(), an EchoOn() should be called. An EchoOn() is automatically executed at the end of a DPL execution, except for when "NoFinalUpdate()'' has been called.

Arguments:

none

Return value:

void

Example:

The following example de-activates the user-interface to speed up the calculations, after which the user-interface is re-activated again. EchoOff(); .. do some calculation ... EchoOn();

Also see "EchoOn()'' .

Also see "NoFinalUpdate()'' .

NoFinalUpdate

void NoFinalUpdate ()

Prevents the automatic "EchoOn()'' at end of execution.

Arguments:

none

Return value:

void

Example: EchoOff(); .. do some calculation ... NoFinalUpdate();

Also see "EchoOff()'' .

Also see "EchoOn()'' .

GetPageLen

int GetPageLen (int orientation)

Returns the number of lines per page according to the currently selected printer and paper size.

Arguments:

int orientation (optional) : Paper orientation: 0: landscape, 1: portrait ; default: landscape

Return value:

The maximum number of lines that can be printed on a single sheet of paper.

H.2.3 Writing to Files

fprintf Outputs a formatted string to a file.

fscanf Assigns fields in file and returns number of fields.

fscanfsep Assigns fields in file and returns number of fields. Considers separation character and stops after max. number of positions given.

fopen Opens a file from a path.

fclose Closes an open file.

fprintf

void fprintf (int iFH, string Format, string T | double X | int I, ...)

Writes a formatted string to a file. The fprintf() command uses the C++ printf() formatting syntax.

Arguments:

int iFH (obligatory): Number of file handler (0,1,...,9)

string Format (obligatory): Defines a format of variable types (int/string/double) to which the fields are assigned

string T (optional): Return of the result string

double X (optional): Return of the result double

int I (optional): Return of the result integer

Return value:

A return value of 0 indicates that no fields were assigned. The return value is -1 for an error or if the end of the string is reached before the first conversion.

Example:


The following example outputs a defined string to a file. double x; int i; string s; fopen('d:\tmp\test.txt','r',0); x = 123456789.987654321; i = 2468; s = 'hello dpl'; fprintf(0,'string:%s int=%d double=%f', s,i,x); fclose(0);





Also see "Error'' .

Also see "Warn'' .

Also see "Info'' . Also see "Write'' .

fWrite

The command "fWrite'' is obsolete and has been replaced by the "printf'' command. See "printf'' for more information.

fscanf

int fscanf (int iFH, string Format, string T | double X | int I, ...)

Returns the number of fields successfully converted and assigned; the return value does not include fields that were read but not assigned.

Arguments:




int iFH (obligatory) : Number of file handler (0,1,...,9)

string Format (obligatory) : Defines a format of variable types (int/string/double) to which the fields are assigned

string T (optional) : Return of the result string

double X (optional) : Return of the result double

int I (optional) : Return of the result integer

Return value:


Example:

The following example assignes the first to fields of the text file 'test.txt' (contents: 'Name 12.333') to the string sRes and the double rVal fopen('d:\tmp\test.txt','r',0); iRet = fscanf(0,'%s %d',sRes,rVal); printf('%s %.1f iRet = %d',sRes,rVal,iRet); fclose(0);

Output of the script above: Name 12.3 iRet = 0

fscanfsep

int fscanfsep(int iFH, string Ft, string T | double X | int I, ..., string sSep, int iLine)

Functionality like fscanf. Returns the number of fields successfully converted and assigned; the return value does not include fields that were read but not assigned. This function additionally considers a special character to separate the values, instead of the standard separators like blanks and tabs. It also can be instructed to stop after the line read.

Arguments:


string Ft (obligatory) : Defines a format of variable types (int/string/double) to which the fields are assigned




string sSep : separator character

int iLine (obligatory) : 1 if the interpretation of the line will be stopped after the current line. 0 for continued interpretation.

Return value:


Example: int iRet; string sRes; fopen('c:\test1.txt','r',0); SetLineFeed(0); while (iRet > -1){ iRet = fscanfsep(0,'%s',sRes,';',1); if (iRet = -1){ break; } printf('%s\n',sRes); } fclose(0);

fopen

int fopen (string Path, string Mode, int iFH, int iRet)

Opens file with attribute Mode and assigns an ID iFH of the file handler to the open file.

Arguments:

string Path (obligatory): Path of file to open. Path must exist. File could be created depending on the Mode

string Mode (obligatory): The attribute for opening the file (r,w,a,r+,w+,a+,b,t)

int iFH (obligatory): Number of file handler (0,1,...,9)

int iRet (optional): If it is set to 0 or no value is given, the function does not return any value. If different that 0, value is returned

Return value:

0 on success, 1 on error

Example:

The following example opens a file and closes it again. fopen('d:\tmp\test.txt','r',0); iRet = fscanf(0,'%s %d',sRes,rVal); printf('%s %.1f iRet = %d',sRes,rVal,iRet); fclose(0);

fclose

void fclose (int iFH)

Closes file with the ID iFH of the file handler (between 0 and 9).

Arguments:


Return value:

void

Example:

The following example opens a file and closes it again. fopen('d:\tmp\test.txt','r',0); iRet = fscanf(0,'%s %d',sRes,rVal); printf('%s %.1f iRet = %d',sRes,rVal,iRet); fclose(0);

H.2.4 SetDesktop Methods

SetDesktop.Show

SetDesktop.WriteWMF

SetDesktop.GetPage

SetDesktop.SetResults

SetDesktop.SetXVar

SetDesktop.SetScaleX

SetDesktop.DoAutoScaleX

SetDesktop.SetAutoScaleX

SetDesktop.SetAdaptX




SetDesktop.Show

int SetDesktop.Show ([string name|object O])

Shows the page with the same name as 'O'' or the page with name "name'' in the Graphics Board. The object "O'' is typically a ViPage object but, as only its name is used, it may be any other type of object.

Arguments:

string name (obligatory) : Name of graphics page.

object O (optional) : An object.

Return value:

0 on success, 1 on error.

Example:

The following example activates all pages in the graphics board one by one and exports them as WMF figures. object GrBrd,Pg; set Pgs; int n; string FileName; GrBrd = GetGraphBoard(); if (GrBrd) { Pgs = GrBrd.GetContents(); Pg = Pgs.First(); while (Pg) { GrBrd.Show(Pg); FileName = sprintf('c:\\mydoc\\%s%d', n, Pg:l oc_name); GrBrd.WriteWMF(FileName); Pg = Pgs.Next(); } }

Also see Set Functions and Methods

SetDesktop.WriteWMF

void SetDesktop.WriteWMF (string filename)

Exports the currently open graphic in the graphics board to a WMF figure.

Arguments:

string name (obligatory) : Filename without extension.

Return value:

none

Example:

See SetDeskTop.Show()


SetDesktop.GetPage

object SetDesktop.GetPage (string name, int create)

Searches, activates and returns a graphics page in the currently open Graphics Board. If "create'' is true, then a new ViPage will be created added to the graphics board when no page with the name was found.

Arguments:

string name (obligatory) : Name of the page.

int create=1 (optional) : create > 0 --> create panel if not exists.

Return value:

Virtual Instrument Panel (SetVipage)

Example:

The following example looks for the Virtual Instrument Panels named Voltage, Current and Power in the Graphics Board currently opened. The pages are created if they do not exist.

object aGrf; object aPageV; object aPageC; object aPageP; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Search or create Virtual Instrument Panels aPageV=aGrf.GetPage('Voltage',1); aPageC=aGrf.GetPage('Current',1); aPageP=aGrf.GetPage('Power',1); }


SetDesktop.SetResults

void SetDesktop.SetResults (object res)

Sets default Results (ElmRes) of Graphics Board.

Arguments:

object res (obligatory) : Results to set (ElmRes) or NULL to reset.

Return value:

none

Example:

The following example looks for an opened Graphics Board and sets its default results to the results object named 'Results'. object aGrf; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Set default results object aGrf.SetResults(Results); }


SetDesktop.SetXVar

void SetDesktop.SetXVar (object obj, string varname)

Sets x-axis variable. If obj and varname are empty the default x-axis variable (time) is set.

Arguments:

object obj (optional) : x-axis object

string varname (optional) : variable of obj

Return value:

none

Example:

The following examples look for an opened Graphics Board and set its x-axis variable. The first example sets an user defined x-axis variable. The second one sets the default x-axis (time).

object aGrf; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Set user defined x - axis variable



aGrf.SetXVar(line,'m:U1:bus1'); } object aGrf; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Set default x-axis variable (time) aGrf.SetXVar(); }


SetDesktop.SetScaleX

void SetDesktop.SetScaleX (double min, double max, int log)

Sets scale of x-axis. Invalid arguments like neg. limits for log. scale are not set. No arguments --> automatic scaling.

Arguments:

double min (optional) : Minimum of x-scale.

double max (optional) : Maximum of x-scale.

int log (optional) : > 0 --> x-scale is logarithmic.

Return value:

none

Example:

The following examples look for an opened Graphics Board and set its x-axis scale. There are three different examples. 1. Example: Scale x-axis automatically 2. Example: Set minimum to 0 and maximum to 20. 3. Example: Set minimum to 1 and maximum to 1000. Changes to a log. scale

! Scale x-axis automatically object aGrf; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Scale automatically aGrf.SetScaleX(); } ! Set minimum and maximum without changing map mode object aGrf; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Set minimum and maximum aGrf.SetScaleX(2,10); } ! Set minimum and maximum, change to log. scaleobject aGrf; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Set minimum and maximum aGrf.SetScaleX(1,1000,1); }


SetDesktop.DoAutoScaleX

int SetDesktop.DoAutoScaleX ()

Scales the x-axes of all plots in the graphics board which use the x-axis scale defined in the graphics board. The same can be achieved by pressing the Scale button on the x-Axis page of the graphics board.

Arguments:

none

Return value:

none

Example:

The following example looks for a page named voltage and performs an automatic scaling of the x-axes. ! perform autoscale of x-scales of all plots ! using the x-scale definition of the graphics boar d. object aGrf; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { aGrf.DoAutoScaleX(); }

Also see

VisFft Methods

VisPlot Methods

SetViPage Methods

SetDesktop.SetAutoScaleX

void SetDesktop.SetAutoScaleX (int mode)

Sets the automatic scaling mode of the x-scale.

Arguments:

int mode (obligatory) : Possible values: 0 never, 1 after simulation, 2 during simulation

Return value:

none

Example:

The following example looks for an opened Graphics Board and sets its auto scale mode to off. ! Set autoscale mode to offobject aGrf; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Turn off automatic scaling of x-scale aGrf.SetAutoScaleX(0); }


SetDesktop.SetAdaptX

void SetDesktop.SetAdaptX (int mode, double trigger)

Sets the adapt scale option of the x-scale.

Arguments:

int mode (obligatory) : Possible values: 0 off, 1 on

double trigger (optional) : Trigger value, unused if mode is off or empty.

Return value:

none

Example:

The following example looks for an opened Graphics Board and sets its adapt scale option. object aGrf; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Turn on adapt scale, use a trigger value of 3 aGrf.SetAdaptX(1,3); ! Turn off adapt scale aGrf.SetAdaptX(0,3);



! Turn on adapt scale again, do not change the tr igger value aGrf.SetAdaptX(1); }


H.3 String Functions

The syntax for formating strings is described in: Format String Syntax

Methods related to string formating and operations:

sprintf Returns a formatted string.

strstr Searches for a substring in a string.

strcpy Copies a substring from a string.

strcmp Compares two strings.

strchg Substitutes a sub-string in a string.

strlen Returns the length of a string.

strtok Finds a token in a string.

strftime Creates a formatted time string.

sscanf Assigns fields in string and returns number of fields.

Format String Syntax

The string printing commands "printf'' , "sprintf'' , "fprintf'' as well as "Write'' , "Error'' , "Warn'' and "Info'' all use the same format string syntax.

The format string must contain a valid place holder for every given argument. The placeholder format is [flags] [width] [.precision] type

Where "type'' is one of the following specifiers:

'd' or 'i' For an integer value.

'e' For a double value. The printed format is "[ - ]d.dddd e [sign]ddd'' where d is a single decimal digit, "'dddd'' is one or more decimal digits, "ddd'' is exactly three decimal digits, and "[sign]'' is "+'' or "-''.

'E' Identical to the e format except that "E'' in stead of "e'' is used.

'f' For a double value. Printed format is "[ - ]dddd.dddd'', where "dddd'' is one or more decimal digits. The number of digits before the decimal point depends on the magnitude of the number, and the number of digits after the decimal point depends on the requested precision.

'g' For a double value. Printed format is the "f'' or "e'' format, whichever is more compact for the given value and precision. The e format is used only when the exponent of the value is less than -4 or greater than or equal to the precision argument. Trailing zeros are truncated, and the decimal point appears only if one or more digits follow it.

'G' Identical to the "g'' format, except that "E'' in stead of "e'', is used (where appropriate).

's' For a string.

The optional "flag'' can be one of the following specifiers:

'-' Left align the result within the given field width.

'+' Prefix the output value with a sign (+ or -)

The optional "width'' specifies the number of characters to be printed and the optional ".precision'' specifies the number of decimals printed.

Example:

The following examples shows various placeholder definitions. double x; int i; string s; x = 123456789.987654321; i = 2468; s = 'hello dpl'; printf('%f|%15.3f|%E|%.2e|%+f|', x,x,x,x,x); printf('%d|%6d|%-6d|', i,i,i); printf('%s|%-20s|%20s|',s,s,s); ! string concat is possible: s = 'this'; s = sprintf('%s %s', s, 'DPL script'); ! print and assign in one action: s = printf('%s %s "%s"', s, 'is called', this:loc _name); printf('%s (again)',s); ! print again:

In addition to placeholders, the printed string may also contain "escape''-sequences for line feeds, tabs, form feeds and color. The following escape-sequences can be used:

� "\n'' inserts a line feed

� "\t'' inserts a horizontal tab

� "\f'' inserts a form feed, for printing purposes

� "\\'' writes a backslash, even when the next character is a n,t,f or c

� "%%'' writes a percent sign

� "\cx'' inserts a color change, where "x'' is a color, according to the following table, i.e. #"\ce'' switches to blue

Example: printf('The \cfbrown\ca fox jumped\nover\tthe\nla zy\tcat'); printf('result written to c:\\documents\\pf\\res. txt'); printf('%% = %%%6.2f%% %%', 123.34);

sprintf

string sprintf (String Format, String T | double X | int I, ...)

Returns a formatted string. The sprintf() command uses the C++ printf() formatting syntax.

Arguments:





Return value:


Example:



Table H.3:

a black i gray

b black j light gray

c red k bordeaux

d green l dark red

e blue m dark green

f brown n light green

g cyan o marine

h magenta p dark blue



The following example redirects the output to a file. The filename is formatted from a path and the name of the current calculation case. "Redirect'' is an ComOp and "StopRedirect'' is an ComCl object in the DPL command

Redirect:f = sprintf('%s%s.out', 'c:\\MyDocuments\\results0813\\', O: loc_name); Redirect.Execute(); Form.WriteOut(Lines); ! write a report StopRedirect.Execute(); ! stop redirection

Since version 13.1 there is an easier way of writing an string to a file by using "fprintf'' .





Also see "Error'' .

Also see "Warn'' .

Also see "Info'' . Also see "Write'' .

ToStr

The command "ToStr'' is obsolete and has been replaced by the "sprintf'' command. See "sprintf'' for more information.

strstr

int strstr (string S1, string S2)

Searches for a substring in a string and returns the position of the first letter of substring S2 in string S1.

Arguments:

string S1 (obligatory) : The string

string S2 (obligatory) : The substring

Return value:

The first position in S1 where S2 was found, or -1 when S2 was not found.

Example:

The following example searches for string 'brown' in string S1 string S1, S2; int i; S1 = 'The brown fox'; i = strstr(S1, 'brown'); ! i now equals 4

strcpy

String strcpy (string S, int start, int count)

Copies a substring from a string.

Arguments:

string S (obligatory) : The string

int start (obligatory) : The start position in S

int count (optional) : Number of characters to copy

Return value:

The copied substring

Example: string S1, S2; S1 = 'The brown fox'; S2 = strcpy(S1, 4, 5); ! S2 now equals 'brown'

strcmp

int strcmp (string S1, string S2, int count)

Compares two strings.

Arguments:

string S1 (obligatory) : The first string

string S1 (obligatory) : The second string

int count (optional) : Number of characters to compare

Return value:

< 0 when S1 < S2, for up to count characters

= 0 S1 = S2, for up to count characters

> 0 when S1 > S2, for up to count characters

Please notice that the comparison is case sensitive, therefore:

i = strcmp('a','A'); ! gives as result: i = 1

i = strcmp('A','a'); ! gives as result: i = -1

i = strcmp('a','a'); ! gives as result: i = 0

strchg

int strchg(string sStr, string sFind, string sNew)

Searches in the string sStr for the sub-string sFind and substitutes it by the sub-string sNew.

Arguments:

string sStr (obligatory): string to be scanned and modified.

string sFind (obligatory): sub-string to be found.

string sNew (obligatory): sub-string to be inserted instead of sFind.

Return value:

The first position in sStr where sFind was found (index of the first letter, index begins with 0) ;

-1 if substring was not found.

Example: int iRet; string sStr, sFind, sNew; sStr = 'This is just a test'; sFind = 'just a'; sNew = 'a very important'; iRet = strchg(sStr,sFind,sNew); if (iRet = -1){ printf('String could not be found!'); } else{ printf('%s',sStr); }

strlen

int strlen (string S)

Returns the length of a string.

Arguments:



string S (obligatory) : The string

strtok

string strtok (string Source, string Delimiter, int Pos, int Num)

Splits the string Source into tokens separated by the characters defined in the Delimiter. The function returns the token between separator (Num-1) and (Num) as a string and the position of the token in the Source.

Arguments:

string Source (obligatory) : String containing token(s)

string Delimiter (obligatory) : Set of delimiter characters

int Pos (obligatory) : Returns the position of token in Source (beginning with 0)

int Num (optional) : Number of the token to be read (default = 1)

Return value:

Token read. If nothing is read, the token is empty and Pos = -1

Example:

The following example searches for different tokens in sStr string sRes, sStr, sDel; int iPos; sStr = 'Das, ist nur, ein Test mit Nr. (555); wei ter nichts'; sDel = ',;()'; sRes = strtok(sStr,sDel,iPos); printf('Token: %s iPos = %d',sRes,iPos); sRes = strtok(sStr,sDel,iPos,2); printf('Token: %s iPos = %d',sRes,iPos); sRes = strtok(sStr,sDel,iPos,4); printf('Token: %s iPos = %d',sRes,iPos);

Output of the script above: Token: Das iPos = 0 Token: ist nur iPos = 4 Token: 555 iPos = 32

strftime

string strftime (String Format)

Creates a formatted time string.

Arguments:

String Format (obligatory) : The format string

The following formatting codes are recognized in the format string.

Return value:

The formatted time string

Example:

The following example shows the date. str = strftime('Today is %A, day %d of %B in the year %Y.'); printf('%s', str);

Output: Today is Wednesday, day 30 of April in the year 2 003.

sscanf

int sscanf (string Source, string Format, string T | double X | int I, ...)

Returns the number of fields successfully converted and assigned; the return value does not include fields that were read but not assigned.

Arguments:

string Source (obligatory) : The string

string Format (obligatory) : Defines a format of variable types (int/string/double) to which the fields are assigned




Return value: A return value of 0 indicates that no fields were assigned. The return value is -1 for an error or if the end of the string is reached before the first conversion.

Example:

The following example assignes the first two fields of string sStr to the string sRes and the double rVal iPos = 0; sStr = 'Test 23'; iRet = sscanf(sStr,'%s %d',sRes,iPos); printf('%s %d iRet = %d',sRes,iPos,iRet);

Output of the script above: Test 23 iRet = 0

Table H.4:

%a Abbreviated weekday name

%A Full weekday name

%b Abbreviated month name

%B Full month name

%c Date and time representation appropriate for locale

%d Day of month as decimal number (01..31)

%H Hour in 24-hour format (00..23)

%I Hour in 12-hour format (01..12)

%j Day of year as decimal number (001..366)

%m Month as decimal number (01..12)

%M Minute as decimal number (00..59)

%p Current locale's A.M./P.M. indicator for 12-hour clock

%S Second as decimal number (00..59)

%U Week of year as decimal number, Sunday as first day of week (00..53)

%w Weekday as decimal number (0..6; Sunday is 0)

%W Week of year as decimal number, Monday as first day of week (00..53)

%x Date representation for current locale

%X Time representation for current locale

%y Year without century, as decimal number (00..99)

%Y Year with century, as decimal number

%z, %Z Time-zone name or abbreviation; no characters if zone is unknown

%% Percent sign




H.4 Project Functions and Methods

ActiveProject Returns the active project.

GetLocalLib Returns a local library folder.

Activate Activates the project

Deactivate De-activates the project

ActiveProject

Object ActiveProject ()

Returns the currently active project.

Arguments:

none

Return value:

A "IntPrj'' object

Example:

The following example prints the name of the active project to the output window. object Prj; Prj = ActiveProject(); Prj.ShowFullName();

GetLocalLib

object GetLocalLib ([string ClassName])

Returns the local library for object-types of class "ClassName''. ClassName may be omitted, in which case the complete local library folder is returned.

Arguments:

string ClassName (optional) : The classname of the objects for which the library folder is sought

Return value:

The library folder

Example:

The following example shows the contents of the local library for line types. object Lib, O; set S; Lib = GetLocalLib('TypLne'); S = Lib.GetContents(); O = S.First(); while (O) { O.ShowFullName(); O = S.Next(); }

Also see "GetGlobalLib'' .

IntPrj.Activate

int IntPrj.Activate ()

Activates the project. Deactivates other projects first.

Arguments:

none

Return value:


See also



IntPrj.Deactivate

int IntPrj.Deactivate ()

De-activates the project.

Arguments:

none

Return value:


See also



H.5 Study Case Functions and Methods

General Functions and Methods related to Study Cases

SetTime Methods

H.5.1 General Functions and Methods related to Study Cases

ActiveCase Returns the active calculation case.

Activate Activates the study case

Deactivate De-activates the study case

SummaryGrid Returns the summary grid.

GetGraphBoard Returns the currently active Graphics Board.

See also:

AllRelevant Returns all calculation relevant objects.






ActiveCase

Object ActiveCase ()

Returns the currently active Study Case.

Arguments:

none

Return value

A "IntCase'' object

Example:

The following example writes the name of the active study case to the output window. object aCase; aCase = ActiveCase(); aCase.ShowFullName();

IntCase.Activate

int IntCase.Activate ()

Activates the study case. Deactivates other study cases first.

Arguments:

none

Return value:


See also



IntCase.Deactivate

int IntCase.Deactivate ()

De-activates the study case.

Arguments:

none

Return value:


See also



SummaryGrid

Object SummaryGrid ()

Returns the summary grid in the currently active Study Case. The summary grid is the combination of all active grids in the study case.

Arguments:

none

Return value:

A ElmNet object, or a 'NULL' object when no grids are active

Example:

The following example performs a load-flow and returns the total grid active power losses. object SumGrid; SumGrid = SummaryGrid(); if (SumGrid) { Ldf.Execute(); output('Active Power Losses=SumGrid:c:LossP'); }

GetGraphBoard

SetDeskTop GetGraphBoard ()

Returns the currently active Graphics Board.

Arguments:

none

Return value:

The graphics board object

Example:

The following example looks for an opened Graphics Board and sets its default results to the results object named 'Results'. object aGrf;! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Set default results object aGrf.SetResults(Results); }

Also see

SetDeskTop.GetPage

SetDeskTop.SetResults

SetDeskTop.SetXVar

SetDeskTop.SetScaleX

SetDeskTop.SetAutoScaleX

SetDeskTop.SetAdaptX

H.5.2 SetTime Methods

SetTime Sets the time

Date Sets the date at actual

Time Sets the time at actual

SetTime.SetTime

void SetTime.SetTime (double H,double M,double S)




Sets the time in the current year. There is no restriction to the values for H, M and S, except for the fact that negative values are interpreted as zero. Values higher than 24 or 60 will be processed normally by adding the hours, minutes and seconds into an absolute time, from which a new hour-of-year, hour-of-day, minutes and seconds are calculated.

Arguments:

double H (obligatory) : The hours

double M (optional) : The minutes

double S (optional) : The seconds

Return value:

none

Example:

The following sets the time to 1134.45 hours, 91.2 minutes and 675.3 seconds, which results in the time 08:09:27 on the 48'th day of the year. object Time, Com; Time = GetCaseObject('SetTime'); Time.SetTime(1134.45, 91.2, 675.3);

See also



SetTime.Date

void SetTime.Date ()

Sets the current date.

Arguments:

none

Return value:

none

Example:

The following example executes a load-flow for 14:30 at the current day (the computer's system date). object Time, Com; Time = GetCaseObject('SetTime'); Com = GetCaseCommand('ComLdf'); Time.Date(); Time:hour = 14; Time:min = 30; Com.Execute();

See also



SetTime.Time

void SetTime.Time ()

Sets the current time.

Arguments:

none

Return value:

none

Example:

The following example executes a load-flow for the current time and date (the computer's system time). object Time, Com; Time = GetCaseObject('SetTime'); Com = GetCaseCommand('ComLdf'); Time.Date(); Time.Time(); Com.Execute();

See also



H.6 General Object Functions and Methods

Functions related to Objects

General Object Methods

H.6.1 Functions related to Objects

Delete Deletes an object.

GetCaseObject Returns the found class object from current case.

See also:

General Object Methods

Delete

void Delete (object O | set S)

Deletes an object or a set of objects from the database. The objects are not destroyed but are moved to the recycle bin.

Arguments:

object O (optional): The object to delete

set S (optional): The set of objects to delete

Return value:

void

Example:

The following example removes all "Dummy" fuses from the network. The 'DummyType' variable is a local variable in the DPL script. A set of objects-to-delete is created first





and then that set is deleted. This has the advantage that one single entry in the recycle bin is created which contains all deleted fuses. Manually restoring ('undelete') the deleted fuses, in case of a mistake, can then be done by a single restore command.

object O; set S, Del; S = AllRelevant(); O = S.Firstmatch('RelFuse'); while (O) { if (O:typ_id=DummyType) { Del.Add(O); } O = S.Nextmatch(); } Delete(Del);

GetCaseObject

object GetCaseObject (string ClassName)

Returns the first found object of class "ClassName'' from the currently active calculation case. The object is created when no object of the given name and/or class was found.

Returns the default command object of class "ClassName'' from the currently active calculation case. Initializes newly created commands according to the project settings.

The icons on the main menu for load-flow, short-circuit, transient simulation, etc. also open the corresponding default command from the currently active study case. Using "GetCaseCommand()" in a DPL script will return the same command.

Arguments:

string ClassName (optional) : Class name of the object ("Class''), optionally preceded by an object name without wildcards and a dot ("Name.Class'').

Return value:

The found or created object.

Example:

The following example uses the default SetTime object to change the calculation time, and then executes the load-flow command with the name 'Unbalanced'. object time, com; time = GetCaseObject('SetTime'); time:hourofyear = 1234; com = GetCaseObject('Unbalanced.ComLdf'); com.Execute();

H.6.2 General Object Methods

The object methods are specific for each type of object class. A result file object (ElmRes), for instance, has a "Write'' method, which would not make sense for a load-flow command object.

The general syntax for an object method equals that of the set method: object . [OBJMETHOD] ( arguments) ;

The following overview lists all the non-specific [OBJMETHOD] methods which are available for all classes.

CreateObject Creates a new object.

ShowFullName Prints the full database path and name.

GetFullName Returns the full database path and name.

GetContents Returns the stored objects.

GetClass Returns the class name of an object.

IsClass Checks for a certain class.

GetParent Returns the parent folder.

GetNode Returns the node(s) connected to an object.

IsNode Checks if the object is a busbar or terminal.

GetCubicle Returns the object's cubicle.

HasResults Returns if the object has result parameters.

GetConnectedElms Returns the set of connected elements.

GetConnectionCount Returns the number of electrical connections.

Edit Opens the object dialogue.

Move Moves an objects to this folder.

AddCopy Adds a copy of an object.

IsRelevant Returns if the object is used for calculations.

IsOutOfService Returns if the object is out of service.

IsInFeeder Returns if the object belongs to the feeder.

VarExists Checks a variable name.

GetNet Returns the grid in which the object is located.

GetSize Get the size of a vector or matrix variable.

GetVal Returns the value of a parameter.

lnm Returns the long name of a variable.

snm Returns the short name of a variable.

unm Returns the unit of a variable.

Unom Returns the nominal voltage.

Inom Returns the nominal current.

MarkInGraphics Marks the object in the graphic.

StochEvt Returns the first or the next state of a stochastic object.

See also:

Delete Deletes an object.

GetCaseObject Returns the found class object from current case.

Object.CreateObject

object Object.CreateObject (string ClassNm [, string | int NM1, ...])

Creates a new object of class 'ClassNm' in the target object. The target object must be able to receive an object of the given class. A fatal DPL error will occur when this is not the case, causing the running DPL command to exit. "Fold.CreateObject(aClass, nm1, nm2, ...)'' will create a new object of class aClass and names it to the result of the concatenation of 'nm1', 'nm2', etc.

Arguments:

string ClassNm (obligatory) : The class name of the object to create

string | int NM1 (optional) : The first part of the object name

string | int NM2 (optional) : The next part of the object name

...

Return value:

The created object, or NULL when no object was created

Example:

The following example creates a fuse in a set of cubicles. The new fuses will be named "Fuse Nr.0'', "Fuse Nr.1'', etc. object target; set Cubs; int n; Cubs = SEL.GetAll('StaCubic');




target = Cubs.First(); n = 0; while (target) { target.CreateObject('RelFuse', 'Fuse Nr', n); target = Cubs.Next(); n+=1; }

Object.ShowFullName

void Object.ShowFullName ()

Writes the complete path and name to the output window.

Arguments:

none

Return value:

void

Because the complete database path is written to the output window, the written names can be right-clicked in the output window to edit the objects. This procedure is therefore useful for selecting objects which should be inspected or edited after the DPL script has finished.

Example:

The following example will write all overloaded lines from the selection to the output window. set S; object O; S = SEL.AllLines(); O = S.First(); while (O) { if (O:c:loading>100.0) { O.ShowFullName(); } O = S.Next(); }

Object.GetFullName

string Object.GetFullName ()

Returns the complete path and name as a string.

Arguments:

none

Return value:

The full name of the object

Example:

The following example will write all overloaded lines from the selection to the output window. set S; object O; string objname; S = SEL.AllLines(); O = S.First(); objname = O.GetFullName(); printf('Name of object: %s',objname);

Object.GetContents

set Object.GetContents (string WildCard, int Contents)

Returns the set of objects that are stored in the object and which name matches the wildcard. Returns an empty set, if the object's container is empty or if the object is not capable of storing objects. The wildcard may contain (parts of the) name and classname.

Arguments:

string WildCard (optional) : class name, possibly containing '*' and '?' characters

int Contents (optional) : if Contents = 1, the DPL command will additionally search all subfolders. If Contents = 0 (Default), the DPL command will only search object o.

Return value:

The set of objects

Example:

The following example collects all lines that are stored in line objects. set Grids, Lines; object pLne, pGrd; Grids = AllRelevant('*.ElmNet'); ! get all grids pGrd = Grids.First(); while (pGrd) { printf('Lines in Grid %s',pGrd:loc_name); ! get all objects of class ElmLne* (ElmLne, E lmLneroute) ! in all pGrd and it's subfolders of pGrd Lines = pGrd.GetContents('*.ElmLne*',1); pLne = Lines.First(); while (pLne) { pLne.ShowFullName(); pLne = Lines.Next(); } pGrd = Grids.Next(); }

Object.GetClass

string Object.GetClass ()

Returns the class name of the object.

Arguments:

none

Return value:

The class name of the object

Example:

The following example checks to see if two sets start with the same class. object O1, O2; O1 = S1.First(); O2 = S2.First(); i = O1.IsClass(O2.GetClass()); if (i) { output('Both sets start with the same class'); }

Object.IsClass

int Object.IsClass (string ClassName)

Checks to see if the object is of a certain class.

Arguments:

string ClassName (obligatory) : The name of the class.

Return value:

1 when the object is of the given class, 0 otherwise

Example:

The following example write all overloaded lines and transformers to the output window, where a different maximum loading is used for lines or transformers. set S; object O; int i; S = AllRelevant(); O = S.First();



while (O) { i = O.IsClass('ElmLne'); if (i) { if (O:c:loading>0.85) O.ShowFullName(); } else { i = O.IsClass('ElmTr2'); if (i) { if (O:c:loading>0.95) O.ShowFullName(); } } O = S.Next(); }

Object.GetParent

object Object.GetParent ()

Returns the parent folder.

Arguments:

none

Return value:

The parent folder object.

Example:

The following example returns the folder in which a line is stored. The function "GetBestLine()'' is an example DPL script which returns a line. object Lne, Fold; Lne = GetBestLine(); Fold = Lne.GetParent(); ...

Also see "GetContents'' .

Object.GetNode

string Object.GetNode (int iBusNo, int iSw)

Returns the node(s) connected to the object.

Arguments:

int iBusNo (obligatory) : Bus number (0,1)

int iSw (obligatory) : Considering configuration of switches (0,1), Default=0

Return value:

Connected node object

Object.IsNode

int Object.IsNode () Returns 1 if object is a node (terminal or busbar).

Arguments:

none

Return value:

1 if object is s node, 0 otherwise

Object.GetCubicle

object Object.GetCubicle (int N)

Returns the cubicle of an object at the connection with index n, or NULL if there is no cubicle inside the object.

Arguments:

int N (obligatory) : The connection number.

Return value:

The cubicle object or NULL.

Object.HasResults

void Object.HasResults ()

Returns 'true' when the object has calculated result parameters.

Arguments:

none

Return value:

'true' (1) or 'false' (0)

Object.GetConnectedElms

set Object.GetConnectedElms ([int rBrk[,int rDis[,int rOut]]])

Returns the set of connected elements. Only electrically connected elements are returned when the conditions of all switches are regarded. Possible connections will also be returned when rBrk and/or rDis is zero, in case of open breakers and/or disconnectors. The default values are (0,0,0).

Arguments:

int rBrk (optional) : if true, regards position of breakers

int rDis (optional) : if true, regards position of disconnectors

int rOut (optional) : if true, regards in-service or out-of-service status

Return value:

The set of connected elements

Object.GetConnectionCount

int Object.GetConnectionCount ()

Returns the number of electrical connections.

Arguments:

none

Return value:

The number of connections.

Example: set aSet; int iCount,iCub; object pObj,pCub,pBus; ! list all nodes where a 3-winding transformer is connected aSet = AllRelevant('*.ElmTr3'); for (pObj=aSet.First(); pObj; pObj=aSet.Next()) { iCount = pObj.GetConnectionCount(); for (iCub=0; iCub<iCount; iCub=iCub+1) { pCub=pObj.GetCubicle(iCub); if (pCub) { pBus = pCub:cBusBar; if (pBus) { pBus.ShowFullName(); } } } }



Object.Edit

void Object.Edit ()

Opens the edit dialogue of the object. Command objects (like the ComLdf) will have their Execute button disabled. The execution of the running DPL script will be halted until the edit dialogue is closed again.

Editing of DPL command objects ComDPL is not allowed.

Arguments:

none

Return value:

void

Example:

The following example opens a line dialogue, prior to calculating a load-flow. MyLine.Edit(); Ldf.Execute();

Object.Move

void Object.Move (object O | set S)

Moves an object or a set of objects to this folder.

Arguments:

object O (optional) : Object to move

set S (optional) : Set of objects to move

Return value:


Example: object targetobj,pObj; set AllObjs; ! move pObj to targetobj targetobj.Move(pObj); ! move all objects inside AllObjs to targetobj targetobj.Move(AllObjs);

Object.AddCopy

object Object.AddCopy (set aSet | object aObj [, string | int NM1, ...])

Copies a single object or a set of objects to the target object. "Fold.AddCopy(aObj)'' copies object 'aObj' into the target object 'Fold', "Fold.AddCopy(aSet)'' copies all objects in 'aSet' to "Fold''.

"Fold.AddCopy(aObj, nm1, nm2, ...)'' will copy aObj and rename it to the result of the concatenation of 'nm1', 'nm2', etc.

The target object must be able to receive a copy of the objects. The function "Fold.AddCopy(aObj,...)'' returns the copy of "aObj'', "Fold.AddCopy(aSet)'' returns "Fold'', when the copy operation was successful. A "NULL'' object is returned otherwise.

Copying a set of objects will respect all internal references between those objects. Copying a set of lines and their types, for example, will result in a set of copied lines and line types, where the copied lines will use the copied line types.

Arguments:

set aSet (obligatory) : The set of objects to copy

or

object aObj (obligatory) : The object to copy

string | int NM1 (optional) : The first part of the new name

string | int NM2 (optional) : The next part of the new name

...

Return value:

Returns the copy that has been created.

Example:

The following example copies a fuse to a set of cubicles. The copies will be named "Fuse Nr.0'', "Fuse Nr.1'', etc. object target, copy; set Cubs; Cubs = SEL.GetAll('StaCubic'); target = Cubs.First(); while (target) { copy = target.AddCopy(aFuse, 'Fuse Nr', n); if (copy) copy.ShowFullName(); target = Cubs.Next(); }

Object.IsRelevant

int Object.IsRelevant ()

Returns 1 if the object is currently used for calculations. Returns 0 otherwise.

Arguments:

none

Return value:

0 when not used

Example:

The following example checks if a line is used in the calculation. i = MyLine.IsRelevant(); if (i) { MyLine.ShowFullName(); }

Object.IsOutOfService

int Object.IsOutOfService ()

Returns 1 if the object is currently out of service. Returns 0 otherwise.

Arguments:

none

Return value:

0 when not out of service

Example:

The following example checks if a line is out of service. i = MyLine.IsOutOfService(); if (i) { MyLine.ShowFullName(); }

Object.IsInFeeder

void Object.IsInFeeder (object Feeder [, double OptNested=0])

Returns if the object belongs to the feeder area defined by "Feeder''.

Arguments:



object Feeder (obligatory) : The Feeder definition object

double OptNested (optional) : "Nested feeders'' option (1 or 0)

Return value:

1 if "Feeder'' is a feeder definition and the object is in the feeder area, 0 otherwise.

Object.VarExists

int Object.VarExists (string VarName)

Checks to see if this object has a currently valid variable called "VarName''.

Arguments:

string VarName (obligatory) : The name of the variable.

Return value:

1 when "VarName'' is the name of a currently valid variable for this object.

Example:

The following example calculates the total length of cables and lines. double x; int i; set s; object O; s = AllRelevant(); O = s.First(); while (O) { i = O.VarExists('dline'); if (i) { x += O:dline; } O = s.Next(); } printf('Total length = %d', x);

Object.GetNet

object Object.GetNet(void)

Returns the grid in which the object is located.

Arguments:

none

Return value:

The result object or NULL, if the current object is not stored in any grid.

Object.GetSize

int Object.GetSize (string VarName,int rows,int cols)

Returns the size of the variable "VarName'' when this variable is a vector or a matrix.

Arguments:

string VarName (obligatory) : The name of the variable

int rows (obligatory) : The number of rows for a vector or matrix

int cols (optional) : The number of columns for a matrix

Return value:

0 when "VarName'' is a valid variable name, else 1.

Example:

The following example prints the matrix resistances from a Tower model with 2 circuits. int ierr; double x; int r, rows, c, cols; string s; ierr = Tower.GetSize('R_c',rows, cols); if (.not.ierr) { r=0; while (r<rows) { s = ''; c = 0; while (c<cols) { ierr = Tower.GetVal(x, 'R_c', r,c); if (.not.ierr) s = sprintf('%s %f', s, x); c+=1; } printf(s); r+=1; } }

Example Output : 0.067073 0.016869 0.016594 0.016851 0.016576 0.0163 72 0.016869 0.066832 0.016701 0.016576 0.016445 0.0 16408 0.016594 0.016701 0.066738 0.016372 0.016408 0.016516 0.016851 0.016576 0.0163 72 0.067073 0.016869 0.016594 0.016576 0.016445 0.0 16408 0.016869 0.066832 0.016701 0.016372 0.016408 0.016516 0.016594 0.016701 0.0667 38

Also see "GetVal'' .

Object.GetVal

int Object.GetVal (object/double X,string VarName,int rows,int cols)

Returns the value of the variable "VarName'' when this variable is a vector or a matrix, for the given row and column.

Arguments:

double/object X (obligatory) : The variable in which to return the result

string VarName (obligatory) : The name of the variable

int rows (obligatory) : The row number for a vector or matrix

int cols (optional) : The column number for a matrix

Return value:

0 when "VarName'' is a valid variable name and row number and column number are in range, else 1.

Example:

See "GetSize''

Object.lnm

string Object.lnm (string VarName)

Returns the long description of the variable.

Arguments:

string VarName (obligatory) : The variable name

Return value:

The long variable description.

Example:

The following example prints information about the length of a line. string s1,s2,s3; s1 = Line.lnm('dline'); s2 = Line.snm('dline');



s3 = Line.unm('dline'); printf('%s (%s) = %5.3f [%s]',s1, s2, Line:dline, s3);

Example output: Length of Line (Length) = 0.547 [km]

Also see "snm''

Also see "unm''

Object.snm

string Object.snm (string VarName)

Returns the short variable name. By default, the short name equals the long variable name. In some cases, the variable also has a short name which is used to save space in reports or dialogues.

Arguments:


Return value:

The short name.

Example:

See "lnm''

Also see "unm''

Object.unm

string Object.unm (string VarName)

Returns the unit of the variable.

Arguments:


Return value:

The unit name.

Example:

See "lnm''

Also see "snm''

Object.Unom

double Object.Unom ()

Returns the nominal voltage of the object.

Arguments:

none

Return value:

The nominal voltage

Example:

The following example collects all high voltage lines. The value VoltageLevel is an input parameter. set S, Shv; object O; double U; S = SEL.AllLines(); O = S.First(); while (O) { U = O.Unom(); if (U>VoltageLevel) { Shv.Add(O); } O = S.Next(); }

Also see "Inom''

Object.Inom

double Object.Inom ()

Returns the nominal current of the object.

Arguments:

none

Return value:

The nominal current

Example:

The following example collects all high current lines. The value MinCurrent is an input parameter. set S, Shv; object O; double U; S = SEL.AllLines(); O = S.First(); while (O) { U = O.Inom(); if (U>MinCurrent) { Shv.Add(O); } O = S.Next(); }

Also see "Unom''

Object.MarkInGraphics

void Object.MarkInGraphics ()

Marks the object in the currently visible graphic by hatch crossing it.

Arguments:

none

Return value:

void

When the currently visible single line graphic does not contain the object, nothing will happen.

Example:

The following example will try to mark a set of lines in the single line graphic. set S; object O; S = SEL.AllLines(); O = S.First(); while (O) { O.MarkInGraphics(); O = S.Next(); }

Object.StochEvt

int Object.StochEvt (double d | double st)



Returns the first or the next state of a stochastic object, when the object has a valid failure model. Draws a first state, using the state probabilities, when "st'' is omitted. Draws the next state, using Monte-Carlo simulation, when "st'' is given. The drawn state is returned. The duration of the drawn state is returned in "d''.

Arguments:

double d (obligatory) : duration of the returned state

double st (optional) : current state of the object

Return value:

void

Example:

The following example prints the states of a line for a year. This is a small example of a chronological Monte-Carlo simulation. SetRandSeed(1); st = Line.StochEvt(t); while (t<8760) { printf('%7.2f %d', t, st); st = Line.StochEvt(d, st); t = t + d; }

result: 1172.67

01186.05

15554.87

05560.11

17873.65

07888.94

18260.78

08274.29

1

H.7 Set Functions and Methods

General Set Methods

Functions related to Sets

SetFilt Methods

SetSelect Methods

Feeder (SetFeeder) Methods

Path (SetPath) Methods

H.7.1 Functions related to Sets

AllRelevant Returns all calculation relevant objects.

See also:

General Set Methods

AllRelevant

Set AllRelevant (string S |int i)

Returns a set with calculation relevant objects, i.e. the objects which are used by the calculations. The set of calculation relevant objects is determined by the currently active study case and the currently active grids.

Objects which are out-of-service are ignored when i=0, but are included when i=1 or when i is omitted. A wildcard argument can be given, and only objects whose name and class-name satisfy this wildcard will be returned.

Arguments:

string S (optional) : Classname(s) with wildcards

int i (optional) : flag to include out of service objects

Return value:

The set of all calculation relevant objects, according to the given class-name wildcards

Example 1:

The following example writes the names of calculation relevant objects for various settings. set S; object O; printf('all objects, including out-of-service:'); S = AllRelevant(); for (O=S.First(); O; O=S.Next()) { O.ShowFullName(); } printf('all objects, excluding out-of-service:'); S = AllRelevant(0); for (O=S.First(); O; O=S.Next()) { O.ShowFullName(); } printf('all busbars and terminals,'); printf('including out-of-service:'); S = AllRelevant('*.StaBar,*.ElmTerm'); for (O=S.First(); O; O=S.Next()) { O.ShowFullName(); } printf('all lines, excluding out-of-service:'); S = AllRelevant('*.ElmLne',0); for (O=S.First(); O; O=S.Next()) { O.ShowFullName(); }

Example 2:

The following example writes the full name of all relevant busbars and terminals in the output window. set S; object O; S = AllRelevant('*.StaBar,*.ElmTerm'); ! include s out-of-service objects for (O=S.First(); O; O=S.Next()) { O.ShowFullName(); }






H.7.2 General Set Methods

Set methods are functions for the set type parameters.

set . [SETMETHOD] ( arguments) ;

The following [SETMETHOD] methods are available:

Add Adds an object.

Remove Removes an object.

Clear Removes all objects from the set.

First Returns the first objects.

Next Returns the next object.

Firstmatch Returns the first matching object.

Nextmatch Returns the next matching object.

FirstFilt Returns the first matching object.

NextFilt Returns the next matching object.

IsIn Searches for an object in the set.

Count Returns the number of stored objects.

Obj Returns the object at index i.

SortToVar Sorts the objects to a variable value.

SortToClass Sorts the objects to their class.

SortToName Sorts the objects to their names.

MarkInGraphics Marks the objects in the graphic.

See also:


SetTime Methods

Set.Add

int Set.Add ([object O | set S])

Adds an object or all objects from a set to the set.

Arguments:

One of the following two parameter has to be given

object O (optional) : an object

set S (optional) : a set of objects

Return value:

0 on success

Example:

The following example collects all loads and lines and the first breaker from the general DPL selection set S, Sbig; object O; Sbig = SEL.AllLines(); S = SEL.AllLoads(); Sbig.Add(S); S = SEL.AllBreakers(); O = S.First(); Sbig.Add(O);

Set.Remove

int Set.Remove (object O)

Removes an object from the set.

Arguments:

object O (obligatory) : the object to remove

Return value:

0 on success

Example:

The following example removes al short lines from a set set S; object O; double l; S = SEL.AllLines(); O = S.First(); while (O) { l = O:dline; if (l<1) { S.Remove(O); } O = S.Next(); }

Set.Clear

void Set.Clear()

Clears the set.

Arguments:

none

Return value:

void

Example:

The following example clears a set set Sbig; Sbig = SEL.AllLines(); ... Sbig.Clear();

Set.First

Object Set.First()

Returns the first object in the set.

Arguments:

none

Return value:

The first object or 0 when the set is empty

Example:

The following example writes the full names of all line in the general selection to the output window. set S; object O; S = SEL.AllLines(); O = S.First(); while (O) { O.ShowFullName(); O = S.Next(); }



Also see "Next'' .

Set.Next

Object Set.Next ()

Returns the next object in the set.

Arguments:

none

Return value:

The next object or 0 when the last object has been reached

Example:

The following example writes the full names of all line in the general selection to the output window. set S; object O S = SEL.AllLines(); O = S.First(); while (O) { O.ShowFullName(); O = S.Next(); }

Also see "First'' .

Set.Firstmatch

Object Set.Firstmatch (String WildCard)

Set.Firstmatch (string) is obsolete. Use Set.FirstFilt (string) instead.

Set.Nextmatch

int Set.Nextmatch ()

Set.Nextmatch () is obsolete. Use Set.NextFilt () instead.

Set.FirstFilt

Object Set.FirstFilt (String WildCard)

Returns the first object from the set which name matches the wildcard. The wildcard may contain (parts of the) name and classname.

Arguments:

String WildCard (obligatory) : class name, possibly containing '*' and '?' characters

Return value:

The first matching object, or NULL when no first object exists.

Example:

The following example writes all two and three winding transformers whose name start with a "T'' to the output window set S; object O; S = AllRelevant(); O = S.FirstFilt('T*.ElmTr?'); while (O) { O.ShowFullName(); O = S.NextFilt(); }

Also see "NextFilt'' .

Set.NextFilt

int Set.NextFilt ()

Returns the next object from the set which name matches the wildcard.

Arguments:

none

Return value:

The next object, or NULL when no next object exists.

Example:

The following example writes all two and three winding transformers to the output window set S; object O; S = AllRelevant(); O = S.FirstFilt('T*.ElmTr?'); while (O) { O.ShowFullName(); O = S.NextFilt(); }

Also see "FirstFilt'' .

Set.IsIn

int Set.IsIn (object O)

Checks if the set contains object 'O'.

Arguments:

object O (obligatory) : an object

Return value:

1 if the O is in the set.

Example:

The following example collects all not selected lines. set Ssel, Srel, Snsel; object lne; int i; Ssel = SEL.AllLines(); Srel = AllRelevant(); lne = Srel.Firstmatch('ElmLne'); while (lne) { i = Ssel.IsIn(lne); if (i=0) Snsel.Add(lne); lne = Srel.Nextmatch(); }

Set.Count

int Set.Count ()

Returns the number of objects in the set.

Arguments:

none

Return value:

The number of objects in the set.

Example:

The following example terminates the DPL script when the general selection is found to contain no lines. set S; int n;



S = SEL.AllLines(); n = S.Count(); if (n=0) { exit(); }

Set.Obj

int Set.Obj (int Index) Returns the object at the given index in the set.

Arguments:

int Index (obligatory) : the index of the object.

Return value:

The object at the given index in the set, when "Index'' is in range, NULL otherwise.

Set.SortToVar

int Set.SortToVar (int R, string V1, ..., string V5)

Sorts the objects in the set to the variable names.

Sorts the objects to the values for V1. Within the sorting for V1, a sub-sorting for V2, sub-sub-sorting for V3, etc., until V5 can be performed. The sorting is from higher values to lower when R==1, and reverse when R==0.

Arguments:

int R (obligatory) : sorting direction

string V1 (obligatory) : first variable name

string V2 (optional) : , ..., string V5 (optional) : 2nd..5th variable names

Return value:

0 on success

Example:

The following example writes all lines to the output window, sorted to derating factor and length. set S; object O; S = AllRelevant('*.ElmLne,*.ElmLneRoute'); S.SortToVar(0, 'fline', 'dline'); O = S.First(); while (O) { printf('%10s %f %f',O:loc_name,O:fline,O:dline) ; O = S.Next(); }

Set.SortToClass

int Set.SortToClass (int R) Sorts the objects in the set to their class name. The sorting is from A..Z when R=0 and reverse when R=1.

Arguments:

int R (obligatory) : sorting direction

Return value:

0 on success

Example:

The following example writes all objects to the output window, sorted to classes. set S; object O; S = AllRelevant(); S.SortToClass(0); O = S.First(); while (O) { O.ShowFullName(); O = S.Next(); }

Set.SortToName

int Set.SortToName (int R)

Sorts the objects in the set to their name.

Sorts the objects in the set to their name. The sorting is from A..Z when R=0 and reverse when R=1.

Arguments: int R (obligatory) : sorting direction

Return value:

0 on success

Example:

The following example writes all objects to the output window, sorted to names. set S; object O; S = AllRelevant(); S.SortToName(0); O = S.First(); while (O) { O.ShowFullName(); O = S.Next(); }

Set.MarkInGraphics

void Set.MarkInGraphics ()

Marks all objects in the set in the currently visible graphic by hatch crossing them.

Arguments:

none

Return value:

void

Example:

The following example will try to mark a set of lines in the single line graphic. set S; object O; S = SEL.AllLines(); S.MarkInGraphics();

H.7.3 SetFilt Methods

Get Returns a container with the filtered objects

SetFilt.Get

Set SetFilt.Get ()

Returns a container with the filtered objects.

Arguments:




none

Return value:

The set of filtered objects

Example:

The following example shows the names of objects filtered by the FiltLongLines.SetFilt filter set S; object O; S = FiltLongLines.Get(); O = S.First(); while (O) { O.ShowFullName(); O=S.Next(); }

See also


General Set Methods


H.7.4 SetSelect Methods

All Returns all objects

GetAll Returns all of the given class

AddRef Add references

Clear Empties the selection

AllElm Returns all elements

AllLines Returns all lines

AllBars Returns all busbars and terminals

AllLoads Returns all loads

AllAsm Returns all asynchronous machines

AllSym Returns all synchronous machines

AllTypLne Returns all line types

AllBreakers Returns all breakers

AllClosedBreakers returns all closed breakers

AllOpenBreakers returns all open breakers

SetSelect.AddRef

void SetSelect.AddRef ([object O | set S])

Adds a reference to the objects to the existing selection.

Arguments:




Return value:

void

Example:

The following example adds all loads and lines from the general DPL selection to the selection "MySelection''. set S; S = SEL.AllLines(); MySelection.AddRef(S); S = SEL.AllLoads(); MySelection.AddRef(S);

See also


General Set Methods


SetSelect.Clear

void SetSelect.Clear ()

Empties the selection.

Arguments:

none

Return value:

void

Example:

The following example creates a selection of all loads in the general DPL selection. set S; S = SEL.AllLines(); MySelection.Clear(); MySelection.AddRef(S);

See also


General Set Methods


SetSelect.AllElm

Set SetSelect.AllElm ()

Returns all elements (Elm*) in the selection.

Arguments:

none

Return value:

The set of objects




Example:

The following example writes all objects in the general DPL selection to the output window. set S; object O; S = SEL.AllElm(); O = S.First(); while (O) { O.ShowFullName(); O = S.Next(); }

See also


General Set Methods


SetSelect.AllLines

Set SetSelect.AllLines ()

Returns all lines and line routes in the selection.

Arguments:

none

Return value:

The set of objects

Example:

The following example writes all lines and line routes in the general DPL selection to the output window. set S; object O; S = SEL.AllLines(); O = S.Fir st(); while (O) { O.ShowFullName(); O = S.Next( ); }

See also


General Set Methods


SetSelect.AllBars

Set SetSelect.AllBars ()

Returns all busbars and terminals in the selection.

Arguments:

none

Return value:

The set of objects

Example:

The following example writes all bars in the general DPL selection to the output window. set S; object O; S = SEL.AllBars(); O = S.First(); while (O) { O.ShowFullName(); O = S.Next(); }

See also


General Set Methods


SetSelect.AllLoads

Set SetSelect.AllLoads ()

Returns all loads in the selection.

Arguments:

none

Return value:

The set of objects

Example:

The following example writes all loads in the general DPL selection to the output window. set S; object O; S = SEL.AllLoads(); O = S.First(); while (O) { O.ShowFullName(); O = S.Next(); }

See also


General Set Methods


SetSelect.AllAsm

Set SetSelect.AllAsm ()

Returns all asynchronous machines in the selection.

Arguments:

none

Return value:

The set of objects

Example:

The following example writes all asynchronous machines in the general DPL selection to the output window. set S; object O; S = SEL.AllAsm(); O = S.First(); while (O) { O.ShowFullName(); O = S.Next(); }

See also


General Set Methods




SetSelect.AllSym

Set SetSelect.AllSym ()

Returns all synchronous machines in the selection.

Arguments:

none

Return value:

The set of objects

Example:

The following example writes all synchronous machines in the general DPL selection to the output window. set S; object O; S = SEL.AllSym(); O = S.First(); while (O) { O.ShowFullName(); O = S.Next(); }

See also


General Set Methods


SetSelect.AllTypLne

Set SetSelect.AllTypLne ()

Returns all line types in the selection.

Arguments:

none

Return value:

The set of objects

Example:

The following example writes all line types in the general DPL selection to the output window. set S; object O; S = SEL.AllTypLne(); O = S.First(); while (O) { O.ShowFullName(); O = S.Next(); }

See also


General Set Methods


SetSelect.All

Set SetSelect.All ()

Returns all objects in the selection.

Arguments:

none

Return value:

The set of objects

Example:

The following example writes objects in the general DPL selection to the output window. set S; object O; S = SEL.All(); O = S.First(); while (O) { O.ShowFullName(); O = S.Next(); }

See also


General Set Methods


SetSelect.GetAll

Set SetSelect.GetAll (String ClassName)

Returns all objects in the selection which are of the class 'ClassName'.

Arguments:

String ClassName (obligatory) : The object class name.

Return value:

The set of objects

Example:

The following example writes all three winding transformers in the general DPL selection to the output window. set S; object O; S = SEL.GetAll('ElmTr3'); O = S.First(); while (O) { O.ShowFullName(); O = S.Next(); }

See also


General Set Methods


SetSelect.AllBreakers

Set SetSelect.AllBreakers ()

Returns all breakers in the selection.

Arguments:

none



Return value:

The set of objects

Example:

The following example writes all breakers in the general DPL selection to the output window. set S; object O; S = SEL.AllBreakers(); O = S.First(); while (O) { O.ShowFullName(); O = S.Next(); }

See also


General Set Methods


SetSelect.AllClosedBreakers

Set SetSelect.AllClosedBreakers ()

Returns all closed breakers in the selection.

Arguments:

none

Return value:

The set of objects

Example:

The following example writes all closed breakers in the general DPL selection to the output window. set S; object O; S = SEL.AllClosedBreakers(); O = S.First(); while (O) { O.ShowFullName(); O = S.Next(); }

See also


General Set Methods


SetSelect.AllOpenBreakers

Set SetSelect.AllOpenBreakers ()

Returns all open breakers in the selection.

Arguments:

none

Return value:

The set of objects

Example:

The following example writes all open breakers in the general DPL selection to the output window. set S; object O; S = SEL.AllOpenBreakers(); O = S.First(); while (O) { O.ShowFullName(); O = S.Next(); }

See also


General Set Methods


H.7.5 Feeder (SetFeeder) Methods

GetAll Returns all objects in the feeder

GetBuses Returns all nodes in the feeder

GetBranches Returns all branches in the feeder

SetFeeder.GetAll

Set SetFeeder.GetAll ()

Returns all objects in the feeder.

Arguments:

none

Return value:

The set with all objects

Example:

The following example gets all feeder objects. set S; S = Feeder1.GetAll();

See also


General Set Methods


SetFeeder.GetBuses

Set SetFeeder.GetBuses ()

Returns all busbars and terminals in the feeder.

Arguments:




none

Return value:

The set with all busbars and terminals

Example:

The following example gets all feeder bars. set S; S = Feeder1.GetBuses();

See also


General Set Methods


SetFeeder.GetBranches

Set SetFeeder.GetBranches ()

Returns all branches in a feeder.

Arguments:

none

Return value:

The set with all branches

Example:

The following example gets all feeder branches set S; S = Feeder1.GetBranches();

See also


General Set Methods


H.7.6 Path (SetPath) Methods

GetAll Returns all objects in the path

GetBusses Returns all nodes in the path

GetBranches Returns all branches in the path

AllBreakers Returns all breakers in the path

AllClosedBreakers Returns all closed breakers in the path

AllOpenBreakers Returns all open breakers in the path

SetPath.GetAll

Set SetPath.GetAll ()

Returns all objects in the path definition.

Arguments:

none

Return value:

The set of objects

Example:

The following example writes all objects in the path definition to the output window. set S; object O; S = aPath.GetAll(); O = S.First(); while (O) { O.ShowFullName(); O = S.Next(); }

See also


General Set Methods


SetPath.GetBusses

Set SetPath.GetBusses ()

Returns all busbars and terminals in the path definition.

Arguments:

none

Return value:

The set of objects

Example:

The following example writes all busbars and terminals in the path definition to the output window. set S; object O; S = aPath.GetBusses(); O = S.First(); while (O) { O.ShowFullName(); O = S.Next(); }

See also


General Set Methods


SetPath.GetBranches

Set SetPath.GetBranches ()

Returns all branches in the path definition.




Arguments:

none

Return value:

The set of objects

Example:

The following example writes all branches in the path definition to the output window. set S; object O; S = aPath.GetBranches(); O = S.First(); while (O) { O.ShowFullName(); O = S.Next(); }

See also


General Set Methods


SetPath.AllBreakers

Set SetPath.AllBreakers ()

Returns all breakers in the path definition.

Arguments:

none

Return value:

The set of objects

Example:

The following example writes all breakers in the path definition to the output window. set S; object O; S = aPath.AllBreakers(); O = S.First(); while (O) { O.ShowFullName(); O = S.Next(); }

See also


General Set Methods


SetPath.AllClosedBreakers

Set SetPath.AllClosedBreakers ()

Returns all closed breakers in the path definition.

Arguments:

none

Return value:

The set of objects

Example:

The following example writes all closed breakers in the path definition to the output window. set S; object O; S = aPath.AllClosedBreakers(); O = S.First(); while (O) { O.ShowFullName(); O = S.Next(); }

See also


General Set Methods


SetPath.AllOpenBreakers

Set SetPath.AllOpenBreakers ()

Returns all open breakers in the path definition.

Arguments:

none

Return value:

The set of objects

Example:

The following example writes all open breakers in the path definition to the output window. set S; object O; S = aPath.AllOpenBreakers(); O = S.First(); while (O) { O.ShowFullName(); O = S.Next(); }

See also


General Set Methods


H.8 Analysis Command Functions and Methods

General Analysis Command Functions and Methods

Load Flow Simulation (ComLdf) Functions and Methods

Short-Circuit Calculation (ComShc) Functions and Methods




Time-Domain Simulation Functions and Methods

Result Export (ComRes) Methods

Contingency Case (ComOutage) Methods

Contingency Analysis (ComSimoutage) Methods

Contingency Definition (ComNmink) Methods

Reliability Assessment (ComRel3) Methods

DPL Command (ComDpl) Methods

ComEcho Methods

H.8.1 General Analysis Command Functions and Methods

Execute Executes an analysis command

ResetCalculation Resets the calculations.

GetCaseCommand Returns default command objects.

Exe Executes a command bypassing the command pipe.

PostCommand Adds a command to the command pipe.

ClearCommands Clears the command pipe.

Execute

Commands can be execute by using the Execute() method:

int Com.Execute ()

Arguments:

none

Example:

The following example executes a command named 'Com' Com.Execute();

See also the specialized Execute methods for individual commands.

ComLdf.Execute

ComShc.Execute

ComInc.Execute

ComSimoutage.Execute

ComSimoutage.ExecuteCntcy

ComRel3.Execute

ComDpl.Execute

ResetCalculation

void ResetCalculation ()

Resets all calculations and destroys all volatile calculation results.

Arguments:

none

Return value:


Results that have been written to result objects (for display in graphs) will not be destroyed. All results that are visible in the single line diagrams, however, will be destroyed.

Example:

The following example resets all calculations ResetCalculation();

GetCaseCommand

object GetCaseCommand (string ClassName)

This command is obsolete. Please use the more versatile "GetCaseObject'' in stead.

Please refer to "GetCaseObject()'' .

Exe

void Exe (string Command)

Immediately executes the command, bypassing the command pipe in the input window. The DPL command will continue after the command has been executed. The 'Exe' command is provided for compatibility and testing purposes only and should only be used by experienced users.

Arguments:

string Command (obligatory): The command string

Return value:


Example:

The following command connects two terminals via an existing coupler 'NameBreaker'. while (Obj) { NameBreaker = ...; NameTerm1 = ...; NameTerm2 = ...; ObjTerm = SEL.First(); if (ObjTerm) { printf('Connect to Terminal: %s',NameTerm2); sExec = sprintf('connect obj=%s b1=%s b2=%s', NameBreaker,NameTerm1,NameTer m2); Exe(sExec); Obj = SelGrids.Next(); }

See also

Execute

PostCommand

void PostCommand (string Command)

Adds a command to the command pipe in the input window. The posted commands will be executed after the DPL command has finished.

Arguments:

string Command (obligatory) : The command string

Return value:





Example:

The following command causes the PowerFactory program to end after the DPL script has finished. PostCommand('exit');

ClearCommands

void ClearCommands ()

Clears the command pipe of the input window.

Arguments:

none

Return value:


Example:

The following command clears the input window. ClearCommands();

H.8.2 Load Flow Simulation (ComLdf) Functions and Methods

validLDF Checks for a valid load-flow result.

Execute Executes the command

validLDF

int validLDF ()

Checks to see if the last load-flow results are still valid and available.

Arguments:

none

Return value:

0 if no load-flow results are available

Example:

The following example checks if a load-flow is available, and performs one when not. int valid; valid = validLDF(); if (.not.valid) { Ldf.Execute(); }

ComLdf.Execute

int ComLdf.Execute ()

Execute a load-flow calculation.

Arguments:

none

Return value:

0 on success

Example:

The following example executes the ComLdf command name 'Ldf' Ldf.Execute();

See also



H.8.3 Short-Circuit Calculation (ComShc) Functions and Methods

validSHC Checks for a valid short-circuit result.


validSHC

int validSHC ()

Checks to see if the last short-circuit results are still valid and available.

Arguments:

none

Return value:

0 if no short-circuit results are available

Example:

The following example checks if a short-circuit result is available, and performs one when not. int valid; valid = validSHC(); if (.not.valid) { Shc.Execute(); }

ComShc.Execute

int ComShc.Execute ()

Executes a short-circuit calculation.

Arguments:

none

Return value:

0 on success

Example:

The following example execute the ComShc command named 'Shc' Shc.Execute();





See also



H.8.4 Time-Domain Simulation Functions and Methods

validRMS Checks for a valid simulation result.

validSIM Checks for a valid simulation result.

Execute Executes the command (here: Calculation of Initial Conditions)

validRMS

int validRMS ()

Checks to see if the last RMS simulation results are still valid and available.

Arguments:

none

Return value:

0 if no RMS simulation results are available

Example:

The following example checks if a RMS simulation is available, and performs one when not. int valid; valid = validRMS(); if (.not.valid) { Rms.Execute(); }

validSIM

int validSIM ()

Checks to see if the last simulation results are still valid and available.

Arguments:

none

Return value:

0 if no simulation results are available

Example:

The following example checks if a simulation result is available. int valid; valid = validSIM(); if (.not.valid) { output('No simulation result available'); }

ComInc.Execute

int ComInc.Execute ()

Executes a calculation of initial values.

Arguments:

none

Return value:

0 on success

Example:

The following example executes the ComInc command named 'Inc' Inc.Execute();

See also



H.8.5 Result Export (ComRes) Methods

ExportFullRange Exports the whole data range

FileNmResNm Sets the filename for the data export

ComRes.ExportFullRange

int ComRes.ExportFullRange ()

Executes the export command for the whole data range.

Arguments:

none

Return value:

0

Example:

The following example exports a range of results object O; set S; S = SEL.GetAll('ElmRes'); O = S.First(); while (O) { Export:pResult = O; Export.ExportFullRange(); O = S.Next(); }

See also



ComRes.FileNmResNm





int ComRes.FileNmResNm ()

Sets the filename for the data export.

Arguments:

none

Return value:

1

See also



H.8.6 Contingency Case (ComOutage) Methods

SetObjs Sets the list of objects according to S

GetObject Returns the object at position i

RemoveEvents Removes events stored inside the comman

ComOutage.SetObjs

int ComOutage.SetObjs (set S)

Sets the list of objects according to S.

Arguments:

set S (obligatory) : the set of objects

Return value:

O on success, 1 on error.

See also



ComOutage.GetObject

object ComOutage.GetObject (int line)

Get the element stored in line number line in the table of ComOutage. The line index starts with 0.

Arguments:

int line (obligatory):line index, if index exceeds the range NULL is returned

Return value:

the element of line line in the table.

Example:

The following example shows how to access elements in the table of all ComOutage whose names start with "L". object aCmd, aOutage, aElm; set Outages; int iElements, iElm; aCmd = GetCaseObject('*.ComRel3'); ! get rel. com mand from study case if (aCmd) { ! get all outages of which the names starts wit h "L" Outages = aCmd.GetContents('L*.ComOutage'); ! show the elements of all outages for (aOutage=Outages.First(); aOutage; aOutage= Outages.Next()) { aOutage.GetSize('Elms',iElements); ! get size of vector Elms for (iElm=0; iElm<iElements; iElm=iElm+1) { aElm = aOutage.GetObject(iElm); !aOutage.GetVal(aElm,'Elms',iElm); same lik e GetObject aElm.ShowFullName(); } } }

See also



Object.GetVal

ComOutage.RemoveEvents

void ComOutage.RemoveEvents (string type, int info)

Removes events stored inside the command.

Arguments:

string type (optional):

none remove all events stored inside ComOutage

'Lod remove all EvtLod

'Gen' remove all EvtGen

'Switch' remove all EvtSwitch

int info (optional):

1 show info message in output window (default)

0 do not show info message

Return value:

none

Example:

The following example shows how to remove events from ComOutage object aCmd, aOutage; set Outages; aCmd = GetCaseObject('*.ComRel3'); ! get rel. com mand from study case if (aCmd) { ! get all outages of which the names starts wit h "L" Outages = aCmd.GetContents('L*.ComOutage'); ! remove the events for (aOutage=Outages.First(); aOutage; aOutage= Outages.Next()) { aOutage.RemoveEvents(0);! delete remaining,su ppress info message } }


DIgSILENT GmbH



H.8.7 Contingency Analysis (ComSimoutage) Methods

Reset Resets the intermediate results

Execute Executes a ComSimoutage after resetting the results

ExecuteCntcy(object O) Executes a ComSimoutage for all outage cases stored in the object O, without resetting results

AddCntcy(object O) Executes a ComOutage without resetting results, for the outage cases stored in object O

SetLimits Sets the voltage limits to Umn and Umx and the loading limit to Lmx.

ReportObjs Returns the objects which are normally given to the reporting command to produce the contingency reports.

ComSimoutage.Reset

int ComSimoutage.Reset ()

Resets the intermediate results of the outage simulation.

Arguments:

none

Return value:


See also



ComSimoutage.Execute

int ComSimoutage.Execute ()

Executes an outage simulation after resetting the results.

Arguments:

none

Return value:


See also



ComSimoutage.ExecuteCntcy

int ComSimoutage.ExecuteCntcy (object O)

Executes an (additional) ComSimoutage, without resetting results. The results of the outage analyses will be added to the intermediate results. Object "O'' must be a ComSimoutage object. Outage definitions in O which have already been analyzed will be ignored.

Arguments:

object O (obligatory) : The ComSimoutage object

Return value:


See also



ComSimoutage.AddCntcy

int ComSimoutage.AddCntcy (object O, string name)

Executes an (additional) ComOutage, without resetting results. The results of the outage analysis will be added to the intermediate results. Object "O'' must be a ComOutage object. If the outage definition has already been analyzed, it will be ignored. The ComOutage will be renamed to "name'' when "name'' is given.

Arguments:

object O (obligatory) : The ComOutage object

string name (optional) : A name for the outage

Return value:


See also



ComSimoutage.SetLimits

int ComSimoutage.SetLimits (double vlmin, double vlmax, double ldmax)

Sets the limits for the outage simulation.

Arguments:

double vlmin (obligatory) : The minimum voltage

double vlmax (obligatory) : The maximum voltage

double ldmax (obligatory) : The maximum loading

Return value:

1 always

Example:

The following example analyses all selected outage definitions and adds the results to the intermediate results. set s; object o; s = SEL.GetAll('ComOutage'); o = s.First(); while (o) { CA.AddCntcy(o); o = s.Next(); }

See also



ComSimoutage.ReportObjs

set ComSimoutage.ReportObjs (set s, int mode)

www.digsilent.de Tel: +49 (0)7072 9168-50 Fax: +49 (0)7072 [email protected]



Returns the objects which are normally given to the reporting command to produce the contigency report.

Arguments:

set set (obligatory) : Initial set of objects

int mode (obligatory) : Report mode (1..4)

Return value:

set of objects for report.

See also



H.8.8 Contingency Definition (ComNmink) Methods

AddRef Adds shortcuts

Clear Empties the selection

GetAll Returns all objects of class 'ClassName'

ComNmink.AddRef

void ComNmink.AddRef ([object O | set S]) Adds shortcuts to the objects to the existing selection.

Arguments:




Return value:

void

Example:

The following prepares and executes an outage simulation for all high loaded lines. PrepOut.Clear(); S = AllRelevant(); O = S.Firstmatch('ElmLne'); while (O) { if (O:c:loading>75) { PrepOut.AddRef(O); } O = S.Nextmatch(); } PrepOut.Execute();

See also



ComNmink.Clear

void ComNmink.Clear ()

Empties the selection.

Arguments:

none

Return value:

void

Example:

The following example creates a selection of all loads. PrepOut.Clear(); S = AllRelevant(); O = S.Firstmatch('ElmLne'); while (O) { if (O:c:loading>75) { PrepOut.AddRef(O); } O = S.Nextmatch(); } PrepOut.Execute();

See also



ComNmink.GetAll

Set ComNmink.GetAll (String ClassName)

Returns all objects which are of the class 'ClassName'.

Arguments:

String ClassName (obligatory) : The object class name.

Return value:

The set of objects

Example:

The following example writes all three winding transformers in the preparation command to the output window. set S; object O; S = Prep.GetAll('ElmTr3'); O = S.First(); while (O) { O.ShowFullName(); O = S.Next(); }

See also







H.8.9 Reliability Assessment (ComRel3) Methods


RemoveOutages Removes contingency definitions

RemoveEvents Removes events stored in contingencies

AnalyseElmRes Evaluates results object created in last calculation

ComRel3.Execute

int ComRel3.Execute ()

Executes the Level 3 reliability assessment calculations.

Arguments:

none

Return value:

0 on success

Example:

The following example executes a ComRel3 Command named 'Rel3' Rel3.Execute();

ComRel3.RemoveOutages

void ComRel3.RemoveOutages ()

Removes all contingency definitions (*.ComOutage) stored inside the command. This is exactly the same like pressing the button named "Delete Contingencies" in the dialogue box of the command.

Arguments:

int msg (optional) :

1 show info message in output window (taken by default),

0 do not show a message

Return value:

none

Example:

The following example removes all ComOutage objects stored inside the ComRel command in the study case. object aCmd; aCmd = GetCaseObject('*.ComRel3'); ! get the comm and from study case if (aCmd) { aCmd.RemoveOutages(0); ! suppress info message }

ComRel3.RemoveEvents

void ComRel3.RemoveEvents (string type, int info)

Removes events stored inside the contingencies (*.ComOutage) inside the command.

Arguments:

string type (optional):

none remove all events stored inside the ComOutages inside ComRel3

'Lod' remove all EvtLod

'Gen' remove all EvtGen'

'Switch' remove all EvtSwitch'

int info (optional):

1 show info message in output window (default)

0 do not show info message

Return value:

none

Example:

The following example shows how to remove events from the ComOutage commands stored inside ComRel3: object aCmd; aCmd = GetCaseObject('*.ComRel3'); ! get the comm and from study case if (aCmd) { aCmd.RemoveOutages('Lod');! delete all EvtLod aCmd.RemoveOutages('Gen');! remove all EvtGen aCmd.RemoveOutages(0); ! delete remaining, s uppress info message }

ComRel3.AnalyseElmRes

int ComRel3.AnalyseElmRes (int error)

Evaluate the results object created by the last calculation. Performs exactly the same like pressing the button 'Perform Evaluation of Result File' in the dialogue box of the command.

Arguments:

int error (optional):

0 do not display an error message (default)

1 display error messages in case of errors

Return value:

0 on success, !=0 on error.

Example:

The following example shows how to call the evaluation of the results. object aCmd, aResFile; int iError; aCmd = GetCaseObject('*.ComRel3'); ! get the comm and from study case if (aCmd) { iError=aCmd.AnalyseElmRes(0); ! hide error m essage if (iError) { ! display my own error message aResFile = aCmd:p_resenum; if (aResFile) { Error('Evaluation of results %s failed', aR esFile:loc_name); } } }

See also






H.8.10 DPL Command (ComDpl) Methods

Execute Executes an external DPL script as a subroutine

ComDpl.Execute

int ComDpl.Execute (user defined arguments)

Executes an external DPL script as a subroutine.

Arguments:

user defined arguments

Return value:

0 on success

Example:

The following example performs a load-flow and calls the DPL subroutine "CheckVoltages'' to check the voltage conditions. int err; err = Ldf.Execute(); if (.not.err) err = CheckVoltages(0.94, 1.05); if (err) printf('Voltage conditions are violated' );

See also



H.8.11 ComEcho Methods

On Turns on the user interface

Off Turns off the user interface

ComEcho.On

int ComEcho.On ()

Turns on the user interface.

ComEcho.On() is obsolete. Use the internal command EchoOn instead.

Arguments:

none

Return value:

0 on success

Example:

The following example turns off the user interface, calls a subroutine and turns it back on again. aEcho.Off(); PerformCalculation(); aEcho.On();

See also



ComEcho.Off

int ComEcho.Off ()

Turns off the user interface.

ComEcho.Off() is obsolete. Use the internal command EchoOff instead.

Arguments:

none

Return value:

0 on success

Example:

The following example turns off the user interface, calls a subroutine and turns it back on again. aEcho.Off(); PerformCalculation(); aEcho.On();

See also



H.9 Specialized Methods for Elements and Types

The external methods are available for external PowerFactory objects, such as the load-flow command, the line object, the asynchronous machine, etc. as well as additional functions dealing with classes and virtual instruments.

For Feeder Methods please refer to Section H.7.5: Feeder (SetFeeder) Methods.

For Path Methods please refer to Section H.7.6: Path (SetPath) Methods.

Grid (ElmNet) Methods

Induction Machine Type (TypAsm) Methods

Induction Machine Type (TypAsmo) Methods

Feeder (ElmFeeder) Methods

Composite Model (ElmComp) Methods

Breaker/Switch (ElmCoup) Methods

Line (ElmLne) Methods

Line Route (ElmLneroute) Methods

Line Type (TypLne) Methods

Result Object (ElmRes) Methods





Zone (ElmZone) Methods

Switch (StaSwitch) Methods

H.9.1 Grid (ElmNet) Methods

Activate Adds a grid to the active study case

Deactivate Removes a grid from the active study case

ElmNet.Activate

int ElmNet.Activate ()

Adds a grid to the active study case.

Arguments:

none

Return value:


See also



ElmNet.Deactivate

int ElmNet.Deactivate ()

Removes a grid from the active study case.

Arguments:

none

Return value:


See also



H.9.2 Induction Machine Type (TypAsm) Methods

CalcElParams Calculates the electrical parameters

TypAsm.CalcElParams

int TypAsm.CalcElParams ()

Calculates the electrical parameters from the input data.

Arguments:

none

See also



H.9.3 Induction Machine Type (TypAsmo) Methods

CalcElParams Calculates the electrical parameters

TypAsmo.CalcElParams

int TypAsmo.CalcElParams ()

Calculates the electrical parameters from the input data.

Arguments:

none

See also



H.9.4 Feeder (ElmFeeder) Methods

GetAll Returns all objects in this feeder

GetBuses Returns all buses in this feeder

GetBranches Returns all branch elements in this feeder

GetNodesBranches Returns all buses and branches in this feeder

GetObjs Returns all objects of class 'ClassName'' in this feeder







ElmFeeder.GetAll

set ElmFeeder.GetAll (int iNested)

Returns a set with all objects belonging to this feeder.

Arguments:

int iNested (optional) : In case of nested feeders, all elements will be returned when iNested=1, otherwise only the objects up to the next feeder will be returned.

Return value:

The set of feeder objects.

Example: set aAll,aFeeders; object pPrj,pFeeder,pObj; ! output elements in the feeders pPrj = ActiveProject(); if (pPrj) { aFeeders = pPrj.GetContents('*.ElmFeeder',1); aFeeders.SortToVar(0,'loc_name'); for (pFeeder=aFeeders.First(); pFeeder; pFeeder =aFeeders.Next()){ printf('Elements in feeder %s',pFeeder:loc_na me); aAll = pFeeder.GetAll(1); for (pObj=aAll.First(); pObj; pObj=aAll.Next( )) { printf(' %s\\%s',pObj:r:fold_id:loc_name ,pObj:loc_name); } } }

See also



ElmFeeder.GetBuses

set ElmFeeder.GetBuses (int iNested)

Returns a set with all buses belonging to this feeder.

Arguments:


Return value:

The set of bus elements in feeder.

Example: set aNodes,aFeeders; object pPrj,pFeeder,pObj; ! output elements in the feeders pPrj = ActiveProject(); if (pPrj) { aFeeders = pPrj.GetContents('*.ElmFeeder',1); aFeeders.SortToVar(0,'loc_name'); for (pFeeder=aFeeders.First(); pFeeder; pFeed er=aFeeders.Next()){ printf('Buses in feeder %s',pFeeder:loc_nam e); aNodes = pFeeder.Getbuses(1); for (pObj=aNodes.First(); pObj; pObj=aNodes .Next()) { printf(' %s\\%s',pObj:r:fold_id:loc_na me,pObj:loc_name); } } }

See also



ElmFeeder.GetBranches

set ElmFeeder.GetBranches (int iNested)

Returns a set with all branch elements belonging to this feeder.

Arguments:


Return value:

The set of branch elements in feeder.

Example: set aBranches,aFeeders; object pPrj,pFeeder,pObj; ! output elements in the feeders pPrj = ActiveProject(); if (pPrj) { aFeeders = pPrj.GetContents('*.ElmFeeder',1); aFeeders.SortToVar(0,'loc_name'); for (pFeeder=aFeeders.First(); pFeeder; pFeeder =aFeeders.Next()){ printf('Branches in feeder %s',pFeeder:loc_na me); aBranches = pFeeder.GetBranches(1); for (pObj=aBranches.First(); pObj; pObj=aBran ches.Next()) { printf(' %s\\%s',pObj:r:fold_id:loc_name ,pObj:loc_name); } } }

See also



ElmFeeder.GetNodesBranches

set ElmFeeder.GetNodesBranches (int iNested)

Returns a set with all buses and branches belonging to this feeder.

Arguments:


Return value:

The set of bus and branch elements in feeder.

Example: set aAll,aFeeders; object pPrj,pFeeder,pObj; ! output elements in the feeders pPrj = ActiveProject(); if (pPrj) { aFeeders = pPrj.GetContents('*.ElmFeeder',1); aFeeders.SortToVar(0,'loc_name'); for (pFeeder=aFeeders.First(); pFeeder; pFeed er=aFeeders.Next()){ printf('Branches and Nodes in feeder %s',pF eeder:loc_name); aAll = pFeeder.GetNodesBranches(1); for (pObj=aAll.First(); pObj; pObj=aAll.Nex t()) { printf(' %s\\%s',pObj:r:fold_id:loc_na me,pObj:loc_name); } } }

See also



ElmFeeder.GetObjs



set ElmFeeder.GetObjs (string ClassNameint iNested)

Returns a set with all objects of class 'ClassName'' which belong to this feeder.

Arguments:


Return value:

The set of feeder objects.

Example: set aAll,aFeeders; object pPrj,pFeeder,pObj; ! output elements in the feeders pPrj = ActiveProject(); if (pPrj) { aFeeders = pPrj.GetContents('*.ElmFeeder',1); aFeeders.SortToVar(0,'loc_name'); for (pFeeder=aFeeders.First(); pFeeder; pFeeder =aFeeders.Next()){ printf('Cubicles in feeder %s',pFeeder:loc_na me); aAll = pFeeder.GetObjs('StaCubic'); for (pObj=aAll.First(); pObj; pObj=aAll.Next( )) { printf(' %s\\%s',pObj:r:fold_id:loc_name ,pObj:loc_name); } } }

See also



H.9.5 Composite Model (ElmComp) Methods

Slotupd Performs a slot update

ElmComp.Slotupd

int ElmComp.Slotupd ()

Performs a slot update for the composite model, to automatically select available models for the slots.

Arguments:

none

Return value:

void

See also



H.9.6 Breaker/Switch (ElmCoup) Methods

Close Closes the buscoupler

Open Opens the buscoupler

IsOpen Returns 1 when the coupler is open

IsClosed Returns 1 when the coupler is closed

ElmCoup.Close

int ElmCoup.Close ()

Closes the buscoupler.

Arguments:

none

Return value:

0 on success

Example:

The following example gathers all open couplers before closing them. int opn; set S, So; object O; S = Couplers.AllElm(); O = S.First(); while (O) { opn = O.IsOpen(); if (opn) { O.Close(); So.Add(O); }; }

See also



ElmCoup.Open

int ElmCoup.Open ()

Opens the buscoupler.

Arguments:

none

Return value:

0 on success

Example:

The following example gathers all closed couplers before opening them. int cl; set S, Sc; object O; S = Couplers.AllElm(); O = S.First();





while (O) { cl = O.IsClosed(); if (opn) { O.Open(); Sc.Add(O); }; }

See also



ElmCoup.IsOpen

int ElmCoup.IsOpen ()

Returns 1 when the coupler is open.

Arguments:

none

Return value:

1 when open, 0 when closed

Example:

See ElmCoup.Close for an example

ElmCoup.IsClosed

int ElmCoup.IsClosed ()

Returns 1 when the coupler is closed.

Arguments:

none

Return value:

1 when closed, 0 when open

Example:

See ElmCoup.Open for an example

H.9.7 Line (ElmLne) Methods

HasRoutes Returns if the line is subdivided into routes

HasRoutesOrSec Returns if the line is subdivided into routes or sections

GetType Returns the line type object

IsCable Returns if this is a cable

IsNetCoupling Returns if the line connects two grids

SetCorr Sets the correction factor of the line

CreateFeederWithRoutes Splits the line in 2 routes

ElmLne.HasRoutes

int ElmLne.HasRoutes ()

Returns if the line is subdivided into routes.

Arguments:

none

Return value:

0 when the line is a single line, 1 when it is subdivided into routes.

Example:

The following example reports all lines with routes. set S; object O; int i; S = AllRelevant(); O = S.Firstmatch('ElmLne'); while (O) { i = O.HasRoutes(); if (i) O.ShowFullName(); O = S.Nextmatch(); }

See also



ElmLne.HasRoutesOrSec

int ElmLne.HasRoutesOrSec ()

Returns if the line is subdivided into routes or sections.

Arguments:

none

Return value:

0 when the line is a single line, 1 when it is subdivided into routes, 2 when into sections.

Example:

The following example reports all lines with sections. set S; object O; int i; S = AllRelevant(); O = S.Firstmatch('ElmLne'); while (O) { i = O.HasRoutesOrSec(); if (i=2) O.ShowFullName(); O = S.Nextmatch(); }

See also



ElmLne.GetType

int ElmLne.GetType ()




Returns the line type object.

Arguments:

none

Return value:

The TypLne object

Example:

The following example reports all 'untyped' lines set S; object O, T; S = AllRelevant(); O = S.Firstmatch('ElmLne'); while (O) { T = O.GetType(); if (T=0) { O.ShowFullName(); } O = S.Nextmatch(); }

See also



ElmLne.IsCable

int ElmLne.IsCable ()

Returns if this is a cable.

Arguments:

none

Return value:

1 when the line is a cable, otherwise 0.

Example:

The following example reports the loading of all cables. set S; object O; int i; S = AllRelevant(); O = S.Firstmatch('ElmLne'); while (O) { i = O.IsCable(); if (i) { Write('# : #.## $N, @ACC(1):loc_name, @ACC(1) :c:loading, O); } O = S.Nextmatch(); }

ElmLne.IsNetCoupling

int ElmLne.IsNetCoupling ()

Returns if the line connects two grids.

Arguments:

none

Return value:

1 when the line is a coupler, otherwise 0.

Example:

The following example reports all the loading of all couplers set S; object O; int i; S = AllRelevant(); O = S.Firstmatch('ElmLne'); while (O) { i = O.IsNetCoupling(); if (i) { Write('# : #.## $N, @ACC(1):loc_name, @ACC( 1):c:loading, O); } O = S.Nextmatch(); }

See also



ElmLne.SetCorr

int ElmLne.SetCorr ()

Sets the correction factor of the line, according to IEC364-5-523.

Arguments:

none

Return value:

0 on success, 1 on error;

Example:

The following example sets a correction factor. BuriedLine.SetCorr();

See also



ElmLne.CreateFeederWithRoutes

int ElmLne.CreateFeederWithRoutes (double dis,double rem,object O[int sw0,int sw1])

Creates a new feeder in the line by splitting the line in 2 routes and inserting a terminal.

Arguments:

double dis (obligatory) :

double rem (obligatory) :

object O (obligatory) : A branch object that is to be connected at the inserted terminal.

int sw0 (optional) : when true, a switch is inserted on the one side

int sw1 (optional) : when true, a switch is inserted on the other side

Return value:

0 on success, 1 on error;

See also





H.9.8 Line Route (ElmLneroute) Methods

IsCable Returns if the route is a cable

HasSections Returns if the line route is subdivided into sections

Hint: ElmLneroute has been replaced by ElmBranch containing ElmLne in PowerFactory Version 14.0. Please refer to Line (ElmLne) Methods.

ElmLneroute.IsCable

int ElmLneroute.IsCable ()

Returns if the route is a cable.

Arguments:

none

Return value:

1 when a cable, otherwise 0.

Example:

The following example reports all cable routes. set S; object O; int i; S = AllRelevant(); O = S.Firstmatch('ElmLneroute'); while (O) { i = O.IsCable(); if (i) O.ShowFullName(); O = S.Nextmatch(); }

See also




ElmLneroute.HasSections

int ElmLneroute.HasSections ()

Returns if the line route is subdivided into sections.

Arguments:

none

Return value:

1 when subdivided sections, 0 otherwise

Example:

The following example reports all lines routes with sections. set S; object O; int i; S = AllRelevant(); O = S.Firstmatch('ElmLneroute'); while (O) { i = O.HasSections(); if (i) O.ShowFullName(); O = S.Nextmatch(); }

See also




H.9.9 Line Type (TypLne) Methods

IsCable Returns if the line type is a cable type

SetNomCurr Sets the nominal current of the line type

TypLne.IsCable

int TypLne.IsCable ()

Returns if the line type is a cable type.

Arguments:

none

Return value:

1 when the line type is a cable type, otherwise 0.

Example:

The following example reports all cable types. set S; object O; int i; S = AllRelevant(); O = S.Firstmatch('TypLne'); while (O) { i = O.IsCable(); if (i) O.ShowFullName(); O = S.Nextmatch(); }

See also



TypLne.SetNomCurr

int TypLne.SetNomCurr ()





Sets the nominal current of the line type, according to IEC364-5-523.

Arguments:

none

Return value:


Example:

The following example sets the correction factor. BuriedLineType.SetNomCurr();

See also



H.9.10 Result Object (ElmRes) Methods

Init Initializes the result object

Clear Clears the result object

Write Writes the current results

Draw Updates all relevant plots

WriteDraw Writes results and updates all plots

SetAsDefault Sets this as default results

AddVars Adds to the list of monitored variables

GetObj Returns objects used in the result file

ResIndex Returns column number of variable in result object.

GetResData Returns a value from a certain result curve.

ResNval Returns number of values stored in certain result curve.

ResNvars Returns the number of variables (columns) in result file.

LoadResData Loads the data of a result file in memory.

ElmRes.Init

int ElmRes.Init ()

Initializes the result object. This is required for all result files that are not stored in the DPL command object.

Arguments:

none

Return value:

0 on success

Example:

The following example initializes the result object. Res.Init();

See also



ElmRes.Clear

int ElmRes.Clear ()

Clears the result object.

Arguments:

none

Return value:

0 on success

Example:

The following example clears the result object. Res.Clear();

See also



ElmRes.Write

int ElmRes.Write ()

Writes the current results to the result object.

Arguments:

none

Return value:

0 on success

Example:

The following example performs load-flows for a number of load levels and writes the results to the result object double P; double i; P = LoadMin; i = 1; while ({P<LoadMax}.and.{i}) { i = Ldf.Execute(); if (i) { Res.Write(); P += LoadStep; } }

See also



ElmRes.Draw




int ElmRes.Draw ()

Updates all plots that display values from the result object.

Arguments:

none

Return value:

0 on success

Example:

The following example updates the graphics every 10 steps to save time and yet follow the results while calculating double i,n; Ld:pini = LoadMin; i = 1; n = 0; while ({Ld:pini<LoadMax}.and.{i}) { i = Ldf.Execute(); if (i) { Res.Write(); n += 1; Ld:pini += LoadStep; } if (n>9) { Res.Write(); n = 0; } }

See also



ElmRes.WriteDraw

int ElmRes.WriteDraw ()

Writes current results to the result objects and updates all plots that display values from the result object.

Arguments:

none

Return value:

0 on success

Example:

The following example performs load-flows for a number of load levels and writes the results to the result object double P; double i; P = LoadMin; i = 1; while ({P<LoadMax}.and.{i}) { i = Ldf.Execute(); if (i) { Res.WriteDraw(); P += LoadStep; } }

See also



ElmRes.SetAsDefault

void ElmRes.SetAsDefault ()

Sets this results object as the default results object.

Arguments:

none

Return value:

none

See also



ElmRes.AddVars

void ElmRes.AddVars (object O, string v1 [,string v2,...])

Adds variables to the list of monitored variables for the Result object.

Arguments:

object O (obligatory) : an object.

string v1 (obligatory) : variable name for object O.

string v2..v9 (optional) : optional further variables names for object O.

Return value:

none

Example: object Res; Res = MyResults(); Res.AddVars(MyLine,'m:Ikss:busshc','m:I:busshc');

See also



ElmRes.GetObj

object ElmRes.GetObj (int index)

Returns the objects used in the result file. Positive index means objects for which parameters are being monitored (i.e. column objects). Negative index means objects which occur in written result rows as values.

Arguments:

int index (obligatory) : index of the object.

Return value:

the object, when found.

See also



ResIndex

int ResIndex (object res, object O, string vnm)



Returns the column number of the variable 'vnm' of object 'O' in the result object 'res'. An error is produced when 'res' is not a ElmRes object, when 'O' is not in the result file.

Arguments:

object res (obligatory) : the result file

object O (obligatory) : The monitored object

string vnm (obligatory) : the name of the monitored variable of object 'O'

Return value:

The index of the variable. This index can be used in "GetResData'' to retrieve the value. A negative index is returned when 'vnm' is not in the result file.

Example: object obj, res; double x, x1, x2; int n, ix, i1, i2; int Nval; obj = GetCaseCommand('ComInc'); res = obj:p_resvar; LoadResData(res); Nval = ResNval(res,0); obj = res.GetObject(1); i1 = ResIndex(res, obj, 'm:I1:bus1'); i2 = ResIndex(res, obj, 'm:U1:bus1'); if (i1<0.or.i2<0) exit(); ix = 0; while (ix<Nval) { GetResData(x, res, ix); GetResData(x1, res, ix, i1); GetResData(x2, res, ix, i2); printf('%8.5f %8.5f %8.5f', x, x1, x2); ix += 1; }

Also see "LoadResData()''

"GetResData()''

"GetObject'' .

GetResData

int GetResData (double d, object O, int iX, int iCrv)

Returns a value from a result object for row iX of curve iCrv. An error is produced when O is not a ElmRes object.

Arguments:

double d (obligatory) : the returned value

object O (obligatory) : The result file object

int iX (obligatory) : the row index

int iCrv (optional) : The curve number, which equals the variable or column number, first column value (time,index, etc.) is returned when omitted.

Return value:

0 when ok

1 when iX out of bound

2 when iCrv out of bound

3 when invalid value is returned ('INFINITY', 'DUMMY', etc.)

Also see "LoadResData()'' .

ResNval

int ResNval (object O, int iCrv)

Returns the number of values stored in result object for curve iCrv. An error is produced when O is not a ElmRes object.

Arguments: object O (obligatory) : The result file object int iCrv (obligatory) : The curve number, which equals the variable or column number.


ResNvars

int ResNvars (object O)

Returns the number of variables (columns) in result file. An error is produced when O is not a ElmRes object.

Arguments:



LoadResData

void LoadResData (object O)

Loads the data of a result file (ElmRes) in memory. An error is produced when O is not a ElmRes object.

Arguments:


Return value:

void

Example: object obj, res; double x; int Nvar, Nval, n, ix,iy; string str; obj = GetCaseCommand('ComInc'); res = obj:p_resvar; LoadResData(res); Nvar = ResNvars(res); Nval = ResNval(res,0); printf('Nvar=%d Nval=%d', Nvar, Nval); ix = 0; while (ix<Nval) { iy = 0; GetResData(x, res, ix); str = sprintf('%f :', x); while (iy<Nvar) { GetResData(x, res,ix,iy); str = sprintf('%s %8.5f ', str, x); iy += 1; } printf('%s', str); ix += 1; }

An example (depending of the results in the result object) of the output for this script : Nvar=3

Nval=11

-0.050000 : 0.12676 30.73286 12.91360

-0.040000 : 0.12676 30.73286 12.91360

-0.030000 : 0.12676 30.73286 12.91360

-0.020000 : 0.12676 30.73286 12.91360

-0.010000 : 0.12676 30.73286 12.91360

-0.000000 : 0.12676 30.73286 12.91360

0.010000 : 0.12676 30.73286 12.91360



0.020000 : 0.12676 30.73286 12.91360

0.030000 : 0.12676 30.73286 12.91360

0.040000 : 0.12676 30.73286 12.91360

0.050000 : 0.12676 30.73286 12.91360

H.9.11 Zone (ElmZone) Methods

GetAll Returns all objects in this zone

GetBuses Returns all buses in this zone

GetNodes Returns all nodes in this zone

GetBranches Returns all branches and buses in this zone

GetObjs Returns all objects of the given class in this zone

ElmZone.GetAll

set ElmZone.GetAll ()

Returns all objects which belong to this zone.

Arguments:

none

Return value:

The set of objects

Example: set aAll,aZones; object pPrj,pZone,pObj; ! output elements in the zone pPrj = ActiveProject(); if (pPrj) { aZones = pPrj.GetContents('*.ElmZone',1); aZones.SortToVar(0,'loc_name'); for (pZone=aZones.First(); pZone; pZone=aZone s.Next()) { printf('Elements in zone %s',pZone:loc_name ); aAll = pZone.GetAll(); for (pObj=aAll.First(); pObj; pObj=aAll.Nex t()) { printf(' %s\\%s',pObj:r:fold_id:loc_na me,pObj:loc_name); } } }

See also



ElmZone.GetBuses

set ElmZone.GetBuses ()

Returns all buses which belong to this zone.

Arguments:

none

Return value:

The set of objects

See also



ElmZone.GetNodes

set ElmZone.GetNodes ()

Returns all nodes which belong to this zone.

Arguments:

none

Return value:

The set of objects

Example: set aAll,aZones; object pPrj,pZone,pObj; ! output elements in the zone pPrj = ActiveProject(); if (pPrj) { aZones = pPrj.GetContents('*.ElmZone',1); aZones.SortToVar(0,'loc_name'); for (pZone=aZones.First(); pZone; pZone=aZones. Next()) { printf('Nodes in zone %s',pZone:loc_name); aAll = pZone.GetBuses(); for (pObj=aAll.First(); pObj; pObj=aAll.Next( )) { printf(' %s\\%s',pObj:r:fold_id:loc_name ,pObj:loc_name); } } }

See also



ElmZone.GetBranches

set ElmZone.GetBranches ()

Returns all branches which belong to this zone.

Arguments:

none

Return value:

The set of objects

Example: set aAll,aZones; object pPrj,pZone,pObj; ! output elements in the zone pPrj = ActiveProject(); if (pPrj) { aZones = pPrj.GetContents('*.ElmZone',1); aZones.SortToVar(0,'loc_name'); for (pZone=aZones.First(); pZone; pZone=aZones. Next()) { printf('Branches in zone %s',pZone:loc_name); aAll = pZone.GetBranches(); for (pObj=aAll.First(); pObj; pObj=aAll.Next( )) {




printf(' %s\\%s',pObj:r:fold_id:loc_name ,pObj:loc_name); } } }

See also



ElmZone.GetObjs

set ElmZone.GetObjs (string classname)

Returns all objects of the given class which belong to this zone.

Arguments:

string classname (obligatory) : name of the class.

Return value:

The set of objects

Example: set aAll,aZones; object pPrj,pZone,pObj; ! output cubicles in the zone pPrj = ActiveProject(); if (pPrj) { aZones = pPrj.GetContents('*.ElmZone',1); aZones.SortToVar(0,'loc_name'); for (pZone=aZones.First(); pZone; pZone=aZones. Next()) { printf('Cubicles in zone %s',pZone:loc_name); aAll = pZone.GetObjs('StaCubic'); for (pObj=aAll.First(); pObj; pObj=aAll.Next( )) { printf(' %s\\%s',pObj:r:fold_id:loc_name ,pObj:loc_name); } } }

See also



H.9.12 Switch (StaSwitch) Methods

Close Closes the switch

Open Opens the switch

IsOpen Returns if the switch is open

IsClosed Returns if the switch is closed

Hint: StaSwitch has been replaced by ElmCoup in PowerFactory Version 14.0. Please refer to Breaker/Switch (ElmCoup) Methods.

StaSwitch.Close

int StaSwitch.Close ()

Closes the switch.

Arguments:

none

Return value:

0 on success

Example:

The following example gathers all open switches before closing them. int opn; set S, So; object O; S = Switches.AllElm(); O = S.First(); while (O) { opn = O.IsOpen(); if (opn) { O.Close(); So.Add(O); }; }

See also




StaSwitch.Open

int StaSwitch.Open ()

Opens the switch.

Arguments:

none

Return value:

0 on success

Example:

The following example gathers all closed switches before opening them. int cl; set S, Sc; object O; S = Couplers.AllElm(); O = S.First(); while (O) { cl = O.IsClosed(); if (opn) { O.Open(); Sc.Add(O); }; }

See also




StaSwitch.IsOpen

int StaSwitch.IsOpen ()




Checks if the switch is open.

Arguments:

none

Return value:

1 when open, 0 when closed

Example:

See StaSwitch.Close for an example.


StaSwitch.IsClosed

int StaSwitch.IsClosed ()

Checks if the switch is closed.

Arguments:

none

Return value:

1 when closed, 0 when open

Example:

See StaSwitch.Open for an example.


H.10 Methods for Virtual Instruments

SetVipage Methods

VisPlot/VisPlot2 Methods

VisFft Methods

IntPlot Methods

H.10.1 SetVipage Methods

GetVI

SetStyle

SetTile

SetResults

SetXVar

SetScaleX

SetDefScaleX

DoAutoScaleX

DoAutoScaleY

SetAutoScaleX

SetAdaptX

GetScaleObjX

SetVipage.GetVI

object SetVipage.GetVI (string name, string class, int create)

Searches for a virtual instruments on the Virtual Instrument Panel.

Arguments:

string name (obligatory) : Name of Virtual Instrument

string class='VisPlot' (optional) : classname of Virtual Instrument.

int create=1 (optional) : create >0 --> create panel if not exists.

Return value:

Virtual Instrument

Example:

The following example looks for a Plot (VisPlot) named RST on a Virtual Instrument Panel. The plot is created if it was not found. object aGrf; object aPage; object aPlot; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get plot named RST. Create the plot if not ex ists aPlot=aPage.GetVI('RST','VisPlot',1); } }

Also see Methods for Additional Objects (Int*)

SetVipage.SetStyle

void SetVipage.SetStyle (string name)

Sets style folder of Virtual Instrument Panel.

Arguments:

string name (obligatory) : Name of style.

Return value:

none

Example:





The following example looks for a Virtual Instrument Panel named Voltage and sets its style to 'Paper'. object aGrf; object aPage; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Set style named Paper aPage.SetStyle('Paper'); } }


SetVipage.SetTile

void SetVipage.SetTile (int tile)

Rearranges the Virtual Instruments.

Arguments:

int tile=1 (optional) : tile > 0 --> tile Virtual Instruments, tile =0 --> arrange them horizontally.

Return value:

none

Example:

The following example looks for a Virtual Instrument Panel named Voltage and rearranges the Virtual Instrument. object aGrf;object aPage; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Arrange the VIs horizontally aPage.SetTile(0); ! Tile VIs (default input parameter is 1) aPage.SetTile(); } }


SetVipage.SetResults

void SetVipage.SetResults (object res)

Sets default Results (ElmRes) of Virtual Instrument Panel.

Arguments:

object res (obligatory) : Results to set (ElmRes) or NULL to reset.

Return value:

none

Example:

The following example looks for a Virtual Instrument Panel named Voltage and resets its default results. object aGrf; object aPage; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Set default results on page aPage.SetResults(NULL); } }


SetVipage.SetXVar

void SetVipage.SetXVar (object obj, string varname)


Arguments:



Return value:

none

Example:

The following examples look for a Virtual Instrument Panel named Voltage and set the x-axis variable. The first example sets an user defined x-axis variable of the Virtual Instrument Panel. The second one sets the default x-axis (time).

object aGrf; object aPage; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Set x-scale from 100 to 120 aPage.SetScaleX(100,120); ! Set x-scale variable aPage.SetXVar(line,'m:U1:bus1'); } } object aGrf; object aPage; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Set x-scale from 100 to 120 aPage.SetScaleX(100,120); ! Set default x-scale variable (time) aPage.SetXVar(); } }


SetVipage.SetScaleX

void SetVipage.SetScaleX (double min, double max, int log)

Sets scale of x-axis. Invalid arguments like negative limits for logarithmic scale are not set. No input arguments --> automatic scaling.

Arguments:




Return value:

none



Example:

The following examples look for a Virtual Instrument Panel named Voltage and set its x-axis scale. There are three different examples. 1. Example: Scale x-scale automatically. 2. Example: Set minimum to 0 and maximum to 20. 3. Example: Set minimum to 1 and maximum to 1000. Changes to a log. scale

! Scale x-scale automatically. object aPage; object aGrf; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Automatic scaling aPage.SetScaleX(); } } ! Set minimum and maximum without changing map modeobject aPage; object aGrf; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Set minimum and maximum aPage.SetScaleX(0,20); } } ! Set minimum and maximum, set map mode to log. object aPage; object aGrf; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Set minimum and maximum, change to log. scale aPage.SetScaleX(1,1000,1); } }


SetVipage.SetDefScaleX

void SetVipage.SetDefScaleX ()

Sets default scale of x-axis (SetDesktop).

Arguments:

none

Return value:

none

Example:

The following example looks for a Virtual Instrument Panel named Voltage and resets the option 'Use local x-Axis' to 0. After that the x-scale used is the Graphics Board (SetDesktop).

! Set default x-scale object aPage; object aGrf; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Reset option 'Use local x-Axis' aPage.SetD efScaleX(); } }


SetVipage.DoAutoScaleX

int SetVipage.DoAutoScaleX ()

Scales the x-axes of all plots on the virtual instrument panel automatically. The same can be achieved by pressing the icon in the toolbar of the graphic.

Arguments:

none

Return value:

none

Example:

The following example looks for a page named voltage and performs an automatic scaling of the x-axes. ! perform autoscale of x-axis of all plots on page object aPage; object aGrf; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { aPage.DoAutoScaleX(); } }

Also see VisFft Methods

VisPlot Methods

SetDesktop Methods

SetVipage.DoAutoScaleY

int SetVipage.DoAutoScaleY ()

Scales the y-axes of all plots on the virtual instrument panel automatically. The same can be achieved by pressing the icon in the toolbar of the graphic.

Arguments:

none

Return value:

none

Example:

The following example looks for a page named voltage and performs an automatic scaling of the y-axes. ! perform autoscale of y-axis of all plots on page object aPage; object aGrf; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { aPage.DoAutoScaleY(); } }

Also see VisPlot Methods

SetVipage.SetAutoScaleX



void SetVipage.SetAutoScaleX (int mode)

Sets automatic scaling mode of the x-scale for local scales.

Arguments:


Return value:

none

Example:

The following examples look for a Virtual Instrument Panel named Voltage and change its auto scale mode. The first example works fine, the second one generates an error message because the x-scale is unused.

! Set autoscale mode Off object aGrf; object aPage; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Set limits to change x-scale of page to use d scale aPage.SetScaleX(0,10); ! Turn off automatic scaling of x-scale aPage.SetAutoScaleX(0); } } ! Try to set autoscale mode to online object aGrf; object aPage; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Reset option 'Use local x-Axis' of Virtual Instrument Panel aPage.SetDefScaleX(); ! Try to set automatic scaling of x-scale to Online aPage.SetAutoScaleX(2); } }


SetVipage.SetAdaptX

void SetVipage.SetAdaptX (int mode, double trigger)

Sets the adapt scale option of the x-scale for local scales.

Arguments:


double trigger (optional) : Trigger value, unused if mode is off or empty

Return value:

none

Example:

The following examples look for a Virtual Instrument Panel named Voltage and sets its adapt scale option. The first example works fine, the second one generates an error message because the x-scale is unused.

! Modify adapt scale option of Virtual Instrument Panel object aPage; object aGrf; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Set x-scale limits to set option 'Use local x-Axis' aPage.SetScaleX(0,20); ! Turn on adapt scale, use a trigger value of 3 aPage.SetAdaptX(1,3); ! Turn off adapt scale aPage.SetAdaptX(0,3); ! Turn on adapt scale again, do not change th e trigger value aPage.SetAdaptX(1); } } ! Try to turn on adapt scale object aPage; object aGrf; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Reset option 'Use local x-Axis' of Virtual Instrument Panel aPage.SetDefScaleX(); ! Try to turn on adapt scale, use a trigger v alue of 3 ! Leads to error message because scale is not local aPage.SetAdaptX(1,3); } }


SetVipage.GetScaleObjX

object SetVipage.GetScaleObjX ()

Returns used object defining x-scale. The returned object is either the Virtual Instrument Panel itself or the Graphics Board.

Arguments:

none

Return value:

Object defining the x-scale.

Example:

The following examples look for a Virtual Instrument Panel named Voltage and get the used x-scale object. GetScaleObjX of the first example gets the Graphics Board, in the second one the Virtual Instrument Panel itself is returned.

! Used scale is Graphics Board object aPage; object aGrf; object aScale; ! Look for opened graphics board.aGrf=GetGraphBoa rd(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Reset option 'Use local x-Axis' of Virtual Instrument Panel aPage.SetDefScaleX(); ! Get object defining scale aScale=aPage.GetScaleObjX(); if (aPage=aScale) { output('The scale used is the Virtual Instr ument Panel itself.'); } else if (aGrf=aScale) { output('The scale used is the Graphics Boar d.'); } else { output('The scale used was not found.'); } } } ! Used scale is Virtual Instrument Panel itself object aPage; object aGrf; object aScale; ! Look for opened graphics board. aGrf=GetGraphBoard();



if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Set x-scale to change it to local aPage.SetScaleX(1,100); ! Get object defining scale aScale=aPage.GetScaleObjX(); if (aPage=aScale) output('The scale used is the Virtual Inst rument Panel itself.'); else if (aGrf=aScale) output('The scale used is the Graphics Boa rd.'); else output('The scale used was not found.'); } }


H.10.2 VisPlot/VisPlot2 Methods

AddVars

AddResVars

Clear

SetXVar

SetScaleX

SetScaleY

SetDefScaleX

SetDefScaleY

DoAutoScaleX

DoAutoScaleY

DoAutoScaleY2

SetAutoScaleX

SetAutoScaleY

SetAdaptX

SetAdaptY

GetScaleObjX

GetScaleObjY

SetCrvDesc

VisPlot.AddVars

void VisPlot.AddVars (string V, object O1,...,O8)

void VisPlot.AddVars (object O, string V1,...V8)

Appends variables to the SubPlot. Variables which are already in the plot are not added.

Arguments:

object O (obligatory) : Object for which variables V1..V8 are added

string V1..V8 (obligatory) : One to eight variables names for object O

or

string V (obligatory) : Variable name which is added for objects O1..O8

object O1..O8 (obligatory) : One to eight objects variable V

Return value:

none

Using AddVars a single object with different variables or one variable with several objects can be add to the Subplot. To append a list of variables of a single object the first input parameter is an object followed by a list of maximum nine variables. To append the same variable for several objects the first input parameter is the variable name followed by a list of maximum nine objects.

Example:

The following examples look for a Subplot named RST on Virtual Instrument Panel named Voltage and append a list of variables.

1. Example: Append several variables for one single object.

2. Example: Append one variable for a list of objects. ! Append several variables for one single object. object aPage; object aGrf; object aPlot; object aScale; ! Note: object load is an interface parameter, ! therefore it is not defined here ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Clear variable list aPlot.Clear(); ! Append variables aPlot.AddVars(load, 'm:U1:bus1','m:U1l:bus1 ','m:phiu1:bus1'); } } } ! Append several objects with one single variable object aPage; object aGrf; object aPlot; object aScale; ! objects load,line and xnet are interface parame ters, ! therefore they are not defined here. ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Clear variable list aPlot.Clear(); ! Append variables aPlot.AddVars('m:U1:bus1',load, line, xnet) ; } } }





VisPlot.AddResVars

void VisPlot.AddResVars (object Res, string V, object O1,...,O7)

void VisPlot.AddResVars (object Res, object O, string V1,...V7)

Appends variables from a specific result file to the SubPlot. Combinations of result file and variables which are already in the plot are not added.

Arguments:

object Res (obligatory) : Result object

plus

object O (obligatory) : Object for which variables V1..V8 are added

string V1..V8 (obligatory) : One to eight variables names for object O

or

string V (obligatory) : Variable name which is added for objects O1..O8

object O1..O8 (obligatory) : One to eight objects variable V

Return value:

none

See "AddResVars'' for more information.

VisPlot.Clear

void VisPlot.Clear()

Removes all variables from SubPlot.

Arguments:

none

Return value:

none

Example:

The following example looks for a Subplot named RST on Virtual Instrument Panel named Voltage and removes all variables from the plot. ! Remove all variables in Subplot named RST on ! Virtual Instrument Panel named Voltage object aPage; object aGrf; object aPlot; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get Subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Remove all variables from Subplot aPlot.Clear(); } } }


VisPlot.SetXVar

void VisPlot.SetXVar (object obj, string varname)


Arguments:



Return value:

none

Example:

The following examples look for a Subplot named RST and set its x-axis variable. The first example sets an user defined x-axis variable of the plot. The second one sets the default x-axis variable (time).

! Set user defined x-axis variable object aPage; object aGrf; object aPlot; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get Subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Set x-scale from 100 to 120 aPlot.SetScaleX(100,120); ! Set x-scale variable aPlot.SetXVar(line,'m:U1:bus1'); } } } ! Set default x-axis variable (time) object aPage; object aGrf; object aPlot; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get Subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Set x-scale from 100 to 120 aPlot.SetScaleX(100,120); ! Set default x-scale variable (time) aPlot.SetXVar(); } } }


VisPlot.SetScaleX

void VisPlot.SetScaleX (double min, double max, int log)

Sets scale of x-axis. Invalid arguments like negative limits for logarithmic scale are not set. No arguments --> automatic scaling.

Arguments:




Return value:

none



Example:

The following examples look for a Subplot named 'RST' and set its x-scale. There are three different examples. 1. Example: Perform auto scaling on x-axis. 2. Example: Set minimum to 0 and maximum to 20. 3. Example: Set minimum to 1 and maximum to 1000. Changes to a log. scale

! Automatic scaling of x-scale object aPage; object aGrf; object aPlot; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Automatic scaling aPlot.SetScaleX(); } } } ! Set minimum and maximum without changing map mo de object aPage; object aGrf;object aPlot; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Set minimum and maximum aPlot.SetScaleX(0,20); } } } ! Set minimum and maximum, set map mode to log. object aPage; object aGrf; object aPlot; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Set minimum and maximum, change to log sc ale aPlot.SetScaleX(1,1000,1); } } }


VisPlot.SetScaleY

void VisPlot.SetScaleX (double min, double max, int log)

Sets scale of y-axis. Invalid arguments like negative limits for logarithmic scale are not set. No arguments --> automatic scaling.

Arguments:

double min (optional) : Minimum of y-scale.

double max (optional) : Maximum of y-scale.

int log (optional) : > 0 --> y-scale is logarithmic.

Return value:

none

Example:

The following examples look for a Subplot named 'RST' and set its y-axis scale. There are three different examples. 1. Example: Perform auto scaling on y-Axis. 2. Example: Set minimum to 0 and maximum to 20. 3. Example: Set minimum to 1 and maximum to 1000. Changes to a log. scale

! Automatic scaling of y-scale object aPage; object aGrf; object aPlot; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Automatic scaling aPlot.SetScaleY(); } } } ! Set minimum and maximum without changing map mo de object aPage; object aGrf; object aPlot; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Set minimum and maximum aPlot.SetScaleY(0,20); } } } ! Set minimum and maximum, set map mode to log. object aPage; object aGrf; object aPlot; ! Look for opened graphics board.aGrf=GetGraphBoa rd(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Set minimum and maximum, change to log. s cale aPlot.SetScaleY(1,1000,1); } } }


VisPlot.SetDefScaleX

void VisPlot.SetDefScaleX ()

Sets default scale of x-axis (SetDesktop or SetVipage).

Arguments:

none

Return value:

none

Example:

The following example looks for a Subplot named 'RST' and sets the option 'Use local x-Axis' to 0. After that the x-scale used is the Graphics Board (SetDesktop) or the Virtual



Instrument Panel (SetVipage). ! Reset option 'Use local x-Axis' object aPage; object aGrf; object aPlot; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Reset option 'Use local x-Axis' aPlot.SetDefScaleX(); } } }


VisPlot.SetDefScaleY

void VisPlot.SetDefScaleY ()

Sets default scale of y-axis (IntPlot).

Arguments:

none

Return value:

none

Example:

The following example looks for a Subplot named 'RST' and sets its option 'Use local y-Axis' to 0. After that the y-scale used is the Plot Type (IntPlot). ! Reset option 'Use local y-Axis' object aPage; object aGrf; object aPlot; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Reset option 'Use local y-Axis' aPlot.SetDefScaleY(); } } }


VisPlot.DoAutoScaleX

int VisPlot.DoAutoScaleX ()

Scales the x-axis of the plot automatically. The function works for local x-scales only. If the x-scale is not local a warning is shown in the output window and 1 is returned by the function. This command works for the plot VisPlot, VisHrm and VisPlot2.

Arguments:

none

Return value:


Example:

The following example looks for a subplot named 'RST' and performs an automatic scaling. ! perform autoscale of x-axis object aPage; object aGrf; object aPlot; int iFailed; iFailed=1; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! perform automatic scaling now iFailed = aPlot.DoAutoScaleX(); if (iFailed > 0) { ! just to demonstrate the return value. printf('Could not scale x-axis'); } } } }

Also see VisFft Methods

SetViPage Methods

SetDesktop Methods

VisPlot.DoAutoScaleY

int VisPlot.DoAutoScaleY ()

Scales the y-axis of the plot automatically. The function works for local y-scales only. If the y-scale is not local a warning is shown in the output window and 1 is returned by the function. This command works for the plot VisPlot, VisHrm, VisFft and VisPlot2.

Arguments:

none

Return value:


Example:

The following example looks for a subplot named 'RST' and performs an automatic scaling. ! perform autoscale of y-axis object aPage; object aGrf; object aPlot; int iFailed; iFailed=1; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! perform automatic scaling now iFailed = aPlot.DoAutoScaleY(); if (iFailed > 0) { ! just to demonstrate the return value. printf('Could not scale y-axis'); } } } }



Also see SetViPage Methods

VisPlot2.DoAutoScaleY2

int VisPlot2.DoAutoScaleY2 ()

Scales the second y-axis of the plot automatically. The function works if the y-Axis is enabled and uses the local y-scale settings. In any other case a warning is produced and the function returns 1.

Arguments:

none

Return value:


Example:

The following example looks for a subplot named 'RST' and performs an automatic scaling. ! perform autoscale of y2-axis object aPage; object aGrf; object aPlot; int iFailed; iFailed=1; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot2',1); if (aPlot) { ! perform automatic scaling now iFailed = aPlot.DoAutoScaleY2(); if (iFailed > 0) { ! just to demonstrate the return value. printf('Could not scale y2-axis'); } } } }

Also see SetViPage Methods

VisPlot.SetAutoScaleX

void VisPlot.SetAutoScaleX (int mode)

Sets automatic scaling mode of the x-scale for local scales.

Arguments:


Return value:

none

Example:

The following example looks for a Subplot named 'RST' and change its auto scale mode. The first example works fine, the second one generates an error message because the x-scale is unused.

! Set autoscale mode of x-scale to off object aPage; object aGrf; object aPlot; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Set limits to change x-scale of page to u sed scale aPlot.SetScaleX(0,10); ! Turn off automatic scaling of x-scale aPlot.SetAutoScaleX(0); } } } ! Try to set autoscale mode of x-scale to online object aPage; object aGrf; object aPlot; ! Look for opened Graphics Board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Reset option 'Use local x-Axis' of Subplo t aPlot.SetDefScaleX(); ! Try to set automatic scaling of x-scale t o Online aPlot.SetAutoScaleX(2); } } }


VisPlot.SetAutoScaleY

void VisPlot.SetAutoScaleY (int mode) Sets automatic scaling mode of the y-scale for local scales.

Arguments:


Return value:

none

Example:

The following example looks for a Subplot named 'RST' and change its auto scale mode. The first example works fine, the second one generates an error message because the y-scale is unused.

! Set autoscale mode of y-scale to off object aPage; object aGrf; object aPlot; ! Look for opened graphics board.aGrf=GetGraphBoa rd(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Set limits to change y-scale of page to u sed scale aPlot.SetScaleY(0,10); ! Turn off automatic scaling of y-scale aPlot.SetAutoScaleY(0); } } } ! Try to set autoscale mode of y-scale to online object aPage; object aGrf; object aPlot; ! Look for opened Graphics Board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1);



if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Reset option 'Use local y-Axis' of Subplo t aPlot.SetDefScaleY(); ! Try to set automatic scaling of y-scale t o Online aPlot.SetAutoScaleY(2); } } }


VisPlot.SetAdaptX

void VisPlot.SetAdaptX (int mode, double trigger)

Sets the adapt scale option of the x-scale for local scales.

Arguments:


double trigger (optional) : Trigger value, unused if mode is off or empty

Return value:

none

Example:

The following examples look for a Subplot named 'RST' and change its adapt scale option. The first example works fine, the second one generates an error message because the x-scale is unused.

! Modify adapt scale option of Subplot object aPage; object aGrf; object aPlot; ! Look for opened Graphics Board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Set x-scale limits to set option 'Use local x-Axis' aPlot.SetScaleX(0,20); ! Turn on adapt scale, use a trigger value of 3 aPlot.SetAdaptX(1,3); ! Turn off adapt scale aPlot.SetAdaptX(0,3); ! Turn on adapt scale again, do not change th e trigger value aPlot.SetAdaptX(1); } } } ! Try to turn on adapt scale of x-scale object aPage; object aGrf;object aPlot; ! Look for opened Graphics Board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Reset option 'Use local x-Axis' of Subplot aPlot.SetDefScaleX(); ! Try to turn on adapt scale, use a trigger v alue of 3 ! Leads to error message because scale is not local aPlot.SetAdaptX(1,3); } } }


VisPlot.SetAdaptY

void VisPlot.SetAdaptY (int mode, double offset)

Sets the adapt scale option of the y-scale for local scales.

Arguments:


double trigger (optional) : Offset, unused if mode is off or empty

Return value:

none

Example:

The following examples look for a Subplot named 'RST' and change its adapt scale option of the y scale. The first example works fine, the second one generates an error message because the y-scale is unused.

! Modify adapt scale option of Subplot object aPage; object aGrf; object aPlot; ! Look for opened Graphics Board.aGrf=GetGraphBoard (); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Set y-scale limits to set option 'Use local y-Axis' aPlot.SetScaleY(0,20); ! Turn on adapt scale, use a trigger value of 3 aPlot.SetAdaptY(1,3); ! Turn off adapt scale aPlot.SetAdaptY(0,3); ! Turn on adapt scale again, do not change th e trigger value aPlot.SetAdaptY(1); } } } ! Try to turn on adapt scale for y-scale object aPage; object aGrf; object aPlot; ! Look for opened Graphics Board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Reset option 'Use local y-Axis' of Subplot aPlot.SetDefScaleY(); ! Try to turn on adapt scale, use a trigger v alue of 3 ! Leads to error message because scale is not local aPlot.SetAdaptY(1,3); } } }


VisPlot.GetScaleObjX

object VisPlot.GetScaleObjX ()

Returns used object defining x-scale. The returned object is the Subplot itself, the Virtual Instrument Panel or the Graphics Board.

Arguments:



none

Return value:

Object defining the x-scale.

Example:

The following examples look for a Subplot named 'RST' and get the used x-scale object. There are three different examples.

1. Example: Used scale is Graphics Board 2. Example: Used scale is Virtual Instrument Panel 3. Example: Used scale is Subplot itself. ! Used scale is Graphics Board object aPage; object aGrf; object aPlot; object aScale; ! Look for opened graphics board.aGrf=GetGraphBoard (); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Reset option 'Use local x-Axis' of Virtual In strument Panel aPage.SetDefScaleX(); ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Reset option 'Use local x-Axis' of Subplot aPlot.SetDefScaleX(); ! Get object defining scale aScale=aPlot.GetScaleObjX(); if (aPlot=aScale) { output('The scale used is the Subplot itsel f.'); } else if (aPage=aScale) { output('The scale used is the Virtual Instr ument Panel.'); } else if (aGrf=aScale) { output('The scale used is the Graphics Boar d.'); } else { output('The scale used was not found.'); } } } } ! Used Scale is Virtual Instrument Panel object aPage; object aGrf; object aPlot; object aScale; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Set x-scale to change it to local aPage.SetScaleX(1,100); ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Reset option 'Use local x-Axis' of Subplot aPlot.SetDefScaleX(); ! Get object defining scale aScale=aPlot.GetScaleObjX(); if (aPlot=aScale) { output('The scale used is the Subplot itsel f.'); } else if (aPage=aScale) { output('The scale used is the Virtual Instr ument Panel.'); } else if (aGrf=aScale) { output('The scale used is the Graphics Boar d.'); } else { output('The scale used was not found.'); } } } } ! Used Scale is Subplot itself object aPage; object aGrf; object aPlot; object aScale; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Reset option 'Use local x-Axis' of Virtual In strument Panel aPage.SetDefScaleX(); ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Set x-scale of Subplot to change it to loca l aPlot.SetScaleX(1,100); ! Get object defining scale aScale=aPlot.GetScaleObjX(); if (aPlot=aScale) { output('The scale used is the Subplot itsel f.'); } else if (aPage=aScale) { output('The scale used is the Virtual Instr ument Panel.'); } else if (aGrf=aScale) { output('The scale used is the Graphics Boar d.'); } else { output('The scale used was not found.'); } } } }


VisPlot.GetScaleObjY

object VisPlot.GetScaleObjY ()

Returns used object defining y-scale. The returned object is either the Subplot itself or the Plot Type (IntPlot).

Arguments:

none

Return value:

Object defining the y-scale.

Example:

The following examples look for a Subplot named 'RST' and get the used y-scale object. There are three different examples.

1. Example: Used scale is Plot Type.

2. Example: Used scale is Subplot itself. ! Used scale is Plot Type object aPage; object aGrf; object aPlot; object aScale; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Reset option 'Use local y-Axis' of Subplot aPlot.SetDefScaleY(); ! Get object defining scale aScale=aPlot.GetScaleObjY(); if (aScale=aPlot) { output('The y-scale used is the Subplot its elf.'); } else { output('The y-scale used is the Plot Type.' ); } } } } ! Used scale is Subplot itself object aPage;



object aGrf; object aPlot; object aScale; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Set x-scale of Subplot to change it to loca l aPlot.SetScaleY(1,100); ! Get object defining scale aScale=aPlot.GetScaleObjY(); if (aScale=aPlot) { output('The y-scale used is the Subplot its elf.'); } else { output('The y-scale used is the Plot Type.' ); } } } }


VisPlot.SetCrvDesc

object VisPlot.SetCrvDesc (int index, string desc [, string desc1]...)

Sets the description of curves starting at curve number 'index'. A list of descriprions can be set.

Arguments:

int index (obligatory) : Row of first curve to change the description.

string desc (obligatory) : Description to set for curve in row index.

string desc1 (optional) : Description to set for curve in row index+1. Object defining the y-scale.

Example:

The following examples look for a Subplot named 'RST' sets the description for the curves defined in row two and three. The first variable's description remains unchanged. ! Modify descriptions object aPage; object aGrf; object aPlot; object aScale; ! Note: object load is an interface parameter, ! therefore it is not defined here! Look for opened graphics board.aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Clear variable list aPlot.Clear(); ! Append variables aPlot.AddVars(load, 'm:U1:bus1','m:U1l:bus1', 'm:phiu1:bus1'); ! Set description of row 2 and 3 aPlot.SetCrvDesc(2,,'Line-Line Voltage','Angl e'); } } }


H.10.3 VisFft Methods

DoAutoScaleX

VisFft.DoAutoScaleX

int VisFft.DoAutoScaleX ()

Scales the x-axis of the fft plot automatically. After scaling the x-axis automatically the x-scale minimum is 0. The maximum is nsamples/2 or nsamples/2 x fundamental frequency.

Arguments:

none

Return value:

always 0

Example:

The following example looks for a FFT-Plot named 'FFT' and performs an automatic scaling. ! perform autoscale of x-axis object aPage; object aGrf; object aPlot; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get FFT plot named 'FFT' aPlot=aPage.GetVI('RST','VisFft',1); if (aPlot) { ! perform automatic scaling now aPlot.DoAutoScaleX(); } } }

Also see VisPlot Methods and SetViPage Methods

H.10.4 IntPlot Methods

SetScaleY

SetAutoScaleY

SetAdaptY

IntPlot.SetScaleY

void IntPlot.SetScaleY (double min, double max, int log)

Sets scale of y-axis. Invalid arguments like negative limits for logarithmic scale are not set. No arguments --> automatic scaling.

Arguments:

double min (optional) : Minimum of y-scale.





double max (optional) : Maximum of y-scale.

int log (optional) : > 0 --> y-scale is logarithmic; 0 --> y-scale is linear.

Return value:

none

Example:

The following example looks for a Subplot named 'RST' and set its y-axis scale. There are three different examples. 1. Example: Perform auto scaling on y-Axis. 2. Example: Set minimum to 0 and maximum to 20. 3. Example: Set minimum to 1 and maximum to 1000. Changes to a log. scale

! Automatic scaling of y-scale object aPage; object aGrf; object aPlot; object aScale; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Reset option 'Use local y-Axis' of subplot aPlot.SetDefScaleY(); ! Get object defining scale (now IntPlot) aScale=aPlot.GetScaleObjY(); if (aScale) { ! Perform auto scaling aScale.SetScaleY(); } } } } ! Set minimum and maximum without changing map mode object aPage; object aGrf; object aPlot; object aScale; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Reset option 'Use local y-Axis' of subplot aPlot.SetDefScaleY(); ! Get object defining scale (now IntPlot) aScale=aPlot.GetScaleObjY(); if (aScale) { ! Perform auto scaling aScale.SetScaleY(0,20); } } } } ! Set minimum and maximum, set map mode to log. object aPage; object aGrf; object aPlot; object aScale; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Reset option 'Use local y-Axis' of subplot aPlot.SetDefScaleY(); ! Get object defining scale (now IntPlot) aScale=aPlot.GetScaleObjY(); if (aScale) { ! Perform auto scaling aScale.SetScaleY(1,1000,1); } } } }


IntPlot.SetAutoScaleY

void IntPlot.SetAutoScaleY (int mode)

Sets automatic scaling mode of the y-scale.

Arguments:


Return value:

none

Example:

The following example sets the auto scale mode of the Plot Type to On. ! Set autoscale option of Plot Type object aPage; object aGrf; object aPlot; object aScale; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Reset option 'Use local y-Axis' of subplot aPlot.SetDefScaleY(); ! Get object defining scale (now IntPlot) aScale=aPlot.GetScaleObjY(); if (aScale) { ! Set auto scale option to on aScale.SetAutoScaleY(1); } } } }


IntPlot.SetAdaptY

void IntPlot.SetAdaptY (int mode, double offset)

Sets the adapt scale option of the y-scale.

Arguments:


double offset (optional) : Offset, unused if mode is off or empty

Return value:

none

Example:

The following examples look for a Subplot named 'RST', gets its Plot Type and changes the adapt scale option of the scale. ! Modify adapt scale option of Plot Type



object aPage; object aGrf; object aPlot; object aScale; ! Look for opened graphics board. aGrf=GetGraphBoard(); if (aGrf) { ! Get Virtual Instrument Panel named Voltage aPage=aGrf.GetPage('Voltage',1); if (aPage) { ! Get subplot named 'RST' aPlot=aPage.GetVI('RST','VisPlot',1); if (aPlot) { ! Reset option 'Use local y-Axis' of subplot aPlot.SetDefScaleY(); ! Get object defining scale (now IntPlot) aScale=aPlot.GetScaleObjY(); if (aScale) { ! Set y-scale limits to set option 'Use loc al y-Axis' aScale.SetScaleY(0,20); ! Turn on adapt scale, use an offset of 3 aScale.SetAdaptY(1,3); ! Turn off adapt scale aScale.SetAdaptY(0,3); ! Turn on adapt scale again, do not change the offset aScale.SetAdaptY(1); } } } }


H.11 Methods for Additional Objects (Int*)

IntVariant Methods

IntMon Methods

IntMat Methods

IntVec Methods

IntForm Methods

H.11.1 IntVariant Methods

Activate Adds a variant to the active study case

Deactivate Removes a variant from the active study case

IntVariant.Activate

int IntVariant.Activate ()

Adds a variant to the active study case.

Arguments:

none

Return value:


See also



IntVariant.Deactivate

int IntVariant.Deactivate ()

Removes a variant from the active study case.

Arguments:

none

Return value:


See also



H.11.2 IntMon Methods

PrintVal Prints the values of the selected variables

PrintAllVal Prints a description for all variables

NVars returns the number of selected variables

GetVar Returns the n'th selected variable name

RemoveVar De-selects a variable

ClearVars Clears the selected variable names

AddVar Selects a variable name

IntMon.PrintVal

void IntMon.PrintVal ()

Prints the values of the selected variables to the output window.

Arguments:

none

Return value:






none

See also



IntMon.PrintAllVal

void IntMon.PrintAllVal ()

Prints a description for all available variables to the output window.

Arguments:

none

Return value:

none

See also



IntMon.NVars

int IntMon.NVars ()

Returns the number of selected variables or, more exact, the number of lines in the variable selection text on the second page of the IntMon dialogue, which should contain one variable name per line.

Arguments:

none

Return value:

The number of selected variables.

See also



IntMon.GetVar

string IntMon.GetVar (int row)

Returns the variable name on the given row of the variable selection text on the second page of the IntMon dialogue, which should contain one variable name per line.

Arguments:

none

Return value:

The variable name.

See also



IntMon.RemoveVar

int IntMon.RemoveVar (string name)

Removes the variable "name'' from the list of selected variable names.

Arguments:

The variable name.

Return value:

1 when the variable name was not found, 0 otherwise.

See also



IntMon.ClearVars

int IntMon.ClearVars ()

Clears the list of selected variable names.

Arguments:

none

Return value:

none

See also



IntMon.AddVar

int IntMon.AddVar (string name)

Appends the variable "name'' to the list of selected variable names.

Arguments:

The variable name.

Return value:

none

See also



H.11.3 IntMat Methods

Get Returns the (row, col) value




Set Set the value at position (row,col)

Init Initializes the matrix

Resize Resizes the matrix

NRow Returns the number of rows in the matrix

NCol Returns the number of columns in the matrix

RowLbl Sets the label of the R'th row

ColLbl Sets the label of the C'th column

IntMat.Get

double IntMat.Get (int row, int col)

Returns the (row, col) value from the matrix. An run-time error will occur when 'row' or 'col' are out of range.

Arguments:

int row (obligatory) : row in matrix: 1..NRow()

int col (obligatory) : column in matrix: 1..NCol()

Return value:

Value in matrix.

Example:

The following example multiplies two matrices int r,c,z,s,s1r,s2c; double v1,v2,v; s = M1.NCol(); r = M2.NRow(); if (s<>r) {exit();} s1r = M1.NRow(); s2c = M2.NCol(); M3.Init(s1r,s2c); r=1; while (r<=s1r) { c=1; while (c<=s2c) { z=1; v=0.0; while (z<=s) { v1=M1.Get(r,z); v2=M2.Get(z,c); v+=v1*v2; z+=1; } M3.Set(r,c,v); c+=1; } r+=1; }

See also



IntMat.Set

int IntMat.Set (int row, int col, double V)

Set the value at position (row,col) in the matrix to V. The matrix is automatically resized if necessary.

Arguments:

int row (obligatory) : row number: 1..NRows()

int col (obligatory) : col number: 1..NCols()

double Vj (obligatory) : value

Return value:

0 on success

Example:

See IntMat.Get for an example.

IntMat.Init

int IntMat.Init (int NRows, int NCols)

Initializes the matrix. The size is set to (NRows, NCols), all values are set to 0.

Arguments:

int NRows (obligatory) : number of rows

int NCols (obligatory) : number of columns

Return value:

0 on success

Example:


IntMat.Resize

int IntMat.Resize (int NRows, int NCols)

Resizes the matrix. Existing values will not be changed. Added values will be set to 0.

Arguments:

int NRows (obligatory) : number of rows

int NCols (obligatory) : number of columns

Return value:

0 on success

Example:

The following example gets a value from the matrix, possibly resizing it first. int Nc,Nr,x,y; Nr = Mat.NRows(); Nc = Mat.NCols(); x=5;y=3; if ({x>Nr}.or.{y>Nc}) { Mat.Resize(x,y); } v = Mat.Get(x,y);

See also



IntMat.NRow

int IntMat.NRow ()

Returns the number of rows in the matrix. The function "NRow()'' replaces the obsolete function "SizeX()''.

Arguments:



none

Return value:

The number of rows

Example:


IntMat.NCol

int IntMat.NCol ()

Returns the number of columns in the matrix. The function "NCol()'' replaces the obsolete function "SizeY()''.

Arguments:

none

Return value:

The number of columns

Example:


IntMat.RowLbl

string IntMat.RowLbl (String S, int R)

Sets or reads the label of the R'th row.

Arguments:

String S (optional) : Labelstring, required to set the label

int R (obligatory) : Number of the row

Return value:

Assigned or read labelstring

Example:

The following example labels some rows. Mat.RowLbl('overloaded',1); Mat.RowLbl('overvoltage',2); Mat.RowLbl('undervoltage',3);

The following example assigns the label of the first row to the string aLabel string aLabel; aLabel = Mat.RowLbl(1);

See also



IntMat.ColLbl

string IntMat.ColLbl (String S, int C)

Sets or reads the label of the C'th column.

Arguments:

String S (optional) : Labelstring

int C (obligatory) : Number of the column

Return value:

Assigned or read labelstring

Example:

The following example labels some columns. Mat.ColLbl('transformers',1); Mat.ColLbl('lines',2); Mat.ColLbl('busbars',3);

The following example assigns the label of the first column to the string aLabel string aLabel; aLabel = Mat.ColLbl(1);

See also



H.11.4 IntVec Methods

Get Returns the value at index i

Set Sets the value at index i

Init Initializes the vector

Resize Resizes the vector

Size Returns the size of the vector

IntVec.Get

double IntVec.Get (int i)

Returns the value at index i.

Arguments:

int i (obligatory) : Vector index.

Return value:

Value at index i.

Example:

The following example adds two vectors. int i,j; double v1,v2; i = Vec1.Size(); j = Vec2.Size(); if (i<>j) { output('invalid operation'); exit(); } Vec3.Init(i); i=1; while (i<=j) { v1 = Vec1.Get(i); v2 = Vec2.Get(i);




Vec3.Set(i,v1+v2); i+=1; }

See also



IntVec.Set

double IntVec.Set (int i, double V)

Sets the value at index i to V. Valid indexes are in [1, IntVec.Size()].

Arguments:

int i (obligatory) : Vector index.

double V (obligatory) : The value to set.

Return value:

0 on success

Example:

See IntVec.Get for an example.

IntVec.Init

int IntVec.Init (int Size)

Initializes the vector. Sets the length to Size and all values to 0.

Arguments:

int Size (obligatory) : The initial size.

Return value:

0 on success

Example:


IntVec.Resize

int IntVec.Resize (int Size)

Resizes the vector. Added values are set to 0.0.

Arguments:

none

Return value:

0 on success

Example:

The following example adds a value to a dynamically scaled vector. int i,s; i = 5; s = Vec.Size(); if (i>s) { Vec.Resize(i); } Vec.Set(i,V);

See also



IntVec.Size

int IntVec.Size ()

Returns the size of the vector.

Arguments:

none

Return value:

The size of the vector

Example:


H.11.5 IntForm Methods

SetText Sets the format text

WriteOut Write the report to the output window

IntForm.SetText

int IntForm.SetText (String Text)

Sets the format text of a report form.

Arguments:

String Text (obligatory) : The format text string

Return value:

0 on success

Example:

The following example sets a format string and writes the report for two sets set SLines,SLoads; ... fill SLines and SLoads ... OvlReport.SetText(' | Loading of lines: |$H $LOOP,_EXTERNAL |# #.# |$N,loc_name,loading $END '); OvlReport.WriteOut(SLines, SLoads);

See also IntForm.WriteOut

See also






IntForm.WriteOut

int IntForm.WriteOut (set ListSet, set PoolSet, int Landscape)

Write the report to the output window.

The report form object will write a report to the output window, based on the format text, for the objects in the ListSet and the PoolSet. The ListSet is used in the _EXTERNAL macro. All format lines between the $LOOP,_EXTERNAL and the $END macro's will be written for each object in the Listset, which is therefore called the 'sequential set'. In the format text itself, objects from the PoolSet may be referenced directly by the "ACC(x)'' macro, which is replaced by the x'th object in the PoolSet. The PoolSet is therefore called the 'random access set'. The ListSet or PoolSet may be empty.

The command object that is normally reached by the macro "DEF'' in report forms will always return the main DPL command that is running at the moment, even when the 'WriteOut' call is made in a DPL subscript.

Arguments: Set ListSet (obligatory) : The sequential set of objects

Set PoolSet (optional) : The random access set of objects

int Landscape (optional) : Sets the page orientation used to calculate the number of lines fitting on a printed page

0 = Portrait, 1 = Landscape; default: Landscape

Return value:

0 on success

Example:

The following example reports the loading of a list of objects for a certain load condition. The objects for the loading are sequentially listed. The load conditions are reported for a special set of loads, which are given as a pool of objects.

set SLines,SLoads; ... fill SLines and SLoads ... OvlReport.WriteOut(SLines, SLoads);

If OvlReport has the following format string: ---------------------$H, | command : # |$H,DEF:loc_name | Load settings: |$H| # #.# |$H,AC C(2):loc_name,ACC(2):plini | # #.# |$H,ACC(3):loc_name,ACC(3):pl ini ---------------------$H, | Loading of lines: |$H $LOOP,_EXTERNAL |# #.# |$N,loc_name,loading $END ---------------------$F,

the following report could be the result: ---------------------|

command : FindWL |

| Load settings: |

| Ld12a 3.43 |

| Ld14b 2.52 |

---------------------

| Loading of lines: |

| Ln1 95.6 |

| Ln2 92.1 |

| Ln3 90.4 |

| Ln4 85.3 |

| Ln5 84.7 |

| Ln6 84.2 |

| Ln7 82.6 |

| Ln8 62.5 |

---------------------

See also IntForm.SetText

See also



H.12 DDE Functions

ddeOpen Establishes a DDE connection to a topic of an application.

ddeClose Closes the DDE link.

ddeExe Starts command in the current dde opened topic.

ddePoke Sends data to an item in the currently opened DDE topic.

ddeRequest Receives data from an item in a previously opened DDE topic.

ddeOpen

int ddeOpen(string sPath, string sAppName, string sTopic)

Establishes a DDE connection to a topic of an application.

Arguments:

string sPath (obligatory) :Path to application to start. If empty ('') the application must be started manually by the user. If path is given, ddeOpen will start the application if it not already running.

string sAppName (obligatory) : Application name.

string sTopic (obligatory) : Topic; The topic of a DDE conversation can be either the name of a open document or the special topic "System". A document can be either a regular document in the application, a template, or a macro

Return value:

0 on success, != 0 on errors

Example:

The following example establishes a DDE connection to topic System of Excel and closes the connection if successfully established. int ierr; ! open a DDE connection to Excel : ierr = ddeOpen(s, 'Excel', 'System'); if (.not.ierr) { ! ok, excel can be opened. ! ... ddeClose(); }

Also see ddeClose

ddeClose

void ddeClose()

Closes the DDE link.

Arguments:




none

Return value:

none

Example:

The following example establishes a DDE link to topic named 'System' of Excel and closes the connection if successfully established. int ierr; ! open a DDE connection to Excel : ierr = ddeOpen(s, 'Excel', 'System'); if (.not.ierr) { ! ok, excel can be opened. ! ... ddeClose(); }

Also see ddeOpen

ddeExe

int ddeExe (string sCmd)

Starts command in the currently opened topic. A command can be a visual basic command, too. Commands are usually sent to the topic named 'System'.

Arguments:

string sCmd (obligatory): Command to execute

Return value:

<0 if the dde connection was not established before calling ddeExe, =0 if ddeExe successfully executed, >0 if ddeExe failed

Example:

The following example looks for a sheet named 'Sheet1'. A new sheet is created if Sheet1 was not found. Then the DDE link to the page is established. int ierr; ierr = ddeOpen('', 'Excel', 'System'); if (.not.ierr) { ! excel can be opened. Now close and connect to a specific sheet ddeClose(); ierr = ddeOpen('', 'Excel', 'Sheet1'); if (ierr) { Info('No Sheet1 yet, creating one...'); ierr = ddeOpen('', 'Excel', 'System'); if (ierr) { printf('Cannot open DDE to Excel'); } else { ! create a new sheet ddeExe('[New(1)]'); ddeClose(); ierr = ddeOpen('', 'Excel', 'Sheet1'); } } } if (ierr) { Error('Could not open DDE connection'); exit(); }

ddePoke

int ddePoke (string sItem, string sData)

Sends data to an item in the currently opened DDE topic.

Arguments:

string sItem: the item receiving the data. Examples for an item are a cell in excel or a named bookmark in word.

string sData: the data to send.

Return value:

<0 if the dde connection was not established before calling ddePoke, =0 if the ddePoke was successfully executed, >0: if the ddePoke failed.

Example:

The following example writes data to some cells on the worksheet named 'Sheet1' in Excel. It is assumed that Excel is already running when starting the dpl command. int ierr, i; double x,y,z; string s,s1,s2; Warn('This example assumes an English Excel'); Warn('Other languages should translate the Excel commands'); Warn('like "concatenate"'); ! open a DDE connection to Sheet1 : ierr = ddeOpen('', 'Excel', 'System'); if (.not.ierr) { ! excel can be opened. Now close and connect to a specific sheet ddeClose(); ierr = ddeOpen('', 'Excel', 'Sheet1'); if (ierr) { Info('No Sheet1 yet, creating one...'); ierr = ddeOpen('', 'Excel', 'System'); if (ierr) { printf('Cannot open DDE to Excel'); } else { ! create a new sheet ddeExe('[New(1)]'); ddeClose(); ierr = ddeOpen('', 'Excel', 'Sheet1'); } } } if (ierr) { Error('Could not open DDE connection'); exit(); } ! write some numbers x = 3; while (x<7) { y = 5; while (y<14) { z = x+y/100; s1 = sprintf('R%dC%d',x,y); s2 = sprintf('%f',z); ddePoke(s1,s2); ! poke the numbers in the she et y+=1; } x+=1; }

Also see ddeRequest

ddeRequest

int ddeRequest (string sItem, string sStringData, double dNumVal)

Receives data from an item in a previously opened DDE topic

Arguments:

string sItem: The item. Examples for an item are a cell in excel or a named bookmark in word

string sStringData:The data received from the topic as string (return value=2)

double dNumVal:The data received from the topic as a number (if sStringData is a number, return value=2)

Return value:

<0 if the dde connection was not established before calling ddeRequest, =0 if the ddeRequest failed, =1 if value is a number, =2 if value is a string.

Example:

The following is a small code fragment where data is read from an Excel sheet. The code fragment runs fine, in case that the currently opened DDE topic is an Excel sheet. i = ddeRequest('R12C2',s,x); ! get the contents o f a cel if (i=1) printf('%f', x); ! i=1 means a number i = ddeRequest('R5C2',s,x); if (i=2) printf('%s', s); ! i=2 means a string

Also see ddePoke



Appendix I DSL Reference

DSL Standard Functions

DSL Special Functions

I.1 DSL Standard Functions

All trigonometric functions use RADIANS.

I.2 DSL Special Functions

lim

lim (x, min, max)


Nonlinear limiter function:

limstate

limstate (x1, min, max)


Nonlinear limiter function for creating limited integrators.

Example: x1. = xe/Ti; y = limstate(x1,min,max);

This was previously realized by using "select'' and "lim'' functions: x1. = select( {x1>=max.and.xe>0} & .or.{x1<=min.and.xe<0}, 0, xe/Ti); y = lim(x1,min,max);

delay

delay (x, Tdelay)


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

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

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



Table I.1: Standard DSL Functions List

function description example

sin(x) sine sin(1.2)=0.93203

cos(x) cosine cos(1.2)=0.36236

tan(x) tangent tan(1.2)=2.57215

asin(x) arcsine asin(0.93203)=1.2

acos(x) arccosine acos(0.36236)=1.2

atan(x) arctangent atan(2.57215)=1.2

sinh(x) hyperbolic sine sinh(1.5708)=2.3013

cosh(x) hyperbolic cosine cosh(1.5708)=2.5092

tanh(x) hyperbolic tangent tanh(0.7616)=1.0000

exp(x) exponential value exp(1.0)=2.718281

ln(x) natural logarithm ln(2.718281)=1.0

log(x) log10 log(100)=2

sqrt(x) square root sqrt(9.5)=3.0822

sqr(x) power of 2 sqr(3.0822)=9.5

pow (x,y) power of y pow(2.5, 3.4)=22.5422

abs(x) absolute value abs(-2.34)=2.34

min(x,y) smaller value min(6.4, 1.5)=1.5

max(x,y) larger value max(6.4, 1.5)=6.4

modulo(x,y) remainder of x/y modulo(15.6,3.4)=2

trunc(x) integral part trunc(-4.58823)=-4.0000

frac(x) fractional part frac(-4.58823)=-0.58823

round(x) closest integer round(1.65)=2.000

ceil(x) smallest larger integer ceil(1.15)=2.000

floor(x) largest smaller integer floor(1.78)=1.000

time() current simulation time time()=0.1234

pi() 3.141592... pi()=3.141592...

twopi() 6.283185... twopi()=6.283185...

e() 2,718281... e()=2,718281...




select

select (boolexpr, x, y)


Returns x if boolexpr is true, else y.

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

time

time ()


Returns the current simulation time.

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

file

file (ascii-parm, expr)


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

picdro

picdro (boolexpr, Tpick, Tdrop)


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

Return value:

The internal state:

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

� changes from 1 to 0, if boolexpr=0, after Tdrop seconds

� remains unaltered in other situations.

flipflop

flipflop (boolset, boolreset)


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

Return value:

The internal state:

� changes from 0 to 1, if boolset=1 and boolreset=0 (SET)

� changes from 1 to 0, if boolset=0 and boolreset=1 (RESET)

� remains unaltered in other situations. (HOLD)

Initial value: boolset.

The initial condition boolset=boolreset=1 will cause an error message.

aflipflop

aflipflop (x, boolset, boolreset)


'Analog' flip-flop function. Returns the (old) value for x at SET-time if internal state=1, else returns the current value of x.

Return value:

The internal state:

� changes from 0 to 1, if boolset=1 and boolreset=0 (SET)

� changes from 1 to 0, if boolset=0 and boolreset=1 (RESET)

� remains unaltered in other situations. (HOLD)

lapprox

lapprox (x, array_iiii)


Returns the linear approximation y=f(x), where f is defined by the array_iiii. Please consider that the array has to be sorted in ascending order.

Example: y = lapprox(1.8, array_valve)

invlapprox

invlapprox (y, array_iiii)


Inverse lapprox with array.

lapprox2

lapprox2 (xl, xc, matrix_iiii)


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

Example: y = lapprox2(2.5, 3.7, matrix_cp)

sapprox

sapprox (x, array_iiii)


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

Example: y = sapprox(1.8, array_valve)

sapprox2

sapprox2 (xl, xc, matrix_iiii)


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

Example: y = sapprox2(2.5, 3.7, matrix_cp)

event

Option 1: calling a predefined event in the DSL element event( Condition, trigger, 'name=ThisEvent dtime=delay value=val variable=var')

Option 2: target specification, no create parameter event( Condition, trigger, 'target=ThisSlot name=ThisEvent dtime=delay value=val variable=var')

Option 3: create and target specification event( Condition, trigger, 'create=ThisEvtType target=ThisSlot name=ThisEvent dtime=delay value=val variable=var')




This function can create or call any kind of event for the DSL model itself or elements inside the network. The event is executed, if the input signal trigger changes sign from - to + with a time delay of dtime.

Mind: the event command has changed from DSL level 3 to level 4!

Arguments:

int Condition (obligatory) Boolean expression to activate (=1) or deactivate (=0) the event handling; if Condition is set to 1, the event can be executed, depending on the trigger signal.

double trigger (obligatory) The trigger signal, which will enable the execution of the event.

The string format determines the details of the eve nt call, and which of the three options above appli es:

string ThisEvtType (mandatory, only option 3) Type of event to be created. To specify the type use e.g. 'EvtParam' for parameter event or 'EvtSwitch' for switch event, etc.

string ThisSlot (mandatory, only options 2 and 3) If 'target=this' is defined, the event is applied to a singal of the present DSL model. If any other name is given, the DSL interpreter checks the composite model where the present DSL model (common model) is used and searches for a slot with the given name. The event is then applied to the element assigned to that slot.

string ThisEvent (obligatory) Name of the event created (option 3) or the external event to be started (option 1/2). The external event must be stored locally in the DSL model. If 'name=this' is set, a parameter event will be created and executed automatically with the DSL element itself as the target.

double delay (obligatory) Delay time of the event after triggering.

double val (optional) Value of the parameter event (only when 'name=this' is set or when a parameter event is created).

double var (optional) Parameter to which the value is set (only when 'name=this' is set or when a parameter event is created).

Return value:


Remark:

If the event()-definition according to options 2/3 is used, the create and target parameters must be the first parameters that are listed.

Examples:

The example shows a clock made with DSL using event( , ,'name=this ...') which automatically creates and configures a parameter event. The variable named xclock will be reset to value val=0 within dtime=0, if the integrator output xclock is larger than 1 . The input signal is a clock signal with the time period Tclock.

inc(xclock)=0 inc(clockout)=0 xclock.=1/Tclock reset_clock=select(xclock>1,1,-1) event(enable,reset_clock,'name=this value=0 var iable=xclock') clockout=xclock

The following event calls an external event called 'OpenBreaker', which is stored and defined inside the DSL element, if yo changes sign from - to +. The delay time is 0.2s. event(1,yo,'name=OpenBreaker dtime=0.2')

The following event is a simple undervoltage load-shedding relay. The element in the slot 'Load' will be disconnected with a swicth event 'EvtSwitch', when the signal 'u-umin' becomes positive. The event in the event list will be called 'TripLoad'.

event(1,umin-u,'create=EvtSwitch name=TripLoad target=Load')




04 appendix

Documents

settings sesa157733 configuracin local temp hh3efb

local defined script

context sensitive menu

ground capacitance hv

context menu pops

opened graphics board

active graphics board

ground capacitance lv