Welcome!

Welcome to Easy SimAuto’s (ESA) documentation! If you encounter issues with ESA or the documentation, please file an issue on GitHub.

Citation

If you use ESA in any of your work, please use the citation below.

@article{ESA,
  doi = {10.21105/joss.02289},
  url = {https://doi.org/10.21105/joss.02289},
  year = {2020},
  publisher = {The Open Journal},
  volume = {5},
  number = {50},
  pages = {2289},
  author = {Brandon L. Thayer and Zeyu Mao and Yijing Liu and Katherine Davis and Thomas J. Overbye},
  title = {Easy SimAuto (ESA): A Python Package that Simplifies Interacting with PowerWorld Simulator},
  journal = {Journal of Open Source Software}
}

What Is ESA?

ESA is a “Pip-installable” Python package that eases interaction with the PowerWorld Simulator Automation Server (SimAuto). PowerWorld Simulator is a powerful, commercial-grade electric grid simulation tool with a wide range of capabilities. Information on Simulator can be found here and information on SimAuto can be found here. Since ESA directly interfaces with SimAuto, ESA users will need a PowerWorld license and installation that also includes SimAuto.

ESA makes working with SimAuto, well, easy. Users don’t have to worry about input or output data type conversions, data mapping, determining whether SimAuto has reported an error, and more. Additionally, ESA uses the scientific computing packages you know and love, including Numpy and Pandas. In addition to wrapping 100% of the functions provided by SimAuto, ESA provides helper functions that further ease development. Below is a quick motivating example (also found in Increase Loading in Case) that shows how easy it is to use SimAuto.

This simple example uniformly increases the loading in a power system model by 50%.

If you want to follow along, you’ll first need to define your own CASE_PATH constant (the file path to a PowerWorld .pwb case file), like so (adapt the path for your system):

CASE_PATH = r"C:\Users\myuser\git\ESA\tests\cases\ieee_14\IEEE 14 bus_pws_version_21.pwb"

Then, import the SimAuto wrapper (SAW) class and initialize an instance:

>>> from esa import SAW
>>> saw = SAW(CASE_PATH)

Retrieve key fields for loads:

>>> kf = saw.get_key_field_list('load')
>>> kf
['BusNum', 'LoadID']

Pull load data including active and reactive power demand:

>>> load_frame = saw.GetParametersMultipleElement('load', kf + ['LoadSMW', 'LoadSMVR'])
>>> load_frame
    BusNum LoadID    LoadSMW   LoadSMVR
0        2      1  21.699999  12.700000
1        3      1  94.199997  19.000000
2        4      1  47.799999  -3.900000
3        5      1   7.600000   1.600000
4        6      1  11.200000   7.500000
5        9      1  29.499999  16.599999
6       10      1   9.000000   5.800000
7       11      1   3.500000   1.800000
8       12      1   6.100000   1.600000
9       13      1  13.500001   5.800000
10      14      1  14.900000   5.000000

To learn more about variables such as LoadSMW, see PowerWorld Variables.

Uniformly increase loading by 50% and solve the power flow:

>>> load_frame[['LoadSMW', 'LoadSMVR']] *= 1.5
>>> saw.change_parameters_multiple_element_df('load', load_frame)
>>> saw.SolvePowerFlow()

Let’s confirm that the loading did indeed increase:

>>> new_loads = saw.GetParametersMultipleElement('load', kf + ['LoadSMW', 'LoadSMVR'])
>>> new_loads
    BusNum LoadID     LoadSMW   LoadSMVR
0        2      1   32.549998  19.050001
1        3      1  141.299999  28.500000
2        4      1   71.699995  -5.850000
3        5      1   11.400000   2.400000
4        6      1   16.800001  11.250000
5        9      1   44.250000  24.900000
6       10      1   13.500001   8.700000
7       11      1    5.250000   2.700000
8       12      1    9.150000   2.400000
9       13      1   20.250002   8.700000
10      14      1   22.350000   7.500000

Clean up when done:

>>> saw.exit()

Easy, isn’t it?

About SimAuto

From PowerWorld’s SimAuto page:

"The Simulator Automation Server (SimAuto) allows you to take
advantage of the power of automation to extend the functionality of
PowerWorld Simulator to any external program that you write. Using
Simulator Automation Server you can launch and control PowerWorld
Simulator from within another application, enabling you to: access
the data of a Simulator case, perform defined Simulator functions
and other data manipulations, and send results back to your original
application, to a Simulator auxiliary file, or to a Microsoft® Excel
spreadsheet."

In essence, SimAuto is PowerWorld Simulator’s application programming interface (API). As such, SimAuto users can perform almost any task that can be done through Simulator’s graphic user interface (GUI), but via their own program. This opens up a wealth of opportunity to perform tasks such as:

  • Task automation

  • Sensitivity analysis

  • Co-simulation

  • Machine learning

  • And more!

For more SimAuto details, here are some PowerWorld links:

Since SimAuto strives to be accessible to “any external” program and uses Windows COM, it can be cumbersome, tedious, and difficult to use. That’s where ESA comes in!

SimAuto Functions

Here’s a listing of the currently (as of 2020-06-17, Simulator version 21) available SimAuto functions (documented here):

  • ChangeParameters

  • ChangeParametersSingleElement

  • ChangeParametersMultipleElement

  • CloseCase

  • GetFieldList

  • GetParametersSingleElement

  • GetParametersMultipleElement

  • GetParameters

  • GetSpecificFieldList

  • GetSpecificFieldMaxNum

  • ListOfDevices

  • LoadState

  • OpenCase

  • ProcessAuxFile

  • RunScriptCommand

  • SaveCase

  • SaveState

  • SendToExcel (not recommended for use with ESA as documented in esa.saw Module)

  • TSGetContingencyResults

  • WriteAuxFile

For ESA’s implementation/wrapping of these methods, see esa.saw Module.

SimAuto Properties

Here’s a listing of the currently (as of 2020-06-17, Simulator version 21) available SimAuto properties (documented here):

  • ExcelApp (like SendToExcel function, not recommended for use with ESA)

  • CreateIfNotFound

  • CurrentDir

  • ProcessID

  • RequestBuildDate

  • UIVisible (Simulator versions >= 20)

For ESA’s implementation/wrapping of these properties, see esa.saw Module.

Who Should Use ESA?

ESA is useful for a wide range of audiences, including:

  • Industry practitioners (e.g. power system planners, energy traders, etc.)

  • Power system researchers

  • Researchers from other domains who wish to perform co-simulation with power system models

  • University students and faculty

  • Power system enthusiasts

ESA users should be proficient in Python, and it’s recommended that users get familiar with Numpy and Pandas, as ESA makes significant use of these packages. ESA users do not need to have any knowledge whatsoever related to how the Windows COM API works, nor do users need to be familiar with PyWin32.

Ultimately, ESA is a tool for interacting with PowerWorld Simulator - thus, users should have some familiarity with Simulator. Users do not need to directly understand how to use SimAuto, as ESA abstracts those details away. Advanced users will have a solid understanding of PowerWorld variables and object types, and will make extensive use of the RunScriptCommand method to enable the execution of PowerWorld functions previously only accessible via “Auxiliary Files”.

Why Use ESA?

Simply put, ESA makes working with SimAuto a breeze! ESA has the following desirable properties:

  • Free, open-source, non-restrictive license

  • Fully documented, including a plethora of examples and common issues

  • Fully tested - rest assured that all functions work as intended

  • Abstracts away all interactions with Windows COM

  • Automatically parses errors from PowerWorld

  • Automatically transforms data into the correct types

  • Wraps all available SimAuto functions

  • Provides additional helper functions to further simplify interactions with SimAuto

  • Provides functions to interact with PowerWorld Simulator interface, without the hassle of creating and loading the display auxiliary files

  • Provides native (but much more performant) methods of contingency analysis and sensitivity analysis

  • Returns useful data types such as Pandas DataFrames, unlocking a whole new realm of analysis and control capabilities

  • Gets data from a power system model for other application, like graph analysis or signal processing

  • Co-simulation with other domains such as transportation, communication, or natural gas

  • Task automation, like dynamic model tuning and relay setting tuning

  • AI & ML friendly

  • Compatible with several modern Python versions

  • Lightweight and fast

Whether you’re an energy trader, transmission planner, or academic researcher, ESA will help simplify your simulation an analysis work flows.

Projects That Use ESA

ESA has already been utilized in several research projects past and present. If you use ESA in your work, please file an issue on GitHub and we’ll list your project here! Please cite ESA if you use it in your work: see Citation.

  • In gym-powerworld, ESA was used to create a standardized reinforcement learning environment for power system voltage control. This environment was then used to carry out deep reinforcement learning (DRL) experiments in which the algorithm attempts to learn how to best control grid voltages under a diverse set of grid conditions.

  • In this paper, ESA was leveraged to create and simulate different electric grid scenarios where load, renewable generation levels, generation capacities, scheduled outages, and unit commitment were all varied. The resulting scenarios were used in the Grid Optimization (GO) competition hosted by the U.S. Department of Energy (DOE).

  • Geomagnetic disturbances (GMDs) affect the magnetic and electric field of the earth, inducing dc voltage sources superimposed on transmission lines. In an accepted paper by Martinez et al. entitled “Undergraduate Research on Design Considerations for a GMD Mitigation Systems” (to be published in mid-late 2020), a planning-based GMD mitigation strategy was developed for large power systems. ESA is leveraged to programmatically place GIC blocking devices in test systems per the proposed algorithm, thus minimizing the effects of GMDs on the power grid.

  • ESA is used by an ongoing research project entitled “Real Time Monitoring Applications for the Power Grid under Geomagnetic Disturbances (GMD)”: Recently, a real-world GMD monitoring system consisting of six magnetometers was deployed in Texas. The resulting magnetic field measurements are coupled with ground conductivity models to calculate real-time electric fields. These can then be fed to a grid model of Texas using ESA to enable calculation of real-time geomagnetically induced currents (GICs) for monitoring and visualization.

  • ESA is used by an ongoing research project entitled “Contingency Analysis Based on Graph Theory Concepts and Line Outage Distribution Factors (LODF).” In this project, ESA is leveraged to extract the topology of the power system model and obtain the LODF matrix.

  • ESA can be used with Julia programming language now via EasySimauto.jl. Julia is a fast and amazing language, and it is currently widely used in the research and scientific computing area. EasySimauto.jl is by far the simplest way to interact with PowerWorld Simulator from Julia.

Disclaimer and Credits

Disclaimer

As noted in ESA’s license, no warranty is provided, and the authors cannot be held liable for any issues related to using ESA. If you encounter an issue, find a bug, or would like to provide feedback, please file a ticket on Github.

Credits and Thanks

ESA was developed at Texas A&M University by Zeyu Mao, Brandon Thayer, and Yijing Liu. Significant guidance and oversight was provided by Professor Thomas Overbye, who is a co-founder of PowerWorld Corporation, and Professor Katherine Davis, who is one of the original authors of SimAuto. Funding was provided by the Texas A&M Engineering Experiment Station’s Smart Grid Center, the U.S. Department of Energy (DOE) under award DE-OE0000895 and the Sandia National Laboratories’ directed R&D project #222444.

The authors of ESA would like to give a special thank you to our users. Additionally, we’ve received help from some of our colleagues along the way, including (but not limited to!) Wei Trinh, Diana Wallison and Xiangtian Zheng. Thank you!

We hope you enjoy using ESA as much as we’ve enjoyed creating it.

Changelog

Changes made with each ESA release are listed here. Please note that versions prior to 1.0.0 are not listed here, but are still available on PyPi.

Version 1.3.5

  • Fix bug in get_lodf_matrix that causes mismatched column names and column values

  • Add new parameter ignore_new_branch to get_lodf_matrix to ensure the returned matrix is square

  • Fix bug associated with filename format in DetermineBranchesThatCreateIslands

  • Fix bug associated with filename format in DetermineShortestPath

  • Fix bug in test of ListOfDevices associated with dataframe index data type

  • Fix bug in test of clean_df_or_series associated with dataframe index data type

Version 1.3.4

  • Add DetermineBranchesThatCreateIslands

  • Add DeterminePathDistance

  • Add DetermineShortestPath

  • Add RunScriptCommand2

  • Add ProgramInformation property

Version 1.3.3

  • Fix the get_shift_factor_matrix function when the system is large

Version 1.3.2

  • Fix the fast sensitivity analysis methods to match PW results

Version 1.3.1

  • Fix the get_lodf_matrix function when the system is large

Version 1.3.0

  • Improve the get_lodf_matrix function to support DCPS (DC with phase shifter) and MLCDF

  • Add a new example for the built-in contingency analysis

  • Fix typos and bugs

Version 1.2.9

  • Fix the scipy sparse linalg import issue

  • Add the function to quickly identify the N-2 islanding contingencies

  • Add the functions for robustness and ecological analysis

  • Preliminary support for Streamlit (getting close to thread-safe)

  • Add the support for Python 3.10

Version 1.2.8

  • Native support on sensitivity analysis (ISF, PTDF, LODF) for better performance

Version 1.2.7

  • Officially support PW23

  • Support obtaining LODF matrix from large case (>1000)

  • Fix the self-loop issue when generating inter-substation level graph model

Version 1.2.6

  • Add functions to obtain branch and shunt impedance

  • Add a helper function to convert dataframe into auxiliary(aux/axd) data section

Version 1.2.5

  • Add one example for fast contingency analysis (N-1 & N-2)

  • Supports changing system models based on temperature

Version 1.2.4

  • Supports latest PW22 (Nov and Dec build) and PW23

Version 1.2.3

  • Fix the AOT import error

Version 1.2.2

  • Fix the AOT version-dependent issue

  • Update the dependency version

Version 1.2.1

  • Greatly improve the fast contingency analysis by taking advantage of SIMD, JIT and AOT. Now it could finish a N-1 and N-2 contingency analysis of a synthetic 2000 bus grid in less than 15 seconds!

  • Adjust the release process to include AOT functions

Version 1.2.0

  • Optimize the process to use the same order as shown in simulator (note: if pw_order is used, all data in the dataframe will be string type)

  • Add a method to obtain the incidence matrix

  • Implement a modified fast N-1 and N-2 contingency analysis algorithm. The algorithm is originally developed by Prof. Kostya Turitsyn from MIT and the implementation has been slightly modified and adapted to work with ESA.

  • Add a few helper functions to facilitate contingency analysis powered by the simulator.

Version 1.1.0

  • Allow users to use the same order as shown in simulator for all the dataframes

  • Add a helper function to generate LODF matrix

Version 1.0.9

  • Update the pre-install process and the common issues

  • Update the helper function ‘get_ybus’ with a new argument to accept external ybus file

Version 1.0.8

  • Add new helper function ‘to_graph’. The new function could help generate NetworkX graph model from the case, in two different levels: bus-as-node and substation-as-node. Parallel lines are preserved, and directedgraph is supported (currently the direction is fixed to be the same as real power flow).

Version 1.0.7

  • Add new functions: get_ybus, get_jacobian

Version 1.0.6

  • Hopefully finally fixing locale-based issues. Fixes began in 1.0.4, and continued in 1.0.5.

  • Finalizing JOSS paper. Once published, the citation will be added to the top-level README and the documentation.

Version 1.0.5

  • It turns out version 1.0.4 did not fully/correctly handle automatic locale setting. This version should now properly handle different decimal delimiters automatically.

  • Bug fix: The additional_fields parameter to SAW’s get_power_flow_results was permanently adding the additional_fields to the corresponding list in the SAW object’s SAW.POWER_FLOW_FIELDS attribute.

Version 1.0.4

  • Added support for other locales by automatically detecting the system’s decimal delimiter. This should allow users in Europe and elsewhere to leverage ESA. Thanks to robinroche for pointing out the problem during our JOSS review in this comment.

Version 1.0.3

  • New SAW attribute, build_date

  • New SAW attribute, version

  • New SAW helper method, get_version_and_builddate

  • Add argument additional_fields for get_power_flow_results method which provides an easy and consistent way to add more fields to the power flow result

  • Updating so that ESA is compatible with Simulator version 17. Note that this does not imply ESA has been tested with versions 16, 18, 19, or 20. However, ESA should work with all these versions.

  • Added case files for Simulator versions 16-22(beta) and renamed the cases accordingly (suffixed with pws_version_<version goes here>.pwb.

  • Updated documentation to discuss different versions of Simulator.

Version 1.0.2

  • Add area number to the power flow result

  • Update the citation section

  • Fix a bug in the test file that will result in a failure if some default names are changed in PowerWorld

Version 1.0.1

  • Add new functions: update_ui, OpenOneline and CloseOneline

  • Add documents to meet the requirement of JOSS

  • Add one more example into the documentation

  • Update the coverage_to_rst.py so that it’s more clear that the errors that get printed during testing are as expected.

  • Update the release process

  • Fix minor typos

Version 1.0.0

ESA version 1.0.0 is the first ESA release in which 100% of SimAuto functions are wrapped, and testing coverage is at 100%.