esapp 0.1.1

ESA++ is an open-source power-grid toolkit.

An open-source Python toolkit for power system automation, providing a high-performance “syntax-sugar” fork of Easy SimAuto (ESA). This library streamlines interaction with PowerWorld’s Simulator Automation Server (SimAuto), transforming complex COM calls into intuitive, Pythonic operations.

Key Features

• Intuitive Indexing Syntax: Access and modify grid components using a unique indexing system (e.g., wb[Bus, "BusPUVolt"]) that feels like native Python.

• Comprehensive SimAuto Wrapper: Full coverage of PowerWorld’s API through the SAW class, organized into modular mixins for power flow, contingencies, transients, and more.

• High-Level Adapter Interface: A collection of simplified “one-liner” functions for common tasks like GIC calculation, fault analysis, and voltage violation detection.

• Native Pandas Integration: Every data retrieval operation returns a Pandas DataFrame or Series, enabling immediate analysis, filtering, and visualization.

• Advanced Analysis Apps: Built-in specialized modules for Network topology analysis, Geomagnetically Induced Currents (GIC), and Forced Oscillation detection.

Installation

The ESA++ package is available on PyPI

pip install esapp

Documentation

For a comprehensive tutorial, usage guides, and the full API reference, please visit our documentation website.

Usage Example

Here is a quick example of how ESA++ simplifies data access and power flow analysis.

from esapp import GridWorkBench
from esapp.grid import *

# Open Case
wb = GridWorkBench("path/to/case.pwb")

# Retrieve data
bus_data = wb[Bus, ["BusName", "BusPUVolt"]]

# Solve power flow
V = wb.pflow()

# Do some action, write to PW
violations = wb.find_violations(v_min=0.95)
wb[Gen, "GenMW"] = 100.0

# Save case
wb.save()

Why ESA++?

Traditional automation of PowerWorld Simulator often involves verbose COM calls and manual data parsing. ESA++ abstracts these complexities:

• Speed: Optimized data transfer between Python and SimAuto.

• Clarity: Code that reads like the engineering operations it performs.

• Ecosystem: Built on top of the proven ESA library, adding modern Python features and better integration with the SciPy stack.

More Examples

The docs/examples/ directory contains a gallery of demonstrations, including:

• Object Field Access: Reduce the time you spend searching for field names with ESA++ IDE typehints for objects and fields.

• Matrix Extraction: Retrieving Y-Bus, Jacobian, and GIC conductance matrices for external mathematical modeling.

Testing

ESA++ includes an extensive test suite covering both offline mocks and live PowerWorld connections. To run the tests, install the test dependencies and execute pytest:

pip install .[test]
pytest tests/test_saw.py

Citation

If you use this toolkit in your research or industrial projects, please cite the original ESA work and this fork:

@article{esa2020,
  title={Easy SimAuto (ESA): A Python Package for PowerWorld Simulator Automation},
  author={Mao, Zeyu and Thayer, Brandon and Liu, Yijing and Birchfield, Adam},
  year={2020}
}

Authors

Luke Lowery developed this module during his PhD studies at Texas A&M University. You can learn more on his research page or view his publications on Google Scholar.

ESA++ is maintained by Luke Lowery and Adam Birchfield at Texas A&M University. You can explore more of our research at the Birchfield Research Group.

License

Distributed under the Apache License 2.0.