PowerWorld Simulator version 11. Manual

Auxiliary Script/Data Files

DCPC: for lossless DC that takes into account phase shifter operation.

CalculatePTDFMultipleDirections(StoreValuesForBranches, StoreValuesForInterfaces, LinearMethod);

Use this action to calculate the PTDF values using multiple directions. Only directions with the field INCLUDE set to

YES will be analyzed when calculating the multiple direction PTDF’s. You may optionally specify the linear

calculation method. If no Linear Method is specified, Lossless DC will be used.

StoreValuesForBranches :

Set to YES or NO. YES means that the PTDF’s for lines/transformers will

be stored.

StoreValuesForInterfaces :

Set to YES or NO. YES means that the PTDF’s for interfaces will be

stored.

LinearMethod :

The linear method to be used for the PTDF calculation. The options are:

AC: for calculation including losses.

DC: for lossless DC.

DCPC: for lossless DC that takes into account phase shifter operation.

CalculateLODF([BRANCH nearbusnum farbusnum ckt], LinearMethod);

Use this action to calculate the Line Outage Distribution Factors (or the Line Closure Distribution Factors) for a

particular branch. If the branch is presently closed, then the LODF values will be calculated, otherwise the LCDF

values will be calculated. You may optionally specify the linear calculation method as well. If no Linear Method is

specified, Lossless DC will be used.

[BRANCH nearbusnum farbusnum ckt] : The branch whose status is being changed.

LinearMethod :

The linear method to be used for the LODF calculation. The options are:

DC: for lossless DC.

DCPC: for lossless DC that takes into account phase shifter operation.

Note: AC is NOT an option for the LODF calculation.

CalculateTLR([flow element], direction, [transactor], LinearMethod);

Use this action to calculate the TLR values a particular flow element (transmission line or interface). You also

specify one end of the potential transfer direction. You may optionally specify the linear calculation method. If no

Linear Method is specified, Lossless DC will be used.

[flow element] :

This is the flow element we are interested in. Choices are:

[INTERFACE "name"]

[BRANCH nearbusnum farbusnum ckt]

direction :

the type of the transactor. Either BUYER or SELLER.

[trans actor buyer] :

the transactor of power. There are six possible settings.

[AREA num]

[ZONE num]

[SUPERAREA "name"]

[INJECTIONGROUP "name"]

[BUS num]

[SLACK]

LinearMethod :

The linear method to be used for the calculation. The options are:

AC: for calculation including losses.

DC: for lossless DC.

DCPC: for lossless DC that takes into account phase shifter operation.

CalculateVoltSense([BUS num]);

This calculates the sensitivity of a particular buses voltage to real and reactive power injections at all buses in the

system. (Note: this assumes that the power is injected at a given bus and taken out at the slack bus).

[BUS num] :

The bus to calculate sensitivities for.

CalculateFlowSense([flow element], FlowType);

841

This calculates the sensitivity of the MW, MVAR, or MVA flow of a line or interface to real and reactive power

injections at all buses in the system. (Note: this assumes that the power is injected at a given bus and taken out at

the slack bus).

[flow element] :

This is the flow element we are interested in. Choices are:

[INTERFACE "name"]

[BRANCH num1 num2 ckt]

FlowType :

The type of flow to calculate this for. Either MW, MVAR, or MVA.

CalculateLossSense(FunctionType);

This action calculates the sensitivity of a real power loss function, PLosses, to bus real and reactive power

injections. Stated mathematically, this action calculates d PLosses/d Pi and d PLosses/d Qi , where Pi and Qi are

the real and reactive power injections at bus i, respectively. Stated less formally, this action indicates how losses

would change if one more MW or Mvar of power were injected at bus i.

FunctionType :

Specifies how the losses are computed. Choices are:

NONE: No losses are calculated because a loss function is not specified.

ISLAND: Losses are calculated with respect to the losses in bus’ island. If the power system consists of only

one island, losses are computed with respect to the total system losses.

AREA: Losses are calculated with respect to the total losses for the area containing bus i. This is probably the

most common loss function because usually one is concerned with

minimizing losses for a particular area rather than for the entire case.

AREASA: Losses are calculated with respect to the total losses for the area containing bus i if bus i does not

belong to a super area, and with respect to the total losses for the super

area containing bus i if bus i does belong to a super area.

SELECTED: Losses are calculated with respect to the total losses for a group of areas whose selected field is

set to YES.

SetSensitivitiesAtOutOfServiceToClosest;

This will take the P Sensitivity and Q Sensitivity values calculated using CalculateTLR, CalculateFlowSense, or

CalculateVoltSense actions and then populate the respective values at out-of-service buses so that they are equal

to the value at the closest in service bus. The "distance" to the in-service buses will be measured by the number of

nodes. If an out-of-service bus is equally close to a set of buses, then the average of that set of buses will be used.

In addition to the general run mode actions, there are specific actions for the following submodes: PowerFlow,

Contingency, ATC, Fault, PV and QV.

842

Auxiliary Script/Data Files

Script PowerFlow Submode Actions

The following actions are specific to the Run Mode submode PowerFlow:

DoCTGAction([contingency action]);

SolvePowerFlow(SolMethod, "filename1", "filename2", CreateIfNotFound1, CreateIfNotFound2);

SolvePrimalLP("filename1", "filename2", CreateIfNotFound1, CreateIfNotFound2);

SolveSinglePrimalLPOuterLoop("filename1", "filename2", CreateIfNotFound1, CreateIfNotFound2);

SolveFullSCOPF(BCMethod, "filename1", "filename2", CreateIfNotFound1, CreateIfNotFound2);

ResetToFlatStart(FlatVoltagesAngles, ShuntsToMax, LTCsToMiddle, PSAnglesToMiddle);

DiffFlowSetAsBase;

DiffFlowClearBase;

DiffFlowMode

(diffmode);

PRESENT

BASE

DIFFERENCE

OPFWriteResultsAndOptions ("filename");

DoCTGAction([contingency action]);

Call this action to use the formats seen in the CTGElement subdata record for Contingency Data. Note that all

actions are supported, except COMPENSATION sections are not allowed.

SolvePowerFlow(SolMethod, "filename1", "filename2", CreateIfNotFound1, CreateIfNotFound2);

Call this action to perform a single power flow solution. The parameters are all optional and specify a conditional

response depending on whether the solution is successfully found. If parameters are not passed then default

values will be used.

SolMethod

The solution method to be used for the power flow calculation. The

options are:

RECTNEWT: For Rectangular Newton-Raphson method.

POLARNEWTON: For Polar Newton-Raphson method.

GAUSSSEIDEL: For Gauss-Seidel method.

FASTDEC: For Fast Decoupled method.

DC: For DC method.

ROBUST: For ROBUST method.

The default method is RECTNEWT.

"filename1"

The filename of the auxiliary file to be loaded if there is a successful

solution. You may also specify STOP, which means that all AUX file

execution should stop under the condition. Default Value is "".

"filename2"

The filename of the auxiliary file to be loaded if there is a NOT successful

solution. You may also specify STOP, which means that all AUX file

execution should stop under the condition. Default Value is "".

CreateIfNotFound1

Set to YES or NO. YES means that objects which can not be found will

be created while reading in DATA sections of filename1. Default Value is

NO.

CreateIfNotFound2

Set to YES or NO. YES means that objects which can not be found will

be created while reading in DATA sections of filename2. Default Value is

NO.

SolvePrimalLP("filename1", "filename2", CreateIfNotFound1, CreateIfNotFound2);

843

Call this action to perform a primal LP OPF solution. The parameters are all optional and specify a conditional

response depending on whether the solution is successfully found. If parameters are not passed then default

values will be used.

"filename1"

The filename of the auxiliary file to be loaded if there is a successful

solution. You may also specify STOP, which means that all AUX file

execution should stop under the condition. Default Value is "".

"filename2"

The filename of the auxiliary file to be loaded if there is a NOT successful

solution. You may also specify STOP, which means that all AUX file

execution should stop under the condition. Default Value is "".

CreateIfNotFound1

Set to YES or NO. YES means that objects which can not be found will

be created while reading in DATA sections of filename1. Default Value is

NO.

CreateIfNotFound2

Set to YES or NO. YES means that objects which can not be found will

be created while reading in DATA sections of filename2. Default Value is

NO.

SolveSinglePrimalLPOuterLoop("filename1", "filename2", CreateIfNotFound1, CreateIfNotFound2);

This action is basically identical to the SolvePrimalLP action, except that this will only perform a single optimization.

The SolvePrimalLP will iterate between solving the power flow and an optimization until this iteration converges.

This action will only solve the optimization routine once, then resolve the power flow once and then stop.

SolveFullSCOPF (BCMethod, "filename1", "filename2", CreateIfNotFound1, CreateIfNotFound2);

Call this action to perform a full Security Constrained OPF solution. The parameters are all optional and specify a

conditional response depending on whether the solution is successfully found. If parameters are not passed then

default values will be used.

BCMethod

The solution method to be used for solving the base case. The options

are:

POWERFLOW - for single power flow algorithm.

OPF - for the optimal power flow algorithm.

Default Value is POWERFLOW.

"filename1"

The filename of the auxiliary file to be loaded if there is a successful

solution. You may also specify STOP, which means that all AUX file

execution should stop under the condition. Default Value is "".

"filename2"

The filename of the auxiliary file to be loaded if there is a NOT successful

solution. You may also specify STOP, which means that all AUX file

execution should stop under the condition. Default Value is "".

CreateIfNotFound1

Set to YES or NO. YES means that objects which can not be found will

be created while reading in DATA sections of filename1. Default Value is

NO.

CreateIfNotFound2

Set to YES or NO. YES means that objects which can not be found will

be created while reading in DATA sections of filename2. Default Value is

NO.

ResetToFlatStart (FlatVoltagesAngles, ShuntsToMax, LTCsToMiddle, PSAnglesToMiddle);

Use this action to initialize the Power Flow Solution to a "flat start." The parameters are all optional and specify a

conditional response depending on whether the solution is successfully found. If parameters are not passed then

default values will be used.

FlatVoltagesAngles

Set to YES or NO. YES means setting all the voltage magnitudes and

generator setpoint voltages to 1.0 per unit and all the voltage angles to

zero. Default Value is YES.

ShuntsToMax

Set to YES or NO. YES means to increase Switched Shunts Mvar half

way to maximum. Default Value is NO.

LTCsToMiddle

Set to YES or NO. YES means setting the LTC Transformer Taps to

middle of range. Default Value is NO.

PSAnglesToMiddle

Set to YES or NO. YES means setting Phase Shifter angles to middle of

range. Default Value is NO.

DiffFlowSetAsBase;

Call this action to set the present case as the base case for the difference flows abilities of Simulator.

844

Script Contingency Submode Actions

The following actions are specific to the Run Mode Submode Contingency:

CTGSolveAll;

CTGSolve("ContingencyName");

CTGSetAsReference;

CTGRestoreReference;

CTGProduceReport("filename");

CTGWriteResultsAndOptions("filename");

CTGAutoInsert;

CTGCalculateOTDF( [transactor seller],

[transactor buyer],

LinearMethod);

[AREA num]

[ZONE num]

[SUPERAREA "name"]

DCPS

[INJECTIONGROUP "name"]

[BUS num]

[SLACK]

CTGSolveAll;

Call this action to solve all the contingencies which are not marked skip.

CTGSolve("ContingencyName");

Call this action solve a particular contingency. The contingency is denoted by the "Contingency Name".

CTGSetAsReference;

Call this action to set the present system state as the reference for contingency analysis.

CTGRestoreReference;

Call this action to reset the system state to the reference state for contingency analysis.

CTGProduceReport("filename");

Produces a text-based contingency analysis report using the settings defined in CTG_Options.

CTGWriteResultsAndOptions("filename");

Writes out all information related to contingency analysis as an auxiliary file. This includes Contingency Definitions,

Limit Monitoring Settings, Contingency Results, Solution Options, CTG Options as well as any Model Criteria that

are used by the Contingency Definitions.

CTGAutoInsert;

Automatically generates a contingency list using the settings defined in CTG_Options.

CTGCalculateOTDF([transactor seller], [transactor buyer], LinearMethod);

This action calculate OTDFs for each contingency-caused branch or interface violation. The values calculated will

be a measure of what percent of a transfer would appear on the branch or interface after the respective contingency

occurs. Realize for branch violations, that the sign of the OTDF value will be relative to the direction of the MW flow

found during the contingency analysis.

846

Auxiliary Script/Data Files

The parameters will be used to calculate the PTDFs for the transfer direction you are interested in. These PTDF

values will then be used throughout the OTDF calculation. Note that the buyer and seller must not be same thing.

If no Linear Method is specified, Lossless DC will be used.

NOTE: All the parameters are optional. If they are not specified, then the existing PTDFs will be used.

[transactor seller] :

The seller (or source) of power. There are six possible settings:

[AREA num]

[ZONE num]

[SUPERAREA "name"]

[INJECTIONGROUP "name"]

[BUS num]

[SLACK]

[transactor buyer] :

The buyer (or sink) of power. There are six possible settings, which are

the same as for the seller.

LinearMethod :

The linear method to be used for the PTDF calculation. The options are:

AC: for calculation including losses.

DC: for lossless DC.

DCPC: for lossless DC that takes into account phase shifter operation.

847

Script ATC Submode Actions

The following actions are specific to the Run Mode Submode ATC:

ATCDetermine

([transactor seller],

[transactor buyer]);

[AREA num]

[ZONE num]

[SUPERAREA "name"]

[SUPERAREA name]

[INJECTIONGROUP "name"]

INJECTIONGROUP name]

[BUS num]

[SLACK]

SLACK]

ATCRestoreInitialState;

ATCIncreaseTransferBy

(amount);

ATCTakeMeToScenario

(RL,

I);

ATCDetermineFor

(RL,

I);

ATCWriteResultsAndOptions ("filename");

ATCDetermine([transactor seller], [transactor buyer]);

Use this action to calculate the Available Transfer Capability (ATC) between a seller and a buyer. Note that the

buyer and seller must not be same thing. Other options regarding ATC calculations should be set using a DATA

section via the ATC_Options object type.

[transactor seller] :

The seller (or source) of power. There are six possible settings

[AREA num]

[ZONE num]

[SUPERAREA "name"]

[INJECTIONGROUP "name"]

[BUS num]

[SLACK]

[transactor buyer] :

The buyer (or sink) of power. There are six possible settings which are

the same as for the seller.

ATCRestoreInitialState;

Call this action to restore the initial state for the ATC tool.

ATCIncreaseTransferBy(amount);

Call this action to increase the transfer between the buyer and seller.

ATCTakeMeToScenario(RL, G, I);

Call this action to set the present case according to Scenario RL, G, I.

ATCDetermineFor(RL, G, I);

Call this action to determine the ATC for Scenario RL, G, I.

ATCWriteResultsAndOptions("filename");

Writes out all information related to ATC analysis as an auxiliary file. This includes Contingency Definitions, Limit

Monitoring Settings, Solution Options, ATC Options, ATC results, as well as any Model Criteria that are used by the

Contingency Definitions.

848

Auxiliary Script/Data Files

Script Fault Submode Actions

The following actions are specific to the Run Mode Submode Fault:

Fault

([BUS num],

faulttype,

R, X);

Fault

([BRANCH nearbusnum farbusnum ckt], faultlocation, faulttype,

R, X) ;

SLG

3PB

DLG

Fault([Bus num, faulttype, R, X]);

Fault([BRANCH nearbusnum farbusnum ckt], faultlocation, faulttype, R, X]);

Call this function to calculate the fault currents for a fault. If the fault element is a bus then do not specify the fault

location parameter. If the fault element is a branch, then the fault location is required.

[Bus num] :

This specifies the bus at which the fault occurs.

[BRANCH nearbusnum farbusnum ckt] :

This specifies the branch on which the fault occurs.

Fault location :

This specifies the percentage distance along the branch where the fault

occurs. This percent varies from 0 (meaning at the nearbus) to 100

(meaning at the far bus)

Faulttype :

This specified the type of fault which occurs. There are four options:

SLG: Single Line To Ground fault

LL: Line to Line Fault

3PB: Three Phase Balanced Fault

DLG: Double Line to Group Fault.

R, X :

These parameters are optional and specify the fault impedance. If none

are specified, then a fault impedance of zero is assumed.

849

Script PV Submode Actions

The following actions are specific to the Run Mode Submode PV:

PVCreate

("name",

[element source],

[element sink]);

[INJECTIONGROUP "name"]

PVSetSourceAndSink

("name");

[element source],

[element sink]);

[INJECTIONGROUP "name"]

PVRun

("name");

PVClearResults

("name");

PVStartOver

("name");

PVDestroy

("name");

PVWriteResultsAndOptions

("filename");

RefineModel

(objecttype,

filter,

Action

ForWhichValue);

AREA

TRANSFORMERTAPS

ZONE

SHUNTS

OFFAVR

PVCreate("name", [elementSource], [elementSink]);

Call the function to create a PV study with "name" as identifier. You may optionally specify the source and sink

elements for the study transaction.

"name" :

String that identifies the PV study to be created.

[element source] :

The source of power for the PV study. There is only one possible setting:

[INJECTIONGROUP "name"]

[element sink] :

The sink of power for the PV study. There is only one possible setting,

which is the same as for the source.

PVSetSourceAndSink("name", [elementSource], [elementSink]);

Call the function to specify the source and sink elements to perform the PV study called "name".

"name" :

String that identifies the PV study for which the source and sink elements

are to be assigned to.

[element source] :

The source of power for the PV study. There is only one possible setting:

[INJECTIONGROUP "name"]

[element sink] :

The sink of power for the PV study. There is only one possible setting,

which is the same as for the source.

PVRun("name");

Call the function to start the PV study called "name".

"name" :

String that identifies the PV study.

PVClearResults("name");

Call the function to clear all the results of the PV study called "name".

"name" :

String that identifies the PV study.

PVStartOver("name");

Call the function to start over the PV study called "name". This includes clear the activity log, clear results, restore

the initial state, set the current state as initial state, and initialize the step size.

"name" :

String that identifies the PV study.

850

Auxiliary Script/Data Files

PVDestroy("name");

Call the function to destroy the PV study called "name".

"name" :

String that identifies the PV study.

PVWriteResultsAndOptions("filename");

Call this action to save all the PV results and options in the auxiliary file "filename".

RefineModel(objecttype, filter, Action, Tolerance);

Call this function to refine the system model to fix modeling idiosyncrasies that cause premature loss of

convergence during PV and QV studies.

objecttype :

The objecttype being selected.

AREA

ZONE

filter :

There are three options for the filter:

RefineModel(…, "", …); :

No filter specified means to select all objects of this type.

RefineModel(…, "filtername", …);: "filtername" means select those that meet the filter.

Action :

The way the model will be refined. Choices are:

TRANSFORMERTAPS

Fix all transformer taps at their present values if their Vmax - Vmin is less

than or equal to the user specified tolerance.

SHUNTS

Fix all shunts at their present values if their Vmax - Vmin is less than or

equal to the user specif ied tolerance.

OFFAVR

Remove units from AVR control, thus locking their MVAR output at its

present value if their Qmax - Qmin is less or equal to the user specified

tolerance.

Tolerance :

Tolerance value.

851

Script QV Submode Actions

The following actions are specific to the Run Mode Submode QV:

QVRun

("filename",

InErrorMakeBaseSolvable);

YES or NO

NOTE: The QV study is always performed on selected bus es.

QVWriteResultsAndOptions

("filename");

RefineModel

(objecttype,

filter,

Action

ForWhichValue);

AREA

TRANSFORMERTAPS

ZONE

SHUNTS

OFFAVR

QVRun("filename", InErrorMakeBaseSolvable);

Call the function to start a QV study for the list of buses whose SELECTED? field is set to YES.

"filename" :

This specifies the file to which to save a comma-delimited version of the

results.

InErrorMakeBaseSolvable :

This specifies whether to perform a solvability analysis of the base case if

the pre-contingency base case can not be solved. If not specified, then

YES is assumed.

QVWriteResultsAndOptions("filename");

Call this action to save all the QV results and options in the auxiliary file "filename".

RefineModel(objecttype, filter, Action, Tolerance);

Call this function to refine the system model to fix modeling idiosyncrasies that cause premature loss of

convergence during PV and QV studies.

objecttype :

The objecttype being selected.

AREA

ZONE

filter :

There are three options for the filter:

RefineModel(…, "", …); :

No filter specified means to select all objects of this type.

RefineModel(…, "filtername", …);: "filtername" means select those that meet the filter.

Action :

The way the model will be refined. Choices are:

TRANSFORMERTAPS

Fix all transformer taps at their present values if their Vmax - Vmin is less

than or equal to the user specified tolerance.

SHUNTS

Fix all shunts at their present values if their Vmax - Vmin is less than or

equal to the user specified tolerance.

OFFAVR

Remove units from AVR control, thus locking their MVAR output at its

present value if their Qmax - Qmin is less or equal to the user specified

tolerance.

Tolerance :

Tolerance value.

852

Auxiliary Script/Data Files

Data Section

The Data Section of the script file format can contain numerous functions for modifying the data of a power system

case. The DATA section begins with a left curly brace and ends with a right curly brace.

DATA DataName (object_type, [list_of_fields], file_type_specifier)

{

data_list_1

data_list_n

}

Immediately following the DATA keyword, you may optionally include a DataName. By including the DataName, you

can make use of the script command LoadData("filename", DataName) to call this particular data section from another

auxiliary file.

The first line of the DATA section is referred to as the Data Argument List. The Data Argument List defines the type

and format of the data contained in the following section enclosed in curly braces.

Inside of each DATA section, data lists are given according to the data definition given in the Data Argument List.

853

Data Argument List

The DATA argument list identifies what the information section contains. A left and right parenthesis "( )" mark the

beginning and end of the argument list.

The file_type_specifier parameter distinguishes the information section as containing custom auxiliary data (as

opposed to Simulator’s native auxiliary formats), and indicates the format of the data. Currently, the parser recognizes

two values for file_type_specifier:

(blank) or AUXDEF

Data fields are space delimited

CSV, AUXCSV, or CSVAUX

Data fields are comma delimited

The object_type parameter identifies the type of object or data element the information section describes or models.

For example, if object_type equals BUS, then the data describes BUS objects. Below is a list of many of the object

types recognized by Simulator:

Area

DCTransmissionLine

PartPoint

ATC_Options

Direction

PVCurve_Options

ATCExtraMonitor

Equiv_Options

QVCurve_Options

ATCGeneratorChange

Filter

ReactiveCapability

ATCInterfaceChange

Gen

Scale_Options

ATCLineChange

InjectionGroup

Schedule

ATCScenario

Interface

Shunt

ATCZoneChange

InterfaceElement

Sim_Environment_Options

BidCurve

Limit_Monitoring_Options

Sim_Misc_Options

Branch

LimitSet

Sim_Simulation_Options

Bus

LimitViol

Sim_Solution_Options

ColumnInfo

Load

StudyMWTransactions

Condition

LoadScale

Substation

Contingency

ModelCondition

SuperArea

Ctg_Options

ModelFilter

TransferLimiter

CTGElement

MSLine

Transformer

CustomExpression

MWTransaction

XFCorrection

DataGrid

OPF_Options

Zone

OwnerObject

The list of object types Simulator’s auxiliary file parser can recognize will grow as new applications for the technology

are found. Within Simulator, you will always be able to obtain a list of the available object_types by going to the

main menu and choosing Help > Export Object Fields .

The list_of_fields parameter lists the types of values the ensuing records in the data section contain. The order in

which the fields are listed in list_of_fields dictates the order in which the fields will be read from the file. Simulator

currently recognizes over 800 different field types, each identified by a specific field name. Because the available

fields for an object may grow as new applications are developed, you will always be able to obtain a list of the

available object_types by going to the main menu and choosing Help > Export Obje ct Fields . Certainly, only a

subset of these fields would be found in a typical custom auxiliary file. In crafting applications to export custom

auxiliary files, developers need concern themselves only the fields they need to communicate between their

applications and Simulator. A few points of interest regarding the list_of_fields are:

· The list_of_fields may take up several lines of the text file.

· The list_of_fields should be encompased by braces [ ].

· When encountering the PowerWorld comment string ‘//’ in one of these lines of the text file, all text to the right

of this is ignored.

· Blank lines, or lines whose first characters are ‘//’ will be ignored as comments.

· Field names must be separated by commas.

Example DATA Argument List

854

Auxiliary Script/Data Files

DATA (BUS, [BusNomKV, Bus, // comment here

ABCPhaseAngle:1, ABCPhaseAngle:2, ABCPhaseV, ABCPhaseV:1,

// comments allowed here to

// note that blank rows are ignored

AreaNum, BusAngle, BusB, BusCat, BusEquiv, BusG,

BusGenericSensV, BusKVVolt, BusLambda, BusLoadMVA, // more comment

BusLoadMW, BusLongName])

One general note regarding the field names however. Some field names may be augmented with a field location.

One example of this is the field LineMW. For a branch, there are two MW flows associated with the line: one MW flow

at the from bus, and one MW flow at the to bus. So that the number of fields does not become huge, the same field

name is used for both of these values. For the from bus flow, we write LineMW:0, and for the to bus flow, we write

LineMW:1. Note that fieldnames such as LineMW:0 may simply leave off the :0.

855

Data Key Fields

Simulator uses certain fields to identify the specific object being described. These fields are called key fields. For

example, the key field for BUS objects is BusNum, because a bus can be identified uniquely by its number. The key

fields for GEN objects are BusNum and GenID. To properly identify each object, the object’s key fields must be

present. They can appear in any order in the list_of_fields (i.e. they need not be the first fields listed in

list_of_fields ). As long as the key fields are present, Simulator can identify the specific object. By going to the main

menu and choosing Help > Export Object Fields you will obtain a list of fields available for each object type. In this

output, the key fields will appear with asterisks *.

856

Auxiliary Script/Data Files

Data List

After the data argument list is completed, the Data list is given. The data section lists the values of the fields for each

object in the order specified in list_of_fields . The data section begins with a left curly brace and ends with a right

curly brace. A few points of interest regarding the value_list:

· The value_list may take up several lines of the text file.

· Each new data object must start on its own line of text.

· When encountering the PowerWorld comment string ‘//’ in one of these lines of the text file, all text to the right

of this is ignored.

· Blank lines, or lines whose first characters are ‘//’ will be ignored as comments.

· Remember that the right curly brace must appear on its own line at the end of the data_list.

· If the file_type_specifier is CSV, the values should be separated by commas. Otherwise, separate the field

names using spaces.

· Strings can be enclosed in double quotes, but this is not required. You should however always enclose strings

that contain spaces (or commas) in quotes. Otherwise, strings containing commas would cause errors for

comma-delimited files, and spaces would cause errors for space-delimited formatted files.

857

Data SubData Sections

The format described in the Data Section works well for most kinds of data in Simulator. It does not work as well

however for data that stores a list of objects. For example, a contingency stores some information about itself (such

as its name), and then a list of contingency elements, and possible a list of limit violations as well. For data such as

this, Simulator allows <SubData>, </SubData> tags that store lists of information about a particular object. This

formatting looks like the following:

DATA (object_type, [list_of_fields], file_type_specifier)

{

value_list_1

precise format describing an object_type1

</SUBDATA>

precise format describing an object_type2

</SUBDATA>

value_list_2

value_list_n

}

Note that the information contained inside the <SubData>, </SubData> tags may not be flexibly defined. It must be

written in a precisely defined order that will be documented for each SubData type.

858

Data Contingency

Append Contingency Actions

CTGElement

A contingency element is described by up to four entries. All entries must be on a single line of text.

"Action" "ModelCriteria" Status

//comment

Action :

String describing the action associated with this element. See below for

actions available.

ModelCriteria :

This is the name of a ModelFilter or ModelCondition under which this

action should be performed. This entry is optional. If it is not specified,

then a blank (or no criteria) is assumed. If you want to enter a Status,

then use must specify "" as the ModelCriteria.

Status :

Three options

CHECK: perform action if ModelCriteria is true.

ALWAYS: perform action regardless of ModelCriteria.

NEVER: do not perform action.

This entry is optional. If it is not specified, then CHECK is assumed.

Comment :

All text to the right of the comment symbol (//) will be saved with the

CTGElement as a comment.

Possible Actions:

Calling of a name ContingencyBlock

CONTINGENCYBLOCK | name

Calls a ContingencyBlock and executes each of the actions in that block.

Transmission Line or Transformer outage or insertion

BRANCH

| bus1# bus2# ckt

| OPEN

| CLOSE

Takes branch out of service, or puts it in service.

Series Capacitor Bypass or In Service

SERIESCAP

| bus1# bus2# ckt

| BYPASS

| INSERVICE

Interface outage or insertion

INTERFACE

| name

| OPEN

| CLOSE

Takes all monitored branches in the interface out of service, or puts them all in service

Bus outage causes all lines connected to the bus to be outage

BUS

| bus#

| OPEN

Takes all branches connected to the bus out of service. Also outages all generation, load, or shunts

attached to the bus.

Generator, Load, or Switched Shunt outage or insertion

GEN

| bus# id

| OPEN

LOAD

| bus# id

| CLOSE

SHUNT

| bus#

Takes a generator, load, or shunt out of service, or puts it in service.

Generator, Load or Switched Shunt movement to another bus

GEN

| bus1#

| MOVE_PQ_TO

| bus2#

| value

| MW

LOAD

| MOVE_P_TO

| PERCENT

SHUNT

| MOVE_Q_TO

Use to move generation, load or shunt at a bus1 over to bus2.

Generator, Load or Switched Shunt set or change a specific value

860

Auxiliary Script/Data Files

GEN

| bus#

| SET_P_TO

| value

| MW

LOAD

| SET_Q_TO

| PERCENT

SHUNT

| CHANGE_P_BY

| CHANGE_Q_BY

Use to set the generation, load, or shunt at a bus to a particular value. Also can use to change by a

specified amount.

Injection Group set a specific value

INJECTIONGROUP | name

| SET_P_TO

| value

| MW

| PERCENT

Use to set the MW generation/load in an injection group to a particular value.

Injection Group change a specific value

INJECTIONGROUP | name

| CHANGE_P_TO

| value

| MW

| PERCENT

| MWOPENCLOSE

| PERCENTOPENCLOSE

Use to change the MW generation/load in an injection group by a particular value. Note that MW

and PERCENT OPTIONS will change each point in the injection group by a value in proportion to the

participations factors of the group. MWOPENCLOSE and PERCENTOPENCLOSE will modify points

in the injection group by closing or opening points in the group in order of descending participation

factors until the total change greater than or equal to the requested change has been achieved.

Make-Up Power Compensation.

Only valid immediately following a SET, CHANGE, OPEN or CLOSE action on a Generator, Shunt or

Load. This describes how the change in MW or MVAR are picked up by buses throughout the

system. The values specify participation factors

COMPENSATION

bus#1 value1

bus#2 value2

END

Example:

// just some comments

// action

Model Criteria

Status

comment

"BRANCH 40821 40869 1 OPEN"

ALWAYS

//Raver - Paul 500 kV

"GEN 45041 1 OPEN"

ALWAYS

//Trip Unit #2

"BRANCH 42702 42727 1 OPEN"

"Line X Limited"

CHECK

//Open Fern Hill

"GEN 40221 1 OPEN"

"Interface L1"

CHECK

//Drop ~600 MW

"GEN 40227 1 OPEN"

"Interface L2"

CHECK

//Drop ~1200 MW

"GEN 40221 1 OPEN"

"Interface L3"

CHECK

//Drop ~600 MW

"GEN 40227 1 OPEN"

"Interface L3+"

CHECK

//Drop ~1200 MW

</SUBDATA>

LimitViol

A LimitViol is used to describe the results of a contingency analysis run. Each Limit Violation lists six values:

ViolType ViolElement Limit ViolValue PTDF PTDF

ViolType :

One of five values describing the type of violation

BAMP: branch amp limit violation.

BMVA: branch MVA limit violation.

VLOW: bus low voltage limit violation.

VHIGH: bus high voltage limit violation.

INTER: interface MW limit violation.

ViolElement :

This field depends on the ViolType.

for BAMP, BMVA: "bus1# bus2# ckt violationbus#"

861

for VLOW, VHIGH: "bus1#"

for INTER: "interfacename"

Limit :

This is the numerical limit which was violated.

ViolValue :

This is the numerical value of the violation.

PTDF :

This field is optional. It only makes sense for interface or branch

violations. It stores a sensitivity of the flow on the violating element during

in the base case with respect to a transfer direction This must be

calculated using the Contingency Analysis Other Actions related to

Sensitivities.

OTDF :

This field is optional. It only makes sense for interface or branch

violations. It stores a sensitivity of the flow on the violating element during

this contingency with respect to a transfer direction. This must be

calculated using the Contingency Analysis Other Actions related to

Sensitivities.

Example:

BAMP "1 3 1 1 FROMTO"

271.94031

398.48096

10.0

15.01

// Note OTDF/PTDF

INTER "Right-Top"

45.00000

85.84451

// Note OTDF/PTDF not included

</SUBDA TA>

Sim_Solution_Options

These describe the power flow solution options which should be used under this particular contingency. The

format of the subdata section is two lines of text. The first line is a list of the fieldtypes for Sim_Solution_Options

which should be changed. The second line is a list of the values. Note that in general, power flow solution options

are stored at three different locations in contingency analysis. When implementing a contingency, Simulator gives

precendence to these three locations in the following order:

· Contingency Record Options (stored with the particular contingency)

· Contingency Tool Options (stored with CTG_Options)

· The global solution options

862

Data Filter

Condition

Conditions store the conditions of the filter. Each condition is described by one line of text which can contain up to

five fields.

Variablename condition "value"

("othervalue")

(fieldopt)

Variablename :

It is one of the fields for the object_type specified. It may optional be

followed by a colon and a non-negative integer. If not specified, 0 is

assumed.

Example: on a LINE, 0 = from bus, 1 = to bus

Thus: LineMW:0 = the MW flow leaving the from bus

LineMW:1 = the MW flow leaving the to bus

Condition :

Possible Values Alternate1 Alternate2 Requirements

between

requires other value

notbetween

~><

requires other value

equal

notequal

greaterthan

lessthan

greaterthanorequal

lessthanorequal

contains

notcontains

startswith

notstartswith

inrange

notinrange

value :

The value to compare to.

For fields associated with strings, this must be a string

For fields associated with real numbers, this must be a number.

For fields associated with integers, this is normally an integer, except

when the Condition is "inrange" or "notinrange". In this case, value is a

comma/dash separated number string.

(othervalue) :

If required, the other value to compare to.

(FieldOpt) :

Optional integer value with following meanings.

0 - strings are case insensitive, use number fields directly

(0 is the default value if not otherwise specified)

1 - strings are case sensitive, take ABS of field values

Example:

DATA (FILTER, [objecttype, filtername, filterlogic, filterpre])

{

BUS "a bus filter" "AND" "no"

BusNomVolt > 100

AreaNum inrange "1-5 , 7 , 90-95"

ZoneNum between

</SUBDATA>

866

Auxiliary Script/Data Files

Data MultiSectionLine

Bus

A multi section line’s subdata contains a list of each dummy bus, starting with the one connected to the From Bus of

the MultiSectionLine and proceeding in order to the bus connec ted to the To Bus of the Line.

Example

//-----------------------------------------------------------------------------------------------------------

// The following describes a multi-section line that connnects bus

2 - 1 - 5 - 6 - 3

//------------------------------------------------------------------------------------------------------------

DATA (MultiSectionLine, [BusNum, BusName, BusNum:1, BusName:1,

LineCircuit, MSLineNSections, MSLineStatus] )

{

2 "Two" 3 "Three" "&1" 2 "Closed"

</SUBDATA>

}

869

Data InjectionGroup

PartPoint

A participation point is used to describe the contents of an injection group. Each participation point lists six values:

PointType PointBusNum PointID PointParFac ParFacCalcType ParFacNotDynamic

PointType :

One of two values describing the type of violation:

GEN: a generator

LOAD: a load

PointBusNum :

The bus number of the partpoint.

PointID :

The generator or load id for the partpoint.

PointParFac :

The participation factor for the point.

ParFacCalcType :

How the participation point is calculated. There are several options

depending on the PointType.

Generators: SPECIFIED, MAX GEN INC, MAX GEN DEC, or MAX

GEN MW

Loads:

SPECIFIED, or LOAD MW

ParFacNotDynamic:

Should the participation factor be recalculated dynamically as the system

changes.

Example :

<SUBDATA PartPoint

"GEN"

1 "1"

1.00 "SPECIFIED"

"NO"

"GEN"

2 "1"

5.00 "SPECIFIED"

"NO"

"GEN"

4 "1"

104.96 "MAX GEN INC" "NO"

"GEN"

6 "1"

50.32 "MAX GEN DEC" "YES"

"GEN"

7 "1"

600.00 "MAX GEN MW" "NO"

"LOAD" 2 "1"

5.00 "SPECIFIED"

"NO"

"LOAD" 5 "1"

130.00 "LOAD MW"

"NO"

"LOAD" 6 "1"

200.00 "LOAD MW"

"YES"

</SUBDATA>

870

Auxiliary Script/Data Files

Data Interface

InterfaceElement

An interface’s subdata contains a list of the elements in the interface. Each line contains a text description of the

interface element. Note that this text description must be encompassed by quotation marks. There are five kinds of

elements allowed in an interface. Please note that the direction specified in the monitoring elements is important.

"BRANCH num1 num2 ckt"

Monitor the MW flow on the branch starting from bus num1 going to bus

num2 on the branch this branch.

"AREA num1 num2"

Monitor the sum of the tie line MW flow s from area num1 to area num2.

"ZONE num1 num2"

Monitor the sum of the tie line MW flows from zone num1 to zone num2.

"BRANCHOPEN num1 num2 ckt" When monitoring the elements in this interface, monitor them under the

contingency of opening this branch.

"BRA NCHCLOSE num1 num2 ckt" When monitoring the elements in this interface, monitor them under the

contingency of closing this branch.

For the interface element type "BRANCH num1 num2 ckt", an optional field can also be written specifying whether

the flow should be measured at the far end. This field is either YES or NO.

Example

<SUBDATA InterfaceElement

"BRANCH 8

1" NO

// monitor the flow from bus 8 to bus 9 on this branch

"BRANCH 12 33

1" YES

// monitor the flow from bus 12 to bus 33 on branch

// measurefarend is set to true, therefore, we are

// monitoring the MW flow that arrives at bus 33

"AREA

// monitor tie line flow from area 2 to area 1

"ZONE

53"

// monitor tie lines flows from zone 66 to zone 53

"BRANCHOPEN 5 6 1" // doe monitoring after branch opens

"BRANCHCLOSE 7 10 1"

// doe monitoring after branch closes

</SUBDATA>

871

Data Owner

Bus

This subdata section contains a list of the buses which are owned by this owner. Each line of text contains the bus

number.

Example

</SUBDATA>

Load

This subdata section contains a list of the loads which are owned by this owner. Each line of text contains the bus

number followed by the load id.

Example

5 1 // shows ownership of the load at bus 5 with id of 1

423 1

</SUBDATA>

Gen

This subdata section contains a list of the generators which are owned by this owner and the fraction of ownership.

Each line of text contains the bus number, followed by the gen id, followed by an integer showing the fraction of

ownership.

Example

78 1 50 // shows 50% ownership of generator at bus 78 with id of 1

23 3 70

</SUBDATA>

Branch

This subdata section contains a list of the branchs which are owned by this owner and the fraction of ownership.

Each line of text contains the from bus number, followed by the to bus number, followed by the circuit id, followed by

an integer showing the fraction of ownership.

Example

6 10 1 50 // shows 50% ownership of line from bus 6 to 10, circuit 1

</SUBDATA>

874

Data ATCScenario

TransferLimiter

This subdata section contains a list of the TransferLimiters for this scenario. Each line contains fields relating one

of the Transferlimiters. The fields are writen out in the following order:

Limiting Element :

Contains a description of the limiting element. The possible values are

"PowerFlow Divergence"

"AREA num"

"SUPERAREA name"

"ZONE num"

"BRANCH num1 num2 ckt"

"INJECTIONGROUP name"

"INTERFACE name"

Limiting Contingency :

The name of the limiting contingency. If blank, then this means it’s a

limitation in the base case.

MaxFlow :

The transfer limitation in MW.

PTDF :

The PTDF on the limiting element in the base case (not in percent).

OTDF :

The OTDF on the limiting element under the limiting contingency.

LimitUsed :

The limit which was used to determine the MaxFlow in per unit.

PreTransEst :

The estimated flow on the line after the contingency but before the

transfer in per unit.

MaxFlowAtLastIteration :

The total transfer at the last iteration in per unit.

IterativelyFound :

Either YES or NO depending on whether it was iteratively determined.

Example

"BRANCH 40767 42103 1" "Contin" 2.84 -0.0771 -0.3883 -4.35 -4.35 -0.01 "-55.88" YES

"BRANCH 42100 42321 1" "Contin" 4.42 0.1078 0.5466 6.50 5.64 1.57 " 22.59" NO

"BRANCH 42168 42174 1" "Contin" 7.45 -0.0131 -0.0651 -1.39 -1.09 4.60 "-33.31" NO

"BRANCH 42168 42170 1" "Contin" 8.54 0.0131 0.0651 1.39 1.02 5.69 " 26.10" NO

"BRANCH 41004 49963 1" "Contin" 9.17 -0.0500 -0.1940 -4.39 -3.16 6.32 " 68.73" NO

"BRANCH 46403 49963 1" "Contin" 9.53 0.0500 0.1940 4.46 3.16 6.68 "-68.68" NO

"BRANCH 42163 42170 1" "Contin" 10.14 -0.0131 -0.0651 -1.39 -0.92 7.29 "-15.58" NO

</SUBDATA>

ATCExtraMonitor

This subdata section contains a list of the ATCExtraMonitors for this scenario. Each line contains three fields

relating one of the ATCExtraMonitors. The first field describes the ATCExtraMonitor which this subdata

corresponds to. The second and third variables are the initial value and sensitivity for this extra monitor for the

scenario. An option fourth field may be included if we are using one of the iterated ATC solution options. This field

must be the String "ATCFlowValue".

Monitor Description :

Contains a string describing which monitor this belongs to.

Initial Value :

Contains the value for this extra monitor at the last linear iteration.

Sensitivity :

Contains the sensitivity of this monitor.

ATCFlowValue :

A string which signifies that a block will follow which stores a list of flow

values for specified transfer levels. Each line of the block consists of two

values: Flow Value (flow on the monitored element) and a Transfer Level

(in MW). The block is terminated when a line of text that starts with ‘END’

is encountered.

Example

876

PowerWorld Simulator version 11. Manual - page 22