Bases: object
A SimAuto Wrapper in Python
Initialize SimAuto wrapper. The case will be opened, and object fields given in object_field_lookup will be retrieved.
FileName – Full file path to .pwb file to open. This will be passed to the SimAuto function OpenCase.
Change parameters for multiple objects of the same type, and confirm that the change was respected by PowerWorld.
ObjectType – The type of objects you are changing parameters for.
CommandNotRespectedError – if PowerWorld does not actually change the parameters.
PowerWorldError: if PowerWorld reports an error.
None
Helper to call ChangeParametersMultipleElement, but uses a DataFrame to determine parameters and values. This method is lighter weight but perhaps “riskier” than the “change_and_confirm_params_multiple_element” method, as no effort is made to ensure PowerWorld respected the given command.
ObjectType – The type of objects you are changing parameters for.
Helper to cast data to the correct types, clean up strings, and sort DataFrame by BusNum (if applicable/present).
obj – DataFrame or Series to clean up. It’s assumed that the object came more or less directly from placing results @@ -394,7 +394,7 @@ to. E.g. ‘gen’
ValueError – if the DataFrame (Series) columns (index) are not valid fields for the given object type.
Helper function to get all key fields for an object type.
ObjectType – The type of the object to get key fields for.
DataFrame with the following columns: ‘internal_field_name’, ‘field_data_type’, ‘description’, and ‘display_name’. The DataFrame will be indexed based on the key @@ -434,15 +434,15 @@
Convenience function to get a list of key fields for a given object type.
ObjectType – PowerWorld object type for which you would like a list of key fields. E.g. ‘gen’.
List of key fields for the given object type. E.g. [‘BusNum’, ‘GenID’]
Get the power flow results from SimAuto server.
ObjectType – Object type to get results for. Valid types are the keys in the POWER_FLOW_FIELDS class attribute (case @@ -463,11 +463,11 @@ the default attributes in the POWER_FLOW_FIELDS.
Pandas DataFrame with the corresponding results, or None if the given ObjectType is not present in the model.
ValueError – if given ObjectType is invalid.
Helper which looks up PowerWorld internal field names to determine if they’re numeric (True) or not (False).
ObjectType – Type of object for which we’re identifying numeric fields. E.g. “Branch” or “gen”
Numpy boolean array indicating which of the given fields are numeric. Going along with the example given for “fields”: np.array([True, True, False, False])
@@ -503,13 +503,13 @@Set a SimAuto property, e.g. CreateIfNotFound. The currently supported properties are listed in the SAW.SIMAUTO_PROPERTIES class constant.
property_name – Name of the property to set, e.g. UIVisible.
Helper to obtain the YBus matrix from PowerWorld (in Matlab sparse matrix format) and then convert to scipy csr_matrix by default. :param full: Convert the csr_matrix to the numpy array (full matrix). @@ -530,7 +530,7 @@
Helper function to get the branch admittance matrix, usually known as Yf and Yt. :returns: A Yf sparse matrix and a Yt sparse matrix
@@ -538,14 +538,14 @@Get shunt admittance Ysh. :return: A Ysh sparse matrix
Helper function to get the Jacobian matrix, by default return a scipy sparse matrix in the csr format :param full: Convert the csr_matrix to the numpy array (full matrix).
@@ -553,13 +553,13 @@Generate the graph network model (NetworkX) from the topology. Currently supports the bus-level topology and the inter-substation level topology. Parallel lines (if exist) are preserved in the model.
edge_attr – A valid field name(str) or iterable of field names that are used to retrieve values and add them to the @@ -578,7 +578,7 @@ ‘substation’ is supported.
A network graph
Obtain LODF matrix in numpy array or scipy sparse matrix. By default, it obtains the lodf matrix directly from PW. If size is larger than 1000, then precision will be applied to filter out small values and the result will be returned in scipy sparse matrix.
precision – number of decimal to keep.
method – The linear method to be used for the LODF calculation. Default is DC. @@ -606,7 +606,7 @@ table shown in the PW GUI. Default is False.
The LODF matrix and a boolean vector to indicate which lines would cause islanding.
Obtain the incidence matrix.
Incidence matrix
Calculate the injection shift factor matrix using the auxiliary script CalculateShiftFactorsMultipleElement.
method – The linear method to be used for the calculation. The options are AC, DC or DCPS.
A dense float matrix in the numpy array format.
Calculate the injection shift factor matrix directly using the incidence matrix and the susceptance matrix. This method should be much faster than the PW script command for large cases.
A dense float matrix in the numpy array format.
Calculate the power transfer distribution factor natively. This method should be much faster than the PW script command for large cases.
A dense float matrix in the numpy array format.
Calculate the line outage distribution factor natively. This method should be much faster than the PW script command for large cases.
A dense float matrix in the numpy array format.
A pure LODF-based fast N-1 contingency analysis implementation.
A boolean value to indicate whether the system is N-1 secure.
Quickly identify the N-2 islanding CTGs using LODF
returns: A tuple with the number of islanding CTGs and the islanding matrix
Change line resistance according to temperature. The default coefficients are from IEEE Std 738-2012. Note: The original case has to be set for 25 degree Celsius.
T – Target temperature. If it is a single int or float, then a uniform temperature will be assigned to all the lines; If it is a numpy array, then you need to pass a @@ -716,18 +716,18 @@
ESA implementation of fast N-1 and N-2 contingency analysis. The case is expected to have a valid power flow state. Run SolvePowerFlow first if you are not sure.
option – Choose between N-1 and N-2 mode
validate – Use PW internal CA to validate the result. Default is False.
A tuple of system security status (bool) and a matrix showing the result of contingency analysis (if exist)
Compute the metric RCF to quantify the robustness of power grids against cascading failures. The RCF metric takes the operational states, the branch’s capacities and the topological @@ -746,7 +746,7 @@ “An entropy-based metric to quantify the robustness of power grids against cascading failures.” Safety science 59 (2013): 126-134.
The RCF value.
This method is leveraging applied ecological network analysis to quantify the varity of robustness of the power system.
Reference: @@ -764,7 +764,7 @@ [2] Panyam, V., Huang, H., Davis, K., & Layton, A. (2019). An ecosystem perspective for the design of sustainable power systems. Procedia Cirp, 80, 269-274.
target – the real, reactive, and apparent power over the system. The default value is MW, which is the real power. Users can change to MVR, which is the reactive power; or @@ -774,7 +774,7 @@ generator.
it is a list of ecological metrics, including the Ecological Robustness (Reco), the Ascendancy (ASC), the Development Capacity (DC), the Cycled Throughflow (tstc), the Finn Cycling Index (CI) and the Total System Overhead (TSO)
@@ -784,10 +784,10 @@A modified fast N-1 method.
c1_isl – Array of islanding lines
count – Number of lines
lim – Array of line limits
A tuple of N-1 status (bool) and the N-1 result (if exist)
Adjust line limits to eliminate N-1 contingencies.
margins – Array of line loading margins.
lines – Array of number of line overloading contingencies.
lim – Array of line limits.
Array of line limits after adjustment.
A modified fast N-2 method.
c1_isl – Array of islanding lines
count – Number of lines
lim – Array of line limits
A tuple of N-2 status (bool) and the N-2 result (if exist)
Bruteforce for fast N-2 method
count – number of branches
A0 – filtered contingencies
f – branch flow
Security status and detailed results
Auto insert contingencies.
object_type – Object type, e.g. branch.
options – Optional. Pass a custom dictionary if you need to modify the Ctg_AutoInsert_Options.
List of contingencies.
Solve all of the contingencies that are not marked to be skipped.
List of results.
Re-render the PowerWorld user interface (UI).
None
The ChangeParameters function has been replaced by the ChangeParametersSingleElement function. ChangeParameters can still be called as before, but will now just automatically @@ -921,7 +921,7 @@ ChangeParameters calls.
ObjectType – The type of object you are changing parameters for.
Set a list of parameters for a single object.
ObjectType – The type of object you are changing parameters for.
Set parameters for multiple objects of the same type.
ObjectType – The type of object you are changing parameters for.
Result from calling SimAuto, which should always simply be None.
PowerWorldError – if PowerWorld reports an error.
The ChangeParametersMultipleElementFlatInput function allows you to set parameters for multiple objects of the same type in a case loaded into the Simulator Automation Server. This @@ -1002,7 +1002,7 @@ as it’s simply easier to use.
ObjectType – The type of object you are changing parameters for.
Result from calling SimAuto, which should always simply be None.
The GetCaseHeader function is used to extract the case header information from the file specified. A tuple of strings containing the contents of the case header or description is returned.
filename – The name of the file you wish to extract the header information from.
A tuple of strings containing the contents of the case header or description.
Get all fields associated with a given ObjectType.
ObjectType – The type of object for which the fields are requested.
Pandas DataFrame with columns from either SAW.FIELD_LIST_COLUMNS or SAW.FIELD_LIST_COLUMNS_OLD, depending on the version of PowerWorld Simulator being used.
@@ -1080,11 +1080,11 @@Request values of specified fields for a particular object.
ObjectType – The type of object you’re retrieving parameters for.
Pandas Series indexed by the given ParamList. This Series will be cleaned by clean_df_or_series, so data will be of the appropriate type and strings are cleaned up.
PowerWorldError – if the object cannot be found.
ValueError – if any given element in ParamList is not @@ -1116,12 +1116,12 @@
Request values of specified fields for a set of objects in the load flow case.
ObjectType – Type of object to get parameters for.
ParamList – List of variables to obtain for the given @@ -1135,12 +1135,12 @@ load flow case.
Pandas DataFrame with columns matching the given ParamList. If the provided ObjectType is not present in the case, None will be returned.
PowerWorldError – if PowerWorld reports an error.
ValueError – if any parameters given in the ParamList @@ -1156,7 +1156,7 @@
This function operates the same as the GetParametersMultipleElement function, only with one notable difference. The values returned as the output of the function @@ -1169,7 +1169,7 @@ be directly returned. This will show you just how useful ESA really is!
ObjectType – Type of object to get parameters for.
ParamList – List of variables to obtain for the given @@ -1183,7 +1183,7 @@ load flow case.
[ NumberOfObjectsReturned, NumberOfFieldsPerObject, Ob1Fld1, Ob1Fld2, …, Ob(n)Fld(m-1), Ob(n)Fld(m)] @@ -1202,13 +1202,13 @@
This function is maintained in versions of Simulator later than version 9 for compatibility with Simulator version 9. This function will call the GetParametersSingleElement implicitly.
ObjectType – The type of object you’re retrieving parameters for.
Pandas Series indexed by the given ParamList. This Series will be cleaned by clean_df_or_series, so data will be of the appropriate type and strings are cleaned up.
PowerWorldError – if the object cannot be found.
ValueError – if any given element in ParamList is not @@ -1240,14 +1240,14 @@
The GetSpecificFieldList function is used to return identifying information about specific fields used by an object type. Note that in many cases simply using the GetFieldList method is simpler and gives more information.
ObjectType – The type of object for which fields are requested.
A Pandas DataFrame with columns given by the class constant SPECIFIC_FIELD_LIST_COLUMNS. There will be a row for each element in the FieldList input unless ‘ALL’ is @@ -1274,13 +1274,13 @@
The GetSpecificFieldMaxNum function is used to return the maximum number of a fields that use a particular variablename for a specific object type.
ObjectType – The type of object for which information is being requested.
An integer that specifies the maximum number of fields that use the same variablename for a particular object type. Fields are identified in the format variablename:location @@ -1308,12 +1308,12 @@
Request a list of objects and their key fields. This function is general, and you may be better off running more specific methods like “get_gens”
ObjType – The type of object for which you are acquiring the list of devices. E.g. “Shunt,” “Gen,” “Bus,” “Branch,” @@ -1325,7 +1325,7 @@ returning all objects in the case of type ObjectType.
None if there are no objects of the given type in the model. Otherwise, a DataFrame of key fields will be returned. There will be a row for each object of the given @@ -1337,7 +1337,7 @@
While this method is implemented, you are almost certainly better off using ListOfDevices instead. Since this method isn’t particularly useful, no type casting will be performed on the @@ -1356,7 +1356,7 @@ same manner. This solved some compatibility issues with some software languages.
ObjType – The type of object for which you are acquiring the list of devices.
Tuple of tuples as documented by PowerWorld for the ListOfDevices function.
While this method is implemented, you are almost certainly better off using ListOfDevices instead. Since this method isn’t particularly useful, no type casting, data type changing, or @@ -1395,7 +1395,7 @@ have other key fields as well.
ObjType – The type of object for which you are acquiring the list of devices.
List in the following format: [NumberOfObjectsReturned, NumberOfFieldsPerObject, Ob1Fld1, Ob1Fld2, …, Ob(n)Fld(m-1), Ob(n)Fld(m)]. @@ -1424,7 +1424,7 @@
LoadState is used to load the system state previously saved with the SaveState function. Note that LoadState will not properly function if the system topology has changed due to the @@ -1434,15 +1434,15 @@
Load PowerWorld case into the automation server.
FileName – Full path to the case file to be loaded. If None, this method will attempt to use the last FileName used to open a case.
TypeError – if FileName is None, and OpenCase has never been called before.
to opening a file using the File > Open Case menu option in @@ -1463,7 +1463,7 @@
FileName – Full path to the case file to be loaded. If None, this method will attempt to use the last FileName @@ -1483,13 +1483,13 @@
Load a PowerWorld Auxiliary file into SimAuto. 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.
FileName – Name of auxiliary file to load. Should be a full path.
Execute a list of script statements. The script actions are those included in the script sections of auxiliary files.
Execute a list of script statements. The script actions are +those included in the script sections of auxiliary files. +This function differs from RunScriptCommand in that it allows +informational messages to be returned from the script execution +when the execution is successful.
+Output is a boolean value indicating whether the script command +was succesful or not. If False is returned, the error message will +be returned as defined in Status message input parameter. If True, +the Status message will be empty.
+ + +Save the current case to file.
FileName – The name of the file you wish to save as, including file path. If None, the original path which was @@ -1544,7 +1560,7 @@
SaveState is used to save the current state of the power system. This can be useful if you are interested in comparing various cases, much as the “Difference Flows” feature works in @@ -1554,7 +1570,7 @@
Send data from SimAuto to an Excel spreadsheet. While ESA
provides this function, we strongly recommend you to use the
GetParametersMultipleElement function and save the DataFrame
@@ -1564,7 +1580,7 @@
manually save it.
ObjectType – A String describing the type of object for which you are requesting data.
None
WARNING: This function should only be used after the simulation is run (for example, use this after running script commands TSSolveAll or TSSolve).
@@ -1613,7 +1629,7 @@ been tested as extensively as we would prefer. If your case/code has issues with this method, please file an issue on GitHub.CtgName – The contingency to obtain results from. Only one contingency be obtained at a time.
A tuple containing two DataFrames, “meta” and “data.” Alternatively, if the given CtgName does not exist, a tuple of (None, None) will be returned. @@ -1661,7 +1677,7 @@
The WriteAuxFile function can be used to write data from the case in the Simulator Automation Server to a PowerWorld Auxiliary file. The name of an advanced filter which was @@ -1674,10 +1690,10 @@
Run the SolvePowerFlow command.
SolMethod – Solution method to be used for the Power Flow calculation. Case insensitive. Valid options are: ‘RECTNEWT’ - Rectangular Newton-Raphson @@ -1695,11 +1711,11 @@
Use this function to open a oneline diagram. This function can be used to associate onelines with a PWB file.
filename – The file name of the oneline diagram to open.
view – The view name that should be opened. Pass an empty @@ -1728,7 +1744,7 @@ of the Simulator/Retriever window height.
None
Use this action to close an open oneline diagram without saving it. If the name is omitted, the last focused oneline diagram will be closed.
OnelineName – The name of the oneline diagram to close.
None
set_simauto_property method.
Get the Program Information property of the Simulator Automation
+Server which returns information about the version of PowerWorld
+Simulator run by the current instance of SimAuto. This property
+returns a variant array of variant arrays. The order of each array
+within the main array is subject to change and additional arrays
+may be added in the future. The first entry of each array will
+indicate what type of information is in the array. The order of
+entries within each array will not change. Set this property through
+the set_simauto_property method.
Convert a dataframe to PW aux/axd data section.
fp – file handler
df – dataframe
Given a path, p, convert it to a Windows path.
Given a list, convert to a variant array.
list_in – Simple one-dimensional Python list, e.g. [1, ‘a’, 7]
Given a list of lists, convert to a variant array.
list_in – List of lists, e.g. [[1, ‘1’], [1, ‘2’], [2, ‘1’]]
Bases: Exception
Base class for exceptions in this module.
Bases: Error
Raised when PowerWorld reports an error following a SimAuto call.
The ESA team strives to write good tests with 100% coverage. The table below provides the latest test coverage data for ESA.
-Name |
Num. Statements |
@@ -335,9 +335,9 @@ esa/saw.py |
-1158 |
+1196 |
0 |
-1158 |
+1196 |
100 |
|---|