Simulator Data Structures and

Auxiliary Files

2001 South First Street [email protected]

Champaign, Illinois 61820 http://www.powerworld.com
+1 (217) 384.6330
 Overview
• This section uses a set of scripts that automate
case development and sensitivity analysis (TLR
or shift factors) to introduce data structures
and scripting language in PowerWorld
Simulator
• References
– Auxiliary File Format (pdf document)
– Simulator’s Model Explorer and Case Information
Displays
– Export Case Object Fields…
Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 2
 Auxiliary Files
• PowerWorld Simulator DATA can be stored and
edited in a text file format
• A scripting language is available for modifying
data and automatically running PowerWorld
Simulator commands
• The auxiliary (*.aux) file format accomplishes
both functions

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 3

 Auxiliary File Format Overview
• Has two types of “Sections”
– There is no limit to the number of sections in a file
SCRIPT ScriptName1

SCRIPT
{
script_statement_1;
Section header
:
Section script_statement_n;
}

object_type DataName1(list_of_fields)

DATA
{
data_list_1
Curly braces to
Section
:
data_list_n open and close
}

object_type DataName2(list_of_fields)
sections
DATA {
data_list_1

Section :
data_list_n
}
Semicolon after each
SCRIPT ScriptName2

SCRIPT {
script_statement_1;
SCRIPT statement
Section :
script_statement_n;
}

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 4

 Auxiliary Files
• Auxiliary Script Files (*.aux) may be used to standardize
settings or automate batch processes
• No looping or flow control (e.g. if…then...else; do…while;
for…next)
– minor exceptions with SolvePowerFlow and related functions
– this is where external programming environments (e.g. Python,
Visual Basic, C++, Matlab, etc.) and SimAuto add value
– SimAuto can also facilitate exchange with external databases
(GetParameters and ChangeParameters families of functions)
• SimAuto applications can
– Load Aux files (ProcessAuxFile function)
– Run individual script statements (RunScriptCommand function)

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 5

 What Can You DO with Auxiliary Files?
• Quality Assurance: Standardize settings and controls
for multiple cases and studies
• Customize Simulator environment
• Document
– Describe an analysis procedure for a manager or client
– Create a detailed project record
– Enable reproducibility
• Automate detailed calculations and storage of the
results
• Automate building and editing of a one‐line diagram

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 6

 Aux Automation Example

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 7

 ACTIVSg10k.raw

Aux Automation Example

• Open ..Case Development Aux\ACTIVSg10k.raw
• Series of files with names aux20?0*.aux
– Set Solution Options (aux2010*.aux)
– Load Filters, Expressions, and Calculated Fields that are
used in subsequent processes (aux2020*.aux)
– Set Limit Monitoring (aux2030*.aux)
– Auto‐insert Contingencies (aux2050*.aux)
– Load Generator information (aux2060*.aux)
– Set Generator, Area, and Super Area and AGC
(aux2070*.aux)
– Perform sensitivity calculations and store results
(aux2080*.aux)
Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 8
 Solution Options
• Load the file aux2010SolutionOptions.aux
• This will load options stored in several DATA
sections into the present case
• This file was created by saving the options from
the Simulator Options dialog in the graphical
user interface (GUI); more on next slide…

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 9

 Solution Options
• Export
directly from
GUI
• Case
Information
→ Simulator
Options…
• Save to Aux

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 10

 Solution Options: DATA Section
• This DATA section lists Sim_Solution_Options_Value (Option,Value)
{
each option and value of "AGCToleranceMVA"
"ChkDFACTS"
"5"
"NO"
"ChkMWAGC" "YES"
object "ChkPhaseShifters"
"ChkShunts"
"YES"
"YES"

Sim_Solution_Options "ChkSVCs"
"ChkTaps"
"ChkVarBackoffImmediately"
"YES"
"YES"
"YES"

• EnforceGenMWLimits
"ChkVarImmediately" "NO"
"CloseCBToEnergizeShunts" "NO"
"ConsolidationUse" "NO"

corresponds to a check
"CTGInterfaceEnforcement" "Never"
"DCApprox" "NO"
"DCLossComp" "NO"

box in the GUI (next "DCModelType"

:
"EnforceGenMWLimits"
"RIgnore“

"YES“

slide) }
:

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 11

 Sim_Solution_Options
• Mouse over the
checkbox in the
dialog for a hint and
the corresponding
Object and Variable
names
• Can also alter this
value with the
SetData script
command (more info
to follow)

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 12

 Filters and Expressions
• Load the file aux2020FiltersExpressions.aux
• Makes use of several SCRIPT sections and statements
SCRIPT
{
Comment delimiter // //---------------------
// Custom Filters
//---------------------
CreateData(Condition,
CreateData script [ObjectType,Filter,CondNum,ObjectField,ConditionType,Value,OtherValue,Absolute],
["Area", "Study System", 1, "Number", "between", "3", "7", "NO "]);
action :
}

• This statement creates a condition for the Area filter

“Study System” (and the filter itself in the process)
– consists of the areas with numbers between 3 and 7
– these are California areas in our case

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 13

 Auxiliary File Reference
• Go to Window → Auxiliary File Format
• Opens a PDF document that describes auxiliary
file structures, including a reference with
structure and syntax of SCIRPT actions
• Search for CreateData action
CreateData(objecttype, [fieldlist], [valuelist]);
Use this action to create particular objects.
objecttype : The objecttype being created.
[fieldlist] : A list of fields to set with the object. The key fields and
required fields must be specified.
[valuelist] : A list of values corresponding to the respective fields.

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 14

 Model Explorer
• Encapsulates most Case Information Displays
• Provides means of navigating through almost
all of the data in the model
• Available from a few places
– Case Information Ribbon Tab
– Tools Ribbon Tab
– Quick Access Toolbar

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 15

 Model Explorer
• In the Model Explorer, go to Case Information
and Auxiliary → Advanced Filters → Advanced
Filter Conditions
– The Advanced Filter Conditions are actually
SUBDATA of the Advanced Filter object
– Most Simulator SUBDATA can also be expressed as
DATA, as they are with Advanced Filter Conditions

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 16

 Model Explorer
CreateData(Condition,
[ObjectType,Filter,CondNum,ObjectField,ConditionType,Value,OtherValue,Absolute],
["Area", "Study System", 1, "Number", "between", "3", "7", "NO "]);

This script statement created this object

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 17

 Model Explorer
• From the Case Info Toolbar, choose Options →
Headings → Variable Names

• Also check the box Use Concise Variable

Names and Headers

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 18

 Model Explorer
• Display now shows Object Name and Variable Names
exactly as they appear in the CreateData SCRIPT
statement
Variable Names (concise)
Object Name

• Key Fields are highlighted yellow

– uniquely identify each Object
– must be included for most script actions (exceptions
including referencing ALL objects or those that meet a filter)
• Required Fields are highlighted green
– must be included to create new objects

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 19

 Generator Parameters
• Load the files Generator Key
– aux2030LimitMonitoring.aux Fields: BusNum
and ID
– aux2050Contingencies.aux
– aux2060GeneratorFuelType.aux Gen (BusNum,BusName,ID,FuelType)
{
20283 "POLLOCK PI~2" "1 " "Hydro"
20284 "POLLOCK PI~3" "1 " "Hydro"
20288 "MCCLELLAN 1 " "1 " "Natural Gas"
20293 "BURNEY 1 3 " "1 " "Wind"
20295 "BELDEN 2 " "1 " "Hydro"
:
}

• The last contains a single DATA section that sets

the FuelType variable for the units inside California
• FuelType is used by filters to set AGC field in
subsequent file
Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 20
 Auxiliary File Tips
• Use the Simulator GUI!!!
• Test and debug auxiliary files by loading from
the GUI and examining Message Log
DATA Sections: which objects and
variables; how many records
read and skipped, if any

SCRIPT Sections: which statement(s)

executed; errors, if any

Start and Finish

of Loaded Files

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 21

 Auxiliary File Tips
• Use the Script Command Execution Dialog to
test and debug individual statements
• Choose Script from the Tools Ribbon

SCRIPT Sections: which

statement(s) executed;
errors, if any

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 22

 Creating a DATA Section
from Case Info Display
• Suppose we wish to create a file with generator
fuel types, as the one just loaded
• In the Model Explorer, go to Network →
Generators
• Tip: save only key fields and the records and
columns necessary to make needed changes
– Example: if setting generator Fuel Type is the objective,
do not include other fields such as Gen MW, Gen Max
MW, etc.
– Extra fields may be specific to one case and not
appropriate for other cases
Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 23
 Creating a DATA Section
• To choose fields to save to the Aux file, choose
the Display/Column Options from the Case
Info Toolbar
• Move Cost\Fuel
Type up so that
it directly follows
ID
• Click OK

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 24

 Creating a DATA Section
• Click and Drag to select the first 4 fields for at
least one record; these include
– Key fields: BusNum and ID
– FuelType: what we want to store
– BusName: not needed, but aids readability
• From the Case Info Toolbar, choose Columns →
Select Column(s)

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 25

 Creating a DATA Section
• From the Case Info Toolbar, choose Aux Save →
Save Auxiliary File (selected records and columns)

• Create a new file name and click Save

• For some Object Types, Simulator may prompt if
you would like to save certain types of sub data
(e.g. BidCurve and ReactiveCapability for
Generators)
Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 26
 Creating a DATA Section
• Can also create an AUX Export Format
Description (Case Information → AUX Export
Format Desc…)
• Insert Object
Type Generator
• Use FilterName
AREAZONE
• Choose fields
• Save As

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 27

 More on Simulator Object Fields
• Re‐open the Display/Column Options
• A list of all available object fields appears on
the left, arranged in folders
• You may customize the display to show a
desired set of fields, order, and other
characteristics
• Click Find Field… to search by string
• Special folders for Key Fields and Required
Fields – verify they are shown, if needed

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 28

 More on Simulator Object Fields
• Customizations may be DataGrid (Name,FrozenCols)
{
viewed in the Model Explorer "Area" 4
<SUBDATA ColumnInfo>

under Case Information and "Number"

"Name"
"AGC"
45
75
54
8
8
8
2
2
2

Auxiliary → Case Info "GenMW"

"LoadMW"
"ShuntMW"
75
75
75
8
8
8
2
2
2
Customizations "ExportMWSched"
"ExportMW"
75
75
8
8
2
2
"ACE" 75 8 2

• These also occur in "EconDispLambda"

"LossMW"
"CalcField:0"
75
75
58
8
8
8
2
2
0

aux2020FiltersExpressions.aux "CalcField:1"
"CalcField:2"
47
55
8
8
0
0
"AutoControlShunt" 75 8 2

• List of Columns, width, and

"AutoControlXF" 75 8 2
"SlackBus" 59 8 2
"ExportMWUnspecified" 75 8 2

decimals are given as :

"AGCTolerance"
</SUBDATA>
75 8 2

SUBDATA ColumnInfo }

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 29

 More on Simulator Object Fields
• To Export a complete reference, choose
Window → Export Case Object Fields… →
Send to Excel (or Text File)
• Details for
DataGrid
object

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 30

 Auxiliary Files
• Load the file aux2070GeneratorAGC.aux
– Set of SCRIPT statements that set Generator AGC status
based on fuel type and set Area and SuperArea AGC modes
• TIP: Use script actions to initialize standard or default
values for ALL objects of a given type
– e.g. SetData(objecttype, [fieldlist], [valuelist], ALL);
– Objects that need different values or to be handled specially
(e.g. study areas) can be identified by primary key or filter in
specific statements
– Improves robustness and compatibility with different cases
having different objects and topology – easier to manage
files and code over a life cycle
– Usually makes code more compact and easier to read

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 31

 Tip: Initialize Values
SCRIPT
Initialize for ALL {
// Initialize AGC for ALL units
SetData(GEN, [GenAGCAble], [YES], ALL);

// Set all Hydro, Wind, and Solar Units to NO AGC

// based on Gen Filters
Settings for specific Generators SetData(GEN, [GenAGCAble], [NO], "Hydro");
by exception, using Filters SetData(GEN, [GenAGCAble], [NO], "Wind");
SetData(GEN, [GenAGCAble], [NO], "Solar");

// Initialize all areas to Participation Factor Control,

Setting for specific Area by // AGC Tolerance = 5 MW
SetData(AREA, [BGAGC, ConvergenceTol], ["Part. AGC", 5], ALL);
exception, using Primary Key.
Code will adapt easily to // Set area with Island Slack Buses to Off AGC
SetData(AREA, [AreaNum, BGAGC], [9, "Off AGC"]);
future cases with additional :
// Create California SuperArea on Participation Factor control
(or fewer) areas // and place Study System areas in California SuperArea
CreateData(SUPERAREA, [SAName, BGAGC], ["California", "Part. AGC"]);
SetData(AREA, [SuperArea], ["California"], "Study System");
Assigning Areas to SuperArea :
}
by Filter, rather than listing
each individual area, means
we only need to maintain the
filter definition in one place.
Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 32
 Auxiliary File Tip Summary
• Use the Simulator GUI!!!
– Model Explorer, Case Information Displays, and
Analysis Dialogs for exploring objects and variables
and saving to Auxiliary File
– Message Log and Script Execution Dialog
• Use the References!
– Auxiliary File Format (pdf document)
– Export Case Object Fields…

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 33

 Auxiliary File Tip Summary
• Build files by saving Case Info Displays and settings to
auxiliary files
– Use text editor to review, make changes, and add comments
– Can append new DATA sections to existing auxiliary files
– Add SCRIPT sections where appropriate
– Most Options dialogs in Simulator have a button for Saving to Aux
• DATA sections: save only key fields and the records and
columns necessary to make needed changes
– Example: if setting generator Fuel Type is the objective, do not
include other fields such as Gen MW, Gen Max MW, etc.
– Extra fields may be specific to one case and not appropriate for
other cases
• Add comments to document your process

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 34

 Limit Monitoring Settings
• Open Tools → Limit Monitoring…
• Can Save an Auxiliary File directly from this
dialog (Save Monitoring Settings)
• This is a great start, but we might wish to clean
it up using tips and principles discussed
– Individual Areas and Zones are listed in DATA
sections
– What if our next case has 17 areas, but we still wish
to monitor only Areas 3‐7? This file would leave
Area 17 Monitored for all voltages (default values).

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 35

 Limit Monitoring Settings
Excerpt from file created
from Limit Monitoring dialog. This would handle extra Areas as desired (or
In a future case with Area 17, fewer Areas, without errors).
Area 17 would be monitored. • We only need to maintain the definition of
the “Study System” filter.
: • Code is also much more compact.
Area
(Number,MonitorLimits,MonitorMinkV,Monitor
MaxkV)
{
1 "NO " 100.0000 9999.0000 SCRIPT
2 "NO " 100.0000 9999.0000 {
3 "YES" 100.0000 9999.0000 // set all Areas to not monitor
4 "YES" 100.0000 9999.0000 // report nominal kV between 100-9999 kV
5 "YES" 100.0000 9999.0000 SetData(Area,
6 "YES" 100.0000 9999.0000 [BGReportLimits,BGReportLimMinKV,BGReportLimMaxKV], ["NO",
7 "YES" 100.0000 9999.0000 100, 9999], ALL);
8 "NO " 100.0000 9999.0000
9 "NO " 100.0000 9999.0000 // set only Study Areas to monitor
10 "NO " 100.0000 9999.0000 SetData(Area, [BGReportLimits], ["YES"], "Study System");
11 "NO " 100.0000 9999.0000 :
12 "NO " 100.0000 9999.0000 }
13 "NO " 100.0000 9999.0000
14 "NO " 100.0000 9999.0000
15 "NO " 100.0000 9999.0000
16 "NO " 100.0000 9999.0000
}
:

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 36

 One More Tip!
• Use a Master file to call secondary files (LoadAux)
– Overall procedure can be maintained in the master file
– Parameters subject to change over time (e.g. generator
specifics) can be stored in the secondary files and more
easily updated or replaced without disrupting other parts
– Can suppress confirmation dialogs when creating new
objects
– Comment out statements that load files that are
temporarily not needed
• aux2000Master.aux
• It helps to fully check and debug individual files first,
though review of the log from loading Master file
can still help catch errors
Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 37
 Master File
SCRIPT
{ Yes in second argument suppresses
// Power Flow Solution Options
LoadAux("aux2010SolutionOptions.aux", Yes); confirmation dialog for new objects
// Custom filters, expressions, calculated fields, and data grids
LoadAux("aux2020FiltersExpressions.aux", Yes);

// Limit Monitoring Settings

LoadAux("aux2030LimitMonitoring.aux", Yes);

// Contingency options and auto-insertion

LoadAux("aux2050Contingencies.aux", Yes);

// Generator Fuel Types

LoadAux("aux2060GeneratorFuelType.aux", Yes);

// Generator AGC Settings

LoadAux("aux2070GeneratorAGC.aux", Yes);

// Multiple Element TLR Calculation - perform on base case or with contingencies

//LoadAux("aux2080TLRBaseCase.aux", Yes);
//LoadAux("aux2081TLRCTGCase.aux", Yes); “Comment out” statements that load
}
files that are temporarily not needed

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 38

 Sensitivity Analysis with Aux Files
• Remaining files calculate Multiple Element
TLR/Shift Factors and save results by bus and
SuperArea to csv files
– aux2080TLRBaseCase.aux: calculates on Overloaded
Lines and Transformers in the base case
– aux2081TLRCTGCase.aux: calculates on Overloaded
Lines and Transformers in contingency analysis
• Custom Expressions and Calculated Fields created
earlier compute the estimated loading relief
benefit of changing control outputs (generators
and loads) and the sum of overloads
Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 39
 Sensitivity Analysis
• Go to Aggregations → Super Areas in the Model
Explorer
• Three Calculated Fields show
– MW flow on the branch with the highest MW flow in
the Super Area
– Sum of base case MVA transmission overloads
– Sum of contingency MVA transmission overloads
• These fields are also available
in Areas/Zones/etc.

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 40

 Sensitivity Analysis
• Load aux2080TLRBaseCase.aux
• Go to Network → Generators in the Model
Explorer
• Sort on Custom Expression ETLR Potential in
descending order

Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 41

 Sensitivity Analysis
• Sign convention in calculations and expressions
– Generators with (+) ETLR can relieve overloads by
decreasing output or dropping
– Loads with (‐) ETLR can relieve overloads by shedding
• Connect unit 25938 1 and set Gen MW = Max MW
• Solve Power Flow
• How does Aggregate Overload change for Super
Area? (drops from 175 to 133)
• Also try load shedding or with contingencies
(aux2081TLRCTGCase.aux)
Data Structures and Auxiliary Files © 2019 PowerWorld Corporation 42