powerio

   1"""Parse, transform, and emit power system data.
   2
   3``parse`` returns a module whose ``value`` is the typed power system object
   4and whose ``diagnostics`` record what the parser found::
   5
   6    import powerio as pio
   7
   8    module = pio.parse("case9.m")
   9    net = module.value
  10    print(net.n_buses, net.base_mva)         # 9 100.0
  11    matpower = pio.emit(module, "matpower")
  12    emitted = pio.emit(module, "psse", "case9.raw")
  13
  14    B = net.calc_bprime_matrix()             # scipy.sparse, MATPOWER Bp
  15    Y = net.calc_admittance_matrix()         # complex csr, G + jB
  16    G = net.to_networkx()                    # networkx.Graph keyed by bus id
  17
  18PyPSA CSV folders carry static network topology. NetCDF and HDF5 time series
  19are tracked in https://github.com/eigenergy/powerio/issues/107.
  20
  21A source that defines a calculation parses to that calculation's typed value.
  22Use ``isinstance(module.value, ...)`` to branch on the result type.
  23
  24``import powerio`` and the base parse and emit paths require no
  25third party Python package. Matrix methods require SciPy and NumPy. Graph
  26methods require NetworkX. Install them with ``powerio[matrix]``,
  27``powerio[graph]``, or ``powerio[all]``. Missing extras raise ``ImportError``.
  28"""
  29
  30from __future__ import annotations
  31
  32import importlib
  33import io as _io
  34import json as _json
  35import operator as _operator
  36import os as _os
  37from collections import namedtuple
  38from collections.abc import Mapping, Sequence
  39from dataclasses import dataclass
  40from typing import Any, Iterable, Optional, Union
  41
  42from . import _powerio
  43from ._guard import guard as _guard
  44from ._guard import guard_class as _guard_class
  45from ._powerio import (
  46    ActivePower,
  47    ApparentPower,
  48    CalculationUpdate,
  49    ComponentId,
  50    Diagnostic,
  51    NetworkUpdate,
  52    OperatingPointUpdate,
  53    PowerIODataError,
  54    PowerIOError,
  55    PowerIOParseError,
  56    ReactivePower,
  57    Residuals,
  58    ScucActiveReserveZone,
  59    ScucBranchSwitchingCost,
  60    ScucContingency,
  61    ScucDevice,
  62    ScucDeviceOutputs,
  63    ScucDevicePeriod,
  64    ScucEnergyCostBlock,
  65    ScucEnergyRequirement,
  66    ScucInitialCommitment,
  67    ScucInputs,
  68    ScucNetworkOutputs,
  69    ScucRampLimits,
  70    ScucReactiveCapability,
  71    ScucReactiveReserveZone,
  72    ScucReserveCosts,
  73    ScucReserveLimits,
  74    ScucShunt,
  75    ScucStartupCostAdjustment,
  76    ScucStartupLimit,
  77    ScucTransformerControl,
  78    ScucViolationCosts,
  79    SourceSpan,
  80    UpdateChange,
  81    UpdateReport,
  82    __version__,
  83)
  84
  85__all__ = [
  86    "AcOpfInstance",
  87    "AcOpfSolution",
  88    "AcPfInstance",
  89    "AcPfSolution",
  90    "AcScucInstance",
  91    "AcScucSolution",
  92    "ActivePower",
  93    "ApparentPower",
  94    "Artifact",
  95    "BalancedNetwork",
  96    "CalculationUpdate",
  97    "ComponentId",
  98    "ContingencySet",
  99    "DcOpfInstance",
 100    "DcOpfSolution",
 101    "DcPfInstance",
 102    "DcPfSolution",
 103    "Diagnostic",
 104    "DisplayData",
 105    "EmitResult",
 106    "FormatInfo",
 107    "GeoLayer",
 108    "LinDist3FlowOpfInstance",
 109    "LinDist3FlowOpfSolution",
 110    "LinDist3FlowPfInstance",
 111    "LinDist3FlowPfSolution",
 112    "McAcOpfInstance",
 113    "McAcOpfSolution",
 114    "McAcPfInstance",
 115    "McAcPfSolution",
 116    "MonitoredSet",
 117    "MulticonductorNetwork",
 118    "NetworkUpdate",
 119    "OperatingPoint",
 120    "OperatingPointUpdate",
 121    "PioModule",
 122    "PowerIODataError",
 123    "PowerIOError",
 124    "PowerIOParseError",
 125    "PwdDisplay",
 126    "PwdSubstation",
 127    "ReactivePower",
 128    "Residuals",
 129    "Scenario",
 130    "ScenarioSet",
 131    "ScucActiveReserveZone",
 132    "ScucBranchSwitchingCost",
 133    "ScucContingency",
 134    "ScucDevice",
 135    "ScucDeviceOutputs",
 136    "ScucDevicePeriod",
 137    "ScucEnergyCostBlock",
 138    "ScucEnergyRequirement",
 139    "ScucInitialCommitment",
 140    "ScucInputs",
 141    "ScucNetworkOutputs",
 142    "ScucRampLimits",
 143    "ScucReactiveCapability",
 144    "ScucReactiveReserveZone",
 145    "ScucReserveCosts",
 146    "ScucReserveLimits",
 147    "ScucShunt",
 148    "ScucStartupCostAdjustment",
 149    "ScucStartupLimit",
 150    "ScucTransformerControl",
 151    "ScucViolationCosts",
 152    "SocwrOpfSolution",
 153    "SourceSpan",
 154    "SubsystemSet",
 155    "TimePoint",
 156    "TimeSeries",
 157    "UpdateChange",
 158    "UpdateReport",
 159    "__version__",
 160    "apply_bus_load_active_power",
 161    "apply_updates",
 162    "deserialize",
 163    "diagnostic_record",
 164    "diagnostic_records",
 165    "dist",
 166    "emit",
 167    "features",
 168    "from_ppc",
 169    "parse",
 170    "parse_display",
 171    "parse_geo",
 172    "resolve_format",
 173    "serialize",
 174    "versions",
 175]
 176
 177@dataclass(frozen=True)
 178class Artifact:
 179    """One artifact produced by :func:`emit` or :func:`serialize`.
 180
 181    ``data`` is set for an in-memory result. ``path`` is set after committing
 182    to a filesystem destination.
 183    """
 184
 185    name: str
 186    data: Optional[bytes]
 187    path: Optional[str]
 188
 189    @property
 190    def text(self) -> str:
 191        """Decode an in-memory UTF-8 artifact."""
 192        if self.data is None:
 193            raise ValueError("this artifact was committed to a destination")
 194        return self.data.decode("utf-8")
 195
 196
 197@dataclass(frozen=True)
 198class EmitResult:
 199    """Artifact inventory and diagnostics from an emission or serialization."""
 200
 201    artifacts: tuple[Artifact, ...]
 202    layout: str
 203    fidelity: str
 204    diagnostics: tuple[Diagnostic, ...]
 205
 206    @property
 207    def text(self) -> Optional[str]:
 208        """The sole UTF-8 memory artifact, or ``None`` for other inventories."""
 209        if len(self.artifacts) != 1 or self.artifacts[0].data is None:
 210            return None
 211        return self.artifacts[0].text
 212
 213FormatInfo = namedtuple(
 214    "FormatInfo", ["token", "extension", "is_directory", "can_emit"]
 215)
 216FormatInfo.__doc__ = """Canonical metadata returned by :func:`resolve_format`.
 217
 218``extension`` is the conventional filename suffix without a leading dot; it
 219can be compound and is ``None`` when a directory format has no primary case
 220file. ``can_emit`` reports whether a fresh universal emitter exists for the
 221format. It is not a promise for every concrete module value or a feature probe. A
 222false value neither promises nor forbids a same format retained source echo.
 223"""
 224
 225DisplayData = namedtuple("DisplayData", ["kind", "data"])
 226DisplayData.__doc__ = """Output of :func:`parse_display`.
 227
 228``kind`` names the display format. For PowerWorld PWD data,
 229``kind == "powerworld"`` and
 230``data`` is a :class:`PwdDisplay`.
 231"""
 232
 233PwdDisplay = namedtuple(
 234    "PwdDisplay", ["canvas_width", "canvas_height", "stamp", "substations"]
 235)
 236PwdDisplay.__doc__ = """Decoded PowerWorld ``.pwd`` display metadata."""
 237
 238PwdSubstation = namedtuple("PwdSubstation", ["number", "name", "x", "y"])
 239PwdSubstation.__doc__ = """One decoded PowerWorld display substation."""
 240
 241def _require(module: str, extra: str):
 242    """Import ``module`` or raise a clear ImportError naming the extra to install."""
 243    try:
 244        return importlib.import_module(module)
 245    except ImportError as exc:
 246        # Only rewrite "module is absent". A present-but-broken install (e.g. a
 247        # failed C-extension load) raises ImportError from a sub-import; let its
 248        # own traceback through instead of misdirecting the user to reinstall.
 249        if getattr(exc, "name", None) not in (module, module.split(".")[0]):
 250            raise
 251        raise ImportError(
 252            f"powerio needs {module!r} for this call; install it with "
 253            f"`pip install 'powerio[{extra}]'`"
 254        ) from exc
 255
 256
 257def _to_csr(coo):
 258    """Assemble a ``(data, row, col, shape)`` COO tuple into a csr_matrix."""
 259    sparse = _require("scipy.sparse", "matrix")
 260    data, row, col, shape = coo
 261    return sparse.coo_matrix((data, (row, col)), shape=shape).tocsr()
 262
 263
 264def _dc_angles(n_buses: int, voltage_angles):
 265    np = _require("numpy", "matrix")
 266    angles = np.asarray(voltage_angles, dtype=float)
 267    if angles.ndim != 1 or angles.shape[0] != n_buses:
 268        raise ValueError(
 269            f"voltage_angles must be a one dimensional array of length {n_buses}"
 270        )
 271    return np, angles
 272
 273
 274def _wrap_display(raw) -> DisplayData:
 275    kind, payload = raw
 276    if kind == "powerworld":
 277        substations = [
 278            PwdSubstation(
 279                row["number"],
 280                row["name"],
 281                row["x"],
 282                row["y"],
 283            )
 284            for row in payload["substations"]
 285        ]
 286        payload = PwdDisplay(
 287            payload["canvas_width"],
 288            payload["canvas_height"],
 289            payload["stamp"],
 290            substations,
 291        )
 292    return DisplayData(kind, payload)
 293
 294
 295_BALANCED_DELEGATED_NAMES = frozenset(
 296    {
 297        "areas",
 298        "base_frequency",
 299        "base_mva",
 300        "branches",
 301        "buses",
 302        "detailed_connectivity",
 303        "generators",
 304        "hvdc",
 305        "is_radial",
 306        "loads",
 307        "n_areas",
 308        "n_branches",
 309        "n_buses",
 310        "n_generators",
 311        "n_hvdc",
 312        "n_islands",
 313        "n_loads",
 314        "n_shunts",
 315        "n_static_var_compensators",
 316        "n_storage",
 317        "n_switches",
 318        "n_transformers_3w",
 319        "name",
 320        "reference_bus_index",
 321        "reference_bus_indices",
 322        "shunts",
 323        "static_var_compensators",
 324        "source_format",
 325        "storage",
 326        "switches",
 327        "transformers_3w",
 328    }
 329)
 330
 331
 332@_guard_class
 333class BalancedNetwork:
 334    """A parsed balanced power network.
 335
 336    The data attributes (``buses``, ``branches``, ``generators``, ``loads``,
 337    ``shunts``) and reference bus queries delegate to the compiled handle; the
 338    matrix methods below return ``scipy.sparse`` objects. Parse and transform
 339    diagnostics belong to the owning :class:`PioModule`.
 340
 341    Errors: a bad file path raises the standard ``OSError`` subclass
 342    (``FileNotFoundError``); a malformed case raises :class:`PowerIOParseError`
 343    and an unmet calculation precondition (no generators, no reference bus) raises
 344    :class:`PowerIODataError`; both subclass :class:`PowerIOError`, so
 345    ``except PowerIOError`` catches either; an unknown
 346    ``scheme``/``formula``/``units`` string raises ``ValueError``.
 347    """
 348
 349    def __init__(self, inner: "_powerio._BalancedNetwork"):
 350        self._inner = inner
 351
 352    def __dir__(self):
 353        # The data attributes arrive through __getattr__, so name them here or
 354        # they stay invisible to tab completion.
 355        return sorted(set(super().__dir__()) | _BALANCED_DELEGATED_NAMES)
 356
 357    def __getattr__(self, name: str):
 358        # Reached only when normal lookup misses, so the matrix methods below
 359        # win. Guard underscore names so a lookup before _inner exists raises
 360        # AttributeError instead of recursing forever.
 361        if name not in _BALANCED_DELEGATED_NAMES:
 362            raise AttributeError(
 363                f"{type(self).__name__!r} object has no attribute {name!r}"
 364            )
 365        return getattr(self._inner, name)
 366
 367    def __repr__(self) -> str:
 368        # The inner handle's __repr__ already renders the public ``BalancedNetwork(...)``
 369        # form, so this is a straight delegate.
 370        return repr(self._inner)
 371
 372    def calc_connectivity_report(self) -> dict[str, Any]:
 373        """Calculate the in-service topology summary."""
 374        return self._inner.calc_connectivity_report()
 375
 376    def to_geo_layer(self) -> dict[str, Any]:
 377        """Transform coordinates to a canonical GeoJSON FeatureCollection.
 378
 379        A case without coordinates produces an empty feature collection.
 380        """
 381        return _json.loads(self._inner.to_geo_layer_json())
 382
 383    def apply_geo_layer(
 384        self, text: str, name_hint: Optional[str] = None
 385    ) -> tuple["BalancedNetwork", dict[str, Any]]:
 386        """Apply a geographic sidecar and return ``(placed, report)``.
 387
 388        ``text`` is any form :func:`parse_geo` accepts; this case is
 389        unchanged. The report carries ``matched_buses``, ``matched_branches``,
 390        ``unmatched_features``, ``unlocated_buses``, ``unlocated_branches``,
 391        and ``notes``. The two unlocated counts cover the whole case when the
 392        pass ends, so a layer that matched nothing reads apart from a case
 393        that needed nothing. The placed copy drops the retained source text,
 394        so a same-format emission re-serializes.
 395        """
 396        inner, report = self._inner.apply_geo_layer(text, name_hint)
 397        return BalancedNetwork(inner), report
 398
 399    def resolve_contingencies(self, text: str) -> dict[str, Any]:
 400        """Read PSS/E contingency text and bind every case to this network.
 401
 402        ``text`` is the content of a ``.con`` file, such as
 403        ``parse("cases.con").value.text``. The result carries ``cases``,
 404        ``resolved``, ``unresolved``, and ``unrecognized_statements`` as
 405        counts; ``case_results``, one entry per case in the file's order with
 406        its ``name``, whether it ``resolved``, the ``components`` it bound to,
 407        and the actions that bound to nothing as ``{"action", "reason"}``; and
 408        ``diagnostics``, the reader's notes on statements it kept as text.
 409
 410        Each component states the ``type`` naming the table, the ``row`` it
 411        occupies there, the element's own ``in_service`` flag, and the ``id``
 412        the network states for it. ``id`` is ``None`` when the network states
 413        no identity for that row; ``type`` and ``row`` name the element either
 414        way.
 415
 416        Binding reports rather than refuses, so a case naming an element this
 417        network does not hold is counted unresolved and listed.
 418        """
 419        return self._inner.resolve_contingencies(text)
 420
 421    def expand_contingencies(
 422        self, con_text: str, sub_text: str
 423    ) -> tuple[str, list[Diagnostic]]:
 424        """Turn automatic contingency specifications into explicit cases.
 425
 426        ``con_text`` and ``sub_text`` are the contents of a ``.con`` and a
 427        ``.sub`` file. A specification such as ``SINGLE BRANCH IN SUBSYSTEM
 428        'A1'`` states a rule, so expanding it needs both the network and the
 429        subsystem the ``.sub`` file names. Returns the expanded ``.con`` text,
 430        which states every outage explicitly, and the notes from the two
 431        readers followed by the expansion's own notes. Only elements this
 432        network states in service expand into cases.
 433        """
 434        return self._inner.expand_contingencies(con_text, sub_text)
 435
 436    def select_subsystem_buses(self, sub_text: str, name: str) -> list[int]:
 437        """The bus numbers one named subsystem of ``sub_text`` selects.
 438
 439        ``sub_text`` is the content of a ``.sub`` file. The numbers come back
 440        in ascending order. A name the file does not state raises
 441        ``ValueError``.
 442        """
 443        return self._inner.select_subsystem_buses(sub_text, name)
 444
 445    # --- matrix calculations (scipy.sparse) -----------------------------
 446
 447    def calc_bprime_matrix(
 448        self, scheme: str = "bx", *, skip_zero_impedance: bool = False
 449    ):
 450        """MATPOWER FDPF Bp matrix. ``scheme`` is ``"bx"`` or ``"xb"``.
 451
 452        ``skip_zero_impedance=False`` refuses a zero impedance branch
 453        (``r`` and ``x`` both zero); pass ``True`` to drop it instead.
 454        """
 455        return _to_csr(
 456            self._inner.bprime(scheme, skip_zero_impedance=skip_zero_impedance)
 457        )
 458
 459    def calc_incidence_matrix(
 460        self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False
 461    ):
 462        """Return PowerModels incidence ``A`` (branches by buses).
 463
 464        Rows are the in service, non self loop branches in table order
 465        (three winding transformer windings follow the branches); columns
 466        are every bus in table order. :meth:`calc_dc_index_map` names both
 467        axes. ``skip_zero_impedance=False`` refuses a zero impedance branch;
 468        ``True`` drops it from the branch axis.
 469        """
 470        return _to_csr(
 471            self._inner.calc_incidence_matrix(
 472                formula, skip_zero_impedance=skip_zero_impedance
 473            )
 474        )
 475
 476    def calc_branch_susceptances(
 477        self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False
 478    ):
 479        """Return per branch susceptances over the branch axis of
 480        :meth:`calc_dc_index_map`."""
 481        np = _require("numpy", "matrix")
 482        return np.asarray(
 483            self._inner.calc_branch_susceptances(
 484                formula, skip_zero_impedance=skip_zero_impedance
 485            ),
 486            dtype=float,
 487        )
 488
 489    def calc_branch_flow_matrix(
 490        self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False
 491    ):
 492        """Return ``Bf = diag(b) A`` as a CSR matrix (branches by buses)."""
 493        return _to_csr(
 494            self._inner.calc_branch_flow_matrix(
 495                formula, skip_zero_impedance=skip_zero_impedance
 496            )
 497        )
 498
 499    def calc_bus_susceptance_matrix(
 500        self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False
 501    ):
 502        """Return ``B = A.T diag(b) A`` as a CSR matrix (buses by buses)."""
 503        return _to_csr(
 504            self._inner.calc_bus_susceptance_matrix(
 505                formula, skip_zero_impedance=skip_zero_impedance
 506            )
 507        )
 508
 509    def calc_branch_phase_shift_injection(
 510        self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False
 511    ):
 512        """Return ``b * shift`` over the branch axis."""
 513        np = _require("numpy", "matrix")
 514        return np.asarray(
 515            self._inner.calc_branch_phase_shift_injection(
 516                formula, skip_zero_impedance=skip_zero_impedance
 517            ),
 518            dtype=float,
 519        )
 520
 521    def calc_bus_phase_shift_injection(
 522        self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False
 523    ):
 524        """Return ``A.T @ (b * shift)`` over the bus axis."""
 525        np = _require("numpy", "matrix")
 526        return np.asarray(
 527            self._inner.calc_bus_phase_shift_injection(
 528                formula, skip_zero_impedance=skip_zero_impedance
 529            ),
 530            dtype=float,
 531        )
 532
 533    def calc_branch_flow_dc(
 534        self,
 535        voltage_angles,
 536        formula: str = "series_susceptance",
 537        *,
 538        skip_zero_impedance: bool = False,
 539    ):
 540        """Compute ``-Bf @ va + b * shift`` over the branch axis."""
 541        np, angles = _dc_angles(self.n_buses, voltage_angles)
 542        return np.asarray(
 543            self._inner.calc_branch_flow_dc(
 544                angles.tolist(), formula, skip_zero_impedance=skip_zero_impedance
 545            ),
 546            dtype=float,
 547        )
 548
 549    def calc_bus_injection_dc(
 550        self,
 551        voltage_angles,
 552        formula: str = "series_susceptance",
 553        *,
 554        skip_zero_impedance: bool = False,
 555    ):
 556        """Compute ``-B @ va + p_shift`` over the bus axis."""
 557        np, angles = _dc_angles(self.n_buses, voltage_angles)
 558        return np.asarray(
 559            self._inner.calc_bus_injection_dc(
 560                angles.tolist(), formula, skip_zero_impedance=skip_zero_impedance
 561            ),
 562            dtype=float,
 563        )
 564
 565    def calc_dc_index_map(
 566        self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False
 567    ) -> dict[str, Any]:
 568        """Return the axes every DC calculation shares.
 569
 570        ``bus_ids`` maps a bus axis row to the source bus id (every bus, in
 571        table order). ``branch_rows`` maps a branch axis row to the position
 572        in the branch table (three winding transformer windings follow the
 573        branches) and ``branch_ids`` to the stable identity, the branch uid
 574        when the source states one and ``branches:<row>`` otherwise; out of
 575        service branches and self loops have no row. ``skipped_branch_rows``
 576        lists the zero impedance branches dropped under
 577        ``skip_zero_impedance=True`` and is empty otherwise. The same
 578        selection applies to :meth:`calc_ptdf` rows and :meth:`calc_lodf`.
 579        """
 580        return self._inner.calc_dc_index_map(
 581            formula, skip_zero_impedance=skip_zero_impedance
 582        )
 583
 584    def calc_bdoubleprime_matrix(
 585        self, scheme: str = "bx", *, skip_zero_impedance: bool = False
 586    ):
 587        """MATPOWER FDPF Bpp matrix. ``scheme`` is ``"bx"`` or ``"xb"``.
 588        ``skip_zero_impedance`` as in :meth:`calc_bprime_matrix`.
 589        """
 590        return _to_csr(
 591            self._inner.bdoubleprime(scheme, skip_zero_impedance=skip_zero_impedance)
 592        )
 593
 594    def calc_lacpf_matrix(
 595        self,
 596        *,
 597        include_taps: bool = True,
 598        include_shifts: bool = True,
 599        skip_zero_impedance: bool = False,
 600    ):
 601        """LACPF 2n×2n block ``[[G, -B], [-B, -G]]``. ``skip_zero_impedance``
 602        as in :meth:`calc_bprime_matrix`."""
 603        return _to_csr(
 604            self._inner.lacpf(
 605                include_taps=include_taps,
 606                include_shifts=include_shifts,
 607                skip_zero_impedance=skip_zero_impedance,
 608            )
 609        )
 610
 611    def calc_adjacency_matrix(self):
 612        """0/1 bus adjacency matrix."""
 613        return _to_csr(self._inner.adjacency())
 614
 615    def calc_admittance_matrix(
 616        self,
 617        *,
 618        include_taps: bool = True,
 619        include_shifts: bool = True,
 620        skip_zero_impedance: bool = False,
 621    ):
 622        """``Y_bus = G + jB`` as a complex csr_matrix. ``skip_zero_impedance``
 623        as in :meth:`calc_bprime_matrix`."""
 624        g, b = self._inner.ybus_parts(
 625            include_taps=include_taps,
 626            include_shifts=include_shifts,
 627            skip_zero_impedance=skip_zero_impedance,
 628        )
 629        g, b = _to_csr(g), _to_csr(b)
 630        return (g + 1j * b).tocsr()
 631
 632    def calc_ptdf(self, formula: str = "series_susceptance", solver: str = "auto"):
 633        """DC PTDF (m×n). ``formula`` is ``"series_susceptance"``,
 634        ``"tap_adjusted_reactance"``, or ``"reactance_only"``.
 635
 636        ``solver`` is ``"auto"``, ``"dense"``, or ``"sparse"``. ``"auto"``
 637        uses the dense factorization on small cases and the sparse Cholesky
 638        path on large ones, the same policy as the CLI.
 639        """
 640        return _to_csr(self._inner.ptdf(formula, solver))
 641
 642    def calc_lodf(self, formula: str = "series_susceptance", solver: str = "auto"):
 643        """DC LODF (m×m). ``formula`` and ``solver`` as in :meth:`calc_ptdf`."""
 644        return _to_csr(self._inner.lodf(formula, solver))
 645
 646    def calc_weighted_laplacian(
 647        self,
 648        formula: str = "series_susceptance",
 649    ):
 650        """Weighted Laplacian ``L = -B``. ``formula`` as in :meth:`calc_ptdf`."""
 651        return _to_csr(self._inner.weighted_laplacian(formula))
 652
 653    def to_normalized(
 654        self,
 655        *,
 656        clamp_angle_bounds: bool = False,
 657        angle_bound_pad: Optional[float] = None,
 658    ) -> "BalancedNetwork":
 659        """Return a normalized copy with per unit power and radian angles.
 660
 661        The result removes out of service elements, preserves source bus IDs,
 662        and normalizes bus types. It carries no retained source, so
 663        :func:`powerio.emit` produces a grid exchange representation from the
 664        derived module. Raises
 665        :class:`PowerIODataError` if the network cannot be
 666        normalized (no reference bus can be chosen, or a non-positive base MVA).
 667
 668        ``clamp_angle_bounds=True`` applies the PowerModels angle difference
 669        bound repair: limits at or beyond ``+/-pi/2`` and zero/zero windows
 670        become ``[-angle_bound_pad, angle_bound_pad]``. A repair that would
 671        invert the interval widens to that same window. The default pad is
 672        1.0472 radians.
 673        """
 674        if not clamp_angle_bounds and angle_bound_pad is None:
 675            return BalancedNetwork(self._inner.to_normalized())
 676        return BalancedNetwork(
 677            self._inner.to_normalized_with_options(
 678                clamp_angle_bounds=clamp_angle_bounds, angle_bound_pad=angle_bound_pad
 679            )
 680        )
 681
 682    def to_ppc(self):
 683        """PYPOWER case dict (``ppc``) with MATPOWER-style numpy tables.
 684
 685        Values are emitted as the model holds them, so a case read from a
 686        file carries MW, MVAr, and degrees. A network from
 687        :meth:`to_normalized` holds per unit and radians, and those are what
 688        its tables carry — PYPOWER reads a ppc dict as MW and degrees, so
 689        build this from the raw network unless the consumer expects per unit.
 690
 691        Loads and shunts are summed onto their bus in the
 692        ``PD``/``QD``/``GS``/``BS`` columns, the same aggregation as the
 693        MATPOWER emitter. The bus table has no per element status
 694        column, so an element the model marks out of service still
 695        contributes its value, and a de-energized bus is carried as type 4.
 696        ``gencost`` is present only when every generator carries cost data,
 697        because MATPOWER requires cost rows for all generators or none.
 698        :func:`from_ppc` reads the tables back.
 699        """
 700        np = _require("numpy", "matrix")
 701        buses = self._inner.buses
 702        bus = np.array(
 703            [
 704                (
 705                    b["id"],
 706                    _PPC_BUS_TYPE.get(b["kind"], 1.0),
 707                    0.0,
 708                    0.0,
 709                    0.0,
 710                    0.0,
 711                    b["area"],
 712                    b["vm"],
 713                    b["va"],
 714                    b["base_kv"],
 715                    b["zone"],
 716                    b["vmax"],
 717                    b["vmin"],
 718                )
 719                for b in buses
 720            ],
 721            dtype=float,
 722        ).reshape(len(buses), 13)
 723        bus[:, 2], bus[:, 3], bus[:, 4], bus[:, 5] = _bus_sums(
 724            np, buses, self._inner.loads, self._inner.shunts
 725        )
 726
 727        # The capability and ramp columns past PMIN are an OPF extension that a
 728        # source need not carry. Widen to the full 21 only when a generator
 729        # actually states one: a table of zeros there reads back as eleven
 730        # explicit zero limits, which a ramp aware solver takes as a generator
 731        # that cannot move.
 732        gens = self._inner.generators
 733        caps = [g["caps"] for g in gens]
 734        width = 21 if any(c is not None for row in caps for c in row) else 10
 735        gen = np.array(
 736            [
 737                [
 738                    g["bus"],
 739                    g["pg"],
 740                    g["qg"],
 741                    g["qmax"],
 742                    g["qmin"],
 743                    g["vg"],
 744                    g["mbase"],
 745                    float(g["in_service"]),
 746                    g["pmax"],
 747                    g["pmin"],
 748                ]
 749                + ([0.0 if c is None else c for c in row] if width == 21 else [])
 750                for g, row in zip(gens, caps)
 751            ],
 752            dtype=float,
 753        ).reshape(len(gens), width)
 754
 755        branches = self._inner.branches
 756        branch = np.array(
 757            [
 758                (
 759                    br["from_id"],
 760                    br["to_id"],
 761                    br["r"],
 762                    br["x"],
 763                    br["b"],
 764                    br["rate_a"],
 765                    br["rate_b"],
 766                    br["rate_c"],
 767                    br["tap"],
 768                    br["shift"],
 769                    float(br["in_service"]),
 770                    br["angmin"],
 771                    br["angmax"],
 772                )
 773                for br in branches
 774            ],
 775            dtype=float,
 776        ).reshape(len(branches), 13)
 777
 778        ppc = {
 779            "version": "2",
 780            "baseMVA": float(self._inner.base_mva),
 781            "bus": bus,
 782            "gen": gen,
 783            "branch": branch,
 784        }
 785
 786        # Coefficients sit left-aligned after ncost, padded to the widest
 787        # row, which is the layout PYPOWER's own loadcase produces.
 788        costs = [g["cost"] for g in gens]
 789        if costs and all(c is not None for c in costs):
 790            gencost = np.zeros((len(costs), 4 + max(len(c["coeffs"]) for c in costs)))
 791            for i, c in enumerate(costs):
 792                gencost[i, :4] = (
 793                    c["model"],
 794                    c["startup"],
 795                    c["shutdown"],
 796                    c["ncost"],
 797                )
 798                gencost[i, 4 : 4 + len(c["coeffs"])] = c["coeffs"]
 799            ppc["gencost"] = gencost
 800        return ppc
 801
 802    def to_networkx(self):
 803        """Undirected networkx graph keyed by bus id.
 804
 805        In-service branches become edges carrying ``branch`` (index), ``r``,
 806        ``x``, and ``b``.
 807        """
 808        nx = _require("networkx", "graph")
 809        g = nx.Graph()
 810        g.add_nodes_from(bus["id"] for bus in self._inner.buses)
 811        for k, br in enumerate(self._inner.branches):
 812            if br["in_service"]:
 813                g.add_edge(
 814                    br["from_id"],
 815                    br["to_id"],
 816                    branch=k,
 817                    r=br["r"],
 818                    x=br["x"],
 819                    b=br["b"],
 820                )
 821        return g
 822
 823
 824@_guard
 825def parse_display(path: Any, format: Optional[str] = None) -> DisplayData:
 826    """Parse a display artifact such as a PowerWorld ``.pwd`` file."""
 827    return _wrap_display(_powerio.parse_display(str(path), format))
 828
 829
 830@_guard
 831def resolve_format(name: str) -> Optional[FormatInfo]:
 832    """Resolve a format token or common alias to its canonical metadata."""
 833    resolved = _powerio.resolve_format(name)
 834    return None if resolved is None else FormatInfo(*resolved)
 835
 836
 837@_guard
 838def parse_geo(text: str, name_hint: Optional[str] = None) -> dict[str, Any]:
 839    """Tolerantly read a geographic sidecar and return its canonical form.
 840
 841    Accepts headerless buscoords CSV, aliased CSV/JSON records, and GeoJSON
 842    Point/LineString features. Returns ``{"geojson": <FeatureCollection dict>,
 843    "diagnostics": [...]}``; ``name_hint`` (a file name) picks CSV against JSON
 844    when the content alone is ambiguous. Input with no usable coordinates
 845    raises :class:`PowerIOParseError`.
 846    """
 847    parsed = _powerio.parse_geo(text, name_hint)
 848    parsed["geojson"] = _json.loads(parsed["geojson"])
 849    return parsed
 850
 851
 852# powerio bus kind -> MATPOWER/PYPOWER BUS_TYPE code.
 853def _bus_sums(np, buses, loads, shunts):
 854    """Per bus `(pd, qd, gs, bs)` in bus order.
 855
 856    :meth:`BalancedNetwork.to_ppc` folds the element
 857    tables onto their bus the way the Rust indexed analysis view does. This is
 858    that fold, once.
 859    """
 860    row_of = {b["id"]: i for i, b in enumerate(buses)}
 861    pd, qd, gs, bs = (np.zeros(len(buses), dtype=float) for _ in range(4))
 862    for load in loads:
 863        i = row_of.get(load["bus"])
 864        if i is not None:
 865            pd[i] += load["p"]
 866            qd[i] += load["q"]
 867    for shunt in shunts:
 868        i = row_of.get(shunt["bus"])
 869        if i is not None:
 870            gs[i] += shunt["g"]
 871            bs[i] += shunt["b"]
 872    return pd, qd, gs, bs
 873
 874
 875_PPC_BUS_TYPE = {"PQ": 1.0, "PV": 2.0, "REF": 3.0, "ISOLATED": 4.0}
 876
 877# MATPOWER case-input table widths. PYPOWER result tables append columns
 878# (LAM_P, MU_*) past these; from_ppc drops them.
 879_PPC_INPUT_WIDTH = {"bus": 13, "gen": 21, "branch": 13}
 880
 881# Columns a table must carry, which is what the MATPOWER reader requires. The
 882# gen table's capability and ramp columns are an OPF extension, so a 10 column
 883# gen table is a complete case and passes through at its own width; padding it
 884# would hand the reader eleven explicit zero limits the source never stated. A
 885# bus or branch row below 13 is truncated data, and zero padding it would
 886# invent a bus at 0 p.u. and 0 kV, so it is refused here as the reader refuses
 887# it in a `.m` file.
 888_PPC_MIN_WIDTH = {"bus": 13, "gen": 10, "branch": 13}
 889
 890
 891def _ppc_rows(name, table):
 892    """The table's rows as float lists, trimmed to the MATPOWER input width."""
 893    width = _PPC_INPUT_WIDTH.get(name)
 894    minimum = _PPC_MIN_WIDTH.get(name)
 895    out = []
 896    for i, row in enumerate(table):
 897        try:
 898            vals = [float(v) for v in row]
 899        except TypeError as e:
 900            raise ValueError(
 901                f"ppc table {name!r} row {i} is not a sequence of numbers: "
 902                f"pass a 2-D array, one row per element"
 903            ) from e
 904        except ValueError as e:
 905            raise ValueError(
 906                f"ppc table {name!r} row {i} has a non-numeric value: {e}"
 907            ) from e
 908        if minimum is not None and len(vals) < minimum:
 909            raise ValueError(
 910                f"ppc table {name!r} row {i} has {len(vals)} columns; "
 911                f"MATPOWER requires at least {minimum}"
 912            )
 913        out.append(vals[:width] if width is not None else vals)
 914    return out
 915
 916
 917def _ppc_to_matpower_text(ppc) -> str:
 918    missing = [k for k in ("baseMVA", "bus", "gen", "branch") if k not in ppc]
 919    if missing:
 920        raise ValueError(f"ppc dict is missing required keys: {missing}")
 921    lines = [
 922        "function mpc = from_ppc",
 923        f"mpc.version = '{ppc.get('version', '2')}';",
 924        f"mpc.baseMVA = {float(ppc['baseMVA'])!r};",
 925    ]
 926    names = ["bus", "gen", "branch"] + (["gencost"] if "gencost" in ppc else [])
 927    for name in names:
 928        rows = _ppc_rows(name, ppc[name])
 929        lines.append(f"mpc.{name} = [")
 930        for vals in rows:
 931            lines.append("  " + "  ".join(repr(v) for v in vals) + ";")
 932        lines.append("];")
 933    return "\n".join(lines) + "\n"
 934
 935
 936@_guard
 937def from_ppc(ppc) -> BalancedNetwork:
 938    """Case from a PYPOWER dict (``ppc``); the inverse of :meth:`BalancedNetwork.to_ppc`.
 939
 940    The tables route through the MATPOWER reader, so the semantics match a
 941    ``.m`` case exactly: bus ``PD``/``QD`` become loads, ``GS``/``BS`` become
 942    shunts, and ``gencost`` is read when present. Result columns past the
 943    MATPOWER input widths are dropped. A 10 column ``gen`` table (the layout
 944    without the OPF capability columns) passes through at its own width, so
 945    the generators come back with no capability limits rather than eleven
 946    zero ones. Raises :class:`ValueError` when a required table is absent,
 947    when a ``bus`` or ``branch`` row is below its 13 column width, when a row
 948    is not a sequence of numbers, or when a cell is not numeric; the message
 949    names the table and the row.
 950    """
 951    value = parse(
 952        _io.StringIO(_ppc_to_matpower_text(ppc)),
 953        format="matpower",
 954        name="from_ppc.m",
 955    ).value
 956    assert isinstance(value, BalancedNetwork)
 957    return value
 958
 959
 960from . import dist  # noqa: E402  (needs EmitResult defined above)
 961
 962MulticonductorNetwork = dist.MulticonductorNetwork
 963
 964
 965@_guard
 966def versions() -> Any:
 967    """Return the PowerIO release, sole IR identity, and BMOPF schema."""
 968    return _json.loads(_powerio.versions_json())
 969
 970
 971class _TypedValue:
 972    """Typed view rooted in its owning :class:`PioModule`."""
 973
 974    __slots__ = ("module", "_collection_entry")
 975
 976    def __init__(self, module: "PioModule") -> None:
 977        self.module = module
 978        self._collection_entry = None
 979
 980    def __repr__(self) -> str:
 981        return f"{type(self).__name__}()"
 982
 983
 984@dataclass(frozen=True)
 985class TimePoint:
 986    label: str
 987    duration_seconds: Optional[float] = None
 988
 989
 990@dataclass(frozen=True)
 991class Scenario:
 992    id: str
 993    probability: Optional[float] = None
 994
 995
 996@dataclass(frozen=True)
 997class _CollectionEntry:
 998    root: "PioModule"
 999    time_index: Optional[int] = None
1000    scenario_id: Optional[str] = None
1001
1002
1003def _bind_collection_entry(
1004    value: Any,
1005    location: _CollectionEntry,
1006) -> Any:
1007    value._collection_entry = location
1008    return value
1009
1010
1011@_guard_class
1012class TimeSeries(_TypedValue, Sequence):
1013    """Values of one type ordered in time."""
1014
1015    def __init__(
1016        self,
1017        values: Sequence[Any],
1018        *,
1019        time_points: Sequence[TimePoint],
1020    ) -> None:
1021        if isinstance(values, (str, bytes, bytearray)) or not isinstance(
1022            values, Sequence
1023        ):
1024            raise TypeError("TimeSeries values must be a sequence of PowerIO values")
1025        if not isinstance(time_points, Sequence):
1026            raise TypeError("time_points must be a sequence of TimePoint values")
1027        points = tuple(time_points)
1028        if not all(isinstance(point, TimePoint) for point in points):
1029            raise TypeError("time_points must contain only TimePoint values")
1030        modules = [PioModule.from_value(value)._inner for value in values]
1031        inner = _powerio._PioModule._from_time_series(
1032            modules,
1033            [(point.label, point.duration_seconds) for point in points],
1034        )
1035        super().__init__(PioModule(inner))
1036
1037    @classmethod
1038    def _from_module(cls, module: "PioModule") -> "TimeSeries":
1039        value = object.__new__(cls)
1040        _TypedValue.__init__(value, module)
1041        return value
1042
1043    @property
1044    def time_points(self) -> tuple[TimePoint, ...]:
1045        return tuple(TimePoint(*point) for point in self.module._inner._time_series_points())
1046
1047    def __len__(self) -> int:
1048        return self.module._inner._time_series_len()
1049
1050    def __getitem__(self, index):
1051        if isinstance(index, slice):
1052            return [self[position] for position in range(*index.indices(len(self)))]
1053        try:
1054            position = _operator.index(index)
1055        except TypeError:
1056            raise TypeError("time series indices must be integers") from None
1057        if position < 0:
1058            position += len(self)
1059        if position < 0 or position >= len(self):
1060            raise IndexError("time series index out of range")
1061        current = self._collection_entry or _CollectionEntry(self.module)
1062        if current.time_index is not None:
1063            raise TypeError("nested TimeSeries values are not supported")
1064        value = PioModule(self.module._inner._time_series_get(position)).value
1065        return _bind_collection_entry(
1066            value,
1067            _CollectionEntry(
1068                root=current.root,
1069                time_index=position,
1070                scenario_id=current.scenario_id,
1071            ),
1072        )
1073
1074    def __iter__(self):
1075        return (self[position] for position in range(len(self)))
1076
1077
1078@_guard_class
1079class ScenarioSet(_TypedValue, Mapping):
1080    """Named alternatives of one type, with optional probabilities."""
1081
1082    def __init__(
1083        self,
1084        values: Mapping[str, Any],
1085        *,
1086        probabilities: Optional[Mapping[str, float]] = None,
1087    ) -> None:
1088        if not isinstance(values, Mapping):
1089            raise TypeError("ScenarioSet values must be a mapping from IDs to values")
1090        if probabilities is not None and not isinstance(probabilities, Mapping):
1091            raise TypeError("probabilities must be a mapping from scenario IDs to numbers")
1092        ids = list(values)
1093        modules = [PioModule.from_value(values[id])._inner for id in ids]
1094        inner = _powerio._PioModule._from_scenario_set(
1095            modules,
1096            ids,
1097            None if probabilities is None else dict(probabilities),
1098        )
1099        super().__init__(PioModule(inner))
1100
1101    @classmethod
1102    def _from_module(cls, module: "PioModule") -> "ScenarioSet":
1103        value = object.__new__(cls)
1104        _TypedValue.__init__(value, module)
1105        return value
1106
1107    @property
1108    def scenarios(self) -> tuple[Scenario, ...]:
1109        return tuple(Scenario(*entry) for entry in self.module._inner._scenario_entries())
1110
1111    def __len__(self) -> int:
1112        return len(self.scenarios)
1113
1114    def __iter__(self):
1115        return (scenario.id for scenario in self.scenarios)
1116
1117    def __contains__(self, scenario: object) -> bool:
1118        return isinstance(scenario, str) and any(
1119            entry.id == scenario for entry in self.scenarios
1120        )
1121
1122    def __getitem__(self, scenario: str) -> Any:
1123        if not isinstance(scenario, str):
1124            raise TypeError("scenario keys must be strings")
1125        if scenario not in self:
1126            raise KeyError(scenario)
1127        current = self._collection_entry or _CollectionEntry(self.module)
1128        if current.scenario_id is not None:
1129            raise TypeError("nested ScenarioSet values are not supported")
1130        value = PioModule(self.module._inner._scenario_get(scenario)).value
1131        return _bind_collection_entry(
1132            value,
1133            _CollectionEntry(
1134                root=current.root,
1135                time_index=current.time_index,
1136                scenario_id=scenario,
1137            ),
1138        )
1139
1140
1141@_guard_class
1142class OperatingPoint(_TypedValue):
1143    """A possibly partial assignment over fixed equipment identities."""
1144
1145    @property
1146    def network(self) -> "BalancedNetwork":
1147        """The balanced network this operating point is stated over.
1148
1149        The point's own values are applied to the returned copy, so it is the
1150        network a solver receives for this entry; the collection's shared
1151        base network is not changed. A multiconductor operating point raises
1152        :class:`PowerIOError`.
1153
1154        Net bus injection quantities have no balanced network field, so they
1155        are dropped here and the property reports nothing. Emit the
1156        collection when you need that omission reported: `emit` warns
1157        `EMIT.OPERATING_POINT.DATA_OMITTED` for the same point.
1158        """
1159        return BalancedNetwork(self.module._inner._operating_point_network())
1160
1161
1162@_guard_class
1163class _BalancedCalculation(_TypedValue):
1164    """A calculation over one shared balanced network."""
1165
1166    @property
1167    def network(self) -> BalancedNetwork:
1168        """The balanced network used by this calculation."""
1169        return BalancedNetwork(self.module._inner._balanced_calculation_network())
1170
1171
1172@_guard_class
1173class _MulticonductorCalculation(_TypedValue):
1174    """A calculation over one shared multiconductor network."""
1175
1176    @property
1177    def network(self) -> MulticonductorNetwork:
1178        """The multiconductor network used by this calculation."""
1179        return MulticonductorNetwork(
1180            self.module._inner._multiconductor_calculation_network()
1181        )
1182
1183
1184@_guard_class
1185class _CalculationSolution(_TypedValue):
1186    """A solution that retains the exact typed instance it solves."""
1187
1188    @property
1189    def instance(self) -> _TypedValue:
1190        """The calculation instance solved by this result."""
1191        return PioModule(self.module._inner._calculation_solution_instance()).value
1192
1193
1194class DcPfInstance(_BalancedCalculation):
1195    """A DC power flow calculation instance."""
1196
1197
1198class AcPfInstance(_BalancedCalculation):
1199    """An AC power flow calculation instance."""
1200
1201
1202class DcOpfInstance(_BalancedCalculation):
1203    """A DC optimal power flow calculation instance."""
1204
1205
1206class AcOpfInstance(_BalancedCalculation):
1207    """An AC optimal power flow calculation instance."""
1208
1209
1210class McAcPfInstance(_MulticonductorCalculation):
1211    """A multiconductor AC power flow calculation instance."""
1212
1213
1214@_guard_class
1215class LinDist3FlowPfInstance(_MulticonductorCalculation):
1216    """A fixed-dispatch LinDist3Flow power-flow instance."""
1217
1218    @property
1219    def metadata(self) -> dict[str, Any]:
1220        """Node/conductor axes, preparation actions, and reference phasors."""
1221        return self.module._inner._lindist3flow_metadata()
1222
1223
1224@_guard_class
1225class LinDist3FlowOpfInstance(_MulticonductorCalculation):
1226    """A radial fixed-reference multiconductor linear OPF instance."""
1227
1228    @property
1229    def metadata(self) -> dict[str, Any]:
1230        """Node and conductor axes, roots, and reference phasors in volts/radians."""
1231        return self.module._inner._lindist3flow_metadata()
1232
1233
1234class McAcOpfInstance(_MulticonductorCalculation):
1235    """A multiconductor AC optimal power flow calculation instance."""
1236
1237
1238@_guard_class
1239class AcScucInstance(_BalancedCalculation):
1240    """An AC security constrained unit commitment calculation instance."""
1241
1242    @property
1243    def inputs(self) -> ScucInputs:
1244        """Scheduling, reserve, and contingency inputs."""
1245        return self.module._inner._ac_scuc_inputs()
1246
1247
1248class DcPfSolution(_BalancedCalculation, _CalculationSolution):
1249    """A DC power flow solution."""
1250
1251
1252class AcPfSolution(_BalancedCalculation, _CalculationSolution):
1253    """An AC power flow solution."""
1254
1255
1256class DcOpfSolution(_BalancedCalculation, _CalculationSolution):
1257    """A DC optimal power flow solution."""
1258
1259
1260class AcOpfSolution(_BalancedCalculation, _CalculationSolution):
1261    """An AC optimal power flow solution."""
1262
1263
1264class SocwrOpfSolution(_BalancedCalculation, _CalculationSolution):
1265    """A PowerModels SOCWR relaxation solution and objective lower bound."""
1266
1267
1268class McAcPfSolution(_MulticonductorCalculation, _CalculationSolution):
1269    """A multiconductor AC power flow solution."""
1270
1271
1272@_guard_class
1273class LinDist3FlowPfSolution(_MulticonductorCalculation, _CalculationSolution):
1274    """Fixed-dispatch LinDist3Flow values and monitored SI line limits."""
1275
1276    @property
1277    def termination(self) -> str:
1278        """How the calculation ended."""
1279        return self.module._inner._lindist3flow_solution_termination()
1280
1281    @property
1282    def limit_checks(self) -> list[dict[str, Any]]:
1283        """Monitored line ratings, values, loading ratios, and overload flags."""
1284        return self.module._inner._lindist3flow_limit_checks()
1285
1286    def __getitem__(self, quantity: str) -> list[float]:
1287        """Copy one named primal column in its physical instance order."""
1288        return self.module._inner._lindist3flow_solution_values(quantity)
1289
1290
1291@_guard_class
1292class LinDist3FlowOpfSolution(_MulticonductorCalculation, _CalculationSolution):
1293    """LinDist3Flow primal values in squared volts, watts, and vars."""
1294
1295    @property
1296    def termination(self) -> str:
1297        """How the calculation ended."""
1298        return self.module._inner._lindist3flow_solution_termination()
1299
1300    @property
1301    def objective(self) -> float:
1302        """The reported objective value."""
1303        return self.module._inner._lindist3flow_solution_objective()
1304
1305    def __getitem__(self, quantity: str) -> list[float]:
1306        """Copy one named primal column in its physical instance order."""
1307        return self.module._inner._lindist3flow_solution_values(quantity)
1308
1309
1310class McAcOpfSolution(_MulticonductorCalculation, _CalculationSolution):
1311    """A multiconductor AC optimal power flow solution."""
1312
1313
1314@_guard_class
1315class AcScucSolution(_BalancedCalculation, _CalculationSolution):
1316    """An AC security constrained unit commitment solution."""
1317
1318    @property
1319    def termination(self) -> str:
1320        """How the calculation ended."""
1321        return self.module._inner._ac_scuc_solution_termination()
1322
1323    @property
1324    def residuals(self) -> Residuals:
1325        """Reported active and reactive power balance residuals."""
1326        return self.module._inner._ac_scuc_solution_residuals()
1327
1328    @property
1329    def producer(self) -> Optional[str]:
1330        """Producer or solver identity, when recorded."""
1331        return self.module._inner._ac_scuc_solution_producer()
1332
1333    @property
1334    def network_outputs(self) -> ScucNetworkOutputs:
1335        """Per interval network outputs."""
1336        return self.module._inner._ac_scuc_solution_network_outputs()
1337
1338    @property
1339    def device_outputs(self) -> ScucDeviceOutputs:
1340        """Per interval dispatchable device outputs."""
1341        return self.module._inner._ac_scuc_solution_device_outputs()
1342
1343    @property
1344    def objective(self) -> Optional[float]:
1345        """Reported objective value, when present."""
1346        return self.module._inner._ac_scuc_solution_objective()
1347
1348
1349@_guard_class
1350class GeoLayer(_TypedValue):
1351    """A standalone geographic document: element points and routes keyed by
1352    element identity, in one coordinate space.
1353
1354    :func:`parse` returns it for the canonical ``.geo.json``, GeoJSON, aliased
1355    CSV or JSON records, headerless buscoords CSV, and a PowerWorld ``.pwd``
1356    display. :func:`powerio.emit` writes the canonical document as
1357    ``geo-json``, and :func:`serialize` carries the layer through PowerIO IR.
1358    Place a layer onto a case with
1359    ``network.apply_geo_layer(layer.geojson)``.
1360    """
1361
1362    @property
1363    def geojson(self) -> str:
1364        """The canonical ``.geo.json`` document for this layer."""
1365        result = emit(self.module, "geo-json")
1366        data = result.artifacts[0].data
1367        if data is None:
1368            raise ValueError("the layer emission returned no artifact bytes")
1369        return data.decode("utf-8")
1370
1371
1372def _emitted_text(module: "PioModule[Any]", format: str) -> str:
1373    """Emit ``module`` under one token and decode the single UTF-8 artifact."""
1374    result = emit(module, format)
1375    data = result.artifacts[0].data
1376    if data is None:
1377        raise ValueError(f"the {format} emission returned no artifact bytes")
1378    return data.decode("utf-8")
1379
1380
1381@_guard_class
1382class ContingencySet(_TypedValue):
1383    """A PSS/E contingency description file: the cases to run, the automatic
1384    specifications that state cases by rule, and the ``SKIP`` rules.
1385
1386    :func:`parse` returns it for a ``.con`` file or for text declared as
1387    ``psse-con``, :func:`powerio.emit` writes it back under that token, and
1388    :func:`serialize` carries it through PowerIO IR. Bind a set to a case with
1389    ``network.resolve_contingencies(cases.text)`` and turn its automatic
1390    specifications into explicit cases with
1391    ``network.expand_contingencies(cases.text, groups.text)``.
1392    """
1393
1394    @property
1395    def text(self) -> str:
1396        """The ``.con`` text for this set."""
1397        return _emitted_text(self.module, "psse-con")
1398
1399
1400@_guard_class
1401class SubsystemSet(_TypedValue):
1402    """A PSS/E subsystem description file: the named bus groups a contingency
1403    run and a monitored element file draw on.
1404
1405    :func:`parse` returns it for a ``.sub`` file or for text declared as
1406    ``psse-sub``, and ``network.select_subsystem_buses(groups.text, name)``
1407    names the buses one subsystem selects.
1408    """
1409
1410    @property
1411    def text(self) -> str:
1412        """The ``.sub`` text for this set."""
1413        return _emitted_text(self.module, "psse-sub")
1414
1415
1416@_guard_class
1417class MonitoredSet(_TypedValue):
1418    """A PSS/E monitored element file: the branches, interfaces, and voltage
1419    scopes a contingency run reports on.
1420
1421    :func:`parse` returns it for a ``.mon`` file or for text declared as
1422    ``psse-mon``.
1423    """
1424
1425    @property
1426    def text(self) -> str:
1427        """The ``.mon`` text for this set."""
1428        return _emitted_text(self.module, "psse-mon")
1429
1430
1431_VALUE_CLASSES: dict[str, type[_TypedValue]] = {
1432    "powerio.ContingencySet": ContingencySet,
1433    "powerio.GeoLayer": GeoLayer,
1434    "powerio.MonitoredSet": MonitoredSet,
1435    "powerio.SubsystemSet": SubsystemSet,
1436    "powerio.OperatingPoint<powerio.BalancedNetwork>": OperatingPoint,
1437    "powerio.OperatingPoint<powerio.MulticonductorNetwork>": OperatingPoint,
1438    "powerio.DcPfInstance": DcPfInstance,
1439    "powerio.AcPfInstance": AcPfInstance,
1440    "powerio.DcOpfInstance": DcOpfInstance,
1441    "powerio.AcOpfInstance": AcOpfInstance,
1442    "powerio.McAcPfInstance": McAcPfInstance,
1443    "powerio.McAcOpfInstance": McAcOpfInstance,
1444    "powerio.LinDist3FlowPfInstance": LinDist3FlowPfInstance,
1445    "powerio.LinDist3FlowOpfInstance": LinDist3FlowOpfInstance,
1446    "powerio.AcScucInstance": AcScucInstance,
1447    "powerio.DcPfSolution": DcPfSolution,
1448    "powerio.AcPfSolution": AcPfSolution,
1449    "powerio.DcOpfSolution": DcOpfSolution,
1450    "powerio.AcOpfSolution": AcOpfSolution,
1451    "powerio.SocwrOpfSolution": SocwrOpfSolution,
1452    "powerio.McAcPfSolution": McAcPfSolution,
1453    "powerio.McAcOpfSolution": McAcOpfSolution,
1454    "powerio.LinDist3FlowPfSolution": LinDist3FlowPfSolution,
1455    "powerio.LinDist3FlowOpfSolution": LinDist3FlowOpfSolution,
1456    "powerio.AcScucSolution": AcScucSolution,
1457}
1458
1459
1460@_guard_class
1461class PioModule:
1462    """One typed value with diagnostics, producer, sources, source mappings,
1463    history, and extensions.
1464    """
1465
1466    def __init__(self, inner: "_powerio._PioModule"):
1467        self._inner = inner
1468
1469    @classmethod
1470    def from_value(cls, value: Any) -> "PioModule":
1471        """Wrap an existing typed value without serializing it."""
1472        if isinstance(value, BalancedNetwork):
1473            return cls(_powerio._PioModule.from_balanced_network(value._inner))
1474        if isinstance(value, dist.MulticonductorNetwork):
1475            return cls(_powerio._PioModule.from_multiconductor_network(value._inner))
1476        if isinstance(value, _TypedValue):
1477            location = value._collection_entry
1478            inner = value.module._inner
1479            if location is not None:
1480                inner = location.root._inner
1481                if location.scenario_id is not None:
1482                    inner = inner._scenario_get(location.scenario_id)
1483                if location.time_index is not None:
1484                    inner = inner._time_series_get(location.time_index)
1485            return cls(inner._copy())
1486        raise TypeError("PioModule.from_value expects a typed PowerIO value")
1487
1488    @property
1489    def value(self) -> Any:
1490        """The contained typed value."""
1491        type_name = self._inner._type_name
1492        if type_name == "powerio.BalancedNetwork":
1493            return BalancedNetwork(self._inner.as_balanced_network())
1494        if type_name == "powerio.MulticonductorNetwork":
1495            return dist.MulticonductorNetwork(self._inner.as_multiconductor_network())
1496        if type_name.startswith("powerio.TimeSeries<"):
1497            return TimeSeries._from_module(self)
1498        if type_name.startswith("powerio.ScenarioSet<"):
1499            return ScenarioSet._from_module(self)
1500        value_class = _VALUE_CLASSES.get(type_name)
1501        if value_class is None:
1502            raise RuntimeError(f"this binding has no Python class for {type_name}")
1503        return value_class(self)
1504
1505    @property
1506    def type_name(self) -> str:
1507        """The canonical structural name of the contained value, such as
1508        ``powerio.OperatingPoint<powerio.BalancedNetwork>``. The C ABI and
1509        PowerIO IR name the same type with the same string.
1510        """
1511        return str(self._inner._type_name)
1512
1513    @property
1514    def diagnostics(self) -> list[Diagnostic]:
1515        """The diagnostics stored on this module, in encounter order."""
1516        return list(self._inner.diagnostics)
1517
1518    def to_balanced_report(self, base_mva: float = 100.0) -> Any:
1519        """Report whether a multiconductor network can become balanced."""
1520        return _json.loads(self._inner.lowering_readiness_json(base_mva))
1521
1522    def to_balanced(self, base_mva: float = 100.0) -> "PioModule":
1523        """Transform a multiconductor network to a balanced module."""
1524        return PioModule(self._inner.lower_to_balanced(base_mva))
1525
1526    def to_dc_pf_instance(self) -> "PioModule":
1527        """Build a DC power flow instance from a balanced network module."""
1528        return PioModule(self._inner._to_dc_pf_instance())
1529
1530    def to_ac_pf_instance(self) -> "PioModule":
1531        """Build an AC power flow instance from a balanced network module."""
1532        return PioModule(self._inner._to_ac_pf_instance())
1533
1534    def to_dc_opf_instance(self) -> "PioModule":
1535        """Build a DC optimal power flow instance from a balanced network module."""
1536        return PioModule(self._inner._to_dc_opf_instance())
1537
1538    def to_ac_opf_instance(self) -> "PioModule":
1539        """Build an AC optimal power flow instance from a balanced network module."""
1540        return PioModule(self._inner._to_ac_opf_instance())
1541
1542    def to_mc_ac_pf_instance(self) -> "PioModule":
1543        """Build a multiconductor AC power flow instance from a network module."""
1544        return PioModule(self._inner._to_mc_ac_pf_instance())
1545
1546    def to_mc_ac_opf_instance(self) -> "PioModule":
1547        """Build a multiconductor AC optimal power flow instance from a network module."""
1548        return PioModule(self._inner._to_mc_ac_opf_instance())
1549
1550    def to_lindist3flow_opf_instance(self) -> "PioModule":
1551        """Build a LinDist3Flow optimal power flow instance from a network module."""
1552        return PioModule(self._inner._to_lindist3flow_opf_instance())
1553
1554    def to_lindist3flow_pf_instance(self) -> "PioModule":
1555        """Build a fixed-dispatch LinDist3Flow instance from a network module."""
1556        return PioModule(self._inner._to_lindist3flow_pf_instance())
1557
1558    def __repr__(self) -> str:
1559        return repr(self._inner)
1560
1561
1562def _selected_collection_value(location: _CollectionEntry) -> Any:
1563    value = location.root.value
1564    time_index = location.time_index
1565    scenario_id = location.scenario_id
1566    while time_index is not None or scenario_id is not None:
1567        if isinstance(value, TimeSeries) and time_index is not None:
1568            value = value[time_index]
1569            time_index = None
1570        elif isinstance(value, ScenarioSet) and scenario_id is not None:
1571            value = value[scenario_id]
1572            scenario_id = None
1573        elif time_index is not None:
1574            raise TypeError("the selected value is not a TimeSeries")
1575        else:
1576            raise TypeError("the selected value is not a ScenarioSet")
1577    return value
1578
1579
1580def _refresh_collection_entry(target: Any, location: _CollectionEntry) -> None:
1581    refreshed = _selected_collection_value(location)
1582    if type(refreshed) is not type(target):
1583        raise RuntimeError("a collection update changed the entry type")
1584    if isinstance(target, BalancedNetwork):
1585        target._inner = refreshed._inner
1586    elif isinstance(target, dist.MulticonductorNetwork):
1587        target._inner = refreshed._inner
1588    elif isinstance(target, _TypedValue):
1589        target.module = refreshed.module
1590        target._collection_entry = refreshed._collection_entry
1591    else:
1592        raise TypeError("the selected value does not support typed updates")
1593
1594
1595@_guard
1596def apply_updates(
1597    target: Any,
1598    updates: Union[
1599        Iterable[OperatingPointUpdate],
1600        Iterable[NetworkUpdate],
1601        Iterable[CalculationUpdate],
1602    ],
1603) -> UpdateReport:
1604    """Validate and apply one batch of typed updates atomically.
1605
1606    ``updates`` contains one update class: :class:`OperatingPointUpdate`,
1607    :class:`NetworkUpdate`, or :class:`CalculationUpdate`. Values are absolute
1608    replacements and power quantities carry their units in the typed value.
1609    ``target`` is a module or a value obtained by indexing a :class:`TimeSeries`
1610    or :class:`ScenarioSet`. If validation fails, the module is unchanged.
1611    """
1612    batch = list(updates)
1613    if isinstance(target, PioModule):
1614        return target._inner._apply_updates(batch)
1615    location = getattr(target, "_collection_entry", None)
1616    if not isinstance(location, _CollectionEntry):
1617        raise TypeError(
1618            "target must be a PioModule or a TimeSeries/ScenarioSet entry"
1619        )
1620    report = location.root._inner._apply_collection_updates(
1621        batch,
1622        time_index=location.time_index,
1623        scenario_id=location.scenario_id,
1624    )
1625    _refresh_collection_entry(target, location)
1626    return report
1627
1628
1629@_guard
1630def apply_bus_load_active_power(
1631    module: PioModule,
1632    bus_id: int,
1633    total: ActivePower,
1634    *,
1635    allocation: str = "proportional_to_current_active_power",
1636) -> UpdateReport:
1637    """Replace aggregate bus demand through an explicit PowerIO allocation rule.
1638
1639    ``"proportional_to_current_active_power"`` preserves each participating
1640    load's current share. ``"equal"`` gives every participating load the same
1641    share, including when their current aggregate demand is zero. PowerIO
1642    requires stable load IDs and reports each load changed.
1643    """
1644    if not isinstance(module, PioModule):
1645        raise TypeError("module must be a PioModule")
1646    if not isinstance(total, ActivePower):
1647        raise TypeError("total must be an ActivePower")
1648    return module._inner._apply_bus_load_active_power(
1649        bus_id,
1650        total,
1651        allocation=allocation,
1652    )
1653
1654
1655def _path_from_source(source: Any) -> Optional[str]:
1656    if isinstance(source, str):
1657        return source
1658    if isinstance(source, (bytes, bytearray, memoryview)):
1659        return None
1660    try:
1661        path = _os.fspath(source)
1662    except TypeError:
1663        return None
1664    if isinstance(path, bytes):
1665        raise TypeError("a path-like source must return str, not bytes")
1666    return path
1667
1668
1669def _memory_from_source(source: Any, name: Optional[str]) -> tuple[bytes, str]:
1670    if isinstance(source, (bytes, bytearray, memoryview)):
1671        data = bytes(source)
1672    else:
1673        read = getattr(source, "read", None)
1674        if read is None:
1675            raise TypeError(
1676                "source must be a path, file object, or bytes-like object"
1677            )
1678        data = read()
1679        if isinstance(data, str):
1680            data = data.encode("utf-8")
1681        elif isinstance(data, (bytes, bytearray, memoryview)):
1682            data = bytes(data)
1683        else:
1684            raise TypeError("source.read() must return str or bytes-like data")
1685    if name is None:
1686        candidate = getattr(source, "name", None)
1687        try:
1688            candidate = _os.fspath(candidate) if candidate is not None else None
1689        except TypeError:
1690            candidate = None
1691        name = candidate if isinstance(candidate, str) else "<memory>"
1692    if not isinstance(name, str):
1693        raise TypeError("name must be a string")
1694    return data, name
1695
1696
1697@_guard
1698def parse(
1699    source: Any,
1700    *,
1701    format: Optional[str] = None,
1702    name: Optional[str] = None,
1703) -> PioModule:
1704    """Parse a path, file object, or bytes-like source.
1705
1706    A string is always a path. Pass raw text through ``io.StringIO`` or
1707    another file object.
1708    """
1709    path = _path_from_source(source)
1710    if path is not None:
1711        if name is not None:
1712            raise ValueError("name is only valid for memory and file object sources")
1713        return PioModule(_powerio._PioModule._parse_path(path, format))
1714    data, source_name = _memory_from_source(source, name)
1715    return PioModule(_powerio._PioModule._parse_memory(data, source_name, format))
1716
1717
1718def _result_from_native(result: dict[str, Any]) -> EmitResult:
1719    return EmitResult(
1720        artifacts=tuple(Artifact(**artifact) for artifact in result["artifacts"]),
1721        layout=result["layout"],
1722        fidelity=result["fidelity"],
1723        diagnostics=tuple(result["diagnostics"]),
1724    )
1725
1726
1727def _emit_to_destination(
1728    module: PioModule,
1729    destination: Optional[Any],
1730    memory_call: Any,
1731    path_call: Any,
1732) -> EmitResult:
1733    if not isinstance(module, PioModule):
1734        raise TypeError("module must be a PioModule")
1735    if destination is None:
1736        return _result_from_native(memory_call())
1737    path = _path_from_source(destination)
1738    if path is not None:
1739        return _result_from_native(path_call(path))
1740    write = getattr(destination, "write", None)
1741    if write is None:
1742        raise TypeError("destination must be a path or writable file object")
1743    result = _result_from_native(memory_call())
1744    if result.layout != "file" or len(result.artifacts) != 1:
1745        raise ValueError("a directory emission requires a path destination")
1746    data = result.artifacts[0].data
1747    if data is None:
1748        raise ValueError("the emission returned no artifact bytes to write")
1749    # A text mode stream takes str and a binary one takes bytes. Ask a real
1750    # stream which it is rather than writing bytes and retrying on TypeError:
1751    # a TypeError raised inside the stream's own write would otherwise trigger
1752    # a second, partially duplicated write. A duck typed sink states neither,
1753    # so it keeps the retry.
1754    if isinstance(destination, _io.TextIOBase) or isinstance(
1755        getattr(destination, "encoding", None), str
1756    ):
1757        write(data.decode("utf-8"))
1758    elif isinstance(destination, (_io.RawIOBase, _io.BufferedIOBase)):
1759        write(data)
1760    else:
1761        try:
1762            write(data)
1763        except TypeError:
1764            write(data.decode("utf-8"))
1765    return result
1766
1767
1768@_guard
1769def emit(module: PioModule, format: str, destination: Optional[Any] = None) -> EmitResult:
1770    """Emit a module as one grid exchange format."""
1771    return _emit_to_destination(
1772        module,
1773        destination,
1774        lambda: module._inner._emit_memory(format),
1775        lambda path: module._inner._emit_path(format, path),
1776    )
1777
1778
1779@_guard
1780def serialize(module: PioModule, destination: Optional[Any] = None) -> EmitResult:
1781    """Serialize a module as PowerIO IR."""
1782    return _emit_to_destination(
1783        module,
1784        destination,
1785        module._inner._serialize_memory,
1786        module._inner._serialize_path,
1787    )
1788
1789
1790@_guard
1791def deserialize(source: Any) -> PioModule:
1792    """Deserialize PowerIO IR from a path, file object, or bytes-like source."""
1793    path = _path_from_source(source)
1794    if path is not None:
1795        return PioModule(_powerio._PioModule._deserialize_path(path))
1796    data, _ = _memory_from_source(source, None)
1797    return PioModule(_powerio._PioModule._deserialize_memory(data))
1798
1799
1800@_guard
1801def features() -> dict[str, bool]:
1802    """The build-time features compiled into this powerio installation.
1803
1804    ``matrix``, ``dist``, and ``prob`` are unconditional dependencies of the
1805    extension and are always ``True``. ``gridfm`` reports whether GridFM
1806    Parquet parsing and emission were compiled in; the published wheel
1807    includes them, while a custom source build can omit them.
1808    """
1809    return {
1810        "matrix": True,
1811        "gridfm": bool(getattr(_powerio, "_has_gridfm", False)),
1812        "dist": True,
1813        "prob": True,
1814    }
1815
1816
1817@_guard
1818def diagnostic_record(diagnostic: Diagnostic) -> dict[str, Any]:
1819    """One diagnostic as a JSON-ready dictionary.
1820
1821    ``code``, ``severity``, ``message``, and ``target`` are always present, in
1822    that order. ``id``, ``suggested_action``, and ``related`` follow when the
1823    diagnostic sets them, ``details`` when it is not ``None``, and ``spans``
1824    as ``source``, ``byte_start``, ``byte_end`` dictionaries when the
1825    diagnostic carries at least one span.
1826    """
1827    record: dict[str, Any] = {
1828        "code": diagnostic.code,
1829        "severity": diagnostic.severity,
1830        "message": diagnostic.message,
1831        "target": diagnostic.target,
1832    }
1833    if diagnostic.id:
1834        record["id"] = diagnostic.id
1835    if diagnostic.suggested_action:
1836        record["suggested_action"] = diagnostic.suggested_action
1837    if diagnostic.related:
1838        record["related"] = list(diagnostic.related)
1839    if diagnostic.details is not None:
1840        record["details"] = diagnostic.details
1841    if diagnostic.spans:
1842        record["spans"] = [
1843            {
1844                "source": span.source,
1845                "byte_start": span.byte_start,
1846                "byte_end": span.byte_end,
1847            }
1848            for span in diagnostic.spans
1849        ]
1850    return record
1851
1852
1853@_guard
1854def diagnostic_records(diagnostics: Iterable[Diagnostic]) -> list[dict[str, Any]]:
1855    """Every diagnostic as a JSON-ready dictionary, in the order given."""
1856    return [diagnostic_record(item) for item in diagnostics]