|
|
|
ExcelApp Property
The Simulator Automation Server has the ability to send data from Simulator to an Excel spreadsheet using the
SendToExcel. By default, the Simulator Automation Server starts an instance of Excel the first time one of the above
functions is called. Each subsequent call to these two functions will then send data to the same instance of Excel,
until it is manually closed by the user. The ExcelApp property allows the user to gain access to the instance of Excel
used by the Simulator Automation Server from within its own code. Thus the user can write code to manipulate the
external instance of Excel. In addition, the ExcelApp property can be set by the user’s code, meaning that the user
can initialize an external instance of Excel from within their own code and set the ExcelApp property to their external
instance of Excel. Simulator itself is limited to starting only one instance of Excel on its own, but with the ExcelApp
property allowing you to set the instance of Excel that Simulator uses on the fly, you can generate multiple instances
of Excel within your code, and handle setting the ExcelApp property of the Simulator Automation server to the desired
Excel instance depending on the data you want to send to Excel.
The ExcelApp property is a variable of type Variant that returns the pointer to an object representing the external
instance of Excel.
ExcelApp : Variant
To gain access to the external instance of Excel stored in the ExcelApp property, you first need to initialize a variable
as an object. The following are a couple of examples in Borland Delphi and Microsoft Visual Basic.
Examples
Borland Delphi 5
· Var MyExc : TObject
· MyExc = SimAuto.ExcelApp {Makes the connection to the external instance}
·
{Perform activities with the Excel instance}
· MyExc.Quit {Closes the external instance if called; do not call if you wish the instance to remain open}
· MyExc.Free {Removes the connection to the external instance}
Microsoft Visual Basic
· Dim MyExc As Variant
· Set MyExc = SimAuto.ExcelApp {Makes the connection to the external instance}
·
{Perform activities with the Excel instance}
· MyExc.Quit {Closes the external instance if called; do not call if you wish the instance to remain open}
· Set MyExc = Nothing {Removes the connection to the external instance}
800
PowerWorld Simulator Add-on Tools
ExcelApp Property: Sample Code
Microsoft® Visual Basic for Applications
Dim ExcelObject As Variant
If Not (IsEmpty(SimAuto.ExcelApp)) Then
Set ExcelObject = SimAuto.ExcelApp
ExcelObject.DisplayAlerts = False
ExcelObject.Quit
Else
MsgBox("Attempted to obtain Excel COM object from " + _
"Simulator, but there is not one open.")
End If
Matlab®
MATLAB is currently unable to handle COM object properties returning COM objects themselves, such as the
ExcelApp property of Simulator.
801
CurrentDir Property
The CurrentDir property of the Simulator Automation Server allows you to retrieve or set the working directory for the
currently running SimulatorAuto process. This is most useful if using relative filenames (e.g. "relativename.aux"
versus "C:\Program Files\PowerWorld\Working\abosultename.aux") when specifying files.
802
PowerWorld Simulator Add-on Tools
CurrentDir Property: Sample Code
Microsoft® Visual Basic for Applications
' Display the current directory
MsgBox(SimAuto.CurrentDir)
' Set the current directory to c:\
SimAuto.CurrentDir = "c:\"
Matlab®
% Display the current directory
disp(SimAuto.CurrentDir)
% Set the current directory to c:\
SimAuto.CurrentDir = 'c:\';
803
ProcessID Property
The ProcessID property of the Simulator Automation Server allows you to retrieve the process ID of the currently
running SimulatorAuto process, as can also be seen through the Task Manager in Windows® NT 4, 2000 and XP.
This information can be useful if a forced shutdown of the SimulatorAuto object is needed, as all calls to the
SimulatorAuto object are synchronous. This means the SimulatorAuto object will not be destroyed until all calls, no
matter the time of execution, have completed.
804
PowerWorld Simulator Add-on Tools
ProcessID Property: Sample Code
Microsoft® Visual Basic for Applications
' Display the process ID
MsgBox(SimAuto.ProcessID)
Matlab®
% Display the process ID
disp(num2str(SimAuto.ProcessID))
PowerWorld Object Variables
PowerWorld Object Variables
The ability to access power system data for different objects through various Simulator Automation Server Functions is
based on variables defined in Simulator that can be referred to as Object Field Variables. Each object (i.e. bus,
generator, etc.) can have numerous fields associated with it. Each of these fields, in turn, has a variable associated
with the field to enable access to the field for the purpose of acquiring or changing data. For example, the
GetParametersSingleElement function has a parameter called ParamList, which is intended to store a list of Object
Field Variables for a particular type of object. When the function is called, the Simulator Automation Server will return
the values associated with each particular field variable for the type of object specified. These field variables allow for
complete flexibility by the user in specifying as many or as few fields for a particular object when acquiring or changing
data.
805
Examples of Field Variables
PWBusGenMW
PWBusNum
Simulator has literally hundreds of parameters spanning numerous types of device and option specifications. Rather
than list all of the field variables and the value they represent in this help file, we have enabled Simulator to
automatically generate a text file containing the field variables and a description of what value the variable represents.
PowerWorld Corporation highly recommends that you examine this list. To generate this text file, run PowerWorld
Simulator and access the Help menu. Choose the option Export Object Fields… Specify a file name and location
for saving the file, and click Save. Simulator will save out the field variables, the type of variable (string, integer, etc.),
and a description of the value the field variable represents, with key fields for different objects marked with an asterisk.
The field variables will also be split into sections based on the type of object they are valid for. Note that the same
field variable may be available for more than one object, but that the value represented by the field variable might vary
for different objects.
Examples of Field Variables in Listing
PwBusGenMW Real 'Bus Gen MW'
* PwBusNum Integer 'Bus Number' (* denotes key field in text file)
ATC_MaxLimElements Integer 'Max # Limiting Elements'
The last note on the Object Field Variables is that some of the object field variables are reused for more than one
value for an object. For example, a transmission line has "from" and "to" buses associated with the line. Rather than
have separate field variables for values at each terminal bus, the same field variable is used for both, with a colon
followed by a number appended to the variable to signify which bus the value represents. As an example, consider
the field variable for bus per unit voltage, which is PWBusPUVolt. Since there are two buses per line, the "From" bus
voltage would be represented as PWBusPUVolt:0, and the "To" bus voltage would be represented as
PWBusPUVolt:1. The enumeration of the field variables always starts with 0 for the first instance. You may note that
in the text file of field values that you don't see any field variables with :0 appended to them. Since we did not want
you to have to always append the :0 on all field variables, the default for a field variable with no appended :# is 0.
Thus you would only need to be concerned with appending the :# for field variables that require a number greater than
0.
Simulator Automation Server (SIMAUTO) (version 9)
Simulator Automation Server (version 9)
NOTE: The function calls for version 9 of SimAuto have become obsolete in version 10. The reason for the
change was due to problems that arose with the structure of the functions in certain programming languages.
The function structures have been modified for version 10 of Simulator. If you have code written that uses
version 9 SimAuto function structures, it is fairly straightforward to convert the function calls from version 9
to version 10. Please see the updated section on the Simulator Automation Server for version 10. If you still
have questions, please contact PowerWorld Corporation.
The PowerWorld‚ Automation Server is only available to customers who have purchased the SimAuto add-on for
PowerWorld‚ Simulator. The PowerWorld Simulator Automation Server is intended for enabling a PowerWorld
customer with the ability to access PowerWorld Simulator functionality from within a program written externally by the
user. The Simulator Automation Server acts as a COM object, which can be accessed from various different
programming languages that have COM compatibility. Examples of programming tools with COM compatibility are
Borland‚ Delphi, Microsoft‚ Visual C++, and Microsoft‚ Visual Basic, just to name a few. For more information on
COM and Automation servers, see the help for Microsoft Windows.
The Automation Server of Simulator works very well in combination with Simulator Script Commands and Auxiliary
Files. It is beneficial to become familiar with these topics when considering using the Simulator Automation Server.
Starting Simulator Automation Server
Installing Simulator Automation Server (version 9)
Installing the Simulator Automation Server requires no additional steps beyond installing PowerWorld Simulator as
normal. When a version of PowerWorld Simulator containing the Simulator Automation Server is installed on your
computer, the install program automatically adds the information needed by the Simulator Automation Server to the
registry.
806
PowerWorld Simulator Add-on Tools
Including Simulator Automation Server Functions (version 9)
Before you can access the functions defined by the Simulator Automation Server when writing the code for your
external program, you must first include the library of functions defined for the Simulator Automation Server. This kind
of library is referred to as a Type Library, which describes the available functions in a manner that can be interpreted
by different programming languages. Importing a Type Library from another program is usually fairly simple, but the
procedure does vary depending on the programming tool you are using. Please see the help for your programming
tool of choice on how to import a Type Library or COM functions from another program.
Examples
The following examples are just a few specific examples for certain programming media. The procedure may be
different for other programming media not listed. In addition, a procedure given for a certain type of programming
media may be one variation from several possible procedures for accomplishing the same task.
Borland Delphi 5
· Install the version of PowerWorld Simulator with the Simulator Automation Server included.
· In Delphi 5, choose Import Type Library… from the Project menu.
· In the list of libraries, search for and choose pwrworld Library.
· If pwrworld Library is not in the list, click Add. Find and choose the Pwrworld.exe file from the PowerWorld
Simulator directory, and click Open.
· You should see the class name TSimulatorAuto in the list of Class names.
· Click Install to include the PowerWorld Simulator Type Library.
Microsoft Visual Basic
· Install the version of PowerWorld Simulator with the Simulator Automation Server included.
· In VB, choose References… from the Tools menu. Find and choose pwrworld Library from the list of
references.
· If pwrworld Library is not in the list, click Browse. Change the file type to *.exe, find and choose the
Pwrworld.exe file from the PowerWorld Simulator directory, and click Open.
· Click OK to install the Simulator Type Library reference.
Microsoft Visual C++
· Install the version of PowerWorld Simulator with the Simulation Automation Server included.
· Add #import "…\powerworld.exe" in your external program code, using the full path to the PowerWorld
Simulator executable program.
· Add using namespace pwrworld in your external program code.
807
Connecting to Simulator Automation Server (version 9)
Once the Type Library or COM functions have been included in your programming environment, the Simulator
Automation Server can be handled as any other object in your code. The method for assigning and connecting to the
Simulator Automation Server can vary depending on the programming environment used, but the idea is basically the
same. You define a variable in your program to point to the server object, which is called SimulatorAuto. If the Type
Library was imported properly, you should have full access to the SimulatorAuto object and its defined functions.
Again, the procedure for creating the object and connecting to SimulatorAuto may vary for different programming
languages. Check the help for your programming environment on connecting to COM or Automation servers.
Examples
The following examples are just a few specific examples for certain programming media. The procedure may be
different for other programming media not listed. In addition, a procedure given for a certain type of programming
media may be one variation from several possible procedures for accomplishing the same task.
Borland Delphi 5
· Add pwrworld_TLB to the uses section of your unit.
· Declare a variable globally or as part of another object: A : ISimulatorAuto.
· Initialize the variable: A := nil.
· To connect to the Simulator Automation Server, create the connection: A := CoSimulatorAuto.create .
· Perform function calls to the Simulator Automation Server: A.SomeFunction(parameters).
· To close the connection to the Simulator Automation Server, remove the reference by again setting: A :=
nil.
Microsoft Visual Basic
· Declare a variable globally or as part of another object or function: Public A As SimulatorAuto.
· To connect to the Simulator Automation Server, create the connection: Set A = New SimulatorAuto.
· Perform function calls to the Simulator Automation Server: A.SomeFunction parameters.
· To close the connection to the Simulator Automation Server, remove the reference: Set A = Nothing.
Microsoft Visual C++
· Declare a variable globally or as part of another object or function: IsimulatorAutoPtr *A.
· Declare a variable globally or as part of another object or function: CLSID clsid.
· Declare a variable globally or as part of another object or function: HRESULT hr.
· Obtain the class identifier (clsid) with the following command: hr =
CLSIDFromProgID(L"pwrworld.SimulatorAuto", &clsid).
· Initialize variable A: A = new IsimulatorAutoPtr.
· To connect to the Simulator Automation Server, create the connection: hr = A>CreateInstance(clsid,
NULL, CLSCTX_SERVER).
· Perform function calls to the Simulator Automation Server: A.SomeFunction(parameters).
· To close the connection to the Simulator Automation Server, release the reference: hr = A>Release().
808
PowerWorld Simulator Add-on Tools
Simulator Automation Server Properties
Simulator Automation Server Properties (version 9)
The following list of parameters is currently available once the SimulatorAuto object is set in your code. Check the
help sections on these properties to see more detail on the particular property.
ExcelApp
809
ExcelApp Property (version 9)
The Simulator Automation Server has the ability to send data from Simulator to an Excel spreadsheet using the
SendToExcel. By default, the Simulator Automation Server starts an instance of Excel the first time one of the above
functions is called. Each subsequent call to these two functions will then send data to the same instance of Excel,
until it is manually closed by the user. The ExcelApp property allows the user to gain access to the instance of Excel
used by the Simulator Automation Server from within their own code. Thus the user can write code to manipulate the
external instance of Excel. In addition, the ExcelApp property can be set by the user’s code, meaning that the user
can initialize an external instance of Excel from within their own code and set the ExcelApp property to their external
instance of Excel. Simulator itself is limited to starting only one instance of Excel on its own, but with the ExcelApp
property allowing you to set the instance of Excel that Simulator uses on the fly, you can generate multiple instances
of Excel within your code, and handle setting the ExcelApp property of the Simulator Automation server to the desired
Excel instance depending on the data you want to send to Excel.
The ExcelApp property is a variable of type Variant that returns the pointer to an object representing the external
instance of Excel.
ExcelApp : Variant
To gain access to the external instance of Excel stored in the ExcelApp property, you first need to initialize a variable
as an object.
The following are a couple of examples in Borland Delphi and Microsoft Visual Basic.
Examples
Borland Delphi 5
· Var MyExc : TObject
· MyExc = SimAuto.ExcelApp {Makes the connection to the external instance}
·
{Perform activities with the Excel instance}
· MyExc.Quit {Closes the external instance if called; do not call if you wish the instance to remain open}
· MyExc.Free {Removes the connection to the external instance}
Microsoft Visual Basic
· Dim MyExc As Object
· Set MyExc = SimAuto.ExcelApp {Makes the connection to the external instance}
·
{Perform activities with the Excel instance}
· MyExc.Quit {Closes the external instance if called; do not call if you wish the instance to remain open}
· Set MyExc = Nothing {Removes the connection to the external instance}
Simulator Automation Server Functions
Simulator Automation Server Functions (version 9)
The following list of functions is currently available once the SimulatorAuto object is set in your code. Check the help
sections on these functions to see more detail on the particular function.
ChangeParameters
CloseCase
GetParameters
ListOfDevices
LoadContingencies
OpenCase
ProcessAuxFile
RunScriptCommand
SaveCase
SendToExcel
WriteAuxFile
810
PowerWorld Simulator Add-on Tools
ChangeParameters Function (version 9)
The ChangeParameters function allows you to set a list of parameters for a specific object in a case loaded into the
Simulator Automation Server. In addition to changing parameters for objects, this function can also be used to set
options for some of the Simulator tools, such as ATC and OPF. This function is identical in setup to the
GetParameters function, with the exception that the Values array must contain a value for each field variable given in
the ParamList array.
ChangeParameters(tObjectType, ParamList, Values, EString)
Parameter Definitions
TobjectType : String
The type of object you are changing parameters for. No default.
ParamList : Variant
A variant array storing strings. This array stores a list of PowerWorld‚ object
field variables, as defined in the section on PowerWorld Object Fields. The
ParamList must contain the key field variables for the specific device, or the
device cannot be identified. No Default.
Values : Variant
A variant array storing variants. This array can store any type of information
(integer, string, etc.) in each array position. A value should be passed for each
field variable given in the ParamList. The Values array must contain the key
field values for the specific device, or the device cannot be identified. No
Default.
EString : Variant
This parameter must be assigned a variable declared as a Variant. This
parameter is for a return value only, and will assign the passed variable a string
representing an error that may have occurred in the Simulator Automation
Server. If no error occurred, the EString variable will return an empty string.
Example
ChangeParameters("gen", [pwBusNum, pwGenID, pwGenAGCAble], [1, "1", "Yes"], EString)
This function call will change the AGC Status of bus number one, generator ID number 1, to "Yes", meaning
the generator will be included in AGC if it's area is on AGC control.
811
CloseCase Function (version 9)
The CloseCase function is used to close a load flow case loaded in the Simulator Automation Server. This function
should be called at some point after the OpenCase function. An error will be returned through the EString parameter if
an error occurred while trying to close the case.
CloseCase(EString)
Parameter Definitions
EString : Variant
This parameter must be assigned a variable declared as a Variant. This
parameter is for a return value only, and will assign the passed variable a string
representing an error that may have occurred in the Simulator Automation
Server. If no error occurred, the EString variable will return an empty string.
812
PowerWorld Simulator Add-on Tools
GetParameters Function (version 9)
The GetParameters function is used to request the values of specified fields for a particular object in the load flow
case. For returning field values for multiple objects, you can use a loop to make repeated calls to the GetParameters
function, and pass the object and desired field information for each object. This function is identical in setup to the
ChangeParameters function, with the exception that the Values array will be updated with the values for the field
variables defined in ParamList.
GetParameters(tObjectType, ParamList, Values, EString)
Parameter Definitions
TobjectType : String
The type of object you are changing parameters for. No default.
ParamList : Variant
A variant array storing strings. This array stores a list of PowerWorld‚ object
field variables, as defined in the section on PowerWorld Object Fields. The
ParamList must contain the key field variables for the specific device, or the
device cannot be identified. The remaining field variables in the array define
which values to retrieve from Simulator. No Default.
Values : Variant
A variant array storing variants. This array can store any type of information
(integer, string, etc.) in each array position. Values must be passed for the key
field variables in ParamList, in the same array position. The remaining field
positions in the Values array can initially be filled with either empty strings or
zeroes, as the values will be replaced when the function is processed. No
Default.
EString : Variant
This parameter must be assigned a variable declared as a Variant. This
parameter is for a return value only, and will assign the passed variable a string
representing an error that may have occurred in the Simulator Automation
Server. If no error occurred, the EString variable will return an empty string.
Example
GetParameters("gen", [pwBusNum, pwGenID, pwGenAGCAble], ValArray = [1, "1", ""], EString)
This function call will return the AGC Status of bus number one, generator ID number 1, in the ValArray
variable. Note that the generator bus number and ID had to be passed into the function, while the remaining
field could be assigned an empty string. If the bus number and ID had not been passed, an error would have
been returned since Simulator would not be able to identify a generator. With a valid bus number and ID for
the generator, the ValArray variable would have returned an array of the following format: ValArray = [1, "1",
"Yes"].
813
ListOfDevices Function (version 9)
The ListOfDevices function is used to request a list of objects and their key fields from the Simulator Automation
Server. The function can return all devices of a particular type, or can return only a list of devices of a particular type
based on an advanced filter defined for the loaded case. This function is best used in conjunction with a looping
procedure and the ChangeParameters or GetParameters functions to process a group of devices.
ListOfDevices(tObjType, EString, filterName, objList1, {objList2}, {objList3})
Parameter Definitions
TobjType : String
The type of object for which you are acquiring the list of devices. No default.
EString : Variant
This parameter must be assigned a variable declared as a Variant. This
parameter is for a return value only, and will assign the passed variable a string
representing an error that may have occurred in the Simulator Automation
Server. If no error occurred, the EString variable will return an empty s tring.
FilterName : String
The name of an advanced filter defined in the load flow case open in the
Simulator Automation Server. If the filter cannot be found, the server will
default to returning all objects in the case of type TobjType.
ObjList1 : Variant
This parameter must be assigned a variable declared as a Variant. The
Simulator Simulation Server will return a variant array filled with the first key
field for the devices of type TobjType. This parameter is required for all types
of devices.
ObjLis t2 : Variant
This parameter may be optional. For device types that only have one key field,
you can omit passing a variable for this parameter. If the device type
requested has two or more key fields, then this parameter must be assigned a
variable declared as a Variant. The Simulator Simulation Server will return a
variant array filled with the second key field for the devices of type TobjType.
ObjList3 : Variant
This parameter may be optional. For device types that have one or two key
fields, you can omit passing a variable for this parameter. If the device type
requested has three key fields, then this parameter must be assigned a
variable declared as a Variant. The Simulator Simulation Server will return a
variant array filled with the third key field for the devices of type TobjType.
Example
ListOfDevices("gen", EString, "", objList1, objList2)
This function call will return a list of all generators in the load flow case. By passing an empty string as the
filter name, Simulator will not use an advanced filter before returning the generator key fields. Since
generators have two key fields, bus number and ID, it was required to pass two variant array variables to
receive the key fields. Each generator in the case would have its bus number returned in objList1 and ID in
objList2. The corresponding bus number and ID are stored in the same index position in the two arrays. If
only one variant array, objList1, had been passed in this instance, an error would have been returned stating
more arrays were necessary. If the third variant array, objList3, had been included, Simulator would have still
returned the key fields in objList1 and objList2, and would have returned objList3 as an empty variant.
814
PowerWorld Simulator Add-on Tools
LoadContingencies Function (version 9)
The LoadContingencies function can be used to read a set of predefined contingencies from a PowerWorld‚ Auxiliary
Contingency file. Thus once you have defined a set of contingencies in Simulator and saved the list to a PowerWorld
‚ Auxiliary file, you can specify the filename with this function and the Simulator Automation Server will load the
contingencies into memory.
LoadContingencies(fileName, EString, {tAppend})
Parameter Definitions
Filename : String
The name of the PowerWorld‚ Auxiliary file containing the defined
contingencies. If the file cannot be found, and error will be returned through
EString.
EString : Variant
This parameter must be assigned a variable declared as a Variant. This
parameter is for a return value only, and will assign the passed variable a string
representing an error that may have occurred in the Simulator Automation
Server. If no error occurred, the EString variable will return an empty string.
TAppend : Boolean
This parameter is optional. If you have more than one list of contingencies in
separate files, you can append the lists together in the Simulator Automation
Client by passing the Boolean value True in this parameter. The default if not
passed is False, meaning any existing contingencies in the Simulator
Automation Client would be cleared prior to loading the new list.
Example
LoadContingencies("c:\my files\ctgfile.aux", EString, True)
This function call will load a previously created list of contingencies that was saved in the PowerWorld
Auxiliary file format. The file name string identifies the location and name of the auxiliary file. By passing the
value True in the optional parameter tAppend, Simulator will read the list of contingencies and add them to
any existing contingencies already loaded in Simulator. Contingencies in the list existing list with the same
name as contingencies in the appending list will be replaced by the records in the appending list.
815
OpenCase Function (version 9)
The OpenCase function will load a PowerWorld‚ Simulator load flow file into the Simulator Automation Server. If an
error occurs trying to open the case, an error message will be returned through EString.
OpenCase(filename, EString)
Parameter Definitions
FileName : String
The name of the PowerWorld‚ Simulator case file to be loaded into the
Simulator Automation Server. This string includes the directory location and full
file name. If the file cannot be found or an error occurs while reading the file,
an error message will be returned through EString.
EString : Variant
This parameter must be assigned a variable declared as a Variant. This
parameter is for a return value only, and will assign the passed variable a string
representing an error that may have occurred in the Simulator Automation
Server. If no error occurred, the EString variable will return an empty string.
816
PowerWorld Simulator Add-on Tools
ProcessAuxFile Function (version 9)
The ProcessAuxFile function will load a PowerWorld‚ Auxiliary file into the Simulator Automation Server. This allows
you to create a text file (conforming to the PowerWorld‚ Auxiliary file format) that can list a set of data changes and
other information for making batch changes in Simulator. If an error occurs while processing the auxiliary file, an error
message is returned through EString.
ProcessAuxFile(filename, EString)
Parameter Definitions
FileName : String
The name of the PowerWorld‚ Auxiliary file to be loaded into the Simulator
Automation Server. This string includes the directory location and full file
name.
EString : Variant
This parameter must be assigned a variable declared as a Variant. This
parameter is for a return value only, and will assign the passed variable a string
representing an error that may have occurred in the Simulator Automation
Server. If no error occurred, the EString variable will return an empty string.
817
RunScriptCommand Function (version 9)
The RunScriptCommand function is used to execute a list of script statements. The script actions are those included
in the script sections of the Auxiliary Files. If an error occurs trying to run a script command, an error will be returned
through EString.
RunScriptCommand(Statements, EString)
Parameter Definitions
Statements : String
The block of script actions to be executed. Each script statement must end in a
semicolon. The block of script actions should not be enclosed in curly braces.
EString : Variant
This parameter must be assigned a variable declared as a Variant. This
parameter is for a return value only, and will assign the passed variable a string
representing an error that may have occurred in the Simulator Automation
Server. If no error occurred, the EString variable will return an empty string.
Example
RunScriptCommand("Entermode(PowerFlow); SolvePowerFlow;", EString)
This function call will switch to the PowerFlow submode and then will solve the power flow of the present
case.
818
PowerWorld Simulator Add-on Tools
SaveCase Function (version 9)
The SaveCase function is used to save a case previously loaded in the Simulator Automation Server using the
OpenCase function. The function allows you to specify a file name and a format for the save file. If an error occurs
while trying to save a case, an error message is returned through EString.
SaveCase(fileName, EString, {fileType}, {Overwrite})
Parameter Definitions
fileName : String
The name of the file you wish to save as, including file path. No default.
EString : Variant
This parameter must be assigned a variable declared as a Variant. This
parameter is for a return value only, and will assign the passed variable a string
representing an error that may have occurred in the Simulator Automation
Server. If no error occurred, the EString variable will return an empty string.
fileType : String
This parameter is optional. If you desire to save the case in a format other than
the current PowerWorld Binary (pwb) format, you must specify the type of
format in this parameter as a string. If the parameter is not passed, the format
type defaults to the most recent version of PowerWorld binary (pwb) file. If a
string is passed for this parameter, it must at least be the "PWB" string. An
empty string will return an error. The following list is the currently supported list
of string identifiers and the file types they represent.
"PTI23"
PTI version 23 (raw)
"PTI24"
PTI version 24 (raw)
"PTI25"
PTI version 25 (raw)
"PTI26"
PTI version 26 (raw)
"PTI27"
PTI version 27 (raw)
"GE"
GE PSLF (epc)
"IEEE"
IEEE common format (cf)
"PWB70"
PowerWorld Binary version 7.0 (pwb)
"PWB"
PowerWorld Binary (most recent) (pwb)
Overwrite : Boolean
This parameter is optional. If you do not want to overwrite a file with the same
name as passed in filename, you must specify this parameter as False. Default
is True.
819
SendToExcel Function (version 9)
The SendToExcel function can be called to send data from the Simulator Automation Server to an Excel spreadsheet.
The function is flexible in that you can specify the type of object data you want to export, an advanced filter name for a
filter you want to use, and as many or as few field types as desired that are supported by the type of object. The first
time this function is called, a new instance of Excel will be started, and the data requested will be pasted to a new
sheet. For each subsequent call of this function, the requested data will be pasted to a new sheet within the same
w orkbook, until the workbook is closed. If an error occurs while trying to send data to Excel, an error message is
returned through EString.
SendToExcel(tObjectType, filterName, EString, {tFieldList})
Parameter Definitions
tObjectType : String
A string describing the type of object for which your are requesting data. No
Default.
filterName : String
The name of an advanced filter which was previously defined in the case
before being loaded in the Simulator Automation Server. If no filter is desired,
then simply pass an empty string. If a filter name is passed but the filter cannot
be found in the loaded case, no filter is used. Default is an empty string.
EString : Variant
This parameter must be assigned a variable declared as a Variant. This
parameter is for a return value only, and will assign the passed variable a string
representing an error that may have occurred in the Simulator Automation
Server. If no error occurred, the EString variable will return an empty string.
TFieldList : Variant
This parameter is optional. A variant array of strings, where each string
represents an object field variable, as defined in the section on PowerWorld
Object Variables. If no array is passed, the Simulator Automation Server will
use predefined default fields when exporting the data.
Example
SendToExcel("gen", "", EString, [pwBusNum, pwGenID, pwGenAGCAble])
This function call will send the values of the fields in tFieldList to an Excel workbook for all the generators in
the load flow case. If a filter name had been passed instead of an empty string, Simulator would have located
and used a pre-defined advanced filter and applied it to the information if it was found. By specifying the
fields in the optional parameter tFieldList, only the three field values for eac h generator will be returned. If the
optional parameter tFieldList had been omitted, Simulator would have returned internally defined default
information for the generators.
820
PowerWorld Simulator Add-on Tools
WriteAuxFile Function (version 9)
The WriteAuxFile function can be used to write data from the case in the Simulator Automation Server to a
PowerWorld‚ Auxiliary file. The function is flexible in that you can specify the type of object data you want to export,
an advanced filter name for a filter you want to use, and as many or as few field types as desired that are supported by
the type of object. In addition, you can specify a new file name for each call to WriteAuxFile, or you can specify the
same file name and append the data to the file. If an error occurs while trying to write the auxiliary file, an error
message is returned through EString.
WriteAuxFile(fileName, filterName, tObjectType, EString, {tAppend}, {tFieldList})
Parameter Definitions
FileName : String
The name of the PowerWorld‚ Auxiliary file you wish to save. No default.
filterName : String
The name of an advanced filter which was previously defined in the case
before being loaded in the Simulator Automation Server. If no filter is desired,
then simply pass an empty string. If a filter name is passed but the filter cannot
be found in the loaded case, no filter is used. Default is an empty string.
tObjectType : String
A string describing the type of object for which your are requesting data. No
Default.
EString : Variant
This parameter must be assigned a variable declared as a Variant. This
parameter is for a return value only, and will assign the passed variable a string
representing an error that may have occurred in the Simulator Automation
Server. If no error occurred, the EString variable will return an empty string.
TAppend : Boolean
This parameter is optional. If you have given a file name of an auxiliary file that
already exists, then the file will either be appended to or overwritten according
to the setting of this parameter. If the parameter is not passed, the Simulator
Automation Server assumes false.
TFieldList : Variant
This parameter is optional. A variant array of strings, where each string
represents an object field variable, as defined in the section on PowerWorld
Object Variables. If no array is passed, the Simulator Automation Server will
use predefined default fields when exporting the data.
Example
WriteAuxFile("c:\my files \myauxfile.aux", "", "gen", EString, False, [pwBusNum, pwGenID,
pwGenAGCAble])
This function call will send the values of the fields in tFieldList to a PowerWorld Auxiliary file for all the
generators in the load flow case. If a filter name had been passed instead of an empty string, Simulator would
have located and used a pre-defined advanced filter and applied it to the information if it was found. By
specifying the fields in the optional parameter tFieldList, only the three field values for each generator will be
returned. If the optional parameter tFieldList had been omitted, Simulator would have returned internally
defined default information for the generators. Since the tFieldList optional parameter was included, the
tAppend optional parameter also had to be included, even though it's default value is already False.
821
PowerWorld Object Variables
PowerWorld Object Variables (Version 9)
The ability to access power system data for different objects through various Simulator Automation Server functions is
based on variables defined in Simulator that can be referred to as Object Field Variables. Each object (i.e. bus,
generator, etc.) can have numerous fields associated with it. Each of these fields, in turn, has a variable associated
with the field to enable access to the field for the purpose of acquiring or changing data. For example, the
GetParameters function has a parameter called ParamList, which is intended to store a list of Object Field Variables
for a particular type of object. When the func tion is called, the Simulator Automation Server will return the values
associated with each particular field variable for the type of object specified. These field variables allow for complete
flexibility by the user in specifying as many or as few fields for a particular object when acquiring or changing data.
822
PowerWorld Simulator Add-on Tools
Examples of Field Variables
PWBusGenMW
PWBusNum
Simulator has literally hundreds of parameters spanning numerous types of device and option specifications. Rather
than list all of the field variables and the value they represent in this help file, we have enabled Simulator to
automatically generate a text file containing the field variables and a description of what value the variable represents.
PowerWorld Corporation highly recommends that you examine this list. To generate this text file, run PowerWorld
Simulator and access the Help menu. Choose the option Export Object Fields… Specify a file name and location
for saving the file, and click Save. Simulator will save out the field variables , the type of variable (string, integer, etc.),
and a description of the value the field variable represents, with key fields for different objects marked with an asterisk.
The field variables will also be split into sections based on the type of object they are valid for. Note that the same
field variable may be available for more than one object, but that the value represented by the field variable might vary
for different objects.
Examples of Field Variables in Listing
PwBusGenMW Real 'Bus Gen MW'
* PwBusNum Integer 'Bus Number' (* denotes key field in text file)
ATC_MaxLimElements Integer 'Max # Limiting Elements'
The last note on the Object Field Variables is that some of the object field variables are reused for more than one
value for an object. For example, a transmission line has "from" and "to" buses associated with the line. Rather than
have separate field variables for values at each terminal bus, the same field variable is used for both, with a colon
followed by a number appended to the variable to signify which bus the value represents. As an example, consider
the field variable for bus per unit voltage, which is PWBusPUVolt. Since there are two buses per line, the "From" bus
voltage would be represented as PWBusPUVolt:0, and the "To" bus voltage would be represented as
PWBusPUVolt:1. The enumeration of the field variables always starts with 0 for the first instance. You may note that
in the text file of field values that you don't see any field variables with :0 appended to them. Since we did not want
you to have to always append the :0 on all field variables, the default for a field variable with no appended :# is 0.
Thus you would only need to be concerned with appending the :# for field variables that require a number greater than
0.
823
Auxiliary Script/Data Files
Chapter 14 : Auxiliary Script/Data Files
Auxiliary Script and Data files are used to automatically change data and control the Simulator in a batch mode
fashion.
This chapter covers the following:
· Overview of Auxiliary Files
· Script Command Execution Dialog
· Quick Auxiliary Files Dialog
· Script Section
· Data Section
825
Auxiliary Files
PowerWorld has incorporated the ability to import data from data sources other than power flow models into
PowerWorld Simulator. Simulator has always had the ability to import supplemental data into a power flow model, but
this facility was limited to ten or twelve native data formats targeted to specific applications for which the data had to
have a precise format. The extensions described in this help document provide a more versatile interface to data from
non-power-flow sources.
In addition to developing auxiliary data formats, a script language was also developed. The script language and
auxiliary data formats are incorporated together. This format is described in this help document.
Script/Data files are called auxiliary files in Simulator. An auxiliary file may be comprised of one or more DATA or
SCRIPT sections. A DA TA section provides specific data for a specific type of object. A SCRIPT section provides a
list of script actions for Simulator to perform.
These sections have the following format:
SCRIPT ScriptName1
{
script_statement_1
script_statement_n
}
DATA DataName1(object_type, [list_of_fields], file_type_specifier)
{
data_list_1
data_list_n
}
DATA DataName2(object_type, [list_of_fields], file_type_specifier)
{
data_list_1
data_list_n
}
SCRIPT ScriptName2
{
script_statement_1
script_statement_n
}
Note that the keywords SCRIPT or DATA must occur at the start of a text file line. Auxiliary files may contain more
than one DATA or SCRIPT section. These sections always begin with the keyword DATA or SCRIPT. DATA sections
are followed by an argument list enclosed in ( ). The actual data or script commands are then contained within curly
braces { }.
826
Auxiliary Script/Data Files
Script Command Execution Dialog
The Script Command Execution dialog provides a location for the user to enter script commands manually, or to load
auxiliary files containing Script and/or Data sections previously defined.
Loading Auxiliary Files
The first feature of the Script Command Execution dialog is that it provides a location to load previously defined
auxiliary files for the currently loaded case. The Auxiliary File menu provides a location for loading an auxiliary file,
or simply validating that the Script and/or Data sections of an Auxiliary file are correctly formatted in the file.
The Quick Aux option allows you to open the Quick Auxiliary Files dialog for creating a list of auxiliary files to be
opened and processed en masse.
Lastly, you can export the Simulator recognized objects and object fields using the Export Field Names option.
You can export the field names to a text for or to Excel.
Running Script Commands
The second feature of the Script Command Execution dialog is that you can run script commands manually. To run
a script command, type the command into the display, and press the Execute button. Note that if the Execute on
ENTER key option is checked, the command will also be processed when ENTER is pressed. Note that similar to
script command syntax in the Script section of auxiliary files, script commands must be ended w ith a semi-colon (;)
in the Script Command Execution dialog as well.
You can enter multiple script commands to be processed in sequence in this display. To do so, you must uncheck
the option Execute on ENTER key. Then you can press enter after each script command to move to the next line
and enter another command. Use the Execute button to process the sequence of script commands.
If you are running a sequence of script commands and wish to abort the run, use the Abort button.
If you wish to view the message log while script commands are processing, open the log using the Show Log
button.
827
Quick Auxiliary Files Dialog
The Quick Auxiliary Files dialog can be accessed from the Quick Aux Files menu option of the Script Command
Execution dialog. This dialog gives you a location for creating a list of auxiliary files to be processed en masse for the
currently loaded case.
Using the Define option of the Quick Aux Files menu, the Quick Auxiliary Files dialog will open. Use this dialog to
Add previously defined auxiliary files to the list of files to be processed. You can rearrange the order of the files by
selecting a file and using the up and down arrows on the right to move the selected file within the list, or you can sort
them alphabetically using the Sort button. To remove an auxiliary file from the list, use the Delete button.
Once the list of auxiliary files to process is complete, press the Execute button to process the list of auxiliary files.
828
Auxiliary Script/Data Files
Script Section
The SCRIPT section begins with a left curly brace and ends with a right curly brace.
SCRIPT ScriptName
{
script_statement_1
script_statement_2
script_statement_n
}
Scripts may optionally contain a ScriptName. This enables you to call a particular SCRIPT by using the LoadScript
action. After the optional name, the SCRIPT section begins with a left curly brace and ends with a right curly brace.
Inside of this, script statements can be given.
In general, a script statement has the following format:
Keyword(arg1, arg2, ...);
· Statement starts with a keyword.
· The keyword is followed by an argument list which is encompassed in parentheses ( ).
· The arguments are separated by commas.
· If a single argument is a list of things, this list is encompassed by braces [ ]. (eg. SetData)
· Statements end with a semicolon.
· Statements may take up several lines of the text file.
· You may put more than one statement on a single text line.
Some features in Simulator are available exclusively in either RUN mode or EDIT mode. This functionality is
preserved in the script language, but with the addition of a submode feature. Submodes limit what script commands
can be called. Only those commands available to the current submode can be executed. You will always be in one of
the submodes when executing a script. If the Script Command Execution Dialog is opened from Edit Mode, Simulator
defaults to the EDIT, CASE submode. If the Script Command Execution Dialog is opened from Run Mode (or when a
script is initially started), Simulator defaults to the RUN, POWERFLOW submode.
To switch submodes, use the EnterMode (mode or submode) script command. Available submodes include:
Edit Mode
· Case Submode
Run Mode
· PowerFlow Submode
· Contingency Submode
· ATC Submode
· Fault Submode
· PV Submode
· QV Submode
829
Script General Actions
The following actions are available to you regardless of the Mode or SubMode:
RenameFile
("oldfilename",
"newfilename");
CopyFile
("oldfilename",
"newfilename");
DeleteFile
("filename");
LoadAux
("filename",
CreateIfNotFound);
LoadScript
("filename",
ScriptName);
LoadData
("filename",
DataName,
CreateIfNotFound);
SelectAll
(objecttype,
filter);
UnSelectAll
(objecttype,
filter);
Delete
(objecttype,
filter);
SaveData
("filename",
filetype,
objecttype,
[fieldlist],
[subdatalist],
filter);
SetData
(objecttype,
[fieldlist],
[valuelist],
filter);
CreateData
(objecttype,
[fieldlist],
[valuelist]);
ChangeData
(objecttype,
[fieldlist],
[valuelist],
filter);
(NOT AVAILABLE YET)
NewCase;
OpenCase
("filename");
// assumes to open as PWB
OpenCase
("filename",
openfiletype);
PWB
GE
PTI
IEEECF
SaveCase
("filename");
// assumes to save as PWB
SaveCase
("filename",
savefiletype);
PWB, PWB5, PWB6, PWB7
PTI23, PTI24, PTI25, PTI26, PTI27,
GE
IEEECF
EnterMode
(mode or
submode);
EDIT
CASE
RUN
POWERFLOW
CONTINGENCY
ATC
FAULT
PV
QV
LogClear;
LogSave
("filename",
AppendFile);
YES or NO
LogAdd
("string");
LogAddDateTime
("string",
IncludeDate,
IncludeTime,
IncludeMilliseconds);
830
Auxiliary Script/Data Files
YES or NO
YES or NO
YES or NO
SaveYbusInMatlabFormat
("filename",
IncludeVoltages);
YES or NO
SaveJacobian
("Jacfilename",
"JIDfilename",
filetype,
JacForm);
M
R
TXT
P
SetParticipationFactors
(Method,
ConstantValue,
ForGensWithin);
MAXMW RAT
[Area num]
RESERVE
[Zone num]
CONSTANT value
SYSTEM
DISPLAYFILTERS
GenForceLDC_RCC
(filter);
DirectionsAutoInsert
(Source,
Sink,
DeleteExisting,
UseDisplayFilters,
Start,
Increment);
AREA
AREA
YES or NO
YES or NO
value
value
ZONE
ZONE
INJECTIONGROUP INJECTIONGROUP
SLACK
CaseDescriptionClear;
Case DescriptionSet
(Text,
Append);
RenameFile("oldfilename", "newfilename");
Use this action to rename a file from within a script.
"oldfilename" :
The present file name.
"newfilename" :
The new file name desired.
CopyFile("oldfilename", "newfilename");
Use this action to copy a file from within a script.
"oldfilename" :
The present file name.
"newfilename" :
The new file name desired.
DeleteFile("filename");
Use this action to delete a file from within a script.
"filename" :
The file name to delete.
LoadAux("filename", CreateIfNotFound);
Use this action to load another auxiliary file from within a script.
"filename" :
The filename of the auxiliary file being loaded.
CreateIfNotFound :
Set to YES or NO. YES means that objects that cannot be found will be
created while reading in DATA sections from filename. If this parameter is
not specified, then NO is assumed.
LoadScript("filename", ScriptName);
Use this action to load a named Script Section from another auxiliary file. This will open the auxiliary file denoted by
"filename", but will only execute the script section specified.
"filename" :
The filename of the auxiliary file being loaded.
ScriptName :
The specific ScriptName from the auxiliary file which should be loaded.
LoadData("filename", DataName, CreateIfNotFound);
831
Use this action to load a named Script Section from another auxiliary file. This will open the auxiliary file denoted by
"filename", but will only execute the script section specified.
"filename" :
The filename of the auxiliary file being loaded.
DataName :
The specific ScriptName from the auxiliary file which should be loaded.
CreateIfNotFound :
Set to YES or NO. YES means that objects which can not be found will
be created while reading in DATA sections from filename. If this
parameter is not specified, then NO is assumed.
SelectAll(objecttype, filter);
Use this to set the selected property of objects of a particular type to true. A filter may optionally be specified to
only set this property for objects which meet a filter.
objecttype :
The objecttype being selected.
filter :
There are three options for the filter:
SelectAll(objecttype); :
No filter specified means to select all objects of this type.
SelectAll(objecttype, "filtername"); : "filtername" means select those that meet the filter.
SelectAll(objecttype, AREAZONE); : AREAZONE means select those that meet the area/zone filters.
UnSelectAll(objecttype, filter);
Same as SelectAll, but this action sets the selected properties to false.
Delete(objecttype, filter);
Use this delete objects of a particular type. A filter may optionally be specified to only delete object which meet a
filter.
objecttype :
The objecttype being selected.
filter :
There are four options for the filter:
Delete(objecttype); :
No filter specified means to delete all objects of this type.
Delete(objecttype, "filtername"); : "filtername" means delete those that meet the filter.
Delete(objecttype, AREAZONE); : AREAZONE means delete those that meet the area/zone filters.
Delete(objecttype, SELECTED); : SELECTED means delete those objects whose selected field is set to
YES.
SaveData("filename", filetype, objecttype, [fieldlist], [subdatalist], filter);
Use this action to save data in a custom defined format. A filter may optionally be specified to save only object
which meet a filter.
"filename" :
The file to save the data to
filetype :
AUX (or AUXCSV): save as a space-delimited (or comma-delimited)
auxiliary data file.
objecttype :
The objecttype being saved.
[fieldlist] :
A list of fields that you want to save.
[subdatalist] :
A list of the subdata objecttypes to save with the
filter :
There are four options for the filter:
SaveData(…); :
No filter specified means to save all objects of this type.
SaveData(…, "filtername"); :
"filtername" means save those that meet the filter.
SaveData(…, AREAZONE); :
AREAZONE means save those that meet the area/zone filters.
SaveData(…, SELECTED); :
SELECTED means save those objects whose selected field is set to YES.
SetData(objecttype, [fieldlist], [valuelist], filter);
Use this action to set fields for particular objects. If a filter is specified, then it will set the respective fields for all
objects which meet this filter. Otherwise, if no filter is specified, then the keyfields must be included in the field list
so that the object can be found.
objecttype :
The objecttype being set.
[fieldlist] :
A list of fields that you want to save.
832
Auxiliary Script/Data Files
[valuelist] :
A list of values to set the respective fields to.
filter :
There are four options for the filter:
SetData(…); :
No filter specified: set data only for the object described by the [fieldlist]
and [valuelist] parameters.
SetData(…, "filtername"); :
"filtername": set data for all objects that meet the filter.
SetData(…, AREAZONE); :
AREAZONE: set data for all objects that meet the area/zone filters.
SetData(…, SELECTED); :
SELECTED: set data for all objects whose selected field is set to YES.
CreateData(objecttype, [fieldlist], [valuelist]);
Use this action to create particular objects. Note that the key fields for the objecttype must be specified.
objecttype :
The objecttype being set.
[fieldlist] :
A list of fields that you want to save.
[valuelist] :
A list of values to set the respective fields to.
NewCase;
This action clear out the existing case and open a new case from scratch.
OpenCase("filename", OpenFileType);
This action will open a case stored in "filename" of the type OpenFileType;
"filename" :
The file to be opened.
OpenFileType :
An optional parameter saying the format of the file begin opened is. If
none is specified, then PWB will be assumed. It may be one of the
following strings:
PWB, PTI, GE, IEEECF.
SaveCase("filename", SaveFileType);
This action will save the case to "filename" in the format SaveFileType.
"filename" :
The file name to save the information to.
SaveFileType :
An optional parameter saying the format of the file to be saved. If none is
specified, then PWB will be assumed. It may be one of the following
strings:
PWB, PWB5, PWB6, PWB7
PTI23, PTI24, PTI25, PTI26, PTI27
GE
IEEECF
EnterMode(mode or submode);
This action will tell Simulator what mode or submode to enter before performing the next script command.
SubMode :
The submode to enter. A parameter stating what submode to put the
program in. Options available are CASE, POWERFLOW,
CONTINGENCY, ATC, FAULT, PV, QV. One may also put in RUN or
EDIT which will place the program in the POWERFLOW or CASE
respectively.
LogClear;
Use this action to clear the Message Log.
LogSave("filename", AppendFile);
This action saves the contents of the Message Log to "filename".
"filename" :
The file name to save the information to.
AppendFile :
Set to YES or NO. YES means that the contents of the log w ill be
appended to "filename". NO means that "filename" will be overwritten.
833
LogAdd("string…");
Use this action to add a personal message to the MessageLog.
"string…" :
The string that will appear as a message in the log.
LogAddDateTime("string…", IncludeDate, IncludeTime, IncludeMilliseconds);
Use this action to add a personal message to the MessageLog, including the posting date/time.
"string…" :
The string that will appear as a message in the log.
IncludeDate :
Set to YES or NO. YES means that the date will be added after the string
specified. If this parameter is not specified, then YES is assumed.
IncludeTime :
Set to YES or NO. YES means that the time will be added after the date. If
there’s no date, then it will be added after the string specified. If this
parameter is not specified, then YES is assumed.
IncludeMilliseconds :
Set to YES or NO. YES means that the time including milliseconds will be
added after the date or string specified. This is valid only if the
IncludeTime is set to YES. If this parameter is not specified, then YES is
assumed.
SaveYbusInMatlabFormat("filename", IncludeVoltages);
Use this action to store the power system bus admittance matrix (Ybus) in a text format that can be easily read into
other programs such as MATLAB®.
"filename" :
The file name to save the information to. The Ybus data is stored using
the MATLAB sparse matrix format in the matrix Ybus.
IncludeVoltages :
Set to YES or NO. YES means that the bus voltages are also stored but in
the vector V.
SaveJacobian("filename", IncludeVoltages);
Use this action to store the power flow Jacobian in a text format that can be easily read into other programs such as
MATLAB®.
"Jacfilename" :
The file name to save the Jacobian data to. The Jacobian is stored using
the MATLAB sparse matrix format in the matrix Jac.
"JIDfilename" :
The file name to save the text identifier information to. This information is
used to translate the bus numbering convention used in the Jacobian and
Ybus files with the actual bus number and name in the case.
filetype :
A parameter saying the format of the file to be saved. It may be one of the
following strings:
M: MATLAB .M Format.
TXT: ASCII format.
JacForm :
Specifies the form of the Jacobian. It may be one of the following strings:
R: Rectangular form
P: Polar form.
SetParticipationFactors(Method, ConstantValue, ForGensWithin);
Use this action to define the participation factors for multiple generators.
Method :
The formula used to calculate the participation factors for each generator.
It may be one of the following strings:
MAXMWRAT: The participation factor for each generator is set to the generator’s maximum MW capability.
RESERVE: The participation factor for each generator is set to the generator’s reserve power, so that each
generator participates in proportion to how much it has left to contribute.
CONSTANT: The participation factor for each generator is set to the same specified value.
ConstantValue :
The value used if CONSTANT method is specified. If CONSTANT
method is not specif ied, enter 0 (zero).
ForGensWithin :
The set of generators to which the participation factors will be assigned. It
may be one of the following settings:
[Area num]: For all the generators in area num.
834
Auxiliary Script/Data Files
[Zone num]: For all the generators in zone num.
SYSTEM: For all the generators in the system regardless of their area or zone affiliation.
DISPLAYFILTERS: For just the generators whose display filter criteria evaluates to true.
GenForceLDC_RCC(filter);
Use this action to convert the voltage setpoint for Line Drop and Reactive Current Compensation (LDC/RCC) for
multiple generators.
filter :
There are four options for the filter:
GenForceLDC_RCC; :
No filter specified means to convert voltage setpoint for LDCC/RCC on
all the generators of the system.
GenForceLDC_RCC ("filtername"); : "filtername" means to convert voltage setpoint for LDCC/RCC on those
generators that meet the filter.
GenForceLDC_RCC (AREAZONE); : AREAZONE means to convert voltage setpoint for LDCC/RCC on those
generators that meet the area/zone filters.
GenForceLDC_RCC (SELECTED); : SELECTED means to convert voltage setpoint for LDCC/RCC on those
generators whose selected field is set to YES.
DirectionsAutoInsert(Source, Sink, DeleteExisting, UseDisplayFilters, Start, Increment);
Use this action to automatically insert multiple directions for PTDF studies.
Source, Sink :
The type of object used as the source/sink of the directions. Currently,
only the following types of directions can be automatically defined:
AREA SLACK :
Directions from areas to slack bus of the system.
ZONE SLACK :
Directions from zones to slack bus of the system.
INJECTIONGROUP SLACK :
Directions from injection groups to slack bus of the system.
AREA AREA :
Directions from areas to other areas of the system.
ZONE ZONE :
Directions from zones to other zones of the system.
INJECTIONGROUP INJECTIONGROUP : Directions from injection groups to other injection groups of the
system.
DeleteExisting :
Set to YES or NO. YES means that previously defined directions will be
deleted before the new directions are automatically inserted. NO means
automatically inserted directions will be added to the list of previously
defined directions. If this parameter is not specified, then YES is
assumed.
UseDisplayFilters :
Set to YES or NO. YES means that only Areas and Zones with their
Area/Zone filters set to YES will be used when automatically inserting
directions. NO specifies all Areas and Zones will be used to automatically
insert directions regardless of their Area/Zone filters. If this parameter is
not specified, then NO is assumed.
Start :
Integer value that specifies the first number used when automatically
numbering the automatically inserted directions. If this parameter is not
specified, then 1 is assumed.
Increment :
Integer value that will be used as increment in numbering the subsequent
automatically inserted directions. If this parameter is not specified, then 1
is assumed.
CaseDescriptionClear;
Use this action to clear the case description of the presently open case.
CaseDescriptionSet(Text, Append);
Use this action to set or append text to the case description
Text :
Specify the text to set/append to the case description
Append :
YES will append the text to the exisiting case description. NO will replace
the cas e description
835
Script Edit Mode Actions
The following script commands are available during the Case submode of Edit mode:
Equivalence;
DeleteExternalSystem;
SaveExternalSystem("filename", Savefiletype, withties);
Scale
(scaletype,
basedon,
[parameters],
ScaleMarker);
LOAD
MW
[P,Q]
BUS
GEN
FACTOR
[P] (means constant pf)
AREA
INJECTIONGROUP
ZONE
BUSSHUNT
[P, +Q, -Q]
Move
([elementA],
[destination parameter]);
[GEN numA idA]
[numB idB]
[LOAD numA idA]
[numB idB]
// NOT AVAILABLE YET
[BRANCH numA1 numA2 cktA]
[numB1 numB2 cktB]
// NOT AVAILABLE YET
Combine
([elementA],
[elementB]);
[GEN numA idA]
[GEN numB idB]
[LOAD numA idA]
[LOAD numB idB]
// NOT AVAILABLE YET
[BRANCH numA1 numA2 cktA]
[BRANCH numB1 numB2 cktB]
// NOT AVAILABLE YET
SplitBus
([element],
NewBusNumber,
InsertBusTieLine,
LineOpen);
[BUS num]
num
YES or NO
YES or NO
MergeBuses
(NewBusNumber,
filter);
num
TapTransmissionLine
([element],
PosAlongTheLine, NewBusNumber, ShuntModel,
TreatAsMSLine
[BRANCH numA1 numA2 cktA]; Value in %
num
LINESHUNTS
YES or NO
CAPACITANCE
InterfacesAutoInsert
(Type,
DeleteExisting,
UseDisplayFilters,
Prefix,
Limits);
AREA YES or NO
YES or NO
"string"
AUTO
ZONE
ZEROS
[value1, … value 8]
Equivalence
This action will equivalence a power system. All options regarding equivalencing are handled by the Equiv_Options
objecttype. Use the SetData() action, or a DATA section to set these options prior to using the Equivalence()
action. Also, remember that the property BusEquiv must be set true for each bus that you want to equivalence.
DeleteExternalSystem
This action will delete part of the power system. It will delete those buses whose property BusEquiv must is set
true.
SaveExternalSystem("filename", SaveFileType, WithTies)
This action will save part of the power system to a "filename". It will save only those buses whose property
BusEquiv must is set true.
"filename" :
The file name to save the information to.
SaveFileType :
An optional parameter saying the format of the file to be saved. If none is
specified, then PWB will be assumed. My be one of the following strings:
836
Auxiliary Script/Data Files
PWB, PWB5, PWB6, PWB7
PTI23, PTI24, PTI25, PTI26, PTI27
GE
IEEECF
WithTies :
An optional parameter. One must specify the file type explicitly in order to
use the WithTies parameter. Allows one to save transmission lines that tie
the a bus marked with BusEquiv as false and one marked true. This must
be a string which starts with the letter Y, otherwise NO will be assumed.
Scale(scaletype, basedon, [parameters], scalemarker);
Use this action to scale the load and generation in the system.
scaletype :
The objecttype begin scaled. Must be either LOAD, GEN,
INJECTIONGROUP, or BUSSHUNT.
basedon:
MW: parameters are given in MW, MVAR units.
FACTOR: parameters a factor to multiple the present values by.
[parameters]:
These parameters have different meanings depending on ScaleType.
LOAD: [MW, MVAR] or [MW]. If you want to scale load using constant power factor, then do not specifying a
MVAR value.
GEN: [MW].
INJECTIONGROUP: [MW, MVAR] or [MW] . If you want to scale load using constant power factor, then do not
specifying a MVAR value.
BUSSHUNT: [GMW, BCAPMVAR, BREAMVAR]. The first values scales G shunt values, the second value
scales positive (capacitive) B shunt values, and the third value scales
negative (reactive) B shunt values.
scalemarker:
This value specifies whether to look at an element’s bus, area, or zone to
determine whether it should be scaled.
BUS: Means that elements will be scaled according to the BusScale
property of the element’s terminal bus.
AREA: Means that elements will be scaled according to the BGScale
property of the element’s Area. Note that it is possible for the area of a
load, generator, or switched shunt to be different than the terminal bus’s
area.
ZONE: Means that elements will be scaled according to the BGScale
property of the element’s Zone. Note that it is possible for the zone of a
load, generator, or switched shunt to be different than the terminal bus’s
zone.
OWNER: Means that the elements will be scaled according to the
BGScale property of the element’s Owner.
Move([elementA], [destination parameters]);
NOTE: THIS ACTION IS ONLY AVAILABLE FOR GENERATORS.
Use this action to move a generator, load, or transmission line.
[elementA] :
the object that should be moved. Must be one of the following formats.
[GEN busnum id]
[LOAD busnum id]
[BRANCH busnum1 busnum2 ckt]
[destination parameters] :
These parameters have different meanings depending on object type of
the element.
GEN: [busnum id]
LOAD: [busnum id]
BRANCH: [busnum1 busnum2 id]
Combine([elementA], [elementB]);
NOTE: THIS ACTION IS ONLY AVAILABLE FOR GENERATORS.
Use this action to combine two generators, two loads, or two transmission line. Note that elementA and elementB
must be of the same object type. You can not combine a BRANCH and a LOAD.
837
[elementA] :
The object that should be moved. Must be one of the following formats.
[GEN busnum id]
[LOAD busnum id]
[BRANCH busnum1 busnum2 ckt]
[elementB] :
The object that element A should be combined with. Must the same
format as for elementA.
SplitBus([element], NewBusNumber, InsertBusTieLine, Line Open);
Use this action to transform one bus into two connected buses.
[element] :
The bus that should be split. Must be of the following format:
[BUS num]
NewBusNumber :
The number of the new bus resulting from the split. Must be unique, that
is, it cannot be a number that identifies another number in the case.
InsertBusTieLine
Set to YES or NO. YES means to insert a very low -impedance bus tie
between the bus to split and its offspring. The new branch will have an
impedance of 0.0000 + j0.0001 ohms. NO means that no bus tie will be
inserted. If this parameter is not specified, then YES is assumed.
LineOpen
Set to YES or NO. YES means that the bus tie should be inserted as an
open branch. NO means that the bus tie will be inserted as a closed
branch. This options is valid only if InsertBusTieLine is set to YES. If this
parameter is not specified, then NO is assumed.
MergeBuses([element], filter);
Use this action to merge a set of buses into a single bus.
[element] :
The number of the new bus resulting from the merging. It should be a
number of a bus that is part of the set of buses to be merged, or it should
be unique, meaning that it cannot be a number that identifies another
number in the case. Must be of the following format:
[BUS num]
filter :
There are four options for the filter:
MergeBuses(…); :
No filter specified means to merge all the buses of the system.
MergeBuses(…, "filtername"); : "filtername" means to merge those buses that meet the filter.
MergeBuses(…, AREAZONE); : AREAZONE means to merge those buses that meet the area/zone filters.
MergeBuses(…, SELECTED); : SELECTED means to merge those buses whose selected field is set to
YES.
TapTransmissionLine([element], PosAlongTheLine, NewBusNumber, ShuntModel, TreatAsMSLine);
Use this action to insert a bus at some location along an existing transmission line.
[element] :
The transmission line to tap. Must be of the following format:
[BRANCH busnum1 busnum2 ckt]
PosAlongTheLine :
The value that indicates the point where the new bus is to be inserted
relative to the location of the nearest of the two buses in terms of a
percentage of the total line length This value controls how the
impedances of the new lines are set, as the impedance of each section
will equal the section’s corresponding percentage length multiplies by the
impedance of the original line.
NewBusNumber :
The number of the new bus resulting from the tapping. Must be unique,
that is, it cannot be a number that identifies another number in the case.
ShuntModel :
The way the original charging capacitance of the line is reassigned. The
choices are:
LINESHUNTS: The original charging capacitance is reassigned as line shunts at the original terminal bus ends
of the two new line segments. The charging capacitance of the two new
branch elements will be set to 0.
CAPACITANCE: The original charging capacitance of the line is converted approximately using percentage
entered as PosAlongTheLine. In other words, the original capacitance will
be scaled and assigned to the new segments as charging capacitance.
838
Auxiliary Script/Data Files
The default ShuntModel is LINESHUNTS.
TreatAsMSLine :
Set to YES or NO. YES means to force the status of the two new line
sections to be controlled in unison. NO means that the two new lines will
be controlled independently of each other.
InterfacesAutoInsert(Type, DeleteExisting, UseDisplayFilters, Prefix, Limits);
Use this action to automatically insert a group of interfaces. The new of the new interfaces defaults to "Area1-
Area2" or "Zone1-Zone2" with an optional Prefix.
Type :
The type of interfaces to insert. Choices are:
AREA: Area-to-area interfaces join adjacent areas (those that share at least one tie line).
ZONE: Zone-to-zone interfaces join adjacent interfaces (those that share at least one tie line).
DeleteExisting :
Set to YES or NO. YES means that previously defined interfaces will be
deleted before the new interfaces are automatically inserted. NO means
automatically inserted interfaces will be added to the list of previously
defined interfaces. If this parameter is not specified, then YES is
assumed.
UseDisplayFilters :
Set to YES or NO. YES means that only Areas and Zones with their
Area/Zone filters set to YES will be used when automatically inserting
interfaces. NO specifies all Areas and Zones will be used to automatically
insert interfaces regardless of their Area/Zone filters. If this parameter is
not specified, then NO is assumed.
Prefix :
An optional prefix of up to three characters. Use this prefix to avoid
duplicating names, particularly when some of the areas or zones have the
same name. If this parameter is not specified, then "" is assumed.
Limits :
Specifies the way the interfaces rating are set. Choices are:
AUTO: The interface rating is calculated based on the ratings of the components included in the interface.
ZEROS: All the interface limits are set to zero.
[value1, …, value8]: The set of rating values to be used for the interfaces. The eight values must be specified,
separated by commas.
The default parameter is ZEROS.
839
Script Run Mode Actions
The following script commands are available during any of the submodes of Run Mode:
CalculatePTDF
([transactor seller],
[transactor buyer],
LinearMethod);
[AREA num]
[AREA num]
AC
[ZONE num]
[ZONE num]
DC
[SUPERAREA "name"]
[SUPERAREA name]
DCPS
[INJECTIONGROUP "name"]
[INJECTIONGROUP name]
[BUS num]
[BUS num]
[SLACK]
[SLACK]
CalculatePTDFMultipleDirections
(StoreValuesForBranches, StoreValuesForInterfaces,
LinearMethod);
YES or NO
YES or NO
AC
DC
DCPS
CalculateLODF
([BRANCH nearbusnum farbusnum ckt],
LinearMethod);
CalculateTLR
([flowelement],
direction,
[transactor],
LinearM
[INTERFACE "name"]
BUYER
same as above for PTDFs
SELLER
[BRANCH nearbusnum farbusnum ckt]
CalculateVoltSense
([BUS num]);
CalculateFlowSense
([flowelement],
FlowType);
[INTERFACE "name"]
MW
[BRANCH num1 num2 ckt]
MVAR
MVA
CalculateLossSense
(FunctionType);
NONE
ISLAND
AREA
AREASA
SELECTED
SetSensitivitiesAtOutOfServiceToClosest;
CalculatePTDF([transactor seller], [transactor buyer], LinearMethod);
Use this action to calculate the PTDF values between a seller and a buyer. You may optionally specif y the linear
calculation method. Note that the buyer and seller must not be same thing. If no Linear Method is specified,
Lossless DC 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.
840
|
|