esapp 0.1.0__py3-none-any.whl

docs/conf.py

@@ -0,0 +1,96 @@
+import os
+import sys
+import importlib.metadata
+
+# Ensure the project root is in the path
+sys.path.insert(0, os.path.abspath(".."))
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary", # Re-enabled to allow automatic class listing
+    "sphinx.ext.viewcode",
+    "sphinx.ext.todo",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.inheritance_diagram",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "sphinx_copybutton",
+    "nbsphinx",
+]
+
+autosummary_generate = True  
+
+autodoc_default_options = {
+    "member-order": "groupwise",
+}
+
+autodoc_preserve_defaults = True
+todo_include_todos = True
+autosectionlabel_prefix_document = True
+
+autoclass_content = "both"
+autodoc_typehints = "none"
+add_module_names = False
+
+intersphinx_mapping = {
+    "python": ("docs.python.org", None),
+    "numpy": ("numpy.org", None),
+    "scipy": ("docs.scipy.org", None),
+}
+
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_preprocess_types = True
+napoleon_type_aliases = {
+    "np": "numpy",
+    "np.ndarray": "~numpy.ndarray",
+    "pd": "pandas",
+    "pd.DataFrame": "~pandas.DataFrame",
+    "optional": "typing.Optional",
+    "union": "typing.Union",
+}
+
+exclude_patterns = [
+    "_build",
+    "**/*.cpg",
+    "**/*.dbf",
+    "**/*.prj",
+    "**/*.shp",
+    "**/*.shx",
+    "**/Shape.xml",
+    "**/Shape.shp.ea.iso.xml",
+    "**/PWRaw",
+]
+
+nbsphinx_execute = 'never'
+html_sourcelink_suffix = ''
+master_doc = "index"
+
+project = "ESA++"
+copyright = "2026, Luke Lowery"
+author = "Luke Lowery"
+
+try:
+    version = importlib.metadata.version("esapp")
+except importlib.metadata.PackageNotFoundError:
+    version = "unknown"
+release = version
+
+html_theme = "sphinx_rtd_theme"
+html_theme_options = {
+    "navigation_depth": 2,
+}
+
+autodoc_mock_imports = [
+    "win32com", 
+    "win32com.client", 
+    "pythoncom",
+    "geopandas",
+    "shapely",
+    "fiona",
+    "pyproj",
+]

esapp/__init__.py

@@ -0,0 +1,26 @@
+"""
+esapp: A Pythonic Interface for PowerWorld Simulator
+=====================================================
+
+The ``esapp`` package provides a high-level, object-oriented interface for
+interacting with PowerWorld Simulator's Automation Server (SimAuto). It aims
+to simplify common power systems analysis tasks by providing a more Pythonic
+and user-friendly API.
+
+The main entry point is the :class:`~.GridWorkBench` class.
+"""
+
+# Please keep the docstring above up to date with all the imports.
+from .saw import (
+    SAW,
+    PowerWorldError,
+    COMError,
+    CommandNotRespectedError,
+    Error,
+    SimAutoFeatureError,
+    PowerWorldPrerequisiteError,
+    PowerWorldAddonError,
+)
+
+# Main Grid Work Bench Class
+from .workbench import GridWorkBench

esapp/apps/__init__.py

@@ -0,0 +1,19 @@
+"""
+Specialized Applications (:mod:`esapp.apps`)
+============================================
+
+This package contains higher-level, specialized tools for advanced power
+systems analysis tasks built on top of the core ``esapp`` components.
+"""
+
+# Applications
+from .gic import GIC
+from .network import Network, BranchType
+from .modes import ForcedOscillation
+
+__all__ = [
+    "GIC",
+    "Network",
+    "BranchType",
+    "ForcedOscillation",
+]

esapp/apps/dynamics.py

@@ -0,0 +1,135 @@
+from numpy import nan, float32
+from pandas import DataFrame, concat
+
+# WorkBench Imports
+from ..grid import TSContingency
+from ..indexable import Indexable
+
+
+class Dynamics(Indexable):
+    """
+    Research-focused transient stability simulation application.
+    
+    This class provides specialized functions for dynamic simulation,
+    transient stability contingency solving, and result extraction.
+    These functions are intentionally untested as they are for highly
+    specific research and data analysis.
+    """
+
+    def fields(self, metric):
+        '''Get TS Formatted Fields for Requested Objects'''
+        objs = self[metric["Type"]] # TODO I don't need to retrieve from PW I have it local. Will Speed up
+        os = objs['ObjectID']
+        flist = [f"{str(os.loc[i])} | {metric['Dynamic']}" for i in range(len(os))]
+        return flist
+
+    # Set Run Time for list of contingencies
+    def setRuntime(self, sec):
+        ctgs = self[TSContingency]
+        ctgs["StartTime"] = 0
+        ctgs["EndTime"] = sec
+        self[TSContingency] = ctgs
+
+    # Create 'SimOnly' contingency if it does not exist
+    # TODO Add TSCtgElement that closes an already closed gen at t=0
+    def simonly(self):
+        try:
+            self.esa.change_and_confirm_params_multiple_element(
+                ObjectType="TSContingency",
+                command_df=DataFrame({"TSCTGName": ["SimOnly"]}),
+            )
+        except CommandNotRespectedError:
+            print("Failure to create 'SimOnly' Contingency")
+        else:
+            print("Contingency 'SimOnly' Initialized")
+
+    def solve(self, ctgs: list[str] = None):
+        # Unique List of Fields to Request From PW
+
+        # Prepare Memory
+        self.esa.clearram()
+
+        # Gen Obj Field list and Mark Fields for RAM storage
+        objFields = []
+        flatFields = []
+        for objects, fields in self.retrieve:
+            self.esa.saveinram(objects, fields)
+            for id in objects['ObjectID']:
+                objFields += [f"{id} | {f}" for f in fields]
+                flatFields += fields
+
+        # Sim Only (No Contingency)
+        if ctgs is None:
+            self.simonly()
+            ctgs = ["SimOnly"]
+        # Cast To List
+        if not isinstance(ctgs, list):
+            ctgs = [ctgs]
+
+        # Only Sims Requested
+        self.esa.skipallbut(ctgs)
+
+        # Set Runtime for Simulation
+        self.setRuntime(self.runtime)
+
+        # Execute Dynamic Simulation for Specified CTGs - High Compute Time
+        self.esa.TSSolveAll()
+
+        # Get Results
+        meta, df = (None, None)
+        for ctg in ctgs:
+            # Extract incoming Dataframe
+            metaSim, dfSim = self.esa.TSGetContingencyResults(ctg, objFields)
+            # Weird ESA bug where if items at end are open, they don't return data :(
+            # Happened Again, if last column is zero valued it removes the column. Awful
+
+            # Proposed Fix: Will Fill in any floating columns not present in data but in meta
+            fillIdx = metaSim.index[~metaSim.index.isin(dfSim.columns)]
+            dfSim[fillIdx] = 0.0
+
+            # Custom Fields, Add CTG, Append to Main
+            metaSim.drop(columns=["Label", "ColHeader"], inplace=True)
+            metaSim.rename(
+                columns={
+                    "ObjectType": "Object",
+                    "PrimaryKey": "ID-A",
+                    "SecondaryKey": "ID-B",
+                    'VariableName': "Metric"
+                },
+                inplace=True,
+            )
+            metaSim['Metric'] = flatFields
+            metaSim["Contingency"] = ctg
+            meta = concat(
+                [metaSim] if meta is None else [meta, metaSim],
+                axis=0,
+                ignore_index=True,
+            )
+
+            # Won't work if first result is bad
+            if len(dfSim.columns) < 2:
+                dfSim = DataFrame(nan, columns=metaSim.index, index=[0])
+                dfSim.index.name = "time"
+            else:
+                # Trim Data Size, Index by Time, Append to Main
+                dfSim = dfSim.astype(float32)
+                dfSim.set_index("time", inplace=True)
+
+            #if df is not None:
+                #print(df.join(dfSim,how='outer'))
+            #TODO only working for same types of ctgs
+            df = concat(
+                [dfSim] if df is None else [df, dfSim], axis=1, ignore_index=True
+            )
+
+        # Clean Up -------------------------------------------------------
+
+        # Hard Copy Before Wiping RAM
+        meta: DataFrame = meta.copy(deep=True)
+        df: DataFrame = df.copy(deep=True)
+
+        # Clear RAM in PW
+        self.esa.clearram()
+
+        # Return as meta/data tuple
+        return (meta, df)