Auxiliary File Scripting Tips - powerworld.com · ©2018 PowerWorld Corporation 3 •The only comprehensive documentation about all of the object types and fields that are available

[email protected]://www.powerworld.com

2001 South First StreetChampaign, Illinois 61820+1 (217) 384.6330

2001 South First StreetChampaign, Illinois 61820+1 (217) 384.6330

Auxiliary File and Scripting Tips

2© 2018 PowerWorld Corporation

• https://www.powerworld.com/WebHelp/Content/Other_Documents/Auxiliary‐File‐Format.pdf–Most up‐to‐date description of all available script commands and other auxiliary file related information

• https://www.powerworld.com/WebHelp/–Most up‐to‐date help information for all of Simulator

– This contains the SimAuto documentation

Available Online Help


• The only comprehensive documentation about all of the object types and fields that are available

Export Case Object Fields(More Documentation)


Export Case Object Fields

< Included in Difference Case comparison* Required for creating object1, 2, 3 Primary keyA, B, C Secondary key

For the majority of fields the description found here is the most comprehensive information that you will find describing them


• SimAuto functions for obtaining field details– GetFieldList(ObjectType)

• Return all fields and details for a particular object type– GetSpecificFieldList(ObjectType, FieldList)

• Return specified fields and details for a particular object type

Export Case Object Fields


• Hover over column headers in case information displays to see the description of fields

Hover Hints

Hints can be enabled/disabled by toggling Show Header Hints option


• Some dialogs have hints that pop up when hovering over option fields

• These hintsprovide the object type and variable name for setting this option in an auxiliary file data sectionor script command

Hover Hints


• Variable Names are used within auxiliary file DATA and SCRIPT sections to identify fields

• For help in creating auxiliary files, column headers within the Model Explorer can be set to show the variable names instead

Specifying Field Variable Names


• Variables follow the naming convention variablename:location where location is an integer indicating the exact variable to be used

• This convention is considered the legacy convention where the same variablename was re‐used by tacking on the location

• Starting with Simulator version 19, concise variable names have been created in an attempt to get rid of the location in as many variables as possible and to make the names more obvious



• The legacy variables to indicate the MW flow at the from end and to ends of a branch are:– LineMW:0 ( :0 is typically omitted because :0 is assumed if no location specified)

– LineMW:1• The same variables in the concise format are:

– MWFrom– MWTo

Specifying Field Variable NamesLegacy vs. Concise


• Both versions of a field variable name can be shown in the Model Explorer

Specifying Field Variable NamesLegacy vs. Concise

Toggle option to switch between legacy and concise. In Simulator version 20 this is set to show concise names by default.


• Location indicators continue to exist for some variable names

• Typically these are fields for which a dynamic number exists– Fields that are available for most objects

• CustomExpression, CustomFloat, CustomInteger, CustomString, CustomExpressionStr, CalcFied, DataCheck, and DataCheckAggr

– Some example fields that are available for specific objects• Bus – MargCostMWValue, MargControl, SensdValuedPinjMult

• Branch – PTDFMult, LODFMult, LODFInterfaceMult• Gen – BidMW, BidMWHr, SensMultMeterMultControl



• To better identify dynamic fields, the Location can be replaced with Location_by_name for fields that have user‐defined names

• This could help prevent conflicts in data where the same Location by number is being referenced in different auxiliary files but these should really be different fields

• The fields can be read and written by Simulator when used in auxiliary files– CustomExpression, CustomFloat, CustomInteger, CustomString, CustomExpressionStr, CalcFied, DataCheck, and DataCheckAggr

– "CustomFloat:My Header"– "CalcField:My calculated field name" – "DataCheckAggr:Bus 'DataCheck Name'"




Toggle Use Defined Names in Variable Name Locations to show the user‐defined name within the case info grid and to use this when saving an auxiliary file


• What if you don’t know how many fields exist for a particular variable name?– Multiple PTDF or LODF calculation produces a matrix of results based on the inputs selected

• Replace the Location identifier with the keyword ALL– PTDFMult:ALL or LODFMult:ALL

• Available with script commands that allow specifying fields to save to file– CTGSaveViolationMatrices, SaveData, SaveDataWithExtra, SaveObjectFields, and SendToExcel

Specifying Field Variable NamesSaving All Fields for a Variable


• Available with SimAuto functions that get fields– GetParametersMultipleElement, GetParametersMultipleElementFlatOutput, GetParametersSingleElement, GetSpecifiedFieldList, SendToExcel, and WriteAuxFile

• Save the LODF matrix results to a CSV file

Specifying Field Variable NamesSaving All Fields for a Variable

SaveData("myfile.CSV",CSVColHeader,Branch,[BusNumFrom,BusNumTo,Circuit,LODFMult:ALL],[],,[],NO);

Hint: use filetype = CSVColHeader to identify the monitored branches by the normal names instead of variable names


• What if you just want everything?• Replace entire list of fields with keyword ALL• Available with script commands that allow specifying fields to save to file– CTGSaveViolationMatrices, SaveData, SaveDataWithExtra, SaveObjectFields, and SendToExcel


Specifying Field Variable NamesSaving All Fields for an Object Type



• Saving all fields for a Branch

Specifying Field Variable NamesSaving All Fields for an Object Type

SaveData("myfile.CSV",CSVColHeader,Branch,[ALL],[],,[],NO);


• Simulator has many fields, but sometimes that is not enough

• Custom fields are available for data that does not fit anywhere else

• Custom fields can also be useful for temporary storage of values– e.g. store the pre‐change flow to compare against post‐change flow

• By default 5 Custom Floating Point, Custom Integer, and Custom String fields are available for most objects

• Number and names of each type of field can be customized on an object type basis

Custom Fields


Custom FieldsCustom Field Descriptions

Default object types are always listed. These apply to all object types.

Number of default fields of a particular type can be changed without additional customization.


Custom Field Descriptions• To customize for a particular object

type right‐click and choose Insert(or Show Dialog for existing)– Choose the Object Name– Choose the Field Type– Choose the Number of Type– Define Field Captions– Define Header Captions

List of available fields reflects the user‐defined Field Captions


Custom Field Descriptions

Column headings reflect the user‐defined Header Captions


• Custom Expressions (Custom String Expressions)– Allow calculation to be performed on fields of the object type for which it is defined

– Model Field, Model Expression, and Model String Expression fields can also be included in the expression function

• Model Expressions (Model String Expressions)– Allow calculation on specific fields of specific objects

• Provide a way of performing calculations and updating data within Simulator

• Useful with contingency actions and remedial actions for specifying the value of the applied action

Expressions


ExpressionsClick New to add a new expression and then give it a meaningful name

Assign fields to expression variables

Define the function for the expression

Fields can be a Field of the particular object type or access fields for particular model objects

https://www.powerworld.com/WebHelp/#MainDocumentation_HTML/Functions_and_Operators_Available.htm


• Example of increasing load by 10%– Create expression Increase MW by 10%– Update the load by the result of the expression using script command

Expressions

SetData(Load, [MW], ["@CustomExpression:Increase MW by 10%"], ALL);

SetData(Load, [MW], ["@CustomExpression"], ALL);


• Original intent was to allow extra information to be stored that is associated with display objects

• Can be used as a user‐defined container object similar to other aggregation objects like areas, zones, substations, etc. – Details of this will be left for other discussions

• Within the context of script commands and auxiliary files can be used as a place to store user‐defined variables– Reference these using the Special Keywords in Script Commands syntax, Specifying Field Values in Script Commands syntax, and as part of Custom Expressions and Model Expressions

Supplemental Data


• Two objects need to be defined– Supplemental Classification

• This is used as the category to group the data• Example –My Custom Options

– Supplemental Data• Individual pieces of information that belong to a Supplemental Classification

• Assign to a Supplemental Classification and provide a Name

• Example – Classification = My Custom Options, Name = My Working Directory

Supplemental Data


Supplemental Data

Use custom fields for assigning the values of the user‐defined variables


• Allowed as part of file name parameters and other text parameters– Generally, these cannot be used for specifying the values to set for specific fields

• The following keywords will be replaced with their actual value when used by a script command– @DATETIME, @DATE, @TIME, @BUILDDATE, @VERSION, and @CASENAME

– @MODELFIELD<objecttype 'key1' 'key2' 'key3' variablename:digits:rod>

Special Keywords in Script Commands


Special Keywords in Script Commands

SaveData("@MODELFIELD<SupplementalData 'My Custom Options' 'My Output Directory' CustomString>@CASENAME_myoutput.CSV", CSV, Bus, [Number, NomkV, Vpu, Vangle], [],,[],NO);

Directory is specified by @MODELFIELD<SupplementalData 'My Custom Options' 'My Output Directory' CustomString>

@CASENAME includes b7flatfrom b7flat.pwb

Remainder of file name, _myoutput.CSV, is remainder of the script command parameters that is not a keyword


• These are the exceptions because generally the special keywords are only used in file names and text fields as parameters in script commands

• The fields where this is allowed currently only include fields that specify output file names or directories

• The keywords will be converted at the time that the fields are accessed to determine the name of the directory or file

• The following fields can include the special keywords (these will also show up in relevant dialog fields in the GUI)– Transient_Options: ExpDirectory– PVCurve_Options: PVCOutFile, PVCStoreStatesWhere– QVCurve_Options: QVOutputDir– CTG_Options: CTGPostSolAuxFile, PostPostAuxFile, CTGResultStorageFile:1 – Contingency: PostCTGAuxFile– Sim_Environment_Options: SEOSpecifiedAUXFile:0, SEOSpecifiedAUXFile:1,

SEOSpecifiedAUXFile:2– MessLog_Options: LogAutoFileName

Special Keywords in Field Values


Special Keywords in Field ValuesExample

Hover hints over the dialog fields indicate the object type and variable name to use in aux files


• When setting the value of a field other fields can be referenced by using special formatting

• The following can be used in script commands and data sections– "@variablename:location:digits:decimals"

• Sets the field to another field within the same object– "&ModelExpressionName:digits:decimals"

• Sets the field to the result of a model expression– "&objecttype 'key fields' variablename:location:digits:decimals"• Sets the field to the value of the specified field for the specified object

Specifying Field Values


• digits specifies the total number of digits– Default is 32

• decimal specifies the digits to the right of the decimal– Default is 16

• When using concise variable names both digit and decimalmust be specified if specified at all– location can be omitted whether or not digit and decimal are specified

• When using legacy variable names location, digit, and decimal can be omitted but the previous parameters must be specified for a given parameter to be included

Specifying Field Values


Specifying Field ValuesExamples

SetData(Load, [MW], ["@CustomExpression"], ALL);

SetData(Load, [MW], ["&Gen 2 '1' MW:8:2"], "<Device>Load 2 '1'");

Set the MW value of all loads to the custom expression result for that load

Set the MW value of the load at bus 2 with ID = 1 to the MW output of the generator at bus 2 with ID = 1


• Many script commands take a filter as input to determine the objects on which the command acts

• Valid filter parameters are typically– "FilterName"

• Name of Advanced Filter, Device Filter, or Secondary Filter (filtering across object types)

– AREAZONE• Filter based on the area/zone/owner filter

– SELECTED• Filter based on the Selected field = YES

– ALL• Special filter for some script commands to include all objects of a specified object type

Filtering


• Device Filter– Instead of creating an Advanced Filter to return a particular object, reference the object directly through the device filter syntax• "<DEVICE>objecttype 'key1' 'key2' 'key3’”

Filtering

SetData(Load, [MW], ["&Gen 2 '1' MW:8:2"], "<Device>Load 2 '1'");

Set the MW value of the load at bus 2 with ID = 1 to the MW output of the generator at bus 2 with ID = 1


• Filtering Across Object Types (Secondary Filter)– Reference an Advanced Filter for a different object type than the

object being filtered– Allows reuse of filters

• Example: define a bus filter and then use this to filter generators, loads, switched shunts, branches, or any other object that connects to a bus

• If the object being filtered contains more than one of the filter object type OR is assumed– If a bus object is being filtered based on an area filter, the bus meets the filter if

the area of the bus meets the filter– If an area object is being filtered based on a bus filter, the area meets the filter

if ANY single bus in the area meets the filter – "<objecttype>filtername"

Filtering

SetData(Load, [MW], ["@CustomExpression"], "<Bus>Nom kV > 138");

Set the MW value of a load if the terminal bus of the load meets the filter


• Auxiliary file scripting is a batch process with no looping structure or condition checks

• The intention is to load an auxiliary file and walk away

• There are a few script commands and special syntax that allow user interaction with a GUI dialog during the scripting

User Interface During Scripting


• Special syntax within the filename parameter in script commands will open a dialog to choose a file– "<PROMPT 'Caption' 'FileTypes'>"

GUI During Scripting

LoadAux("<PROMPT 'Choose an AUX file' 'Auxiliary Files (*.aux)|*.aux|All Files (*.*)|*.*'>");

Specified FileTypes

Specified Caption


• MessageBox("text");– Provide a simple text message to the user with no user input to the scripting


MessageBox("Hello World");


• OpenDataView("ObjectIDString", "DataGridIDString");– Use the Data View feature to display a dialog during scripting that will allow fields to be changed for a single object in a manner similar to how they are changed in a case information display

– See the help documentation for full details on how to customize these data views• https://www.powerworld.com/WebHelp/Default.htm#MainDocumentation_HTML/Data_View.htm



GUI During ScriptingOpenDataView("Bus 1", "DataGrid 'Bus'");

• Opens a dialog containing the same fields that are displayed in the Bus case information display in the Model Explorer

• Color coding for field values is the same as in a case information display

• User can change values for the fields that can be edited


• ObjectFieldsInputDialog("ObjectIDString",[fieldlist], lots of optional parameters);– Create a custom dialog for displaying fields for a particular object without having to define a DataGrid object

– See help documentation for details on how to specify the lots of optional parameters• https://www.powerworld.com/WebHelp/Content/Other_Documents/Auxiliary‐File‐Format.pdf



GUI During ScriptingObjectFieldsInputDialog("Bus 1",[Number, Name, Vpu, Vangle]);

• Opens a dialog containing the fields defined in the script command

• Color coding for field values is the same as in a case information display

• User can change values for the fields that can be edited


GUI During ScriptingObjectFieldsInputDialog("Branch 1 2 1", [BusNumFrom, BusNumTo, Circuit, LimitMVAA, LimitMVAB, LimitMVAC, R, X, Status, MWFrom, MWTo, MvarFrom, MvarTo, MVAFrom, MVATo], "My Custom Branch Dialog", "My Branch", [], [3, 9], ["Input Tab","Output Tab"], [3,8,9,13], ["Ratings","Status","MW","MVA"], [6,11], ["Impedance","Mvar"]);


• Provide a way of performing an arithmetic operation on a group of objects of a single object type based on a specific field

• This calculation can then be applied to objects of a different object type

• The final results are based on how the object type in the calculated field definition relates to the object type to which the calculation is applied– Define a calculation on the branch object type and then apply this to the bus object type. The final result that is displayed with a bus will perform the calculation on all branches that have at least one terminal connected to that bus.

Calculated Fields


• Total Max MW of generators by range– Define calculated fields for the ranges of generators: 0 – 100 MW, 100 – 500 MW, 500 –1000 MW, greater than 1000 MW

• Calculated fields will show up in the list of available fields for all applicable object types

Calculated FieldsExample



Object Type on which the calculation is performed

Field and Operation being applied

Filter is applied to the objects of Object Type to determine which ones are included in the calculation



When used with Area object type, the calculated results give the total Max MW of all generators in each area within the specified MW range



When used with Zone object type, the calculated results give the total Max MW of all generators in each zone within the specified MW range


• Other examples– Return the buses in the island with the most buses– Set the system slack bus based on generator criteria

–Maximum percent flow on all branches in an area or zone

– Trip injection group with largest output– GIC flows in a substation– Losses by owner and nominal kV level– PV results with the lowest transfer level

Calculated Fields


• Allows you to define a list of DATA sections and fields you would like to write out to an auxiliary file

• These formats themselves can then be saved to an auxiliary file and used whenever needed

• The following options define an aux export format– Object Type: Specify type of object– Filter Name: All, Selected, AreaZone, the name of an Advanced Filter in

quotes, or a Filter Condition. Allows you to specify objects for which to write data.

– Fields: a list of all fields to be written for this object– SubData: a list of sub‐data sections to write for each object

• Script command can be used to save an auxiliary file in a defined format– SaveDataUsingExportFormat("filename", filetype, "FormatName");

Auxiliary File Export Format Descriptions


• On the Case Information Ribbon Tab, click AUX Export Format Desc…


Choose Object Types

Choose Fields

Choose SubData

Set formatting and file type


• Default formats can be used as a starting point for customizations



• AUX export formats can be used with Present Case Topological Differences from the Base Case dialog to customize fields and objects saved
