v0.1.2 Release

.claude/settings.local.json

@@ -1,7 +1,14 @@
 {
   "permissions": {
     "allow": [
-      "Bash(pip install:*)"
+      "Bash(conda activate esapp*)",
+      "Bash(C:/Users/wyatt/.conda/envs/esapp/python.exe*)",
+      "Bash(C:/Users/wyatt/.conda/envs/esapp/Scripts/pytest*)",
+      "Bash(C:/Users/wyatt/.conda/envs/esapp/Scripts/flake8*)",
+      "Bash(C:/Users/wyatt/.conda/envs/esapp/Scripts/pip*)"
     ]
+  },
+  "env": {
+    "PATH": "C:\\Users\\wyatt\\.conda\\envs\\esapp;C:\\Users\\wyatt\\.conda\\envs\\esapp\\Scripts;${env:PATH}"
   }
 }

CLAUDE.md

@@ -0,0 +1,103 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+ESA++ (`esapp`) is a Python toolkit for power system automation, providing a high-performance interface to PowerWorld Simulator's Automation Server (SimAuto) via COM on Windows. It requires Windows with PowerWorld Simulator installed.
+
+## Environment Setup
+
+This project uses a **conda environment** named `esapp` located at `C:\Users\wyatt\.conda\envs\esapp` (Python 3.11). All commands (pytest, pip, flake8, etc.) should be run using this environment.
+
+```bash
+# Activate the environment
+conda activate esapp
+```
+
+## Common Commands
+
+```bash
+# Install for development
+pip install -e ".[test]"
+
+# Run all tests
+pytest
+
+# Run only unit tests (no PowerWorld needed)
+pytest -m unit
+
+# Run only integration tests (requires PowerWorld + case file)
+pytest -m integration
+
+# Run a single test file
+pytest tests/test_helpers_unit.py
+
+# Run a single test
+pytest tests/test_helpers_unit.py::TestClassName::test_name
+
+# Run with coverage
+pytest --cov=esapp --cov-report=term-missing --cov-report=html:htmlcov
+
+# Lint (CI uses flake8 for syntax errors and undefined names)
+flake8 . --select=E9,F63,F7,F82 --show-source
+
+# Regenerate auto-generated component definitions from PWRaw schema
+cd esapp/components && python generate_components.py
+
+# Build docs
+cd docs && sphinx-build -b html . _build
+```
+
+## Test Configuration
+
+Integration tests require a PowerWorld case file path, configured via:
+1. Environment variable `SAW_TEST_CASE`, or
+2. `tests/config_test.py` (user-created, not committed)
+
+Tests without PowerWorld access should use `-m unit`. The `--maxfail=5` default stops early on failures.
+
+## Architecture
+
+### Entry Point: `PowerWorld` ([workbench.py](esapp/workbench.py))
+The main user-facing class. Creates a SAW connection, provides high-level grid analysis methods, and hosts embedded application modules (`network`, `gic`).
+
+### SAW (SimAuto Wrapper): [esapp/saw/](esapp/saw/)
+`SAW` class in [saw.py](esapp/saw/saw.py) is composed via **mixin pattern** from ~18 focused modules:
+- **SAWBase** ([base.py](esapp/saw/base.py)) - Core COM interface, case management, generic data retrieval
+- **PowerflowMixin** - Power flow solvers (Newton-Raphson, Gauss-Seidel, DC, etc.)
+- **ContingencyMixin** - Contingency analysis
+- **MatrixMixin** - Y-bus, Jacobian, GIC conductance matrix extraction
+- **TransientMixin** - Transient stability simulation
+- **SensitivityMixin** - PTDF, LODF, shift factors
+- Other mixins: `GeneralMixin`, `ModifyMixin`, `TopologyMixin`, `GICMixin`, `OPFMixin`, `PVMixin`, `QVMixin`, `ATCMixin`, `FaultMixin`, `RegionsMixin`, `CaseActionsMixin`, `ScheduledActionsMixin`, `TimeStepMixin`, `WeatherMixin`
+
+### Indexable Interface ([indexable.py](esapp/indexable.py))
+Pythonic `__getitem__` access for grid data: `pw[Bus, ["BusNum", "BusName"]]` returns a DataFrame. Both `PowerWorld` and `SAW` implement this.
+
+### Component Definitions: [esapp/components/](esapp/components/)
+- **grid.py** (auto-generated, ~13MB) - `GObject` subclasses for all PowerWorld object types (Bus, Gen, Load, Branch, etc.)
+- **ts_fields.py** (auto-generated) - Transient stability field constants for IDE autocomplete
+- **gobject.py** - Base `GObject` class
+- **generate_components.py** - Regeneration script reading from `PWRaw` schema file
+- Do not manually edit `grid.py` or `ts_fields.py`; regenerate them instead.
+
+### Utility Modules: [esapp/utils/](esapp/utils/)
+Embedded analysis applications accessible from `PowerWorld`:
+- **GIC** ([gic.py](esapp/utils/gic.py)) - Geomagnetically Induced Currents analysis, G-matrix, E-field Jacobians
+- **Network** ([network.py](esapp/utils/network.py)) - Incidence matrices, Laplacians, bus mapping
+- **Dynamics** ([dynamics.py](esapp/utils/dynamics.py)) - Transient stability result monitoring
+- **Contingency** ([contingency.py](esapp/utils/contingency.py)) - Programmatic contingency definition
+- **B3D** ([b3d.py](esapp/utils/b3d.py)) - Binary 3D electric field file I/O
+
+### Helpers and Types
+- **_helpers.py** - Data conversion (Windows paths, COM variants, AUX files), TS result processing
+- **_enums.py** - Type-safe enumerations (`SolverMethod`, `LinearMethod`, `FileFormat`, `ObjectType`, filter keywords like `SELECTED`, `ALL`)
+- **_exceptions.py** - Exception hierarchy rooted at `PowerWorldError` with analysis-specific subtypes (`PowerFlowException`, `DivergenceException`, `GICException`, etc.)
+
+## Key Constraints
+
+- **Windows-only**: Depends on `pywin32` for COM interop with PowerWorld
+- **numpy < 2.0**: Pinned in dependencies
+- **Python >= 3.7**: Minimum supported version
+- CI runs on Python 3.9, 3.10, 3.11

README.rst

@@ -1,5 +1,5 @@
 ESA++
-====================================
+=====
 
 .. image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
    :target: https://opensource.org/licenses/Apache-2.0
@@ -13,94 +13,66 @@ ESA++
    :target: https://esapp.readthedocs.io/
    :alt: Documentation
 
-.. image:: https://img.shields.io/badge/coverage-90%25-brightgreen.svg
-   :alt: Coverage 90%
+.. image:: https://img.shields.io/badge/coverage-98%25-brightgreen.svg
+   :alt: Coverage 98%
 
-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.
+An open-source Python toolkit for power system automation, providing a
+high-performance wrapper for PowerWorld's Simulator Automation Server
+(SimAuto). Transforms 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.
+- **Intuitive Indexing** -- Access grid data with ``pw[Bus, "BusPUVolt"]`` syntax
+- **Full SimAuto Coverage** -- All PowerWorld API functions through modular mixins
+- **Pandas Integration** -- Every query returns a DataFrame
+- **Pythonic Settings** -- Solver and GIC options as descriptor attributes (``pw.max_iterations = 250``)
+- **Convenience Methods** -- Flows, overloads, PTDF/LODF, snapshot context manager, case summary
+- **Transient Stability** -- Fluent API with ``TS`` field intellisense
+- **Analysis Utilities** -- Built-in GIC, network topology, and contingency tools
 
 Installation
 ------------
 
-The ESA++ package is available on `PyPI <https://pypi.org/project/esapp/>`_
+Requires Windows with PowerWorld Simulator (SimAuto enabled) and Python 3.9+.
 
 .. code-block:: bash
 
     pip install esapp
 
-
-Documentation
--------------
-
-For a comprehensive tutorial, usage guides, and the full API reference, please visit our `documentation website <https://esapp.readthedocs.io/>`_.
-
-Usage Example
+Quick Example
 -------------
 
-Here is a quick example of how ESA++ simplifies data access and power flow analysis.
-
 .. code-block:: python
 
-    from esapp import GridWorkBench
-    from esapp.grid import *
+    from esapp import PowerWorld
+    from esapp.components import *
 
-    # Open Case
-    wb = GridWorkBench("path/to/case.pwb")
+    pw = PowerWorld("path/to/case.pwb")
 
-    # Retrieve data 
-    bus_data = wb[Bus, ["BusName", "BusPUVolt"]]
+    # Read data
+    bus_data = pw[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()
+    V = pw.pflow()
 
-Why ESA++?
-----------
+    # Inspect and modify
+    violations = pw.violations(v_min=0.95)
+    pw[Gen, "GenMW"] = 100.0
 
-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
+Documentation
 -------------
 
-The `docs/examples/ <https://github.com/lukelowry/ESApp/tree/main/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.
+Full tutorials, API reference, and examples at `esapp.readthedocs.io <https://esapp.readthedocs.io/>`_.
 
 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:
-
 .. code-block:: bash
 
     pip install .[test]
-    pytest tests/test_saw.py
+    pytest tests/
 
 Citation
 --------
 
-If you use this toolkit in your research or industrial projects, please cite the original ESA work and this fork:
-
 .. code-block:: bibtex
 
     @article{esa2020,
@@ -112,10 +84,10 @@ If you use this toolkit in your research or industrial projects, please cite the
 Authors
 -------
 
-Luke Lowery developed this module during his PhD studies at Texas A&M University. You can learn more on his `research page <https://lukelowry.github.io/>`_ or view his publications on `Google Scholar <https://scholar.google.com/citations?user=CTynuRMAAAAJ&hl=en>`_.
-
-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 <https://birchfield.engr.tamu.edu/>`_.
+Developed by **Luke Lowery** and **Adam Birchfield** at Texas A&M University
+(`Birchfield Research Group <https://birchfield.engr.tamu.edu/>`_).
 
 License
 -------
+
 Distributed under the `Apache License 2.0 <https://www.apache.org/licenses/LICENSE-2.0>`_.

VERSION

@@ -1 +1 @@
-0.1.1
+0.1.2