powerio
Parse, transform, and emit power system data.
parse returns a module whose value is the typed power system object
and whose diagnostics record what the parser found::
import powerio as pio
module = pio.parse("case9.m")
net = module.value
print(net.n_buses, net.base_mva) # 9 100.0
matpower = pio.emit(module, "matpower")
emitted = pio.emit(module, "psse", "case9.raw")
B = net.calc_bprime_matrix() # scipy.sparse, MATPOWER Bp
Y = net.calc_admittance_matrix() # complex csr, G + jB
G = net.to_networkx() # networkx.Graph keyed by bus id
A PyPSA CSV directory parses to a network or a time series, depending on its
declared snapshots and supported series files. A time series keeps its
snapshot axis even when the values are identical. Optional powerio[pypsa-files]
transports carry this electrical profile through PyPSA NetCDF and HDF5 files.
A source that defines a calculation parses to that calculation's typed value.
Use isinstance(module.value, ...) to branch on the result type.
import powerio and the base parse and emit paths require no
third party Python package. Matrix methods require SciPy and NumPy. Graph
methods require NetworkX. Install them with powerio[matrix],
powerio[graph], or powerio[all]. Missing extras raise ImportError.
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 18A PyPSA CSV directory parses to a network or a time series, depending on its 19declared snapshots and supported series files. A time series keeps its 20snapshot axis even when the values are identical. Optional ``powerio[pypsa-files]`` 21transports carry this electrical profile through PyPSA NetCDF and HDF5 files. 22 23A source that defines a calculation parses to that calculation's typed value. 24Use ``isinstance(module.value, ...)`` to branch on the result type. 25 26``import powerio`` and the base parse and emit paths require no 27third party Python package. Matrix methods require SciPy and NumPy. Graph 28methods require NetworkX. Install them with ``powerio[matrix]``, 29``powerio[graph]``, or ``powerio[all]``. Missing extras raise ``ImportError``. 30""" 31 32from __future__ import annotations 33 34import importlib 35import io as _io 36import json as _json 37import operator as _operator 38import os as _os 39from collections import namedtuple 40from collections.abc import Mapping, Sequence 41from dataclasses import dataclass 42from typing import Any, Iterable, Optional, Union 43 44from . import _powerio 45from ._guard import guard as _guard 46from ._guard import guard_class as _guard_class 47from ._powerio import ( 48 ActivePower, 49 ApparentPower, 50 CalculationUpdate, 51 ComponentId, 52 Diagnostic, 53 NetworkUpdate, 54 OperatingPointUpdate, 55 PowerIODataError, 56 PowerIOError, 57 PowerIOParseError, 58 ReactivePower, 59 Residuals, 60 ScucActiveReserveZone, 61 ScucBranchSwitchingCost, 62 ScucContingency, 63 ScucDevice, 64 ScucDeviceOutputs, 65 ScucDevicePeriod, 66 ScucEnergyCostBlock, 67 ScucEnergyRequirement, 68 ScucInitialCommitment, 69 ScucInputs, 70 ScucNetworkOutputs, 71 ScucRampLimits, 72 ScucReactiveCapability, 73 ScucReactiveReserveZone, 74 ScucReserveCosts, 75 ScucReserveLimits, 76 ScucShunt, 77 ScucStartupCostAdjustment, 78 ScucStartupLimit, 79 ScucTransformerControl, 80 ScucViolationCosts, 81 SourceSpan, 82 UpdateChange, 83 UpdateReport, 84 __version__, 85) 86from ._sincal import SincalBalancedReadOptions, _native_selections 87from .collection import Collection, CollectionResult 88 89__all__ = [ 90 "AcOpfInstance", 91 "AcOpfSolution", 92 "AcOtsInstance", 93 "AcOtsSolution", 94 "AcPfInstance", 95 "AcPfSolution", 96 "AcScucInstance", 97 "AcScucSolution", 98 "ActivePower", 99 "ApparentPower", 100 "Artifact", 101 "BalancedNetwork", 102 "BusMerge", 103 "CalculationUpdate", 104 "Collection", 105 "CollectionResult", 106 "ComponentId", 107 "ContingencySet", 108 "DcOpfInstance", 109 "DcOpfSolution", 110 "DcPfInstance", 111 "DcPfSolution", 112 "Diagnostic", 113 "EmitResult", 114 "FormatInfo", 115 "GeoLayer", 116 "LinDist3FlowOpfInstance", 117 "LinDist3FlowOpfSolution", 118 "LinDist3FlowPfInstance", 119 "LinDist3FlowPfSolution", 120 "McAcOpfInstance", 121 "McAcOpfSolution", 122 "McAcPfInstance", 123 "McAcPfSolution", 124 "MonitoredSet", 125 "MulticonductorNetwork", 126 "NetworkUpdate", 127 "OperatingPoint", 128 "OperatingPointUpdate", 129 "PioModule", 130 "PowerIODataError", 131 "PowerIOError", 132 "PowerIOParseError", 133 "ReactivePower", 134 "Residuals", 135 "Scenario", 136 "ScenarioSet", 137 "ScucActiveReserveZone", 138 "ScucBranchSwitchingCost", 139 "ScucContingency", 140 "ScucDevice", 141 "ScucDeviceOutputs", 142 "ScucDevicePeriod", 143 "ScucEnergyCostBlock", 144 "ScucEnergyRequirement", 145 "ScucInitialCommitment", 146 "ScucInputs", 147 "ScucNetworkOutputs", 148 "ScucRampLimits", 149 "ScucReactiveCapability", 150 "ScucReactiveReserveZone", 151 "ScucReserveCosts", 152 "ScucReserveLimits", 153 "ScucShunt", 154 "ScucStartupCostAdjustment", 155 "ScucStartupLimit", 156 "ScucTransformerControl", 157 "ScucViolationCosts", 158 "SincalBalancedReadOptions", 159 "SocwrOpfSolution", 160 "SourceSpan", 161 "SubsystemSet", 162 "TimePoint", 163 "TimeSeries", 164 "UpdateChange", 165 "UpdateReport", 166 "__version__", 167 "apply_bus_load_active_power", 168 "apply_updates", 169 "deserialize", 170 "diagnostic_record", 171 "diagnostic_records", 172 "dist", 173 "emit", 174 "features", 175 "from_ppc", 176 "parse", 177 "parse_geo", 178 "resolve_format", 179 "serialize", 180 "versions", 181] 182 183@dataclass(frozen=True) 184class Artifact: 185 """One artifact produced by :func:`emit` or :func:`serialize`. 186 187 ``data`` is set for an in-memory result. ``path`` is set after committing 188 to a filesystem destination. 189 """ 190 191 name: str 192 data: Optional[bytes] 193 path: Optional[str] 194 195 @property 196 def text(self) -> str: 197 """Decode an in-memory UTF-8 artifact.""" 198 if self.data is None: 199 raise ValueError("this artifact was committed to a destination") 200 return self.data.decode("utf-8") 201 202 203@dataclass(frozen=True) 204class EmitResult: 205 """Artifact inventory and diagnostics from an emission or serialization.""" 206 207 artifacts: tuple[Artifact, ...] 208 layout: str 209 fidelity: str 210 diagnostics: tuple[Diagnostic, ...] 211 212 @property 213 def text(self) -> Optional[str]: 214 """The sole UTF-8 memory artifact, or ``None`` for other inventories.""" 215 if len(self.artifacts) != 1 or self.artifacts[0].data is None: 216 return None 217 return self.artifacts[0].text 218 219FormatInfo = namedtuple( 220 "FormatInfo", ["token", "extension", "is_directory", "can_emit"] 221) 222FormatInfo.__doc__ = """Canonical metadata returned by :func:`resolve_format`. 223 224``extension`` is the conventional filename suffix without a leading dot; it 225can be compound and is ``None`` when a directory format has no primary case 226file. ``can_emit`` reports whether a fresh universal emitter exists for the 227format. It is not a promise for every concrete module value or a feature probe. A 228false value neither promises nor forbids a same format retained source echo. 229""" 230 231def _require(module: str, extra: str): 232 """Import ``module`` or raise a clear ImportError naming the extra to install.""" 233 try: 234 return importlib.import_module(module) 235 except ImportError as exc: 236 # Only rewrite "module is absent". A present-but-broken install (e.g. a 237 # failed C-extension load) raises ImportError from a sub-import; let its 238 # own traceback through instead of misdirecting the user to reinstall. 239 if getattr(exc, "name", None) not in (module, module.split(".")[0]): 240 raise 241 raise ImportError( 242 f"powerio needs {module!r} for this call; install it with " 243 f"`pip install 'powerio[{extra}]'`" 244 ) from exc 245 246 247def _to_csr(coo): 248 """Assemble a ``(data, row, col, shape)`` COO tuple into a csr_matrix.""" 249 sparse = _require("scipy.sparse", "matrix") 250 data, row, col, shape = coo 251 return sparse.coo_matrix((data, (row, col)), shape=shape).tocsr() 252 253 254def _dc_angles(n_buses: int, voltage_angles): 255 np = _require("numpy", "matrix") 256 angles = np.asarray(voltage_angles, dtype=float) 257 if angles.ndim != 1 or angles.shape[0] != n_buses: 258 raise ValueError( 259 f"voltage_angles must be a one dimensional array of length {n_buses}" 260 ) 261 return np, angles 262 263 264_BALANCED_DELEGATED_NAMES = frozenset( 265 { 266 "areas", 267 "base_frequency", 268 "base_mva", 269 "branches", 270 "buses", 271 "detailed_connectivity", 272 "generators", 273 "hvdc", 274 "is_radial", 275 "loads", 276 "n_areas", 277 "n_branches", 278 "n_buses", 279 "n_generators", 280 "n_hvdc", 281 "n_islands", 282 "n_lines", 283 "n_loads", 284 "n_shunts", 285 "n_static_var_compensators", 286 "n_storage", 287 "n_substations", 288 "n_switches", 289 "n_transformers_3w", 290 "name", 291 "reference_bus_index", 292 "reference_bus_indices", 293 "shunts", 294 "static_var_compensators", 295 "source_format", 296 "storage", 297 "switches", 298 "transformers_3w", 299 } 300) 301 302 303@_guard_class 304class BusMerge: 305 """The result of :meth:`BalancedNetwork.merge_buses`. 306 307 ``network`` is the merged network. ``merged_buses`` maps every merged 308 bus to the bus that now carries it, and ``groups`` lists each joined set 309 as ``{"survivor", "members"}``. ``removed_branches`` and 310 ``removed_switches`` describe every element the merge removed: its source 311 ``row``, ``id``, ``from_id`` and ``to_id`` buses, ``survivor``, ``reason`` 312 (``"zero_impedance"``, ``"closed_switch"``, or ``"shorted"``), status, and 313 ratings. ``branch_rows`` and ``switch_rows`` map each source row to its 314 merged row, or ``None`` when removed, and ``charging_shunts`` lists the 315 merged shunt rows that hold removed branches' equivalent admittances. ``diagnostics`` holds the merge's 316 findings, which the merged network's module carries as well. 317 """ 318 319 def __init__(self, inner: "_powerio._BusMerge"): 320 self._inner = inner 321 322 def __repr__(self) -> str: 323 return repr(self._inner) 324 325 @property 326 def network(self) -> "BalancedNetwork": 327 return BalancedNetwork(self._inner.network) 328 329 @property 330 def rule(self) -> str: 331 return self._inner.rule 332 333 @property 334 def merged_buses(self) -> dict[int, int]: 335 return self._inner.merged_buses 336 337 @property 338 def groups(self) -> list[dict[str, Any]]: 339 return self._inner.groups 340 341 @property 342 def removed_branches(self) -> list[dict[str, Any]]: 343 return self._inner.removed_branches 344 345 @property 346 def removed_switches(self) -> list[dict[str, Any]]: 347 return self._inner.removed_switches 348 349 @property 350 def branch_rows(self) -> list[Optional[int]]: 351 return self._inner.branch_rows 352 353 @property 354 def switch_rows(self) -> list[Optional[int]]: 355 return self._inner.switch_rows 356 357 @property 358 def charging_shunts(self) -> list[int]: 359 return self._inner.charging_shunts 360 361 @property 362 def diagnostics(self) -> list[Diagnostic]: 363 return self._inner.diagnostics 364 365 def survivor(self, bus: int) -> int: 366 """The bus that carries ``bus`` in the merged network.""" 367 return self._inner.survivor(bus) 368 369 def calc_removed_flows( 370 self, 371 branch_p_from: Any, 372 branch_p_to: Any, 373 *, 374 generator_p: Any = None, 375 transformer_3w_p: Any = None, 376 ) -> dict[str, Any]: 377 """Recover the active power on every removed element. 378 379 ``branch_p_from`` and ``branch_p_to`` are the power entering each 380 merged network branch at its from and to ends; ``generator_p`` 381 replaces the stated generator outputs, and ``transformer_3w_p`` gives 382 the power entering each three winding transformer winding from its 383 bus, three values per transformer. Values are in the network's units 384 (MW for a parsed network). The result has ``branches`` and 385 ``switches``, one ``{"p_from", "method"}`` per removed element in the 386 order of :attr:`removed_branches` and :attr:`removed_switches`, and 387 ``diagnostics``. ``method`` is ``"tree"`` where Kirchhoff's current 388 law fixes the flow, ``"reactance"`` on a loop split by reactance, 389 ``"minimum_norm"`` on a loop of zero reactance elements, and 390 ``"out_of_service"`` for an element that carries none. 391 """ 392 return self._inner.calc_removed_flows( 393 [float(p) for p in branch_p_from], 394 [float(p) for p in branch_p_to], 395 generator_p=None 396 if generator_p is None 397 else [float(p) for p in generator_p], 398 transformer_3w_p=None 399 if transformer_3w_p is None 400 else [tuple(float(p) for p in row) for row in transformer_3w_p], 401 ) 402 403 404@_guard_class 405class BalancedNetwork: 406 """A parsed balanced power network. 407 408 The data attributes (``buses``, ``branches``, ``generators``, ``loads``, 409 ``shunts``) and reference bus queries delegate to the compiled handle; the 410 matrix methods below return ``scipy.sparse`` objects. Parse and transform 411 diagnostics belong to the owning :class:`PioModule`. 412 413 Errors: a bad file path raises the standard ``OSError`` subclass 414 (``FileNotFoundError``); a malformed case raises :class:`PowerIOParseError` 415 and an unmet calculation precondition (no generators, no reference bus) raises 416 :class:`PowerIODataError`; both subclass :class:`PowerIOError`, so 417 ``except PowerIOError`` catches either; an unknown 418 ``scheme``/``formula``/``units`` string raises ``ValueError``. 419 """ 420 421 def __init__(self, inner: "_powerio._BalancedNetwork"): 422 self._inner = inner 423 424 def __dir__(self): 425 # The data attributes arrive through __getattr__, so name them here or 426 # they stay invisible to tab completion. 427 return sorted(set(super().__dir__()) | _BALANCED_DELEGATED_NAMES) 428 429 def __getattr__(self, name: str): 430 # Reached only when normal lookup misses, so the matrix methods below 431 # win. Guard underscore names so a lookup before _inner exists raises 432 # AttributeError instead of recursing forever. 433 if name not in _BALANCED_DELEGATED_NAMES: 434 raise AttributeError( 435 f"{type(self).__name__!r} object has no attribute {name!r}" 436 ) 437 value = getattr(self._inner, name) 438 # A native handle is immutable; scalar counts need no repeated FFI 439 # call. A collection entry update replaces the handle and clears them. 440 if name.startswith("n_"): 441 self.__dict__[name] = value 442 return value 443 444 def __repr__(self) -> str: 445 # The inner handle's __repr__ already renders the public ``BalancedNetwork(...)`` 446 # form, so this is a straight delegate. 447 return repr(self._inner) 448 449 def component_counts(self) -> dict[str, int]: 450 """Count native lines, generators, loads, and substations. 451 452 Lines exclude transformer branches. Loads include equivalent injections 453 represented as loads. Substations count the source hierarchy, or zero 454 when the format supplies no hierarchy. No Python table rows are built. 455 Raises ValueError for normalized networks, whose unity taps no longer 456 distinguish lines from transformers. Count the source network instead. 457 """ 458 return self._inner.component_counts() 459 460 def calc_connectivity_report(self) -> dict[str, Any]: 461 """Calculate the in-service topology summary.""" 462 return self._inner.calc_connectivity_report() 463 464 def calc_stated_state_mismatch( 465 self, 466 *, 467 top_k: int = 20, 468 hvdc: str = "fixed_injection", 469 low_impedance_threshold: float = 1e-3, 470 merge_zero_impedance: bool = False, 471 lcc_reactive_power: str = "converter_model", 472 ) -> dict[str, Any]: 473 """Evaluate every bus's AC balance at the voltages the case stores. 474 475 Each device sits at its stated output: generators at ``pg``/``qg``, 476 loads through their voltage model at the stored magnitude, shunts at 477 their stated admittance, and HVDC lines as fixed injections (or not, 478 with ``hvdc="ignore"``). A bus mismatch is the power the network draws 479 at the stored voltages minus the stated injection, MW and MVAr, so an 480 injection equal to it closes the bus. 481 482 The result holds per bus columns in analysis bus order (``bus_ids``, 483 ``island``, ``p_mw``, ``q_mvar``, and ``flags``, the attached 484 equipment a residual is traced to), ``islands`` totals largest first, 485 ``top`` (row indices of the largest mismatches), the totals, and 486 ``diagnostics`` (a warning per LCC line that kept its stated reactive 487 powers because its converter record reaches no operating point). 488 ``merge_zero_impedance`` first merges the buses joined by in-service 489 zero-impedance branches, whose flows the stored voltages cannot 490 determine; without it such a branch raises. A closed switch joining 491 two buses also raises (``BUILD.SWITCH.CLOSED``); merge it first with 492 ``merge_buses(closed_switches=True)``. ``lcc_reactive_power`` 493 selects where a PSS/E two-terminal converter's reactive demand comes 494 from: its bridge equations at the stored voltages 495 (``"converter_model"``) or the line's stated reactive powers 496 (``"stated"``). 497 """ 498 return self._inner.calc_stated_state_mismatch( 499 top_k=top_k, 500 hvdc=hvdc, 501 low_impedance_threshold=low_impedance_threshold, 502 merge_zero_impedance=merge_zero_impedance, 503 lcc_reactive_power=lcc_reactive_power, 504 ) 505 506 def calc_stated_branch_flows(self) -> dict[str, Any]: 507 """Calculate the power entering every branch end at the stored voltages. 508 509 Columns follow analysis branch order: every branch row, then the three 510 windings of each in-service three-winding transformer, as ``sources`` 511 states. Powers are MW and MVAr; an out-of-service branch carries zero. 512 """ 513 return self._inner.calc_stated_branch_flows() 514 515 def to_geo_layer(self) -> dict[str, Any]: 516 """Transform coordinates to a canonical GeoJSON FeatureCollection. 517 518 A case without coordinates produces an empty feature collection. 519 """ 520 return _json.loads(self._inner.to_geo_layer_json()) 521 522 def apply_geo_layer( 523 self, text: str, name_hint: Optional[str] = None 524 ) -> tuple["BalancedNetwork", dict[str, Any]]: 525 """Apply a geographic sidecar and return ``(placed, report)``. 526 527 ``text`` is any form :func:`parse_geo` accepts; this case is 528 unchanged. The report carries ``matched_buses``, ``matched_branches``, 529 ``unmatched_features``, ``unlocated_buses``, ``unlocated_branches``, 530 and ``notes``. The two unlocated counts cover the whole case when the 531 pass ends, so a layer that matched nothing reads apart from a case 532 that needed nothing. The placed copy drops the retained source text, 533 so a same-format emission re-serializes. 534 """ 535 inner, report = self._inner.apply_geo_layer(text, name_hint) 536 return BalancedNetwork(inner), report 537 538 def resolve_contingencies(self, text: str) -> dict[str, Any]: 539 """Read PSS/E contingency text and bind every case to this network. 540 541 ``text`` is the content of a ``.con`` file, such as 542 ``parse("cases.con").value.text``. The result carries ``cases``, 543 ``resolved``, ``unresolved``, and ``unrecognized_statements`` as 544 counts; ``case_results``, one entry per case in the file's order with 545 its ``name``, whether it ``resolved``, the ``components`` it bound to, 546 and the actions that bound to nothing as ``{"action", "reason"}``; and 547 ``diagnostics``, the reader's notes on statements it kept as text. 548 549 Each component states the ``type`` naming the table, the ``row`` it 550 occupies there, the element's own ``in_service`` flag, and the ``id`` 551 the network states for it. ``id`` is ``None`` when the network states 552 no identity for that row; ``type`` and ``row`` name the element either 553 way. 554 555 Binding reports rather than refuses, so a case naming an element this 556 network does not hold is counted unresolved and listed. 557 """ 558 return self._inner.resolve_contingencies(text) 559 560 def expand_contingencies( 561 self, con_text: str, sub_text: str 562 ) -> tuple[str, list[Diagnostic]]: 563 """Turn automatic contingency specifications into explicit cases. 564 565 ``con_text`` and ``sub_text`` are the contents of a ``.con`` and a 566 ``.sub`` file. A specification such as ``SINGLE BRANCH IN SUBSYSTEM 567 'A1'`` states a rule, so expanding it needs both the network and the 568 subsystem the ``.sub`` file names. Returns the expanded ``.con`` text, 569 which states every outage explicitly, and the notes from the two 570 readers followed by the expansion's own notes. Only elements this 571 network states in service expand into cases. 572 """ 573 return self._inner.expand_contingencies(con_text, sub_text) 574 575 def select_subsystem_buses(self, sub_text: str, name: str) -> list[int]: 576 """The bus numbers one named subsystem of ``sub_text`` selects. 577 578 ``sub_text`` is the content of a ``.sub`` file. The numbers come back 579 in ascending order. A name the file does not state raises 580 ``ValueError``. 581 """ 582 return self._inner.select_subsystem_buses(sub_text, name) 583 584 # --- matrix calculations (scipy.sparse) ----------------------------- 585 586 def calc_bprime_matrix( 587 self, scheme: str = "bx", *, skip_zero_impedance: bool = False 588 ): 589 """MATPOWER FDPF Bp matrix. ``scheme`` is ``"bx"`` or ``"xb"``. 590 591 ``skip_zero_impedance=False`` refuses a zero impedance branch 592 (``r`` and ``x`` both zero); pass ``True`` to drop it instead. 593 """ 594 return _to_csr( 595 self._inner.bprime(scheme, skip_zero_impedance=skip_zero_impedance) 596 ) 597 598 def calc_incidence_matrix( 599 self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False 600 ): 601 """Return PowerModels incidence ``A`` (branches by buses). 602 603 Rows are the in service, non self loop branches in table order 604 (three winding transformer windings follow the branches); columns 605 are every bus in table order. :meth:`calc_dc_index_map` names both 606 axes. ``skip_zero_impedance=False`` refuses a zero impedance branch; 607 ``True`` drops it from the branch axis. 608 """ 609 return _to_csr( 610 self._inner.calc_incidence_matrix( 611 formula, skip_zero_impedance=skip_zero_impedance 612 ) 613 ) 614 615 def calc_branch_susceptances( 616 self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False 617 ): 618 """Return per branch susceptances over the branch axis of 619 :meth:`calc_dc_index_map`.""" 620 np = _require("numpy", "matrix") 621 return np.asarray( 622 self._inner.calc_branch_susceptances( 623 formula, skip_zero_impedance=skip_zero_impedance 624 ), 625 dtype=float, 626 ) 627 628 def calc_branch_flow_matrix( 629 self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False 630 ): 631 """Return ``Bf = diag(b) A`` as a CSR matrix (branches by buses).""" 632 return _to_csr( 633 self._inner.calc_branch_flow_matrix( 634 formula, skip_zero_impedance=skip_zero_impedance 635 ) 636 ) 637 638 def calc_bus_susceptance_matrix( 639 self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False 640 ): 641 """Return ``B = A.T diag(b) A`` as a CSR matrix (buses by buses).""" 642 return _to_csr( 643 self._inner.calc_bus_susceptance_matrix( 644 formula, skip_zero_impedance=skip_zero_impedance 645 ) 646 ) 647 648 def calc_branch_phase_shift_injection( 649 self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False 650 ): 651 """Return ``b * shift`` over the branch axis.""" 652 np = _require("numpy", "matrix") 653 return np.asarray( 654 self._inner.calc_branch_phase_shift_injection( 655 formula, skip_zero_impedance=skip_zero_impedance 656 ), 657 dtype=float, 658 ) 659 660 def calc_bus_phase_shift_injection( 661 self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False 662 ): 663 """Return ``A.T @ (b * shift)`` over the bus axis.""" 664 np = _require("numpy", "matrix") 665 return np.asarray( 666 self._inner.calc_bus_phase_shift_injection( 667 formula, skip_zero_impedance=skip_zero_impedance 668 ), 669 dtype=float, 670 ) 671 672 def calc_branch_flow_dc( 673 self, 674 voltage_angles, 675 formula: str = "series_susceptance", 676 *, 677 skip_zero_impedance: bool = False, 678 ): 679 """Compute ``-Bf @ va + b * shift`` over the branch axis.""" 680 np, angles = _dc_angles(self.n_buses, voltage_angles) 681 return np.asarray( 682 self._inner.calc_branch_flow_dc( 683 angles.tolist(), formula, skip_zero_impedance=skip_zero_impedance 684 ), 685 dtype=float, 686 ) 687 688 def calc_bus_injection_dc( 689 self, 690 voltage_angles, 691 formula: str = "series_susceptance", 692 *, 693 skip_zero_impedance: bool = False, 694 ): 695 """Compute ``-B @ va + p_shift`` over the bus axis.""" 696 np, angles = _dc_angles(self.n_buses, voltage_angles) 697 return np.asarray( 698 self._inner.calc_bus_injection_dc( 699 angles.tolist(), formula, skip_zero_impedance=skip_zero_impedance 700 ), 701 dtype=float, 702 ) 703 704 def calc_dc_index_map( 705 self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False 706 ) -> dict[str, Any]: 707 """Return the axes every DC calculation shares. 708 709 ``bus_ids`` maps a bus axis row to the source bus id (every bus, in 710 table order). ``branch_rows`` maps a branch axis row to the position 711 in the branch table (three winding transformer windings follow the 712 branches) and ``branch_ids`` to the stable identity, the branch uid 713 when the source states one and ``branches:<row>`` otherwise; out of 714 service branches and self loops have no row. ``skipped_branch_rows`` 715 lists the zero impedance branches dropped under 716 ``skip_zero_impedance=True`` and is empty otherwise. The same 717 selection applies to :meth:`calc_ptdf` rows and :meth:`calc_lodf`. 718 """ 719 return self._inner.calc_dc_index_map( 720 formula, skip_zero_impedance=skip_zero_impedance 721 ) 722 723 def calc_bdoubleprime_matrix( 724 self, scheme: str = "bx", *, skip_zero_impedance: bool = False 725 ): 726 """MATPOWER FDPF Bpp matrix. ``scheme`` is ``"bx"`` or ``"xb"``. 727 ``skip_zero_impedance`` as in :meth:`calc_bprime_matrix`. 728 """ 729 return _to_csr( 730 self._inner.bdoubleprime(scheme, skip_zero_impedance=skip_zero_impedance) 731 ) 732 733 def calc_lacpf_matrix( 734 self, 735 *, 736 include_taps: bool = True, 737 include_shifts: bool = True, 738 skip_zero_impedance: bool = False, 739 ): 740 """LACPF 2n×2n block ``[[G, -B], [-B, -G]]``. ``skip_zero_impedance`` 741 as in :meth:`calc_bprime_matrix`.""" 742 return _to_csr( 743 self._inner.lacpf( 744 include_taps=include_taps, 745 include_shifts=include_shifts, 746 skip_zero_impedance=skip_zero_impedance, 747 ) 748 ) 749 750 def calc_adjacency_matrix(self): 751 """0/1 bus adjacency matrix.""" 752 return _to_csr(self._inner.adjacency()) 753 754 def calc_admittance_matrix( 755 self, 756 *, 757 include_taps: bool = True, 758 include_shifts: bool = True, 759 skip_zero_impedance: bool = False, 760 ): 761 """``Y_bus = G + jB`` as a complex csr_matrix. ``skip_zero_impedance`` 762 as in :meth:`calc_bprime_matrix`.""" 763 g, b = self._inner.ybus_parts( 764 include_taps=include_taps, 765 include_shifts=include_shifts, 766 skip_zero_impedance=skip_zero_impedance, 767 ) 768 g, b = _to_csr(g), _to_csr(b) 769 return (g + 1j * b).tocsr() 770 771 def calc_ptdf(self, formula: str = "series_susceptance", solver: str = "auto"): 772 """DC PTDF (m×n). ``formula`` is ``"series_susceptance"``, 773 ``"tap_adjusted_reactance"``, ``"reactance_only"``, 774 ``"tap_adjusted_series_susceptance"``, or 775 ``"series_susceptance_no_phase_shift"``. 776 777 ``solver`` is ``"auto"``, ``"dense"``, or ``"sparse"``. ``"auto"`` 778 uses the dense factorization on small cases and the sparse Cholesky 779 path on large ones, the same policy as the CLI. 780 """ 781 return _to_csr(self._inner.ptdf(formula, solver)) 782 783 def calc_lodf(self, formula: str = "series_susceptance", solver: str = "auto"): 784 """DC LODF (m×m). ``formula`` and ``solver`` as in :meth:`calc_ptdf`.""" 785 return _to_csr(self._inner.lodf(formula, solver)) 786 787 def calc_weighted_laplacian( 788 self, 789 formula: str = "series_susceptance", 790 ): 791 """Weighted Laplacian ``L = -B``. ``formula`` as in :meth:`calc_ptdf`.""" 792 return _to_csr(self._inner.weighted_laplacian(formula)) 793 794 def merge_buses( 795 self, 796 *, 797 closed_switches: bool = True, 798 zero_impedance: Optional[str] = None, 799 threshold: Optional[float] = None, 800 charging: str = "fold", 801 ) -> "BusMerge": 802 """Merge the buses closed switches and zero impedance branches join. 803 804 ``closed_switches`` merges the two buses of every closed switch. 805 ``zero_impedance`` selects the branches merged as well: ``None`` 806 merges none, ``"exact"`` merges ``r == 0`` and ``x == 0``, 807 ``"psse"`` merges non-transformer branches with ``r == 0`` and 808 ``|x| <= threshold`` (PSS/E zero impedance lines; the threshold 809 defaults to the ``THRSHZ`` the case states), and ``"impedance"`` 810 merges non-transformer branches with ``|r + jx| <= threshold``. 811 812 Each joined set keeps one bus: its reference bus, else a bus with an 813 in-service generator, else a bus a generator regulates, smallest id 814 first. Every element moves onto it. The merged elements and any 815 branch the merge shorts are removed and listed with their source rows 816 and ratings. ``charging="fold"`` turns each removed branch's line 817 charging and line shunts, including tap scaling, into a fixed shunt 818 at the survivor. ``"drop"`` discards only terminal charging. Both 819 choices preserve the series equivalent of a bypassed transformer. 820 An ideal transformer with a nonunity tap or phase shift cannot be 821 bypassed and raises an error. This network is unchanged. 822 823 Raises :class:`PowerIODataError` for a threshold that is negative or 824 not finite, or for ``"psse"`` with no threshold when the case states 825 none; an unknown rule name raises ``ValueError``. 826 """ 827 return BusMerge( 828 self._inner.merge_buses( 829 closed_switches=closed_switches, 830 zero_impedance=zero_impedance, 831 threshold=threshold, 832 charging=charging, 833 ) 834 ) 835 836 def to_normalized( 837 self, 838 *, 839 clamp_angle_bounds: bool = False, 840 angle_bound_pad: Optional[float] = None, 841 closed_switches: str = "merge", 842 island_references: str = "stated", 843 ) -> "BalancedNetwork": 844 """Return a normalized copy with per unit power and radian angles. 845 846 The result removes out of service elements, preserves source bus IDs, 847 and normalizes bus types. It carries no retained source, so 848 :func:`powerio.emit` produces a grid exchange representation from the 849 derived module. Raises 850 :class:`PowerIODataError` if the network cannot be 851 normalized (no reference bus can be chosen, or a non-positive base MVA). 852 853 ``clamp_angle_bounds=True`` applies the PowerModels angle difference 854 bound repair: limits at or beyond ``+/-pi/2`` and zero/zero windows 855 become ``[-angle_bound_pad, angle_bound_pad]``. A repair that would 856 invert the interval widens to that same window. The default pad is 857 1.0472 radians. 858 859 The default ``closed_switches="merge"`` merges the buses closed 860 switches join first, as :meth:`merge_buses` does with 861 ``closed_switches=True``, since the matrix and DC calculations model 862 no switches. ``"keep"`` leaves the switches as data, and ``"refuse"`` 863 raises :class:`PowerIODataError` with code ``BUILD.SWITCH.CLOSED``. 864 ``"merge"`` also raises that error when the merge cannot complete, 865 for example across two windings of one three winding transformer. 866 The error names the original switch row and endpoints; no partial 867 normalized network is returned. 868 869 ``island_references="per_island"`` gives every island one reference 870 bus: an island that states none takes the bus of its largest ``pmax`` 871 in-service generator, an island stating several keeps one, and an 872 island no in-service generator supplies is left out. The default 873 ``"stated"`` keeps the case's references and designates one only when 874 none survives. 875 """ 876 if ( 877 not clamp_angle_bounds 878 and angle_bound_pad is None 879 and closed_switches == "merge" 880 and island_references == "stated" 881 ): 882 return BalancedNetwork(self._inner.to_normalized()) 883 return BalancedNetwork( 884 self._inner.to_normalized_with_options( 885 clamp_angle_bounds=clamp_angle_bounds, 886 angle_bound_pad=angle_bound_pad, 887 closed_switches=closed_switches, 888 island_references=island_references, 889 ) 890 ) 891 892 def to_ppc(self): 893 """PYPOWER case dict (``ppc``) with MATPOWER-style numpy tables. 894 895 Values are emitted as the model holds them, so a case read from a 896 file carries MW, MVAr, and degrees. A network from 897 :meth:`to_normalized` holds per unit and radians, and those are what 898 its tables carry — PYPOWER reads a ppc dict as MW and degrees, so 899 build this from the raw network unless the consumer expects per unit. 900 901 Loads and shunts are summed onto their bus in the 902 ``PD``/``QD``/``GS``/``BS`` columns, the same aggregation as the 903 MATPOWER emitter. The bus table has no per element status 904 column, so an element the model marks out of service still 905 contributes its value, and a de-energized bus is carried as type 4. 906 ``gencost`` is present only when every generator carries cost data, 907 because MATPOWER requires cost rows for all generators or none. 908 :func:`from_ppc` reads the tables back. 909 910 Infinite branch ratings become PYPOWER's zero (no bound). A real 911 zero rating raises ``ValueError`` because those tables cannot state 912 a zero flow bound. 913 """ 914 np = _require("numpy", "matrix") 915 buses = self._inner.buses 916 bus = np.array( 917 [ 918 ( 919 b["id"], 920 _PPC_BUS_TYPE.get(b["kind"], 1.0), 921 0.0, 922 0.0, 923 0.0, 924 0.0, 925 b["area"], 926 b["vm"], 927 b["va"], 928 b["base_kv"], 929 b["zone"], 930 b["vmax"], 931 b["vmin"], 932 ) 933 for b in buses 934 ], 935 dtype=float, 936 ).reshape(len(buses), 13) 937 bus[:, 2], bus[:, 3], bus[:, 4], bus[:, 5] = _bus_sums( 938 np, buses, self._inner.loads, self._inner.shunts 939 ) 940 941 # The capability and ramp columns past PMIN are an OPF extension that a 942 # source need not carry. Widen to the full 21 only when a generator 943 # actually states one: a table of zeros there reads back as eleven 944 # explicit zero limits, which a ramp aware solver takes as a generator 945 # that cannot move. 946 gens = self._inner.generators 947 caps = [g["caps"] for g in gens] 948 width = 21 if any(c is not None for row in caps for c in row) else 10 949 gen = np.array( 950 [ 951 [ 952 g["bus"], 953 g["pg"], 954 g["qg"], 955 g["qmax"], 956 g["qmin"], 957 g["vg"], 958 g["mbase"], 959 float(g["in_service"]), 960 g["pmax"], 961 g["pmin"], 962 ] 963 + ([0.0 if c is None else c for c in row] if width == 21 else []) 964 for g, row in zip(gens, caps, strict=True) 965 ], 966 dtype=float, 967 ).reshape(len(gens), width) 968 969 branches = self._inner.branches 970 971 def ppc_rating(rating): 972 if rating == 0.0: 973 raise ValueError("PYPOWER's zero means no bound; it cannot represent a zero branch rating") 974 return 0.0 if rating == float("inf") else rating 975 976 branch = np.array( 977 [ 978 ( 979 br["from_id"], 980 br["to_id"], 981 br["r"], 982 br["x"], 983 br["b"], 984 ppc_rating(br["rate_a"]), 985 ppc_rating(br["rate_b"]), 986 ppc_rating(br["rate_c"]), 987 br["tap"], 988 br["shift"], 989 float(br["in_service"]), 990 br["angmin"], 991 br["angmax"], 992 ) 993 for br in branches 994 ], 995 dtype=float, 996 ).reshape(len(branches), 13) 997 998 ppc = { 999 "version": "2", 1000 "baseMVA": float(self._inner.base_mva), 1001 "bus": bus, 1002 "gen": gen, 1003 "branch": branch, 1004 } 1005 1006 # Coefficients sit left-aligned after ncost, padded to the widest 1007 # row, which is the layout PYPOWER's own loadcase produces. 1008 costs = [g["cost"] for g in gens] 1009 if costs and all(c is not None for c in costs): 1010 gencost = np.zeros((len(costs), 4 + max(len(c["coeffs"]) for c in costs))) 1011 for i, c in enumerate(costs): 1012 gencost[i, :4] = ( 1013 c["model"], 1014 c["startup"], 1015 c["shutdown"], 1016 c["ncost"], 1017 ) 1018 gencost[i, 4 : 4 + len(c["coeffs"])] = c["coeffs"] 1019 ppc["gencost"] = gencost 1020 return ppc 1021 1022 def to_networkx(self): 1023 """Undirected networkx graph keyed by bus id. 1024 1025 In-service branches become edges carrying ``branch`` (index), ``r``, 1026 ``x``, and ``b``. 1027 """ 1028 nx = _require("networkx", "graph") 1029 g = nx.Graph() 1030 g.add_nodes_from(bus["id"] for bus in self._inner.buses) 1031 for k, br in enumerate(self._inner.branches): 1032 if br["in_service"]: 1033 g.add_edge( 1034 br["from_id"], 1035 br["to_id"], 1036 branch=k, 1037 r=br["r"], 1038 x=br["x"], 1039 b=br["b"], 1040 ) 1041 return g 1042 1043 1044@_guard 1045def resolve_format(name: str) -> Optional[FormatInfo]: 1046 """Resolve a format token or common alias to its canonical metadata.""" 1047 resolved = _powerio.resolve_format(name) 1048 return None if resolved is None else FormatInfo(*resolved) 1049 1050 1051@_guard 1052def parse_geo(text: str, name_hint: Optional[str] = None) -> dict[str, Any]: 1053 """Tolerantly read a geographic sidecar and return its canonical form. 1054 1055 Accepts headerless buscoords CSV, aliased CSV/JSON records, and GeoJSON 1056 Point/LineString features. Returns ``{"geojson": <FeatureCollection dict>, 1057 "diagnostics": [...]}``; ``name_hint`` (a file name) picks CSV against JSON 1058 when the content alone is ambiguous. Input with no usable coordinates 1059 raises :class:`PowerIOParseError`. 1060 """ 1061 parsed = _powerio.parse_geo(text, name_hint) 1062 parsed["geojson"] = _json.loads(parsed["geojson"]) 1063 return parsed 1064 1065 1066# powerio bus kind -> MATPOWER/PYPOWER BUS_TYPE code. 1067def _bus_sums(np, buses, loads, shunts): 1068 """Per bus `(pd, qd, gs, bs)` in bus order. 1069 1070 :meth:`BalancedNetwork.to_ppc` folds the element 1071 tables onto their bus the way the Rust indexed analysis view does. This is 1072 that fold, once. 1073 """ 1074 row_of = {b["id"]: i for i, b in enumerate(buses)} 1075 pd, qd, gs, bs = (np.zeros(len(buses), dtype=float) for _ in range(4)) 1076 for load in loads: 1077 i = row_of.get(load["bus"]) 1078 if i is not None: 1079 pd[i] += load["p"] 1080 qd[i] += load["q"] 1081 for shunt in shunts: 1082 i = row_of.get(shunt["bus"]) 1083 if i is not None: 1084 gs[i] += shunt["g"] 1085 bs[i] += shunt["b"] 1086 return pd, qd, gs, bs 1087 1088 1089_PPC_BUS_TYPE = {"PQ": 1.0, "PV": 2.0, "REF": 3.0, "ISOLATED": 4.0} 1090 1091# MATPOWER case-input table widths. PYPOWER result tables append columns 1092# (LAM_P, MU_*) past these; from_ppc drops them. 1093_PPC_INPUT_WIDTH = {"bus": 13, "gen": 21, "branch": 13} 1094 1095# Columns a table must carry, which is what the MATPOWER reader requires. The 1096# gen table's capability and ramp columns are an OPF extension, so a 10 column 1097# gen table is a complete case and passes through at its own width; padding it 1098# would hand the reader eleven explicit zero limits the source never stated. A 1099# bus or branch row below 13 is truncated data, and zero padding it would 1100# invent a bus at 0 p.u. and 0 kV, so it is refused here as the reader refuses 1101# it in a `.m` file. 1102_PPC_MIN_WIDTH = {"bus": 13, "gen": 10, "branch": 13} 1103 1104 1105def _ppc_rows(name, table): 1106 """The table's rows as float lists, trimmed to the MATPOWER input width.""" 1107 width = _PPC_INPUT_WIDTH.get(name) 1108 minimum = _PPC_MIN_WIDTH.get(name) 1109 out = [] 1110 for i, row in enumerate(table): 1111 try: 1112 vals = [float(v) for v in row] 1113 except TypeError as e: 1114 raise ValueError( 1115 f"ppc table {name!r} row {i} is not a sequence of numbers: " 1116 f"pass a 2-D array, one row per element" 1117 ) from e 1118 except ValueError as e: 1119 raise ValueError( 1120 f"ppc table {name!r} row {i} has a non-numeric value: {e}" 1121 ) from e 1122 if minimum is not None and len(vals) < minimum: 1123 raise ValueError( 1124 f"ppc table {name!r} row {i} has {len(vals)} columns; " 1125 f"MATPOWER requires at least {minimum}" 1126 ) 1127 out.append(vals[:width] if width is not None else vals) 1128 return out 1129 1130 1131def _ppc_to_matpower_text(ppc) -> str: 1132 missing = [k for k in ("baseMVA", "bus", "gen", "branch") if k not in ppc] 1133 if missing: 1134 raise ValueError(f"ppc dict is missing required keys: {missing}") 1135 lines = [ 1136 "function mpc = from_ppc", 1137 f"mpc.version = '{ppc.get('version', '2')}';", 1138 f"mpc.baseMVA = {float(ppc['baseMVA'])!r};", 1139 ] 1140 names = ["bus", "gen", "branch"] + (["gencost"] if "gencost" in ppc else []) 1141 for name in names: 1142 rows = _ppc_rows(name, ppc[name]) 1143 lines.append(f"mpc.{name} = [") 1144 for vals in rows: 1145 lines.append(" " + " ".join(repr(v) for v in vals) + ";") 1146 lines.append("];") 1147 return "\n".join(lines) + "\n" 1148 1149 1150@_guard 1151def from_ppc(ppc) -> BalancedNetwork: 1152 """Case from a PYPOWER dict (``ppc``); the inverse of :meth:`BalancedNetwork.to_ppc`. 1153 1154 The tables route through the MATPOWER reader, so the semantics match a 1155 ``.m`` case exactly: bus ``PD``/``QD`` become loads, ``GS``/``BS`` become 1156 shunts, and ``gencost`` is read when present. Result columns past the 1157 MATPOWER input widths are dropped. A 10 column ``gen`` table (the layout 1158 without the OPF capability columns) passes through at its own width, so 1159 the generators come back with no capability limits rather than eleven 1160 zero ones. Raises :class:`ValueError` when a required table is absent, 1161 when a ``bus`` or ``branch`` row is below its 13 column width, when a row 1162 is not a sequence of numbers, or when a cell is not numeric; the message 1163 names the table and the row. 1164 """ 1165 value = parse( 1166 _io.StringIO(_ppc_to_matpower_text(ppc)), 1167 format="matpower", 1168 name="from_ppc.m", 1169 ).value 1170 assert isinstance(value, BalancedNetwork) 1171 return value 1172 1173 1174from . import dist # noqa: E402 (needs EmitResult defined above) 1175 1176MulticonductorNetwork = dist.MulticonductorNetwork 1177 1178 1179@_guard 1180def versions() -> Any: 1181 """Return the PowerIO release, the PowerIO IR identity, and BMOPF schema. 1182 1183 ``powerio_ir`` is ``{"schema": "pio-ir", "version": <release>}``: the 1184 release whose schema the documents this build writes follow. 1185 ``bmopf_schema`` is the ``$id`` of the one BMOPF schema PowerIO writes. 1186 """ 1187 return _json.loads(_powerio.versions_json()) 1188 1189 1190class _TypedValue: 1191 """Typed view rooted in its owning :class:`PioModule`.""" 1192 1193 __slots__ = ("module", "_collection_entry") 1194 1195 def __init__(self, module: "PioModule") -> None: 1196 self.module = module 1197 self._collection_entry = None 1198 1199 def __repr__(self) -> str: 1200 return f"{type(self).__name__}()" 1201 1202 1203@dataclass(frozen=True) 1204class TimePoint: 1205 label: str 1206 duration_seconds: Optional[float] = None 1207 1208 1209@dataclass(frozen=True) 1210class Scenario: 1211 id: str 1212 probability: Optional[float] = None 1213 1214 1215@dataclass(frozen=True) 1216class _CollectionEntry: 1217 root: "PioModule" 1218 time_index: Optional[int] = None 1219 scenario_id: Optional[str] = None 1220 1221 1222def _bind_collection_entry( 1223 value: Any, 1224 location: _CollectionEntry, 1225) -> Any: 1226 value._collection_entry = location 1227 return value 1228 1229 1230@_guard_class 1231class TimeSeries(_TypedValue, Sequence): 1232 """Values of one type ordered in time.""" 1233 1234 def __init__( 1235 self, 1236 values: Sequence[Any], 1237 *, 1238 time_points: Sequence[TimePoint], 1239 ) -> None: 1240 if isinstance(values, (str, bytes, bytearray)) or not isinstance( 1241 values, Sequence 1242 ): 1243 raise TypeError("TimeSeries values must be a sequence of PowerIO values") 1244 if not isinstance(time_points, Sequence): 1245 raise TypeError("time_points must be a sequence of TimePoint values") 1246 points = tuple(time_points) 1247 if not all(isinstance(point, TimePoint) for point in points): 1248 raise TypeError("time_points must contain only TimePoint values") 1249 modules = [PioModule.from_value(value)._inner for value in values] 1250 inner = _powerio._PioModule._from_time_series( 1251 modules, 1252 [(point.label, point.duration_seconds) for point in points], 1253 ) 1254 super().__init__(PioModule(inner)) 1255 1256 @classmethod 1257 def _from_module(cls, module: "PioModule") -> "TimeSeries": 1258 value = object.__new__(cls) 1259 _TypedValue.__init__(value, module) 1260 return value 1261 1262 @property 1263 def time_points(self) -> tuple[TimePoint, ...]: 1264 return tuple(TimePoint(*point) for point in self.module._inner._time_series_points()) 1265 1266 def __len__(self) -> int: 1267 return self.module._inner._time_series_len() 1268 1269 def __getitem__(self, index): 1270 if isinstance(index, slice): 1271 return [self[position] for position in range(*index.indices(len(self)))] 1272 try: 1273 position = _operator.index(index) 1274 except TypeError: 1275 raise TypeError("time series indices must be integers") from None 1276 if position < 0: 1277 position += len(self) 1278 if position < 0 or position >= len(self): 1279 raise IndexError("time series index out of range") 1280 current = self._collection_entry or _CollectionEntry(self.module) 1281 if current.time_index is not None: 1282 raise TypeError("nested TimeSeries values are not supported") 1283 value = PioModule(self.module._inner._time_series_get(position)).value 1284 return _bind_collection_entry( 1285 value, 1286 _CollectionEntry( 1287 root=current.root, 1288 time_index=position, 1289 scenario_id=current.scenario_id, 1290 ), 1291 ) 1292 1293 def __iter__(self): 1294 return (self[position] for position in range(len(self))) 1295 1296 1297@_guard_class 1298class ScenarioSet(_TypedValue, Mapping): 1299 """Named alternatives of one type, with optional probabilities.""" 1300 1301 def __init__( 1302 self, 1303 values: Mapping[str, Any], 1304 *, 1305 probabilities: Optional[Mapping[str, float]] = None, 1306 ) -> None: 1307 if not isinstance(values, Mapping): 1308 raise TypeError("ScenarioSet values must be a mapping from IDs to values") 1309 if probabilities is not None and not isinstance(probabilities, Mapping): 1310 raise TypeError("probabilities must be a mapping from scenario IDs to numbers") 1311 ids = list(values) 1312 modules = [PioModule.from_value(values[id])._inner for id in ids] 1313 inner = _powerio._PioModule._from_scenario_set( 1314 modules, 1315 ids, 1316 None if probabilities is None else dict(probabilities), 1317 ) 1318 super().__init__(PioModule(inner)) 1319 1320 @classmethod 1321 def _from_module(cls, module: "PioModule") -> "ScenarioSet": 1322 value = object.__new__(cls) 1323 _TypedValue.__init__(value, module) 1324 return value 1325 1326 @property 1327 def scenarios(self) -> tuple[Scenario, ...]: 1328 return tuple(Scenario(*entry) for entry in self.module._inner._scenario_entries()) 1329 1330 def __len__(self) -> int: 1331 return len(self.scenarios) 1332 1333 def __iter__(self): 1334 return (scenario.id for scenario in self.scenarios) 1335 1336 def __contains__(self, scenario: object) -> bool: 1337 return isinstance(scenario, str) and any( 1338 entry.id == scenario for entry in self.scenarios 1339 ) 1340 1341 def __getitem__(self, scenario: str) -> Any: 1342 if not isinstance(scenario, str): 1343 raise TypeError("scenario keys must be strings") 1344 if scenario not in self: 1345 raise KeyError(scenario) 1346 current = self._collection_entry or _CollectionEntry(self.module) 1347 if current.scenario_id is not None: 1348 raise TypeError("nested ScenarioSet values are not supported") 1349 value = PioModule(self.module._inner._scenario_get(scenario)).value 1350 return _bind_collection_entry( 1351 value, 1352 _CollectionEntry( 1353 root=current.root, 1354 time_index=current.time_index, 1355 scenario_id=scenario, 1356 ), 1357 ) 1358 1359 1360@_guard_class 1361class OperatingPoint(_TypedValue): 1362 """A possibly partial assignment over fixed equipment identities.""" 1363 1364 @property 1365 def network(self) -> "BalancedNetwork": 1366 """The balanced network this operating point is stated over. 1367 1368 The point's own values are applied to the returned copy, so it is the 1369 network a solver receives for this entry; the collection's shared 1370 base network is not changed. A multiconductor operating point raises 1371 :class:`PowerIOError`. 1372 1373 Net bus injection quantities have no balanced network field, so they 1374 are dropped here and the property reports nothing. Emit the 1375 collection when you need that omission reported: `emit` warns 1376 `EMIT.OPERATING_POINT.DATA_OMITTED` for the same point. 1377 """ 1378 return BalancedNetwork(self.module._inner._operating_point_network()) 1379 1380 1381@_guard_class 1382class _BalancedCalculation(_TypedValue): 1383 """A calculation over one shared balanced network.""" 1384 1385 @property 1386 def network(self) -> BalancedNetwork: 1387 """The balanced network used by this calculation.""" 1388 return BalancedNetwork(self.module._inner._balanced_calculation_network()) 1389 1390 1391@_guard_class 1392class _MulticonductorCalculation(_TypedValue): 1393 """A calculation over one shared multiconductor network.""" 1394 1395 @property 1396 def network(self) -> MulticonductorNetwork: 1397 """The multiconductor network used by this calculation.""" 1398 return MulticonductorNetwork( 1399 self.module._inner._multiconductor_calculation_network() 1400 ) 1401 1402 1403@_guard_class 1404class _CalculationSolution(_TypedValue): 1405 """A solution that retains the exact typed instance it solves.""" 1406 1407 @property 1408 def instance(self) -> _TypedValue: 1409 """The calculation instance solved by this result.""" 1410 return PioModule(self.module._inner._calculation_solution_instance()).value 1411 1412 1413class DcPfInstance(_BalancedCalculation): 1414 """A DC power flow calculation instance.""" 1415 1416 1417class AcPfInstance(_BalancedCalculation): 1418 """An AC power flow calculation instance.""" 1419 1420 1421class DcOpfInstance(_BalancedCalculation): 1422 """A DC optimal power flow calculation instance.""" 1423 1424 1425class AcOpfInstance(_BalancedCalculation): 1426 """An AC optimal power flow calculation instance.""" 1427 1428 1429def _branch_statuses(closed: Sequence[bool]) -> list[bool]: 1430 """A final branch status vector as a list of booleans, in branch order.""" 1431 if isinstance(closed, (str, bytes)): 1432 raise TypeError("branch statuses are a sequence of booleans") 1433 return list(closed) 1434 1435 1436@_guard_class 1437class AcOtsInstance(_BalancedCalculation): 1438 """An AC optimal transmission switching calculation instance. 1439 1440 Its network holds every candidate branch at its initial status. 1441 """ 1442 1443 @property 1444 def options(self) -> dict[str, Any]: 1445 """The switching options as stated, spelled as the keyword arguments of 1446 :meth:`PioModule.to_ac_ots_instance`: ``switchable`` (``"all"``, 1447 ``"none"``, or a list of branch identities), ``switching_costs`` 1448 (``{id: (open_cost, close_cost)}``), ``islanding``, ``max_open``, 1449 ``max_switched``, ``current_limits``, and ``stated_current_limits`` 1450 (``{id: (from_pu, to_pu)}``, ``None`` for an unbounded side). 1451 """ 1452 return self.module._inner._ac_ots_options() 1453 1454 @property 1455 def branches(self) -> list[dict[str, Any]]: 1456 """One row per physical branch, in branch table order: ``id``, 1457 ``initial_closed``, ``switchable``, ``switching_cost`` (``(open_cost, 1458 close_cost)``, or ``None`` when no cost is stated and the branch 1459 switches at zero cost), ``stated_current`` (the stated ``(from_pu, 1460 to_pu)`` limits), and ``current`` (the limits that apply under the 1461 current limit policy). ``None`` in a limit pair is unbounded. 1462 """ 1463 return self.module._inner._ac_ots_branches() 1464 1465 def validate_topology(self, closed: Sequence[bool]) -> float: 1466 """Check a final topology and return its switching cost. 1467 1468 ``closed`` holds one boolean per branch, in branch table order. The 1469 check covers the length, the branches that cannot switch, the 1470 ``max_open`` and ``max_switched`` budgets, and the islanding policy; 1471 it does not certify AC feasibility. A refused topology raises 1472 :class:`PowerIOError` with code ``BUILD.INSTANCE.TOPOLOGY_INVALID``. 1473 """ 1474 return self.module._inner._ac_ots_validate_topology(_branch_statuses(closed)) 1475 1476 def fix_topology( 1477 self, closed: Sequence[bool] 1478 ) -> tuple["AcOpfInstance", list[Diagnostic]]: 1479 """The AC optimal power flow over a final topology. 1480 1481 Every branch row stays in the network with its final status. The 1482 switching options, current limits, and switching cost term are not 1483 part of the AC optimal power flow; the returned diagnostics report 1484 each one dropped, and the instance's module carries them too. The 1485 topology is checked as :meth:`validate_topology` checks it. 1486 """ 1487 inner, diagnostics = self.module._inner._ac_ots_fix_topology( 1488 _branch_statuses(closed) 1489 ) 1490 return PioModule(inner).value, list(diagnostics) 1491 1492 1493class McAcPfInstance(_MulticonductorCalculation): 1494 """A multiconductor AC power flow calculation instance.""" 1495 1496 1497@_guard_class 1498class LinDist3FlowPfInstance(_MulticonductorCalculation): 1499 """A fixed-dispatch LinDist3Flow power-flow instance.""" 1500 1501 @property 1502 def metadata(self) -> dict[str, Any]: 1503 """Node/conductor axes, preparation actions, and reference phasors.""" 1504 return self.module._inner._lindist3flow_metadata() 1505 1506 1507@_guard_class 1508class LinDist3FlowOpfInstance(_MulticonductorCalculation): 1509 """A radial fixed-reference multiconductor linear OPF instance.""" 1510 1511 @property 1512 def metadata(self) -> dict[str, Any]: 1513 """Node and conductor axes, roots, and reference phasors in volts/radians.""" 1514 return self.module._inner._lindist3flow_metadata() 1515 1516 1517class McAcOpfInstance(_MulticonductorCalculation): 1518 """A multiconductor AC optimal power flow calculation instance.""" 1519 1520 1521@_guard_class 1522class AcScucInstance(_BalancedCalculation): 1523 """An AC security constrained unit commitment calculation instance.""" 1524 1525 @property 1526 def inputs(self) -> ScucInputs: 1527 """Scheduling, reserve, and contingency inputs.""" 1528 return self.module._inner._ac_scuc_inputs() 1529 1530 1531class DcPfSolution(_BalancedCalculation, _CalculationSolution): 1532 """A DC power flow solution.""" 1533 1534 1535class AcPfSolution(_BalancedCalculation, _CalculationSolution): 1536 """An AC power flow solution.""" 1537 1538 1539class DcOpfSolution(_BalancedCalculation, _CalculationSolution): 1540 """A DC optimal power flow solution.""" 1541 1542 1543class AcOpfSolution(_BalancedCalculation, _CalculationSolution): 1544 """An AC optimal power flow solution.""" 1545 1546 1547@_guard_class 1548class AcOtsSolution(_BalancedCalculation, _CalculationSolution): 1549 """An AC optimal transmission switching result. 1550 1551 Its network is the instance's network, with the initial branch statuses; 1552 :meth:`solved_network` gives the network with the final statuses and 1553 solved values. 1554 """ 1555 1556 @classmethod 1557 def from_ac_opf_solution( 1558 cls, 1559 instance: AcOtsInstance, 1560 closed: Sequence[bool], 1561 solution: "AcOpfSolution", 1562 ) -> "AcOtsSolution": 1563 """Attach the AC optimal power flow solution computed on 1564 ``instance.fix_topology(closed)``. 1565 1566 The topology is checked as :meth:`AcOtsInstance.validate_topology` 1567 checks it, the solution must answer exactly the fixed-topology problem 1568 (its network, objective, and constraint selections), and open branches 1569 must carry no flow. Residuals and optimality are not checked. The 1570 result's module carries the instance module's records. 1571 """ 1572 if not isinstance(instance, AcOtsInstance): 1573 raise TypeError("instance must be a powerio.AcOtsInstance") 1574 if not isinstance(solution, AcOpfSolution): 1575 raise TypeError("solution must be a powerio.AcOpfSolution") 1576 inner = instance.module._inner._ac_ots_solution( 1577 _branch_statuses(closed), solution.module._inner 1578 ) 1579 return PioModule(inner).value 1580 1581 @property 1582 def branch_closed(self) -> list[bool]: 1583 """The final branch statuses, in branch table order.""" 1584 return self.module._inner._ac_ots_solution_branch_closed() 1585 1586 @property 1587 def switching_cost(self) -> float: 1588 """The cost of the status changes against the initial topology.""" 1589 return self.module._inner._ac_ots_solution_summary()[0] 1590 1591 @property 1592 def branches_open(self) -> int: 1593 """The number of branches open in the final topology.""" 1594 return self.module._inner._ac_ots_solution_summary()[1] 1595 1596 @property 1597 def branches_switched(self) -> int: 1598 """The number of branches whose final status differs from the initial one.""" 1599 return self.module._inner._ac_ots_solution_summary()[2] 1600 1601 @property 1602 def objective(self) -> float: 1603 """The AC solution's objective, plus the switching cost when the 1604 instance's objective states the switching cost term.""" 1605 return self.module._inner._ac_ots_solution_summary()[3] 1606 1607 def solved_network(self) -> "PioModule": 1608 """The balanced network this result states: the final branch statuses 1609 with the solved bus voltages, generator dispatch, and branch flows 1610 applied, ready for :func:`emit`. The C ABI's 1611 ``pio_ac_ots_solution_materialize`` and PowerIO.jl's 1612 ``materialize_ac_ots_solution`` return the same network.""" 1613 return PioModule(self.module._inner._ac_ots_solved_network()) 1614 1615 1616class SocwrOpfSolution(_BalancedCalculation, _CalculationSolution): 1617 """A PowerModels SOCWR relaxation solution and objective lower bound.""" 1618 1619 1620class McAcPfSolution(_MulticonductorCalculation, _CalculationSolution): 1621 """A multiconductor AC power flow solution.""" 1622 1623 1624@_guard_class 1625class LinDist3FlowPfSolution(_MulticonductorCalculation, _CalculationSolution): 1626 """Fixed-dispatch LinDist3Flow values and monitored SI line limits.""" 1627 1628 @property 1629 def termination(self) -> str: 1630 """How the calculation ended.""" 1631 return self.module._inner._lindist3flow_solution_termination() 1632 1633 @property 1634 def limit_checks(self) -> list[dict[str, Any]]: 1635 """Monitored line ratings, values, loading ratios, and overload flags.""" 1636 return self.module._inner._lindist3flow_limit_checks() 1637 1638 def __getitem__(self, quantity: str) -> list[float]: 1639 """Copy one named primal column in its physical instance order.""" 1640 return self.module._inner._lindist3flow_solution_values(quantity) 1641 1642 1643@_guard_class 1644class LinDist3FlowOpfSolution(_MulticonductorCalculation, _CalculationSolution): 1645 """LinDist3Flow primal values in squared volts, watts, and vars.""" 1646 1647 @property 1648 def termination(self) -> str: 1649 """How the calculation ended.""" 1650 return self.module._inner._lindist3flow_solution_termination() 1651 1652 @property 1653 def objective(self) -> float: 1654 """The reported objective value.""" 1655 return self.module._inner._lindist3flow_solution_objective() 1656 1657 def __getitem__(self, quantity: str) -> list[float]: 1658 """Copy one named primal column in its physical instance order.""" 1659 return self.module._inner._lindist3flow_solution_values(quantity) 1660 1661 1662class McAcOpfSolution(_MulticonductorCalculation, _CalculationSolution): 1663 """A multiconductor AC optimal power flow solution.""" 1664 1665 1666@_guard_class 1667class AcScucSolution(_BalancedCalculation, _CalculationSolution): 1668 """An AC security constrained unit commitment solution.""" 1669 1670 @property 1671 def termination(self) -> str: 1672 """How the calculation ended.""" 1673 return self.module._inner._ac_scuc_solution_termination() 1674 1675 @property 1676 def residuals(self) -> Residuals: 1677 """Reported active and reactive power balance residuals.""" 1678 return self.module._inner._ac_scuc_solution_residuals() 1679 1680 @property 1681 def producer(self) -> Optional[str]: 1682 """Producer or solver identity, when recorded.""" 1683 return self.module._inner._ac_scuc_solution_producer() 1684 1685 @property 1686 def network_outputs(self) -> ScucNetworkOutputs: 1687 """Per interval network outputs.""" 1688 return self.module._inner._ac_scuc_solution_network_outputs() 1689 1690 @property 1691 def device_outputs(self) -> ScucDeviceOutputs: 1692 """Per interval dispatchable device outputs.""" 1693 return self.module._inner._ac_scuc_solution_device_outputs() 1694 1695 @property 1696 def objective(self) -> Optional[float]: 1697 """Reported objective value, when present.""" 1698 return self.module._inner._ac_scuc_solution_objective() 1699 1700 1701@_guard_class 1702class GeoLayer(_TypedValue): 1703 """A standalone geographic document: element points and routes keyed by 1704 element identity, in one coordinate space. 1705 1706 :func:`parse` returns it for the canonical ``.geo.json``, GeoJSON, aliased 1707 CSV or JSON records, headerless buscoords CSV, and a PowerWorld ``.pwd`` 1708 display. :func:`powerio.emit` writes the canonical document as 1709 ``geo-json``, and :func:`serialize` carries the layer through PowerIO IR. 1710 Place a layer onto a case with 1711 ``network.apply_geo_layer(layer.geojson)``. 1712 """ 1713 1714 @property 1715 def geojson(self) -> str: 1716 """The canonical ``.geo.json`` document for this layer.""" 1717 result = emit(self.module, "geo-json") 1718 data = result.artifacts[0].data 1719 if data is None: 1720 raise ValueError("the layer emission returned no artifact bytes") 1721 return data.decode("utf-8") 1722 1723 1724def _emitted_text(module: "PioModule[Any]", format: str) -> str: 1725 """Emit ``module`` under one token and decode the single UTF-8 artifact.""" 1726 result = emit(module, format) 1727 data = result.artifacts[0].data 1728 if data is None: 1729 raise ValueError(f"the {format} emission returned no artifact bytes") 1730 return data.decode("utf-8") 1731 1732 1733@_guard_class 1734class ContingencySet(_TypedValue): 1735 """A PSS/E contingency description file: the cases to run, the automatic 1736 specifications that state cases by rule, and the ``SKIP`` rules. 1737 1738 :func:`parse` returns it for a ``.con`` file or for text declared as 1739 ``psse-con``, :func:`powerio.emit` writes it back under that token, and 1740 :func:`serialize` carries it through PowerIO IR. Bind a set to a case with 1741 ``network.resolve_contingencies(cases.text)`` and turn its automatic 1742 specifications into explicit cases with 1743 ``network.expand_contingencies(cases.text, groups.text)``. 1744 """ 1745 1746 @property 1747 def text(self) -> str: 1748 """The ``.con`` text for this set.""" 1749 return _emitted_text(self.module, "psse-con") 1750 1751 1752@_guard_class 1753class SubsystemSet(_TypedValue): 1754 """A PSS/E subsystem description file: the named bus groups a contingency 1755 run and a monitored element file draw on. 1756 1757 :func:`parse` returns it for a ``.sub`` file or for text declared as 1758 ``psse-sub``, and ``network.select_subsystem_buses(groups.text, name)`` 1759 names the buses one subsystem selects. 1760 """ 1761 1762 @property 1763 def text(self) -> str: 1764 """The ``.sub`` text for this set.""" 1765 return _emitted_text(self.module, "psse-sub") 1766 1767 1768@_guard_class 1769class MonitoredSet(_TypedValue): 1770 """A PSS/E monitored element file: the branches, interfaces, and voltage 1771 scopes a contingency run reports on. 1772 1773 :func:`parse` returns it for a ``.mon`` file or for text declared as 1774 ``psse-mon``. 1775 """ 1776 1777 @property 1778 def text(self) -> str: 1779 """The ``.mon`` text for this set.""" 1780 return _emitted_text(self.module, "psse-mon") 1781 1782 1783_VALUE_CLASSES: dict[str, type[_TypedValue]] = { 1784 "powerio.ContingencySet": ContingencySet, 1785 "powerio.GeoLayer": GeoLayer, 1786 "powerio.MonitoredSet": MonitoredSet, 1787 "powerio.SubsystemSet": SubsystemSet, 1788 "powerio.OperatingPoint<powerio.BalancedNetwork>": OperatingPoint, 1789 "powerio.OperatingPoint<powerio.MulticonductorNetwork>": OperatingPoint, 1790 "powerio.DcPfInstance": DcPfInstance, 1791 "powerio.AcPfInstance": AcPfInstance, 1792 "powerio.DcOpfInstance": DcOpfInstance, 1793 "powerio.AcOpfInstance": AcOpfInstance, 1794 "powerio.AcOtsInstance": AcOtsInstance, 1795 "powerio.McAcPfInstance": McAcPfInstance, 1796 "powerio.McAcOpfInstance": McAcOpfInstance, 1797 "powerio.LinDist3FlowPfInstance": LinDist3FlowPfInstance, 1798 "powerio.LinDist3FlowOpfInstance": LinDist3FlowOpfInstance, 1799 "powerio.AcScucInstance": AcScucInstance, 1800 "powerio.DcPfSolution": DcPfSolution, 1801 "powerio.AcPfSolution": AcPfSolution, 1802 "powerio.DcOpfSolution": DcOpfSolution, 1803 "powerio.AcOpfSolution": AcOpfSolution, 1804 "powerio.AcOtsSolution": AcOtsSolution, 1805 "powerio.SocwrOpfSolution": SocwrOpfSolution, 1806 "powerio.McAcPfSolution": McAcPfSolution, 1807 "powerio.McAcOpfSolution": McAcOpfSolution, 1808 "powerio.LinDist3FlowPfSolution": LinDist3FlowPfSolution, 1809 "powerio.LinDist3FlowOpfSolution": LinDist3FlowOpfSolution, 1810 "powerio.AcScucSolution": AcScucSolution, 1811} 1812 1813 1814@_guard_class 1815class PioModule: 1816 """One typed value with diagnostics, producer, sources, source mappings, 1817 history, and extensions. 1818 """ 1819 1820 def __init__(self, inner: "_powerio._PioModule"): 1821 self._inner = inner 1822 1823 def sever_source(self) -> "PioModule": 1824 """Copy this module without retained input bytes, forcing fresh emission. 1825 1826 The original module is unchanged. Values, diagnostics, source 1827 descriptors, and history are preserved; preparing the copy has a cost 1828 separate from emission. 1829 """ 1830 return PioModule(self._inner.sever_source()) 1831 1832 @classmethod 1833 def from_value(cls, value: Any) -> "PioModule": 1834 """Wrap an existing typed value without serializing it.""" 1835 if isinstance(value, BalancedNetwork): 1836 return cls(_powerio._PioModule.from_balanced_network(value._inner)) 1837 if isinstance(value, dist.MulticonductorNetwork): 1838 return cls(_powerio._PioModule.from_multiconductor_network(value._inner)) 1839 if isinstance(value, _TypedValue): 1840 location = value._collection_entry 1841 inner = value.module._inner 1842 if location is not None: 1843 inner = location.root._inner 1844 if location.scenario_id is not None: 1845 inner = inner._scenario_get(location.scenario_id) 1846 if location.time_index is not None: 1847 inner = inner._time_series_get(location.time_index) 1848 return cls(inner._copy()) 1849 raise TypeError("PioModule.from_value expects a typed PowerIO value") 1850 1851 @property 1852 def value(self) -> Any: 1853 """The contained typed value.""" 1854 type_name = self._inner._type_name 1855 if type_name == "powerio.BalancedNetwork": 1856 return BalancedNetwork(self._inner.as_balanced_network()) 1857 if type_name == "powerio.MulticonductorNetwork": 1858 return dist.MulticonductorNetwork(self._inner.as_multiconductor_network()) 1859 if type_name.startswith("powerio.TimeSeries<"): 1860 return TimeSeries._from_module(self) 1861 if type_name.startswith("powerio.ScenarioSet<"): 1862 return ScenarioSet._from_module(self) 1863 value_class = _VALUE_CLASSES.get(type_name) 1864 if value_class is None: 1865 raise RuntimeError(f"this binding has no Python class for {type_name}") 1866 return value_class(self) 1867 1868 @property 1869 def type_name(self) -> str: 1870 """The canonical structural name of the contained value, such as 1871 ``powerio.OperatingPoint<powerio.BalancedNetwork>``. The C ABI and 1872 PowerIO IR name the same type with the same string. 1873 """ 1874 return str(self._inner._type_name) 1875 1876 @property 1877 def diagnostics(self) -> list[Diagnostic]: 1878 """The diagnostics stored on this module, in encounter order.""" 1879 return list(self._inner.diagnostics) 1880 1881 @property 1882 def extension_keys(self) -> list[str]: 1883 """The namespaces of the extensions this module carries, sorted.""" 1884 return list(self._inner._extension_keys) 1885 1886 def extension(self, namespace: str) -> Any: 1887 """The JSON value stored under ``namespace``, or ``None``. 1888 1889 Only that value is decoded; the module is not serialized. 1890 """ 1891 text = self._inner._extension_json(namespace) 1892 return None if text is None else _json.loads(text) 1893 1894 def with_extension(self, namespace: str, value: Any) -> "PioModule": 1895 """A copy of this module carrying ``value`` under ``namespace``. 1896 1897 ``value`` must be JSON serializable. The copy keeps the typed value, 1898 diagnostics, sources, and history without serializing them; an 1899 extension already stored under ``namespace`` is replaced. The original 1900 module is unchanged. 1901 """ 1902 return PioModule(self._inner._with_extension_json(namespace, _json.dumps(value))) 1903 1904 def to_balanced_report(self, base_mva: float = 100.0) -> Any: 1905 """Report whether a multiconductor network can become balanced.""" 1906 return _json.loads(self._inner.lowering_readiness_json(base_mva)) 1907 1908 def to_balanced(self, base_mva: float = 100.0) -> "PioModule": 1909 """Transform a multiconductor network to a balanced module.""" 1910 return PioModule(self._inner.lower_to_balanced(base_mva)) 1911 1912 def to_dc_pf_instance(self) -> "PioModule": 1913 """Build a DC power flow instance from a balanced network module.""" 1914 return PioModule(self._inner._to_dc_pf_instance()) 1915 1916 def to_ac_pf_instance(self) -> "PioModule": 1917 """Build an AC power flow instance from a balanced network module.""" 1918 return PioModule(self._inner._to_ac_pf_instance()) 1919 1920 def to_dc_opf_instance(self) -> "PioModule": 1921 """Build a DC optimal power flow instance from a balanced network module.""" 1922 return PioModule(self._inner._to_dc_opf_instance()) 1923 1924 def to_ac_opf_instance(self) -> "PioModule": 1925 """Build an AC optimal power flow instance from a balanced network module.""" 1926 return PioModule(self._inner._to_ac_opf_instance()) 1927 1928 def to_ac_ots_instance( 1929 self, 1930 *, 1931 switchable: Union[str, Sequence[str], None] = None, 1932 switching_costs: Optional[Mapping[str, tuple[float, float]]] = None, 1933 islanding: Optional[str] = None, 1934 max_open: Optional[int] = None, 1935 max_switched: Optional[int] = None, 1936 current_limits: Optional[str] = None, 1937 stated_current_limits: Optional[ 1938 Mapping[str, tuple[Optional[float], Optional[float]]] 1939 ] = None, 1940 ) -> "PioModule": 1941 """Build an AC optimal transmission switching instance from a balanced 1942 network, AC optimal power flow, or AC optimal transmission switching 1943 module. 1944 1945 With no option, this gives the default instance: every initially 1946 in-service branch may switch, at zero cost, islanding is forbidden, 1947 there is no budget and no current limit, and the objective gains the 1948 switching cost term. An AC optimal transmission switching module comes 1949 back unchanged. 1950 1951 Any option makes the options explicit, as the C ABI's options struct 1952 and PowerIO.jl's ``AcOtsOptions`` do, and an option not given takes 1953 its explicit default: 1954 1955 - ``switchable``: ``"all"`` (the default, which includes initially 1956 open branches), ``"none"``, or a list of branch identities. 1957 - ``switching_costs``: ``{branch_id: (open_cost, close_cost)}``; a 1958 branch with no entry switches at zero cost. 1959 - ``islanding``: ``"forbidden"`` (the default) or ``"allowed"``. 1960 - ``max_open``: the most branches open in the final topology, 1961 counting fixed open rows; ``None`` is no budget. 1962 - ``max_switched``: the most status changes; ``None`` is no budget. 1963 - ``current_limits``: ``"skip"`` (the default), ``"stated"``, or 1964 ``"derive_from_rate_a"``. 1965 - ``stated_current_limits``: ``{branch_id: (from_pu, to_pu)}``, per 1966 unit; ``None`` on a side is unbounded. 1967 1968 The base problem and objective are kept, and the objective gains the 1969 switching cost term once. Refused options raise 1970 :class:`PowerIOError` with code 1971 ``BUILD.INSTANCE.SWITCHING_OPTIONS_INVALID``; an unknown policy name 1972 raises :class:`ValueError`. 1973 """ 1974 if ( 1975 switchable is None 1976 and switching_costs is None 1977 and islanding is None 1978 and max_open is None 1979 and max_switched is None 1980 and current_limits is None 1981 and stated_current_limits is None 1982 ): 1983 return PioModule(self._inner._to_ac_ots_instance()) 1984 if switchable is None: 1985 selection, identities = "all", [] 1986 elif isinstance(switchable, str): 1987 selection, identities = switchable, [] 1988 else: 1989 selection, identities = "only", [str(identity) for identity in switchable] 1990 for name, budget in (("max_open", max_open), ("max_switched", max_switched)): 1991 if budget is not None and ( 1992 isinstance(budget, bool) or not isinstance(budget, int) or budget < 0 1993 ): 1994 raise ValueError(f"{name} must be a nonnegative integer or None") 1995 costs = [ 1996 (str(identity), float(open_cost), float(close_cost)) 1997 for identity, (open_cost, close_cost) in (switching_costs or {}).items() 1998 ] 1999 limits = [ 2000 ( 2001 str(identity), 2002 None if from_pu is None else float(from_pu), 2003 None if to_pu is None else float(to_pu), 2004 ) 2005 for identity, (from_pu, to_pu) in (stated_current_limits or {}).items() 2006 ] 2007 return PioModule( 2008 self._inner._to_ac_ots_instance_with_options( 2009 selection, 2010 identities, 2011 costs, 2012 "forbidden" if islanding is None else islanding, 2013 max_open, 2014 max_switched, 2015 "skip" if current_limits is None else current_limits, 2016 limits, 2017 ) 2018 ) 2019 2020 def to_mc_ac_pf_instance(self) -> "PioModule": 2021 """Build a multiconductor AC power flow instance from a network module.""" 2022 return PioModule(self._inner._to_mc_ac_pf_instance()) 2023 2024 def to_mc_ac_opf_instance(self) -> "PioModule": 2025 """Build a multiconductor AC optimal power flow instance from a network module.""" 2026 return PioModule(self._inner._to_mc_ac_opf_instance()) 2027 2028 def to_lindist3flow_opf_instance(self) -> "PioModule": 2029 """Build a LinDist3Flow optimal power flow instance from a network module.""" 2030 return PioModule(self._inner._to_lindist3flow_opf_instance()) 2031 2032 def to_lindist3flow_pf_instance(self) -> "PioModule": 2033 """Build a fixed-dispatch LinDist3Flow instance from a network module.""" 2034 return PioModule(self._inner._to_lindist3flow_pf_instance()) 2035 2036 def __repr__(self) -> str: 2037 return repr(self._inner) 2038 2039 2040def _selected_collection_value(location: _CollectionEntry) -> Any: 2041 value = location.root.value 2042 time_index = location.time_index 2043 scenario_id = location.scenario_id 2044 while time_index is not None or scenario_id is not None: 2045 if isinstance(value, TimeSeries) and time_index is not None: 2046 value = value[time_index] 2047 time_index = None 2048 elif isinstance(value, ScenarioSet) and scenario_id is not None: 2049 value = value[scenario_id] 2050 scenario_id = None 2051 elif time_index is not None: 2052 raise TypeError("the selected value is not a TimeSeries") 2053 else: 2054 raise TypeError("the selected value is not a ScenarioSet") 2055 return value 2056 2057 2058def _refresh_collection_entry(target: Any, location: _CollectionEntry) -> None: 2059 refreshed = _selected_collection_value(location) 2060 if type(refreshed) is not type(target): 2061 raise RuntimeError("a collection update changed the entry type") 2062 if isinstance(target, BalancedNetwork): 2063 target._inner = refreshed._inner 2064 # Counts cached from the replaced handle may no longer hold, for 2065 # example the island count after a branch status update. 2066 for name in [name for name in vars(target) if name.startswith("n_")]: 2067 del target.__dict__[name] 2068 elif isinstance(target, dist.MulticonductorNetwork): 2069 target._inner = refreshed._inner 2070 elif isinstance(target, _TypedValue): 2071 target.module = refreshed.module 2072 target._collection_entry = refreshed._collection_entry 2073 else: 2074 raise TypeError("the selected value does not support typed updates") 2075 2076 2077@_guard 2078def apply_updates( 2079 target: Any, 2080 updates: Union[ 2081 Iterable[OperatingPointUpdate], 2082 Iterable[NetworkUpdate], 2083 Iterable[CalculationUpdate], 2084 ], 2085) -> UpdateReport: 2086 """Validate and apply one batch of typed updates atomically. 2087 2088 ``updates`` contains one update class: :class:`OperatingPointUpdate`, 2089 :class:`NetworkUpdate`, or :class:`CalculationUpdate`. Values are absolute 2090 replacements and power quantities carry their units in the typed value. 2091 ``target`` is a module or a value obtained by indexing a :class:`TimeSeries` 2092 or :class:`ScenarioSet`. If validation fails, the module is unchanged. 2093 """ 2094 batch = list(updates) 2095 if isinstance(target, PioModule): 2096 return target._inner._apply_updates(batch) 2097 location = getattr(target, "_collection_entry", None) 2098 if not isinstance(location, _CollectionEntry): 2099 raise TypeError( 2100 "target must be a PioModule or a TimeSeries/ScenarioSet entry" 2101 ) 2102 report = location.root._inner._apply_collection_updates( 2103 batch, 2104 time_index=location.time_index, 2105 scenario_id=location.scenario_id, 2106 ) 2107 _refresh_collection_entry(target, location) 2108 return report 2109 2110 2111@_guard 2112def apply_bus_load_active_power( 2113 module: PioModule, 2114 bus_id: int, 2115 total: ActivePower, 2116 *, 2117 allocation: str = "proportional_to_current_active_power", 2118) -> UpdateReport: 2119 """Replace aggregate bus demand through an explicit PowerIO allocation rule. 2120 2121 ``"proportional_to_current_active_power"`` preserves each participating 2122 load's current share. ``"equal"`` gives every participating load the same 2123 share, including when their current aggregate demand is zero. PowerIO 2124 requires stable load IDs and reports each load changed. 2125 """ 2126 if not isinstance(module, PioModule): 2127 raise TypeError("module must be a PioModule") 2128 if not isinstance(total, ActivePower): 2129 raise TypeError("total must be an ActivePower") 2130 return module._inner._apply_bus_load_active_power( 2131 bus_id, 2132 total, 2133 allocation=allocation, 2134 ) 2135 2136 2137def _path_from_source(source: Any) -> Optional[str]: 2138 if isinstance(source, str): 2139 return source 2140 if isinstance(source, (bytes, bytearray, memoryview)): 2141 return None 2142 try: 2143 path = _os.fspath(source) 2144 except TypeError: 2145 return None 2146 if isinstance(path, bytes): 2147 raise TypeError("a path-like source must return str, not bytes") 2148 return path 2149 2150 2151def _memory_from_source(source: Any, name: Optional[str]) -> tuple[bytes, str]: 2152 if isinstance(source, (bytes, bytearray, memoryview)): 2153 data = bytes(source) 2154 else: 2155 read = getattr(source, "read", None) 2156 if read is None: 2157 raise TypeError( 2158 "source must be a path, file object, or bytes-like object" 2159 ) 2160 data = read() 2161 if isinstance(data, str): 2162 data = data.encode("utf-8") 2163 elif isinstance(data, (bytes, bytearray, memoryview)): 2164 data = bytes(data) 2165 else: 2166 raise TypeError("source.read() must return str or bytes-like data") 2167 if name is None: 2168 candidate = getattr(source, "name", None) 2169 try: 2170 candidate = _os.fspath(candidate) if candidate is not None else None 2171 except TypeError: 2172 candidate = None 2173 name = candidate if isinstance(candidate, str) else "<memory>" 2174 if not isinstance(name, str): 2175 raise TypeError("name must be a string") 2176 return data, name 2177 2178 2179@_guard 2180def parse( 2181 source: Any, 2182 *, 2183 format: Optional[str] = None, 2184 name: Optional[str] = None, 2185 sincal_multiconductor: Optional[dist.SincalReadOptions] = None, 2186 sincal_balanced: Optional[SincalBalancedReadOptions] = None, 2187 acquisition_root: Optional[Any] = None, 2188 named_buffers: Optional[Mapping[str, bytes]] = None, 2189 dss_max_include_bytes: Optional[int] = None, 2190 dss_max_properties: Optional[int] = None, 2191) -> PioModule: 2192 """Parse a path, file object, or bytes-like source. 2193 2194 A string is always a path. Pass raw text through ``io.StringIO`` or 2195 another file object. ``sincal_multiconductor`` requires explicit format 2196 ``sincal-multiconductor``; ``sincal_balanced`` requires ``sincal-balanced``. 2197 File companions stay beneath the file's parent, 2198 or an explicitly selected ``acquisition_root``. Memory sources use only 2199 ``named_buffers`` and never acquire companions from the filesystem. 2200 2201 ``dss_max_include_bytes`` and ``dss_max_properties`` raise two limits of 2202 an OpenDSS read for a case too large for the defaults: the bytes it may 2203 pull in through includes (64 MiB) and the property assignments and edit 2204 records it may retain (4,194,304). They have no effect on other formats. 2205 """ 2206 dss_limits = None 2207 for limit_name, limit in (("dss_max_include_bytes", dss_max_include_bytes), ("dss_max_properties", dss_max_properties)): 2208 if limit is None: 2209 continue 2210 if isinstance(limit, bool) or not isinstance(limit, int): 2211 raise TypeError(f"{limit_name} must be an integer") 2212 if limit < 0: 2213 raise ValueError(f"{limit_name} must not be negative") 2214 dss_limits = (dss_max_include_bytes, dss_max_properties) 2215 from . import _sienna_files 2216 if format is not None and format in _sienna_files.FORMATS: 2217 if sincal_balanced is not None or sincal_multiconductor is not None: 2218 raise ValueError("SINCAL options do not apply to Sienna bundles") 2219 return _sienna_files.parse(source, format, name=name, acquisition_root=acquisition_root, named_buffers=named_buffers) 2220 from . import _pypsa_files 2221 binary_format = _pypsa_files.detect(source, format) 2222 if binary_format is not None: 2223 if named_buffers is not None or acquisition_root is not None or sincal_balanced is not None or sincal_multiconductor is not None: 2224 raise ValueError("PyPSA binary containers are standalone sources") 2225 if name is not None and _path_from_source(source) is not None: 2226 raise ValueError("name is only valid for memory and file object sources") 2227 return _pypsa_files.parse(source, binary_format, name=name) 2228 balanced_selection, selection = _native_selections(sincal_balanced, sincal_multiconductor) 2229 path = _path_from_source(source) 2230 if path is not None: 2231 if name is not None: 2232 raise ValueError("name is only valid for memory and file object sources") 2233 if named_buffers is not None: 2234 raise ValueError("named_buffers applies only to memory and file object sources") 2235 root = _path_from_source(acquisition_root) if acquisition_root is not None else None 2236 if acquisition_root is not None and root is None: 2237 raise TypeError("acquisition_root must be a path") 2238 return PioModule(_powerio._PioModule._parse_path(path, format, selection, root, balanced_selection, dss_limits)) 2239 if acquisition_root is not None: 2240 raise ValueError("acquisition_root applies only to path sources") 2241 buffers = None 2242 if named_buffers is not None: 2243 if not isinstance(named_buffers, Mapping): 2244 raise TypeError("named_buffers must map relative names to bytes-like data") 2245 buffers = [] 2246 for buffer_name, buffer_data in named_buffers.items(): 2247 if not isinstance(buffer_name, str) or not isinstance(buffer_data, (bytes, bytearray, memoryview)): 2248 raise TypeError("named_buffers must map relative names to bytes-like data") 2249 buffers.append((buffer_name, bytes(buffer_data))) 2250 data, source_name = _memory_from_source(source, name) 2251 return PioModule(_powerio._PioModule._parse_memory(data, source_name, format, selection, buffers, balanced_selection, dss_limits)) 2252 2253 2254def _result_from_native(result: dict[str, Any]) -> EmitResult: 2255 return EmitResult( 2256 artifacts=tuple(Artifact(**artifact) for artifact in result["artifacts"]), 2257 layout=result["layout"], 2258 fidelity=result["fidelity"], 2259 diagnostics=tuple(result["diagnostics"]), 2260 ) 2261 2262 2263def _emit_to_destination( 2264 module: PioModule, 2265 destination: Optional[Any], 2266 memory_call: Any, 2267 path_call: Any, 2268) -> EmitResult: 2269 if not isinstance(module, PioModule): 2270 raise TypeError("module must be a PioModule") 2271 if destination is None: 2272 return _result_from_native(memory_call()) 2273 path = _path_from_source(destination) 2274 if path is not None: 2275 return _result_from_native(path_call(path)) 2276 write = getattr(destination, "write", None) 2277 if write is None: 2278 raise TypeError("destination must be a path or writable file object") 2279 result = _result_from_native(memory_call()) 2280 if result.layout != "file" or len(result.artifacts) != 1: 2281 raise ValueError("a directory emission requires a path destination") 2282 data = result.artifacts[0].data 2283 if data is None: 2284 raise ValueError("the emission returned no artifact bytes to write") 2285 # A text mode stream takes str and a binary one takes bytes. Ask a real 2286 # stream which it is rather than writing bytes and retrying on TypeError: 2287 # a TypeError raised inside the stream's own write would otherwise trigger 2288 # a second, partially duplicated write. A duck typed sink states neither, 2289 # so it keeps the retry. 2290 if isinstance(destination, _io.TextIOBase) or isinstance( 2291 getattr(destination, "encoding", None), str 2292 ): 2293 write(data.decode("utf-8")) 2294 elif isinstance(destination, (_io.RawIOBase, _io.BufferedIOBase)): 2295 write(data) 2296 else: 2297 try: 2298 write(data) 2299 except TypeError: 2300 write(data.decode("utf-8")) 2301 return result 2302 2303 2304@_guard 2305def emit(module: PioModule, format: str, destination: Optional[Any] = None) -> EmitResult: 2306 """Emit a module as one grid exchange format.""" 2307 from . import _sienna_files 2308 if format is not None and format in _sienna_files.FORMATS: 2309 return _sienna_files.emit(module, format, destination) 2310 from . import _pypsa_files 2311 if format in _pypsa_files.FORMATS: 2312 if not isinstance(module, PioModule): 2313 raise TypeError("module must be a PioModule") 2314 return _pypsa_files.emit(module, format, destination) 2315 return _emit_to_destination( 2316 module, 2317 destination, 2318 lambda: module._inner._emit_memory(format), 2319 lambda path: module._inner._emit_path(format, path), 2320 ) 2321 2322 2323@_guard 2324def serialize(module: PioModule, destination: Optional[Any] = None) -> EmitResult: 2325 """Serialize a module as PowerIO IR.""" 2326 return _emit_to_destination( 2327 module, 2328 destination, 2329 module._inner._serialize_memory, 2330 module._inner._serialize_path, 2331 ) 2332 2333 2334@_guard 2335def deserialize(source: Any) -> PioModule: 2336 """Deserialize PowerIO IR from a path, file object, or bytes-like source.""" 2337 path = _path_from_source(source) 2338 if path is not None: 2339 return PioModule(_powerio._PioModule._deserialize_path(path)) 2340 data, _ = _memory_from_source(source, None) 2341 return PioModule(_powerio._PioModule._deserialize_memory(data)) 2342 2343 2344@_guard 2345def features() -> dict[str, bool]: 2346 """The build-time features compiled into this powerio installation. 2347 2348 ``matrix``, ``dist``, and ``prob`` are unconditional dependencies of the 2349 extension and are always ``True``. ``gridfm`` reports whether GridFM 2350 Parquet parsing and emission were compiled in; the published wheel 2351 includes them, while a custom source build can omit them. 2352 """ 2353 return { 2354 "matrix": True, 2355 "gridfm": bool(getattr(_powerio, "_has_gridfm", False)), 2356 "dist": True, 2357 "prob": True, 2358 } 2359 2360 2361@_guard 2362def diagnostic_record(diagnostic: Diagnostic) -> dict[str, Any]: 2363 """One diagnostic as a JSON-ready dictionary. 2364 2365 ``code``, ``severity``, ``message``, and ``target`` are always present, in 2366 that order. ``id``, ``suggested_action``, and ``related`` follow when the 2367 diagnostic sets them, ``details`` when it is not ``None``, and ``spans`` 2368 as ``source``, ``byte_start``, ``byte_end`` dictionaries when the 2369 diagnostic carries at least one span. 2370 """ 2371 record: dict[str, Any] = { 2372 "code": diagnostic.code, 2373 "severity": diagnostic.severity, 2374 "message": diagnostic.message, 2375 "target": diagnostic.target, 2376 } 2377 if diagnostic.id: 2378 record["id"] = diagnostic.id 2379 if diagnostic.suggested_action: 2380 record["suggested_action"] = diagnostic.suggested_action 2381 if diagnostic.related: 2382 record["related"] = list(diagnostic.related) 2383 if diagnostic.details is not None: 2384 record["details"] = diagnostic.details 2385 if diagnostic.spans: 2386 record["spans"] = [ 2387 { 2388 "source": span.source, 2389 "byte_start": span.byte_start, 2390 "byte_end": span.byte_end, 2391 } 2392 for span in diagnostic.spans 2393 ] 2394 return record 2395 2396 2397@_guard 2398def diagnostic_records(diagnostics: Iterable[Diagnostic]) -> list[dict[str, Any]]: 2399 """Every diagnostic as a JSON-ready dictionary, in the order given.""" 2400 return [diagnostic_record(item) for item in diagnostics]
1426class AcOpfInstance(_BalancedCalculation): 1427 """An AC optimal power flow calculation instance."""
An AC optimal power flow calculation instance.
Inherited Members
1544class AcOpfSolution(_BalancedCalculation, _CalculationSolution): 1545 """An AC optimal power flow solution."""
An AC optimal power flow solution.
Inherited Members
1437@_guard_class 1438class AcOtsInstance(_BalancedCalculation): 1439 """An AC optimal transmission switching calculation instance. 1440 1441 Its network holds every candidate branch at its initial status. 1442 """ 1443 1444 @property 1445 def options(self) -> dict[str, Any]: 1446 """The switching options as stated, spelled as the keyword arguments of 1447 :meth:`PioModule.to_ac_ots_instance`: ``switchable`` (``"all"``, 1448 ``"none"``, or a list of branch identities), ``switching_costs`` 1449 (``{id: (open_cost, close_cost)}``), ``islanding``, ``max_open``, 1450 ``max_switched``, ``current_limits``, and ``stated_current_limits`` 1451 (``{id: (from_pu, to_pu)}``, ``None`` for an unbounded side). 1452 """ 1453 return self.module._inner._ac_ots_options() 1454 1455 @property 1456 def branches(self) -> list[dict[str, Any]]: 1457 """One row per physical branch, in branch table order: ``id``, 1458 ``initial_closed``, ``switchable``, ``switching_cost`` (``(open_cost, 1459 close_cost)``, or ``None`` when no cost is stated and the branch 1460 switches at zero cost), ``stated_current`` (the stated ``(from_pu, 1461 to_pu)`` limits), and ``current`` (the limits that apply under the 1462 current limit policy). ``None`` in a limit pair is unbounded. 1463 """ 1464 return self.module._inner._ac_ots_branches() 1465 1466 def validate_topology(self, closed: Sequence[bool]) -> float: 1467 """Check a final topology and return its switching cost. 1468 1469 ``closed`` holds one boolean per branch, in branch table order. The 1470 check covers the length, the branches that cannot switch, the 1471 ``max_open`` and ``max_switched`` budgets, and the islanding policy; 1472 it does not certify AC feasibility. A refused topology raises 1473 :class:`PowerIOError` with code ``BUILD.INSTANCE.TOPOLOGY_INVALID``. 1474 """ 1475 return self.module._inner._ac_ots_validate_topology(_branch_statuses(closed)) 1476 1477 def fix_topology( 1478 self, closed: Sequence[bool] 1479 ) -> tuple["AcOpfInstance", list[Diagnostic]]: 1480 """The AC optimal power flow over a final topology. 1481 1482 Every branch row stays in the network with its final status. The 1483 switching options, current limits, and switching cost term are not 1484 part of the AC optimal power flow; the returned diagnostics report 1485 each one dropped, and the instance's module carries them too. The 1486 topology is checked as :meth:`validate_topology` checks it. 1487 """ 1488 inner, diagnostics = self.module._inner._ac_ots_fix_topology( 1489 _branch_statuses(closed) 1490 ) 1491 return PioModule(inner).value, list(diagnostics)
An AC optimal transmission switching calculation instance.
Its network holds every candidate branch at its initial status.
1444 @property 1445 def options(self) -> dict[str, Any]: 1446 """The switching options as stated, spelled as the keyword arguments of 1447 :meth:`PioModule.to_ac_ots_instance`: ``switchable`` (``"all"``, 1448 ``"none"``, or a list of branch identities), ``switching_costs`` 1449 (``{id: (open_cost, close_cost)}``), ``islanding``, ``max_open``, 1450 ``max_switched``, ``current_limits``, and ``stated_current_limits`` 1451 (``{id: (from_pu, to_pu)}``, ``None`` for an unbounded side). 1452 """ 1453 return self.module._inner._ac_ots_options()
The switching options as stated, spelled as the keyword arguments of
PioModule.to_ac_ots_instance(): switchable ("all",
"none", or a list of branch identities), switching_costs
({id: (open_cost, close_cost)}), islanding, max_open,
max_switched, current_limits, and stated_current_limits
({id: (from_pu, to_pu)}, None for an unbounded side).
1455 @property 1456 def branches(self) -> list[dict[str, Any]]: 1457 """One row per physical branch, in branch table order: ``id``, 1458 ``initial_closed``, ``switchable``, ``switching_cost`` (``(open_cost, 1459 close_cost)``, or ``None`` when no cost is stated and the branch 1460 switches at zero cost), ``stated_current`` (the stated ``(from_pu, 1461 to_pu)`` limits), and ``current`` (the limits that apply under the 1462 current limit policy). ``None`` in a limit pair is unbounded. 1463 """ 1464 return self.module._inner._ac_ots_branches()
One row per physical branch, in branch table order: id,
initial_closed, switchable, switching_cost ((open_cost,
close_cost), or None when no cost is stated and the branch
switches at zero cost), stated_current (the stated (from_pu,
to_pu) limits), and current (the limits that apply under the
current limit policy). None in a limit pair is unbounded.
1466 def validate_topology(self, closed: Sequence[bool]) -> float: 1467 """Check a final topology and return its switching cost. 1468 1469 ``closed`` holds one boolean per branch, in branch table order. The 1470 check covers the length, the branches that cannot switch, the 1471 ``max_open`` and ``max_switched`` budgets, and the islanding policy; 1472 it does not certify AC feasibility. A refused topology raises 1473 :class:`PowerIOError` with code ``BUILD.INSTANCE.TOPOLOGY_INVALID``. 1474 """ 1475 return self.module._inner._ac_ots_validate_topology(_branch_statuses(closed))
Check a final topology and return its switching cost.
closed holds one boolean per branch, in branch table order. The
check covers the length, the branches that cannot switch, the
max_open and max_switched budgets, and the islanding policy;
it does not certify AC feasibility. A refused topology raises
PowerIOError with code BUILD.INSTANCE.TOPOLOGY_INVALID.
1477 def fix_topology( 1478 self, closed: Sequence[bool] 1479 ) -> tuple["AcOpfInstance", list[Diagnostic]]: 1480 """The AC optimal power flow over a final topology. 1481 1482 Every branch row stays in the network with its final status. The 1483 switching options, current limits, and switching cost term are not 1484 part of the AC optimal power flow; the returned diagnostics report 1485 each one dropped, and the instance's module carries them too. The 1486 topology is checked as :meth:`validate_topology` checks it. 1487 """ 1488 inner, diagnostics = self.module._inner._ac_ots_fix_topology( 1489 _branch_statuses(closed) 1490 ) 1491 return PioModule(inner).value, list(diagnostics)
The AC optimal power flow over a final topology.
Every branch row stays in the network with its final status. The
switching options, current limits, and switching cost term are not
part of the AC optimal power flow; the returned diagnostics report
each one dropped, and the instance's module carries them too. The
topology is checked as validate_topology() checks it.
Inherited Members
1548@_guard_class 1549class AcOtsSolution(_BalancedCalculation, _CalculationSolution): 1550 """An AC optimal transmission switching result. 1551 1552 Its network is the instance's network, with the initial branch statuses; 1553 :meth:`solved_network` gives the network with the final statuses and 1554 solved values. 1555 """ 1556 1557 @classmethod 1558 def from_ac_opf_solution( 1559 cls, 1560 instance: AcOtsInstance, 1561 closed: Sequence[bool], 1562 solution: "AcOpfSolution", 1563 ) -> "AcOtsSolution": 1564 """Attach the AC optimal power flow solution computed on 1565 ``instance.fix_topology(closed)``. 1566 1567 The topology is checked as :meth:`AcOtsInstance.validate_topology` 1568 checks it, the solution must answer exactly the fixed-topology problem 1569 (its network, objective, and constraint selections), and open branches 1570 must carry no flow. Residuals and optimality are not checked. The 1571 result's module carries the instance module's records. 1572 """ 1573 if not isinstance(instance, AcOtsInstance): 1574 raise TypeError("instance must be a powerio.AcOtsInstance") 1575 if not isinstance(solution, AcOpfSolution): 1576 raise TypeError("solution must be a powerio.AcOpfSolution") 1577 inner = instance.module._inner._ac_ots_solution( 1578 _branch_statuses(closed), solution.module._inner 1579 ) 1580 return PioModule(inner).value 1581 1582 @property 1583 def branch_closed(self) -> list[bool]: 1584 """The final branch statuses, in branch table order.""" 1585 return self.module._inner._ac_ots_solution_branch_closed() 1586 1587 @property 1588 def switching_cost(self) -> float: 1589 """The cost of the status changes against the initial topology.""" 1590 return self.module._inner._ac_ots_solution_summary()[0] 1591 1592 @property 1593 def branches_open(self) -> int: 1594 """The number of branches open in the final topology.""" 1595 return self.module._inner._ac_ots_solution_summary()[1] 1596 1597 @property 1598 def branches_switched(self) -> int: 1599 """The number of branches whose final status differs from the initial one.""" 1600 return self.module._inner._ac_ots_solution_summary()[2] 1601 1602 @property 1603 def objective(self) -> float: 1604 """The AC solution's objective, plus the switching cost when the 1605 instance's objective states the switching cost term.""" 1606 return self.module._inner._ac_ots_solution_summary()[3] 1607 1608 def solved_network(self) -> "PioModule": 1609 """The balanced network this result states: the final branch statuses 1610 with the solved bus voltages, generator dispatch, and branch flows 1611 applied, ready for :func:`emit`. The C ABI's 1612 ``pio_ac_ots_solution_materialize`` and PowerIO.jl's 1613 ``materialize_ac_ots_solution`` return the same network.""" 1614 return PioModule(self.module._inner._ac_ots_solved_network())
An AC optimal transmission switching result.
Its network is the instance's network, with the initial branch statuses;
solved_network() gives the network with the final statuses and
solved values.
1557 @classmethod 1558 def from_ac_opf_solution( 1559 cls, 1560 instance: AcOtsInstance, 1561 closed: Sequence[bool], 1562 solution: "AcOpfSolution", 1563 ) -> "AcOtsSolution": 1564 """Attach the AC optimal power flow solution computed on 1565 ``instance.fix_topology(closed)``. 1566 1567 The topology is checked as :meth:`AcOtsInstance.validate_topology` 1568 checks it, the solution must answer exactly the fixed-topology problem 1569 (its network, objective, and constraint selections), and open branches 1570 must carry no flow. Residuals and optimality are not checked. The 1571 result's module carries the instance module's records. 1572 """ 1573 if not isinstance(instance, AcOtsInstance): 1574 raise TypeError("instance must be a powerio.AcOtsInstance") 1575 if not isinstance(solution, AcOpfSolution): 1576 raise TypeError("solution must be a powerio.AcOpfSolution") 1577 inner = instance.module._inner._ac_ots_solution( 1578 _branch_statuses(closed), solution.module._inner 1579 ) 1580 return PioModule(inner).value
Attach the AC optimal power flow solution computed on
instance.fix_topology(closed).
The topology is checked as AcOtsInstance.validate_topology()
checks it, the solution must answer exactly the fixed-topology problem
(its network, objective, and constraint selections), and open branches
must carry no flow. Residuals and optimality are not checked. The
result's module carries the instance module's records.
1582 @property 1583 def branch_closed(self) -> list[bool]: 1584 """The final branch statuses, in branch table order.""" 1585 return self.module._inner._ac_ots_solution_branch_closed()
The final branch statuses, in branch table order.
1587 @property 1588 def switching_cost(self) -> float: 1589 """The cost of the status changes against the initial topology.""" 1590 return self.module._inner._ac_ots_solution_summary()[0]
The cost of the status changes against the initial topology.
1592 @property 1593 def branches_open(self) -> int: 1594 """The number of branches open in the final topology.""" 1595 return self.module._inner._ac_ots_solution_summary()[1]
The number of branches open in the final topology.
1597 @property 1598 def branches_switched(self) -> int: 1599 """The number of branches whose final status differs from the initial one.""" 1600 return self.module._inner._ac_ots_solution_summary()[2]
The number of branches whose final status differs from the initial one.
1602 @property 1603 def objective(self) -> float: 1604 """The AC solution's objective, plus the switching cost when the 1605 instance's objective states the switching cost term.""" 1606 return self.module._inner._ac_ots_solution_summary()[3]
The AC solution's objective, plus the switching cost when the instance's objective states the switching cost term.
1608 def solved_network(self) -> "PioModule": 1609 """The balanced network this result states: the final branch statuses 1610 with the solved bus voltages, generator dispatch, and branch flows 1611 applied, ready for :func:`emit`. The C ABI's 1612 ``pio_ac_ots_solution_materialize`` and PowerIO.jl's 1613 ``materialize_ac_ots_solution`` return the same network.""" 1614 return PioModule(self.module._inner._ac_ots_solved_network())
The balanced network this result states: the final branch statuses
with the solved bus voltages, generator dispatch, and branch flows
applied, ready for emit(). The C ABI's
pio_ac_ots_solution_materialize and PowerIO.jl's
materialize_ac_ots_solution return the same network.
Inherited Members
An AC power flow calculation instance.
Inherited Members
1536class AcPfSolution(_BalancedCalculation, _CalculationSolution): 1537 """An AC power flow solution."""
An AC power flow solution.
Inherited Members
1522@_guard_class 1523class AcScucInstance(_BalancedCalculation): 1524 """An AC security constrained unit commitment calculation instance.""" 1525 1526 @property 1527 def inputs(self) -> ScucInputs: 1528 """Scheduling, reserve, and contingency inputs.""" 1529 return self.module._inner._ac_scuc_inputs()
An AC security constrained unit commitment calculation instance.
1526 @property 1527 def inputs(self) -> ScucInputs: 1528 """Scheduling, reserve, and contingency inputs.""" 1529 return self.module._inner._ac_scuc_inputs()
Scheduling, reserve, and contingency inputs.
Inherited Members
1667@_guard_class 1668class AcScucSolution(_BalancedCalculation, _CalculationSolution): 1669 """An AC security constrained unit commitment solution.""" 1670 1671 @property 1672 def termination(self) -> str: 1673 """How the calculation ended.""" 1674 return self.module._inner._ac_scuc_solution_termination() 1675 1676 @property 1677 def residuals(self) -> Residuals: 1678 """Reported active and reactive power balance residuals.""" 1679 return self.module._inner._ac_scuc_solution_residuals() 1680 1681 @property 1682 def producer(self) -> Optional[str]: 1683 """Producer or solver identity, when recorded.""" 1684 return self.module._inner._ac_scuc_solution_producer() 1685 1686 @property 1687 def network_outputs(self) -> ScucNetworkOutputs: 1688 """Per interval network outputs.""" 1689 return self.module._inner._ac_scuc_solution_network_outputs() 1690 1691 @property 1692 def device_outputs(self) -> ScucDeviceOutputs: 1693 """Per interval dispatchable device outputs.""" 1694 return self.module._inner._ac_scuc_solution_device_outputs() 1695 1696 @property 1697 def objective(self) -> Optional[float]: 1698 """Reported objective value, when present.""" 1699 return self.module._inner._ac_scuc_solution_objective()
An AC security constrained unit commitment solution.
1671 @property 1672 def termination(self) -> str: 1673 """How the calculation ended.""" 1674 return self.module._inner._ac_scuc_solution_termination()
How the calculation ended.
1676 @property 1677 def residuals(self) -> Residuals: 1678 """Reported active and reactive power balance residuals.""" 1679 return self.module._inner._ac_scuc_solution_residuals()
Reported active and reactive power balance residuals.
1681 @property 1682 def producer(self) -> Optional[str]: 1683 """Producer or solver identity, when recorded.""" 1684 return self.module._inner._ac_scuc_solution_producer()
Producer or solver identity, when recorded.
1686 @property 1687 def network_outputs(self) -> ScucNetworkOutputs: 1688 """Per interval network outputs.""" 1689 return self.module._inner._ac_scuc_solution_network_outputs()
Per interval network outputs.
1691 @property 1692 def device_outputs(self) -> ScucDeviceOutputs: 1693 """Per interval dispatchable device outputs.""" 1694 return self.module._inner._ac_scuc_solution_device_outputs()
Per interval dispatchable device outputs.
1696 @property 1697 def objective(self) -> Optional[float]: 1698 """Reported objective value, when present.""" 1699 return self.module._inner._ac_scuc_solution_objective()
Reported objective value, when present.
Inherited Members
184@dataclass(frozen=True) 185class Artifact: 186 """One artifact produced by :func:`emit` or :func:`serialize`. 187 188 ``data`` is set for an in-memory result. ``path`` is set after committing 189 to a filesystem destination. 190 """ 191 192 name: str 193 data: Optional[bytes] 194 path: Optional[str] 195 196 @property 197 def text(self) -> str: 198 """Decode an in-memory UTF-8 artifact.""" 199 if self.data is None: 200 raise ValueError("this artifact was committed to a destination") 201 return self.data.decode("utf-8")
One artifact produced by emit() or serialize().
data is set for an in-memory result. path is set after committing
to a filesystem destination.
405@_guard_class 406class BalancedNetwork: 407 """A parsed balanced power network. 408 409 The data attributes (``buses``, ``branches``, ``generators``, ``loads``, 410 ``shunts``) and reference bus queries delegate to the compiled handle; the 411 matrix methods below return ``scipy.sparse`` objects. Parse and transform 412 diagnostics belong to the owning :class:`PioModule`. 413 414 Errors: a bad file path raises the standard ``OSError`` subclass 415 (``FileNotFoundError``); a malformed case raises :class:`PowerIOParseError` 416 and an unmet calculation precondition (no generators, no reference bus) raises 417 :class:`PowerIODataError`; both subclass :class:`PowerIOError`, so 418 ``except PowerIOError`` catches either; an unknown 419 ``scheme``/``formula``/``units`` string raises ``ValueError``. 420 """ 421 422 def __init__(self, inner: "_powerio._BalancedNetwork"): 423 self._inner = inner 424 425 def __dir__(self): 426 # The data attributes arrive through __getattr__, so name them here or 427 # they stay invisible to tab completion. 428 return sorted(set(super().__dir__()) | _BALANCED_DELEGATED_NAMES) 429 430 def __getattr__(self, name: str): 431 # Reached only when normal lookup misses, so the matrix methods below 432 # win. Guard underscore names so a lookup before _inner exists raises 433 # AttributeError instead of recursing forever. 434 if name not in _BALANCED_DELEGATED_NAMES: 435 raise AttributeError( 436 f"{type(self).__name__!r} object has no attribute {name!r}" 437 ) 438 value = getattr(self._inner, name) 439 # A native handle is immutable; scalar counts need no repeated FFI 440 # call. A collection entry update replaces the handle and clears them. 441 if name.startswith("n_"): 442 self.__dict__[name] = value 443 return value 444 445 def __repr__(self) -> str: 446 # The inner handle's __repr__ already renders the public ``BalancedNetwork(...)`` 447 # form, so this is a straight delegate. 448 return repr(self._inner) 449 450 def component_counts(self) -> dict[str, int]: 451 """Count native lines, generators, loads, and substations. 452 453 Lines exclude transformer branches. Loads include equivalent injections 454 represented as loads. Substations count the source hierarchy, or zero 455 when the format supplies no hierarchy. No Python table rows are built. 456 Raises ValueError for normalized networks, whose unity taps no longer 457 distinguish lines from transformers. Count the source network instead. 458 """ 459 return self._inner.component_counts() 460 461 def calc_connectivity_report(self) -> dict[str, Any]: 462 """Calculate the in-service topology summary.""" 463 return self._inner.calc_connectivity_report() 464 465 def calc_stated_state_mismatch( 466 self, 467 *, 468 top_k: int = 20, 469 hvdc: str = "fixed_injection", 470 low_impedance_threshold: float = 1e-3, 471 merge_zero_impedance: bool = False, 472 lcc_reactive_power: str = "converter_model", 473 ) -> dict[str, Any]: 474 """Evaluate every bus's AC balance at the voltages the case stores. 475 476 Each device sits at its stated output: generators at ``pg``/``qg``, 477 loads through their voltage model at the stored magnitude, shunts at 478 their stated admittance, and HVDC lines as fixed injections (or not, 479 with ``hvdc="ignore"``). A bus mismatch is the power the network draws 480 at the stored voltages minus the stated injection, MW and MVAr, so an 481 injection equal to it closes the bus. 482 483 The result holds per bus columns in analysis bus order (``bus_ids``, 484 ``island``, ``p_mw``, ``q_mvar``, and ``flags``, the attached 485 equipment a residual is traced to), ``islands`` totals largest first, 486 ``top`` (row indices of the largest mismatches), the totals, and 487 ``diagnostics`` (a warning per LCC line that kept its stated reactive 488 powers because its converter record reaches no operating point). 489 ``merge_zero_impedance`` first merges the buses joined by in-service 490 zero-impedance branches, whose flows the stored voltages cannot 491 determine; without it such a branch raises. A closed switch joining 492 two buses also raises (``BUILD.SWITCH.CLOSED``); merge it first with 493 ``merge_buses(closed_switches=True)``. ``lcc_reactive_power`` 494 selects where a PSS/E two-terminal converter's reactive demand comes 495 from: its bridge equations at the stored voltages 496 (``"converter_model"``) or the line's stated reactive powers 497 (``"stated"``). 498 """ 499 return self._inner.calc_stated_state_mismatch( 500 top_k=top_k, 501 hvdc=hvdc, 502 low_impedance_threshold=low_impedance_threshold, 503 merge_zero_impedance=merge_zero_impedance, 504 lcc_reactive_power=lcc_reactive_power, 505 ) 506 507 def calc_stated_branch_flows(self) -> dict[str, Any]: 508 """Calculate the power entering every branch end at the stored voltages. 509 510 Columns follow analysis branch order: every branch row, then the three 511 windings of each in-service three-winding transformer, as ``sources`` 512 states. Powers are MW and MVAr; an out-of-service branch carries zero. 513 """ 514 return self._inner.calc_stated_branch_flows() 515 516 def to_geo_layer(self) -> dict[str, Any]: 517 """Transform coordinates to a canonical GeoJSON FeatureCollection. 518 519 A case without coordinates produces an empty feature collection. 520 """ 521 return _json.loads(self._inner.to_geo_layer_json()) 522 523 def apply_geo_layer( 524 self, text: str, name_hint: Optional[str] = None 525 ) -> tuple["BalancedNetwork", dict[str, Any]]: 526 """Apply a geographic sidecar and return ``(placed, report)``. 527 528 ``text`` is any form :func:`parse_geo` accepts; this case is 529 unchanged. The report carries ``matched_buses``, ``matched_branches``, 530 ``unmatched_features``, ``unlocated_buses``, ``unlocated_branches``, 531 and ``notes``. The two unlocated counts cover the whole case when the 532 pass ends, so a layer that matched nothing reads apart from a case 533 that needed nothing. The placed copy drops the retained source text, 534 so a same-format emission re-serializes. 535 """ 536 inner, report = self._inner.apply_geo_layer(text, name_hint) 537 return BalancedNetwork(inner), report 538 539 def resolve_contingencies(self, text: str) -> dict[str, Any]: 540 """Read PSS/E contingency text and bind every case to this network. 541 542 ``text`` is the content of a ``.con`` file, such as 543 ``parse("cases.con").value.text``. The result carries ``cases``, 544 ``resolved``, ``unresolved``, and ``unrecognized_statements`` as 545 counts; ``case_results``, one entry per case in the file's order with 546 its ``name``, whether it ``resolved``, the ``components`` it bound to, 547 and the actions that bound to nothing as ``{"action", "reason"}``; and 548 ``diagnostics``, the reader's notes on statements it kept as text. 549 550 Each component states the ``type`` naming the table, the ``row`` it 551 occupies there, the element's own ``in_service`` flag, and the ``id`` 552 the network states for it. ``id`` is ``None`` when the network states 553 no identity for that row; ``type`` and ``row`` name the element either 554 way. 555 556 Binding reports rather than refuses, so a case naming an element this 557 network does not hold is counted unresolved and listed. 558 """ 559 return self._inner.resolve_contingencies(text) 560 561 def expand_contingencies( 562 self, con_text: str, sub_text: str 563 ) -> tuple[str, list[Diagnostic]]: 564 """Turn automatic contingency specifications into explicit cases. 565 566 ``con_text`` and ``sub_text`` are the contents of a ``.con`` and a 567 ``.sub`` file. A specification such as ``SINGLE BRANCH IN SUBSYSTEM 568 'A1'`` states a rule, so expanding it needs both the network and the 569 subsystem the ``.sub`` file names. Returns the expanded ``.con`` text, 570 which states every outage explicitly, and the notes from the two 571 readers followed by the expansion's own notes. Only elements this 572 network states in service expand into cases. 573 """ 574 return self._inner.expand_contingencies(con_text, sub_text) 575 576 def select_subsystem_buses(self, sub_text: str, name: str) -> list[int]: 577 """The bus numbers one named subsystem of ``sub_text`` selects. 578 579 ``sub_text`` is the content of a ``.sub`` file. The numbers come back 580 in ascending order. A name the file does not state raises 581 ``ValueError``. 582 """ 583 return self._inner.select_subsystem_buses(sub_text, name) 584 585 # --- matrix calculations (scipy.sparse) ----------------------------- 586 587 def calc_bprime_matrix( 588 self, scheme: str = "bx", *, skip_zero_impedance: bool = False 589 ): 590 """MATPOWER FDPF Bp matrix. ``scheme`` is ``"bx"`` or ``"xb"``. 591 592 ``skip_zero_impedance=False`` refuses a zero impedance branch 593 (``r`` and ``x`` both zero); pass ``True`` to drop it instead. 594 """ 595 return _to_csr( 596 self._inner.bprime(scheme, skip_zero_impedance=skip_zero_impedance) 597 ) 598 599 def calc_incidence_matrix( 600 self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False 601 ): 602 """Return PowerModels incidence ``A`` (branches by buses). 603 604 Rows are the in service, non self loop branches in table order 605 (three winding transformer windings follow the branches); columns 606 are every bus in table order. :meth:`calc_dc_index_map` names both 607 axes. ``skip_zero_impedance=False`` refuses a zero impedance branch; 608 ``True`` drops it from the branch axis. 609 """ 610 return _to_csr( 611 self._inner.calc_incidence_matrix( 612 formula, skip_zero_impedance=skip_zero_impedance 613 ) 614 ) 615 616 def calc_branch_susceptances( 617 self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False 618 ): 619 """Return per branch susceptances over the branch axis of 620 :meth:`calc_dc_index_map`.""" 621 np = _require("numpy", "matrix") 622 return np.asarray( 623 self._inner.calc_branch_susceptances( 624 formula, skip_zero_impedance=skip_zero_impedance 625 ), 626 dtype=float, 627 ) 628 629 def calc_branch_flow_matrix( 630 self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False 631 ): 632 """Return ``Bf = diag(b) A`` as a CSR matrix (branches by buses).""" 633 return _to_csr( 634 self._inner.calc_branch_flow_matrix( 635 formula, skip_zero_impedance=skip_zero_impedance 636 ) 637 ) 638 639 def calc_bus_susceptance_matrix( 640 self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False 641 ): 642 """Return ``B = A.T diag(b) A`` as a CSR matrix (buses by buses).""" 643 return _to_csr( 644 self._inner.calc_bus_susceptance_matrix( 645 formula, skip_zero_impedance=skip_zero_impedance 646 ) 647 ) 648 649 def calc_branch_phase_shift_injection( 650 self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False 651 ): 652 """Return ``b * shift`` over the branch axis.""" 653 np = _require("numpy", "matrix") 654 return np.asarray( 655 self._inner.calc_branch_phase_shift_injection( 656 formula, skip_zero_impedance=skip_zero_impedance 657 ), 658 dtype=float, 659 ) 660 661 def calc_bus_phase_shift_injection( 662 self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False 663 ): 664 """Return ``A.T @ (b * shift)`` over the bus axis.""" 665 np = _require("numpy", "matrix") 666 return np.asarray( 667 self._inner.calc_bus_phase_shift_injection( 668 formula, skip_zero_impedance=skip_zero_impedance 669 ), 670 dtype=float, 671 ) 672 673 def calc_branch_flow_dc( 674 self, 675 voltage_angles, 676 formula: str = "series_susceptance", 677 *, 678 skip_zero_impedance: bool = False, 679 ): 680 """Compute ``-Bf @ va + b * shift`` over the branch axis.""" 681 np, angles = _dc_angles(self.n_buses, voltage_angles) 682 return np.asarray( 683 self._inner.calc_branch_flow_dc( 684 angles.tolist(), formula, skip_zero_impedance=skip_zero_impedance 685 ), 686 dtype=float, 687 ) 688 689 def calc_bus_injection_dc( 690 self, 691 voltage_angles, 692 formula: str = "series_susceptance", 693 *, 694 skip_zero_impedance: bool = False, 695 ): 696 """Compute ``-B @ va + p_shift`` over the bus axis.""" 697 np, angles = _dc_angles(self.n_buses, voltage_angles) 698 return np.asarray( 699 self._inner.calc_bus_injection_dc( 700 angles.tolist(), formula, skip_zero_impedance=skip_zero_impedance 701 ), 702 dtype=float, 703 ) 704 705 def calc_dc_index_map( 706 self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False 707 ) -> dict[str, Any]: 708 """Return the axes every DC calculation shares. 709 710 ``bus_ids`` maps a bus axis row to the source bus id (every bus, in 711 table order). ``branch_rows`` maps a branch axis row to the position 712 in the branch table (three winding transformer windings follow the 713 branches) and ``branch_ids`` to the stable identity, the branch uid 714 when the source states one and ``branches:<row>`` otherwise; out of 715 service branches and self loops have no row. ``skipped_branch_rows`` 716 lists the zero impedance branches dropped under 717 ``skip_zero_impedance=True`` and is empty otherwise. The same 718 selection applies to :meth:`calc_ptdf` rows and :meth:`calc_lodf`. 719 """ 720 return self._inner.calc_dc_index_map( 721 formula, skip_zero_impedance=skip_zero_impedance 722 ) 723 724 def calc_bdoubleprime_matrix( 725 self, scheme: str = "bx", *, skip_zero_impedance: bool = False 726 ): 727 """MATPOWER FDPF Bpp matrix. ``scheme`` is ``"bx"`` or ``"xb"``. 728 ``skip_zero_impedance`` as in :meth:`calc_bprime_matrix`. 729 """ 730 return _to_csr( 731 self._inner.bdoubleprime(scheme, skip_zero_impedance=skip_zero_impedance) 732 ) 733 734 def calc_lacpf_matrix( 735 self, 736 *, 737 include_taps: bool = True, 738 include_shifts: bool = True, 739 skip_zero_impedance: bool = False, 740 ): 741 """LACPF 2n×2n block ``[[G, -B], [-B, -G]]``. ``skip_zero_impedance`` 742 as in :meth:`calc_bprime_matrix`.""" 743 return _to_csr( 744 self._inner.lacpf( 745 include_taps=include_taps, 746 include_shifts=include_shifts, 747 skip_zero_impedance=skip_zero_impedance, 748 ) 749 ) 750 751 def calc_adjacency_matrix(self): 752 """0/1 bus adjacency matrix.""" 753 return _to_csr(self._inner.adjacency()) 754 755 def calc_admittance_matrix( 756 self, 757 *, 758 include_taps: bool = True, 759 include_shifts: bool = True, 760 skip_zero_impedance: bool = False, 761 ): 762 """``Y_bus = G + jB`` as a complex csr_matrix. ``skip_zero_impedance`` 763 as in :meth:`calc_bprime_matrix`.""" 764 g, b = self._inner.ybus_parts( 765 include_taps=include_taps, 766 include_shifts=include_shifts, 767 skip_zero_impedance=skip_zero_impedance, 768 ) 769 g, b = _to_csr(g), _to_csr(b) 770 return (g + 1j * b).tocsr() 771 772 def calc_ptdf(self, formula: str = "series_susceptance", solver: str = "auto"): 773 """DC PTDF (m×n). ``formula`` is ``"series_susceptance"``, 774 ``"tap_adjusted_reactance"``, ``"reactance_only"``, 775 ``"tap_adjusted_series_susceptance"``, or 776 ``"series_susceptance_no_phase_shift"``. 777 778 ``solver`` is ``"auto"``, ``"dense"``, or ``"sparse"``. ``"auto"`` 779 uses the dense factorization on small cases and the sparse Cholesky 780 path on large ones, the same policy as the CLI. 781 """ 782 return _to_csr(self._inner.ptdf(formula, solver)) 783 784 def calc_lodf(self, formula: str = "series_susceptance", solver: str = "auto"): 785 """DC LODF (m×m). ``formula`` and ``solver`` as in :meth:`calc_ptdf`.""" 786 return _to_csr(self._inner.lodf(formula, solver)) 787 788 def calc_weighted_laplacian( 789 self, 790 formula: str = "series_susceptance", 791 ): 792 """Weighted Laplacian ``L = -B``. ``formula`` as in :meth:`calc_ptdf`.""" 793 return _to_csr(self._inner.weighted_laplacian(formula)) 794 795 def merge_buses( 796 self, 797 *, 798 closed_switches: bool = True, 799 zero_impedance: Optional[str] = None, 800 threshold: Optional[float] = None, 801 charging: str = "fold", 802 ) -> "BusMerge": 803 """Merge the buses closed switches and zero impedance branches join. 804 805 ``closed_switches`` merges the two buses of every closed switch. 806 ``zero_impedance`` selects the branches merged as well: ``None`` 807 merges none, ``"exact"`` merges ``r == 0`` and ``x == 0``, 808 ``"psse"`` merges non-transformer branches with ``r == 0`` and 809 ``|x| <= threshold`` (PSS/E zero impedance lines; the threshold 810 defaults to the ``THRSHZ`` the case states), and ``"impedance"`` 811 merges non-transformer branches with ``|r + jx| <= threshold``. 812 813 Each joined set keeps one bus: its reference bus, else a bus with an 814 in-service generator, else a bus a generator regulates, smallest id 815 first. Every element moves onto it. The merged elements and any 816 branch the merge shorts are removed and listed with their source rows 817 and ratings. ``charging="fold"`` turns each removed branch's line 818 charging and line shunts, including tap scaling, into a fixed shunt 819 at the survivor. ``"drop"`` discards only terminal charging. Both 820 choices preserve the series equivalent of a bypassed transformer. 821 An ideal transformer with a nonunity tap or phase shift cannot be 822 bypassed and raises an error. This network is unchanged. 823 824 Raises :class:`PowerIODataError` for a threshold that is negative or 825 not finite, or for ``"psse"`` with no threshold when the case states 826 none; an unknown rule name raises ``ValueError``. 827 """ 828 return BusMerge( 829 self._inner.merge_buses( 830 closed_switches=closed_switches, 831 zero_impedance=zero_impedance, 832 threshold=threshold, 833 charging=charging, 834 ) 835 ) 836 837 def to_normalized( 838 self, 839 *, 840 clamp_angle_bounds: bool = False, 841 angle_bound_pad: Optional[float] = None, 842 closed_switches: str = "merge", 843 island_references: str = "stated", 844 ) -> "BalancedNetwork": 845 """Return a normalized copy with per unit power and radian angles. 846 847 The result removes out of service elements, preserves source bus IDs, 848 and normalizes bus types. It carries no retained source, so 849 :func:`powerio.emit` produces a grid exchange representation from the 850 derived module. Raises 851 :class:`PowerIODataError` if the network cannot be 852 normalized (no reference bus can be chosen, or a non-positive base MVA). 853 854 ``clamp_angle_bounds=True`` applies the PowerModels angle difference 855 bound repair: limits at or beyond ``+/-pi/2`` and zero/zero windows 856 become ``[-angle_bound_pad, angle_bound_pad]``. A repair that would 857 invert the interval widens to that same window. The default pad is 858 1.0472 radians. 859 860 The default ``closed_switches="merge"`` merges the buses closed 861 switches join first, as :meth:`merge_buses` does with 862 ``closed_switches=True``, since the matrix and DC calculations model 863 no switches. ``"keep"`` leaves the switches as data, and ``"refuse"`` 864 raises :class:`PowerIODataError` with code ``BUILD.SWITCH.CLOSED``. 865 ``"merge"`` also raises that error when the merge cannot complete, 866 for example across two windings of one three winding transformer. 867 The error names the original switch row and endpoints; no partial 868 normalized network is returned. 869 870 ``island_references="per_island"`` gives every island one reference 871 bus: an island that states none takes the bus of its largest ``pmax`` 872 in-service generator, an island stating several keeps one, and an 873 island no in-service generator supplies is left out. The default 874 ``"stated"`` keeps the case's references and designates one only when 875 none survives. 876 """ 877 if ( 878 not clamp_angle_bounds 879 and angle_bound_pad is None 880 and closed_switches == "merge" 881 and island_references == "stated" 882 ): 883 return BalancedNetwork(self._inner.to_normalized()) 884 return BalancedNetwork( 885 self._inner.to_normalized_with_options( 886 clamp_angle_bounds=clamp_angle_bounds, 887 angle_bound_pad=angle_bound_pad, 888 closed_switches=closed_switches, 889 island_references=island_references, 890 ) 891 ) 892 893 def to_ppc(self): 894 """PYPOWER case dict (``ppc``) with MATPOWER-style numpy tables. 895 896 Values are emitted as the model holds them, so a case read from a 897 file carries MW, MVAr, and degrees. A network from 898 :meth:`to_normalized` holds per unit and radians, and those are what 899 its tables carry — PYPOWER reads a ppc dict as MW and degrees, so 900 build this from the raw network unless the consumer expects per unit. 901 902 Loads and shunts are summed onto their bus in the 903 ``PD``/``QD``/``GS``/``BS`` columns, the same aggregation as the 904 MATPOWER emitter. The bus table has no per element status 905 column, so an element the model marks out of service still 906 contributes its value, and a de-energized bus is carried as type 4. 907 ``gencost`` is present only when every generator carries cost data, 908 because MATPOWER requires cost rows for all generators or none. 909 :func:`from_ppc` reads the tables back. 910 911 Infinite branch ratings become PYPOWER's zero (no bound). A real 912 zero rating raises ``ValueError`` because those tables cannot state 913 a zero flow bound. 914 """ 915 np = _require("numpy", "matrix") 916 buses = self._inner.buses 917 bus = np.array( 918 [ 919 ( 920 b["id"], 921 _PPC_BUS_TYPE.get(b["kind"], 1.0), 922 0.0, 923 0.0, 924 0.0, 925 0.0, 926 b["area"], 927 b["vm"], 928 b["va"], 929 b["base_kv"], 930 b["zone"], 931 b["vmax"], 932 b["vmin"], 933 ) 934 for b in buses 935 ], 936 dtype=float, 937 ).reshape(len(buses), 13) 938 bus[:, 2], bus[:, 3], bus[:, 4], bus[:, 5] = _bus_sums( 939 np, buses, self._inner.loads, self._inner.shunts 940 ) 941 942 # The capability and ramp columns past PMIN are an OPF extension that a 943 # source need not carry. Widen to the full 21 only when a generator 944 # actually states one: a table of zeros there reads back as eleven 945 # explicit zero limits, which a ramp aware solver takes as a generator 946 # that cannot move. 947 gens = self._inner.generators 948 caps = [g["caps"] for g in gens] 949 width = 21 if any(c is not None for row in caps for c in row) else 10 950 gen = np.array( 951 [ 952 [ 953 g["bus"], 954 g["pg"], 955 g["qg"], 956 g["qmax"], 957 g["qmin"], 958 g["vg"], 959 g["mbase"], 960 float(g["in_service"]), 961 g["pmax"], 962 g["pmin"], 963 ] 964 + ([0.0 if c is None else c for c in row] if width == 21 else []) 965 for g, row in zip(gens, caps, strict=True) 966 ], 967 dtype=float, 968 ).reshape(len(gens), width) 969 970 branches = self._inner.branches 971 972 def ppc_rating(rating): 973 if rating == 0.0: 974 raise ValueError("PYPOWER's zero means no bound; it cannot represent a zero branch rating") 975 return 0.0 if rating == float("inf") else rating 976 977 branch = np.array( 978 [ 979 ( 980 br["from_id"], 981 br["to_id"], 982 br["r"], 983 br["x"], 984 br["b"], 985 ppc_rating(br["rate_a"]), 986 ppc_rating(br["rate_b"]), 987 ppc_rating(br["rate_c"]), 988 br["tap"], 989 br["shift"], 990 float(br["in_service"]), 991 br["angmin"], 992 br["angmax"], 993 ) 994 for br in branches 995 ], 996 dtype=float, 997 ).reshape(len(branches), 13) 998 999 ppc = { 1000 "version": "2", 1001 "baseMVA": float(self._inner.base_mva), 1002 "bus": bus, 1003 "gen": gen, 1004 "branch": branch, 1005 } 1006 1007 # Coefficients sit left-aligned after ncost, padded to the widest 1008 # row, which is the layout PYPOWER's own loadcase produces. 1009 costs = [g["cost"] for g in gens] 1010 if costs and all(c is not None for c in costs): 1011 gencost = np.zeros((len(costs), 4 + max(len(c["coeffs"]) for c in costs))) 1012 for i, c in enumerate(costs): 1013 gencost[i, :4] = ( 1014 c["model"], 1015 c["startup"], 1016 c["shutdown"], 1017 c["ncost"], 1018 ) 1019 gencost[i, 4 : 4 + len(c["coeffs"])] = c["coeffs"] 1020 ppc["gencost"] = gencost 1021 return ppc 1022 1023 def to_networkx(self): 1024 """Undirected networkx graph keyed by bus id. 1025 1026 In-service branches become edges carrying ``branch`` (index), ``r``, 1027 ``x``, and ``b``. 1028 """ 1029 nx = _require("networkx", "graph") 1030 g = nx.Graph() 1031 g.add_nodes_from(bus["id"] for bus in self._inner.buses) 1032 for k, br in enumerate(self._inner.branches): 1033 if br["in_service"]: 1034 g.add_edge( 1035 br["from_id"], 1036 br["to_id"], 1037 branch=k, 1038 r=br["r"], 1039 x=br["x"], 1040 b=br["b"], 1041 ) 1042 return g
A parsed balanced power network.
The data attributes (buses, branches, generators, loads,
shunts) and reference bus queries delegate to the compiled handle; the
matrix methods below return scipy.sparse objects. Parse and transform
diagnostics belong to the owning PioModule.
Errors: a bad file path raises the standard OSError subclass
(FileNotFoundError); a malformed case raises PowerIOParseError
and an unmet calculation precondition (no generators, no reference bus) raises
PowerIODataError; both subclass PowerIOError, so
except PowerIOError catches either; an unknown
scheme/formula/units string raises ValueError.
450 def component_counts(self) -> dict[str, int]: 451 """Count native lines, generators, loads, and substations. 452 453 Lines exclude transformer branches. Loads include equivalent injections 454 represented as loads. Substations count the source hierarchy, or zero 455 when the format supplies no hierarchy. No Python table rows are built. 456 Raises ValueError for normalized networks, whose unity taps no longer 457 distinguish lines from transformers. Count the source network instead. 458 """ 459 return self._inner.component_counts()
Count native lines, generators, loads, and substations.
Lines exclude transformer branches. Loads include equivalent injections represented as loads. Substations count the source hierarchy, or zero when the format supplies no hierarchy. No Python table rows are built. Raises ValueError for normalized networks, whose unity taps no longer distinguish lines from transformers. Count the source network instead.
461 def calc_connectivity_report(self) -> dict[str, Any]: 462 """Calculate the in-service topology summary.""" 463 return self._inner.calc_connectivity_report()
Calculate the in-service topology summary.
465 def calc_stated_state_mismatch( 466 self, 467 *, 468 top_k: int = 20, 469 hvdc: str = "fixed_injection", 470 low_impedance_threshold: float = 1e-3, 471 merge_zero_impedance: bool = False, 472 lcc_reactive_power: str = "converter_model", 473 ) -> dict[str, Any]: 474 """Evaluate every bus's AC balance at the voltages the case stores. 475 476 Each device sits at its stated output: generators at ``pg``/``qg``, 477 loads through their voltage model at the stored magnitude, shunts at 478 their stated admittance, and HVDC lines as fixed injections (or not, 479 with ``hvdc="ignore"``). A bus mismatch is the power the network draws 480 at the stored voltages minus the stated injection, MW and MVAr, so an 481 injection equal to it closes the bus. 482 483 The result holds per bus columns in analysis bus order (``bus_ids``, 484 ``island``, ``p_mw``, ``q_mvar``, and ``flags``, the attached 485 equipment a residual is traced to), ``islands`` totals largest first, 486 ``top`` (row indices of the largest mismatches), the totals, and 487 ``diagnostics`` (a warning per LCC line that kept its stated reactive 488 powers because its converter record reaches no operating point). 489 ``merge_zero_impedance`` first merges the buses joined by in-service 490 zero-impedance branches, whose flows the stored voltages cannot 491 determine; without it such a branch raises. A closed switch joining 492 two buses also raises (``BUILD.SWITCH.CLOSED``); merge it first with 493 ``merge_buses(closed_switches=True)``. ``lcc_reactive_power`` 494 selects where a PSS/E two-terminal converter's reactive demand comes 495 from: its bridge equations at the stored voltages 496 (``"converter_model"``) or the line's stated reactive powers 497 (``"stated"``). 498 """ 499 return self._inner.calc_stated_state_mismatch( 500 top_k=top_k, 501 hvdc=hvdc, 502 low_impedance_threshold=low_impedance_threshold, 503 merge_zero_impedance=merge_zero_impedance, 504 lcc_reactive_power=lcc_reactive_power, 505 )
Evaluate every bus's AC balance at the voltages the case stores.
Each device sits at its stated output: generators at pg/qg,
loads through their voltage model at the stored magnitude, shunts at
their stated admittance, and HVDC lines as fixed injections (or not,
with hvdc="ignore"). A bus mismatch is the power the network draws
at the stored voltages minus the stated injection, MW and MVAr, so an
injection equal to it closes the bus.
The result holds per bus columns in analysis bus order (bus_ids,
island, p_mw, q_mvar, and flags, the attached
equipment a residual is traced to), islands totals largest first,
top (row indices of the largest mismatches), the totals, and
diagnostics (a warning per LCC line that kept its stated reactive
powers because its converter record reaches no operating point).
merge_zero_impedance first merges the buses joined by in-service
zero-impedance branches, whose flows the stored voltages cannot
determine; without it such a branch raises. A closed switch joining
two buses also raises (BUILD.SWITCH.CLOSED); merge it first with
merge_buses(closed_switches=True). lcc_reactive_power
selects where a PSS/E two-terminal converter's reactive demand comes
from: its bridge equations at the stored voltages
("converter_model") or the line's stated reactive powers
("stated").
507 def calc_stated_branch_flows(self) -> dict[str, Any]: 508 """Calculate the power entering every branch end at the stored voltages. 509 510 Columns follow analysis branch order: every branch row, then the three 511 windings of each in-service three-winding transformer, as ``sources`` 512 states. Powers are MW and MVAr; an out-of-service branch carries zero. 513 """ 514 return self._inner.calc_stated_branch_flows()
Calculate the power entering every branch end at the stored voltages.
Columns follow analysis branch order: every branch row, then the three
windings of each in-service three-winding transformer, as sources
states. Powers are MW and MVAr; an out-of-service branch carries zero.
516 def to_geo_layer(self) -> dict[str, Any]: 517 """Transform coordinates to a canonical GeoJSON FeatureCollection. 518 519 A case without coordinates produces an empty feature collection. 520 """ 521 return _json.loads(self._inner.to_geo_layer_json())
Transform coordinates to a canonical GeoJSON FeatureCollection.
A case without coordinates produces an empty feature collection.
523 def apply_geo_layer( 524 self, text: str, name_hint: Optional[str] = None 525 ) -> tuple["BalancedNetwork", dict[str, Any]]: 526 """Apply a geographic sidecar and return ``(placed, report)``. 527 528 ``text`` is any form :func:`parse_geo` accepts; this case is 529 unchanged. The report carries ``matched_buses``, ``matched_branches``, 530 ``unmatched_features``, ``unlocated_buses``, ``unlocated_branches``, 531 and ``notes``. The two unlocated counts cover the whole case when the 532 pass ends, so a layer that matched nothing reads apart from a case 533 that needed nothing. The placed copy drops the retained source text, 534 so a same-format emission re-serializes. 535 """ 536 inner, report = self._inner.apply_geo_layer(text, name_hint) 537 return BalancedNetwork(inner), report
Apply a geographic sidecar and return (placed, report).
text is any form parse_geo() accepts; this case is
unchanged. The report carries matched_buses, matched_branches,
unmatched_features, unlocated_buses, unlocated_branches,
and notes. The two unlocated counts cover the whole case when the
pass ends, so a layer that matched nothing reads apart from a case
that needed nothing. The placed copy drops the retained source text,
so a same-format emission re-serializes.
539 def resolve_contingencies(self, text: str) -> dict[str, Any]: 540 """Read PSS/E contingency text and bind every case to this network. 541 542 ``text`` is the content of a ``.con`` file, such as 543 ``parse("cases.con").value.text``. The result carries ``cases``, 544 ``resolved``, ``unresolved``, and ``unrecognized_statements`` as 545 counts; ``case_results``, one entry per case in the file's order with 546 its ``name``, whether it ``resolved``, the ``components`` it bound to, 547 and the actions that bound to nothing as ``{"action", "reason"}``; and 548 ``diagnostics``, the reader's notes on statements it kept as text. 549 550 Each component states the ``type`` naming the table, the ``row`` it 551 occupies there, the element's own ``in_service`` flag, and the ``id`` 552 the network states for it. ``id`` is ``None`` when the network states 553 no identity for that row; ``type`` and ``row`` name the element either 554 way. 555 556 Binding reports rather than refuses, so a case naming an element this 557 network does not hold is counted unresolved and listed. 558 """ 559 return self._inner.resolve_contingencies(text)
Read PSS/E contingency text and bind every case to this network.
text is the content of a .con file, such as
parse("cases.con").value.text. The result carries cases,
resolved, unresolved, and unrecognized_statements as
counts; case_results, one entry per case in the file's order with
its name, whether it resolved, the components it bound to,
and the actions that bound to nothing as {"action", "reason"}; and
diagnostics, the reader's notes on statements it kept as text.
Each component states the type naming the table, the row it
occupies there, the element's own in_service flag, and the id
the network states for it. id is None when the network states
no identity for that row; type and row name the element either
way.
Binding reports rather than refuses, so a case naming an element this network does not hold is counted unresolved and listed.
561 def expand_contingencies( 562 self, con_text: str, sub_text: str 563 ) -> tuple[str, list[Diagnostic]]: 564 """Turn automatic contingency specifications into explicit cases. 565 566 ``con_text`` and ``sub_text`` are the contents of a ``.con`` and a 567 ``.sub`` file. A specification such as ``SINGLE BRANCH IN SUBSYSTEM 568 'A1'`` states a rule, so expanding it needs both the network and the 569 subsystem the ``.sub`` file names. Returns the expanded ``.con`` text, 570 which states every outage explicitly, and the notes from the two 571 readers followed by the expansion's own notes. Only elements this 572 network states in service expand into cases. 573 """ 574 return self._inner.expand_contingencies(con_text, sub_text)
Turn automatic contingency specifications into explicit cases.
con_text and sub_text are the contents of a .con and a
.sub file. A specification such as SINGLE BRANCH IN SUBSYSTEM
'A1' states a rule, so expanding it needs both the network and the
subsystem the .sub file names. Returns the expanded .con text,
which states every outage explicitly, and the notes from the two
readers followed by the expansion's own notes. Only elements this
network states in service expand into cases.
576 def select_subsystem_buses(self, sub_text: str, name: str) -> list[int]: 577 """The bus numbers one named subsystem of ``sub_text`` selects. 578 579 ``sub_text`` is the content of a ``.sub`` file. The numbers come back 580 in ascending order. A name the file does not state raises 581 ``ValueError``. 582 """ 583 return self._inner.select_subsystem_buses(sub_text, name)
The bus numbers one named subsystem of sub_text selects.
sub_text is the content of a .sub file. The numbers come back
in ascending order. A name the file does not state raises
ValueError.
587 def calc_bprime_matrix( 588 self, scheme: str = "bx", *, skip_zero_impedance: bool = False 589 ): 590 """MATPOWER FDPF Bp matrix. ``scheme`` is ``"bx"`` or ``"xb"``. 591 592 ``skip_zero_impedance=False`` refuses a zero impedance branch 593 (``r`` and ``x`` both zero); pass ``True`` to drop it instead. 594 """ 595 return _to_csr( 596 self._inner.bprime(scheme, skip_zero_impedance=skip_zero_impedance) 597 )
MATPOWER FDPF Bp matrix. scheme is "bx" or "xb".
skip_zero_impedance=False refuses a zero impedance branch
(r and x both zero); pass True to drop it instead.
599 def calc_incidence_matrix( 600 self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False 601 ): 602 """Return PowerModels incidence ``A`` (branches by buses). 603 604 Rows are the in service, non self loop branches in table order 605 (three winding transformer windings follow the branches); columns 606 are every bus in table order. :meth:`calc_dc_index_map` names both 607 axes. ``skip_zero_impedance=False`` refuses a zero impedance branch; 608 ``True`` drops it from the branch axis. 609 """ 610 return _to_csr( 611 self._inner.calc_incidence_matrix( 612 formula, skip_zero_impedance=skip_zero_impedance 613 ) 614 )
Return PowerModels incidence A (branches by buses).
Rows are the in service, non self loop branches in table order
(three winding transformer windings follow the branches); columns
are every bus in table order. calc_dc_index_map() names both
axes. skip_zero_impedance=False refuses a zero impedance branch;
True drops it from the branch axis.
616 def calc_branch_susceptances( 617 self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False 618 ): 619 """Return per branch susceptances over the branch axis of 620 :meth:`calc_dc_index_map`.""" 621 np = _require("numpy", "matrix") 622 return np.asarray( 623 self._inner.calc_branch_susceptances( 624 formula, skip_zero_impedance=skip_zero_impedance 625 ), 626 dtype=float, 627 )
Return per branch susceptances over the branch axis of
calc_dc_index_map().
629 def calc_branch_flow_matrix( 630 self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False 631 ): 632 """Return ``Bf = diag(b) A`` as a CSR matrix (branches by buses).""" 633 return _to_csr( 634 self._inner.calc_branch_flow_matrix( 635 formula, skip_zero_impedance=skip_zero_impedance 636 ) 637 )
Return Bf = diag(b) A as a CSR matrix (branches by buses).
639 def calc_bus_susceptance_matrix( 640 self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False 641 ): 642 """Return ``B = A.T diag(b) A`` as a CSR matrix (buses by buses).""" 643 return _to_csr( 644 self._inner.calc_bus_susceptance_matrix( 645 formula, skip_zero_impedance=skip_zero_impedance 646 ) 647 )
Return B = A.T diag(b) A as a CSR matrix (buses by buses).
649 def calc_branch_phase_shift_injection( 650 self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False 651 ): 652 """Return ``b * shift`` over the branch axis.""" 653 np = _require("numpy", "matrix") 654 return np.asarray( 655 self._inner.calc_branch_phase_shift_injection( 656 formula, skip_zero_impedance=skip_zero_impedance 657 ), 658 dtype=float, 659 )
Return b * shift over the branch axis.
661 def calc_bus_phase_shift_injection( 662 self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False 663 ): 664 """Return ``A.T @ (b * shift)`` over the bus axis.""" 665 np = _require("numpy", "matrix") 666 return np.asarray( 667 self._inner.calc_bus_phase_shift_injection( 668 formula, skip_zero_impedance=skip_zero_impedance 669 ), 670 dtype=float, 671 )
Return A.T @ (b * shift) over the bus axis.
673 def calc_branch_flow_dc( 674 self, 675 voltage_angles, 676 formula: str = "series_susceptance", 677 *, 678 skip_zero_impedance: bool = False, 679 ): 680 """Compute ``-Bf @ va + b * shift`` over the branch axis.""" 681 np, angles = _dc_angles(self.n_buses, voltage_angles) 682 return np.asarray( 683 self._inner.calc_branch_flow_dc( 684 angles.tolist(), formula, skip_zero_impedance=skip_zero_impedance 685 ), 686 dtype=float, 687 )
Compute -Bf @ va + b * shift over the branch axis.
689 def calc_bus_injection_dc( 690 self, 691 voltage_angles, 692 formula: str = "series_susceptance", 693 *, 694 skip_zero_impedance: bool = False, 695 ): 696 """Compute ``-B @ va + p_shift`` over the bus axis.""" 697 np, angles = _dc_angles(self.n_buses, voltage_angles) 698 return np.asarray( 699 self._inner.calc_bus_injection_dc( 700 angles.tolist(), formula, skip_zero_impedance=skip_zero_impedance 701 ), 702 dtype=float, 703 )
Compute -B @ va + p_shift over the bus axis.
705 def calc_dc_index_map( 706 self, formula: str = "series_susceptance", *, skip_zero_impedance: bool = False 707 ) -> dict[str, Any]: 708 """Return the axes every DC calculation shares. 709 710 ``bus_ids`` maps a bus axis row to the source bus id (every bus, in 711 table order). ``branch_rows`` maps a branch axis row to the position 712 in the branch table (three winding transformer windings follow the 713 branches) and ``branch_ids`` to the stable identity, the branch uid 714 when the source states one and ``branches:<row>`` otherwise; out of 715 service branches and self loops have no row. ``skipped_branch_rows`` 716 lists the zero impedance branches dropped under 717 ``skip_zero_impedance=True`` and is empty otherwise. The same 718 selection applies to :meth:`calc_ptdf` rows and :meth:`calc_lodf`. 719 """ 720 return self._inner.calc_dc_index_map( 721 formula, skip_zero_impedance=skip_zero_impedance 722 )
Return the axes every DC calculation shares.
bus_ids maps a bus axis row to the source bus id (every bus, in
table order). branch_rows maps a branch axis row to the position
in the branch table (three winding transformer windings follow the
branches) and branch_ids to the stable identity, the branch uid
when the source states one and branches:<row> otherwise; out of
service branches and self loops have no row. skipped_branch_rows
lists the zero impedance branches dropped under
skip_zero_impedance=True and is empty otherwise. The same
selection applies to calc_ptdf() rows and calc_lodf().
724 def calc_bdoubleprime_matrix( 725 self, scheme: str = "bx", *, skip_zero_impedance: bool = False 726 ): 727 """MATPOWER FDPF Bpp matrix. ``scheme`` is ``"bx"`` or ``"xb"``. 728 ``skip_zero_impedance`` as in :meth:`calc_bprime_matrix`. 729 """ 730 return _to_csr( 731 self._inner.bdoubleprime(scheme, skip_zero_impedance=skip_zero_impedance) 732 )
MATPOWER FDPF Bpp matrix. scheme is "bx" or "xb".
skip_zero_impedance as in calc_bprime_matrix().
734 def calc_lacpf_matrix( 735 self, 736 *, 737 include_taps: bool = True, 738 include_shifts: bool = True, 739 skip_zero_impedance: bool = False, 740 ): 741 """LACPF 2n×2n block ``[[G, -B], [-B, -G]]``. ``skip_zero_impedance`` 742 as in :meth:`calc_bprime_matrix`.""" 743 return _to_csr( 744 self._inner.lacpf( 745 include_taps=include_taps, 746 include_shifts=include_shifts, 747 skip_zero_impedance=skip_zero_impedance, 748 ) 749 )
LACPF 2n×2n block [[G, -B], [-B, -G]]. skip_zero_impedance
as in calc_bprime_matrix().
751 def calc_adjacency_matrix(self): 752 """0/1 bus adjacency matrix.""" 753 return _to_csr(self._inner.adjacency())
0/1 bus adjacency matrix.
755 def calc_admittance_matrix( 756 self, 757 *, 758 include_taps: bool = True, 759 include_shifts: bool = True, 760 skip_zero_impedance: bool = False, 761 ): 762 """``Y_bus = G + jB`` as a complex csr_matrix. ``skip_zero_impedance`` 763 as in :meth:`calc_bprime_matrix`.""" 764 g, b = self._inner.ybus_parts( 765 include_taps=include_taps, 766 include_shifts=include_shifts, 767 skip_zero_impedance=skip_zero_impedance, 768 ) 769 g, b = _to_csr(g), _to_csr(b) 770 return (g + 1j * b).tocsr()
Y_bus = G + jB as a complex csr_matrix. skip_zero_impedance
as in calc_bprime_matrix().
772 def calc_ptdf(self, formula: str = "series_susceptance", solver: str = "auto"): 773 """DC PTDF (m×n). ``formula`` is ``"series_susceptance"``, 774 ``"tap_adjusted_reactance"``, ``"reactance_only"``, 775 ``"tap_adjusted_series_susceptance"``, or 776 ``"series_susceptance_no_phase_shift"``. 777 778 ``solver`` is ``"auto"``, ``"dense"``, or ``"sparse"``. ``"auto"`` 779 uses the dense factorization on small cases and the sparse Cholesky 780 path on large ones, the same policy as the CLI. 781 """ 782 return _to_csr(self._inner.ptdf(formula, solver))
DC PTDF (m×n). formula is "series_susceptance",
"tap_adjusted_reactance", "reactance_only",
"tap_adjusted_series_susceptance", or
"series_susceptance_no_phase_shift".
solver is "auto", "dense", or "sparse". "auto"
uses the dense factorization on small cases and the sparse Cholesky
path on large ones, the same policy as the CLI.
784 def calc_lodf(self, formula: str = "series_susceptance", solver: str = "auto"): 785 """DC LODF (m×m). ``formula`` and ``solver`` as in :meth:`calc_ptdf`.""" 786 return _to_csr(self._inner.lodf(formula, solver))
DC LODF (m×m). formula and solver as in calc_ptdf().
788 def calc_weighted_laplacian( 789 self, 790 formula: str = "series_susceptance", 791 ): 792 """Weighted Laplacian ``L = -B``. ``formula`` as in :meth:`calc_ptdf`.""" 793 return _to_csr(self._inner.weighted_laplacian(formula))
Weighted Laplacian L = -B. formula as in calc_ptdf().
795 def merge_buses( 796 self, 797 *, 798 closed_switches: bool = True, 799 zero_impedance: Optional[str] = None, 800 threshold: Optional[float] = None, 801 charging: str = "fold", 802 ) -> "BusMerge": 803 """Merge the buses closed switches and zero impedance branches join. 804 805 ``closed_switches`` merges the two buses of every closed switch. 806 ``zero_impedance`` selects the branches merged as well: ``None`` 807 merges none, ``"exact"`` merges ``r == 0`` and ``x == 0``, 808 ``"psse"`` merges non-transformer branches with ``r == 0`` and 809 ``|x| <= threshold`` (PSS/E zero impedance lines; the threshold 810 defaults to the ``THRSHZ`` the case states), and ``"impedance"`` 811 merges non-transformer branches with ``|r + jx| <= threshold``. 812 813 Each joined set keeps one bus: its reference bus, else a bus with an 814 in-service generator, else a bus a generator regulates, smallest id 815 first. Every element moves onto it. The merged elements and any 816 branch the merge shorts are removed and listed with their source rows 817 and ratings. ``charging="fold"`` turns each removed branch's line 818 charging and line shunts, including tap scaling, into a fixed shunt 819 at the survivor. ``"drop"`` discards only terminal charging. Both 820 choices preserve the series equivalent of a bypassed transformer. 821 An ideal transformer with a nonunity tap or phase shift cannot be 822 bypassed and raises an error. This network is unchanged. 823 824 Raises :class:`PowerIODataError` for a threshold that is negative or 825 not finite, or for ``"psse"`` with no threshold when the case states 826 none; an unknown rule name raises ``ValueError``. 827 """ 828 return BusMerge( 829 self._inner.merge_buses( 830 closed_switches=closed_switches, 831 zero_impedance=zero_impedance, 832 threshold=threshold, 833 charging=charging, 834 ) 835 )
Merge the buses closed switches and zero impedance branches join.
closed_switches merges the two buses of every closed switch.
zero_impedance selects the branches merged as well: None
merges none, "exact" merges r == 0 and x == 0,
"psse" merges non-transformer branches with r == 0 and
|x| <= threshold (PSS/E zero impedance lines; the threshold
defaults to the THRSHZ the case states), and "impedance"
merges non-transformer branches with |r + jx| <= threshold.
Each joined set keeps one bus: its reference bus, else a bus with an
in-service generator, else a bus a generator regulates, smallest id
first. Every element moves onto it. The merged elements and any
branch the merge shorts are removed and listed with their source rows
and ratings. charging="fold" turns each removed branch's line
charging and line shunts, including tap scaling, into a fixed shunt
at the survivor. "drop" discards only terminal charging. Both
choices preserve the series equivalent of a bypassed transformer.
An ideal transformer with a nonunity tap or phase shift cannot be
bypassed and raises an error. This network is unchanged.
Raises PowerIODataError for a threshold that is negative or
not finite, or for "psse" with no threshold when the case states
none; an unknown rule name raises ValueError.
837 def to_normalized( 838 self, 839 *, 840 clamp_angle_bounds: bool = False, 841 angle_bound_pad: Optional[float] = None, 842 closed_switches: str = "merge", 843 island_references: str = "stated", 844 ) -> "BalancedNetwork": 845 """Return a normalized copy with per unit power and radian angles. 846 847 The result removes out of service elements, preserves source bus IDs, 848 and normalizes bus types. It carries no retained source, so 849 :func:`powerio.emit` produces a grid exchange representation from the 850 derived module. Raises 851 :class:`PowerIODataError` if the network cannot be 852 normalized (no reference bus can be chosen, or a non-positive base MVA). 853 854 ``clamp_angle_bounds=True`` applies the PowerModels angle difference 855 bound repair: limits at or beyond ``+/-pi/2`` and zero/zero windows 856 become ``[-angle_bound_pad, angle_bound_pad]``. A repair that would 857 invert the interval widens to that same window. The default pad is 858 1.0472 radians. 859 860 The default ``closed_switches="merge"`` merges the buses closed 861 switches join first, as :meth:`merge_buses` does with 862 ``closed_switches=True``, since the matrix and DC calculations model 863 no switches. ``"keep"`` leaves the switches as data, and ``"refuse"`` 864 raises :class:`PowerIODataError` with code ``BUILD.SWITCH.CLOSED``. 865 ``"merge"`` also raises that error when the merge cannot complete, 866 for example across two windings of one three winding transformer. 867 The error names the original switch row and endpoints; no partial 868 normalized network is returned. 869 870 ``island_references="per_island"`` gives every island one reference 871 bus: an island that states none takes the bus of its largest ``pmax`` 872 in-service generator, an island stating several keeps one, and an 873 island no in-service generator supplies is left out. The default 874 ``"stated"`` keeps the case's references and designates one only when 875 none survives. 876 """ 877 if ( 878 not clamp_angle_bounds 879 and angle_bound_pad is None 880 and closed_switches == "merge" 881 and island_references == "stated" 882 ): 883 return BalancedNetwork(self._inner.to_normalized()) 884 return BalancedNetwork( 885 self._inner.to_normalized_with_options( 886 clamp_angle_bounds=clamp_angle_bounds, 887 angle_bound_pad=angle_bound_pad, 888 closed_switches=closed_switches, 889 island_references=island_references, 890 ) 891 )
Return a normalized copy with per unit power and radian angles.
The result removes out of service elements, preserves source bus IDs,
and normalizes bus types. It carries no retained source, so
powerio.emit() produces a grid exchange representation from the
derived module. Raises
PowerIODataError if the network cannot be
normalized (no reference bus can be chosen, or a non-positive base MVA).
clamp_angle_bounds=True applies the PowerModels angle difference
bound repair: limits at or beyond +/-pi/2 and zero/zero windows
become [-angle_bound_pad, angle_bound_pad]. A repair that would
invert the interval widens to that same window. The default pad is
1.0472 radians.
The default closed_switches="merge" merges the buses closed
switches join first, as merge_buses() does with
closed_switches=True, since the matrix and DC calculations model
no switches. "keep" leaves the switches as data, and "refuse"
raises PowerIODataError with code BUILD.SWITCH.CLOSED.
"merge" also raises that error when the merge cannot complete,
for example across two windings of one three winding transformer.
The error names the original switch row and endpoints; no partial
normalized network is returned.
island_references="per_island" gives every island one reference
bus: an island that states none takes the bus of its largest pmax
in-service generator, an island stating several keeps one, and an
island no in-service generator supplies is left out. The default
"stated" keeps the case's references and designates one only when
none survives.
893 def to_ppc(self): 894 """PYPOWER case dict (``ppc``) with MATPOWER-style numpy tables. 895 896 Values are emitted as the model holds them, so a case read from a 897 file carries MW, MVAr, and degrees. A network from 898 :meth:`to_normalized` holds per unit and radians, and those are what 899 its tables carry — PYPOWER reads a ppc dict as MW and degrees, so 900 build this from the raw network unless the consumer expects per unit. 901 902 Loads and shunts are summed onto their bus in the 903 ``PD``/``QD``/``GS``/``BS`` columns, the same aggregation as the 904 MATPOWER emitter. The bus table has no per element status 905 column, so an element the model marks out of service still 906 contributes its value, and a de-energized bus is carried as type 4. 907 ``gencost`` is present only when every generator carries cost data, 908 because MATPOWER requires cost rows for all generators or none. 909 :func:`from_ppc` reads the tables back. 910 911 Infinite branch ratings become PYPOWER's zero (no bound). A real 912 zero rating raises ``ValueError`` because those tables cannot state 913 a zero flow bound. 914 """ 915 np = _require("numpy", "matrix") 916 buses = self._inner.buses 917 bus = np.array( 918 [ 919 ( 920 b["id"], 921 _PPC_BUS_TYPE.get(b["kind"], 1.0), 922 0.0, 923 0.0, 924 0.0, 925 0.0, 926 b["area"], 927 b["vm"], 928 b["va"], 929 b["base_kv"], 930 b["zone"], 931 b["vmax"], 932 b["vmin"], 933 ) 934 for b in buses 935 ], 936 dtype=float, 937 ).reshape(len(buses), 13) 938 bus[:, 2], bus[:, 3], bus[:, 4], bus[:, 5] = _bus_sums( 939 np, buses, self._inner.loads, self._inner.shunts 940 ) 941 942 # The capability and ramp columns past PMIN are an OPF extension that a 943 # source need not carry. Widen to the full 21 only when a generator 944 # actually states one: a table of zeros there reads back as eleven 945 # explicit zero limits, which a ramp aware solver takes as a generator 946 # that cannot move. 947 gens = self._inner.generators 948 caps = [g["caps"] for g in gens] 949 width = 21 if any(c is not None for row in caps for c in row) else 10 950 gen = np.array( 951 [ 952 [ 953 g["bus"], 954 g["pg"], 955 g["qg"], 956 g["qmax"], 957 g["qmin"], 958 g["vg"], 959 g["mbase"], 960 float(g["in_service"]), 961 g["pmax"], 962 g["pmin"], 963 ] 964 + ([0.0 if c is None else c for c in row] if width == 21 else []) 965 for g, row in zip(gens, caps, strict=True) 966 ], 967 dtype=float, 968 ).reshape(len(gens), width) 969 970 branches = self._inner.branches 971 972 def ppc_rating(rating): 973 if rating == 0.0: 974 raise ValueError("PYPOWER's zero means no bound; it cannot represent a zero branch rating") 975 return 0.0 if rating == float("inf") else rating 976 977 branch = np.array( 978 [ 979 ( 980 br["from_id"], 981 br["to_id"], 982 br["r"], 983 br["x"], 984 br["b"], 985 ppc_rating(br["rate_a"]), 986 ppc_rating(br["rate_b"]), 987 ppc_rating(br["rate_c"]), 988 br["tap"], 989 br["shift"], 990 float(br["in_service"]), 991 br["angmin"], 992 br["angmax"], 993 ) 994 for br in branches 995 ], 996 dtype=float, 997 ).reshape(len(branches), 13) 998 999 ppc = { 1000 "version": "2", 1001 "baseMVA": float(self._inner.base_mva), 1002 "bus": bus, 1003 "gen": gen, 1004 "branch": branch, 1005 } 1006 1007 # Coefficients sit left-aligned after ncost, padded to the widest 1008 # row, which is the layout PYPOWER's own loadcase produces. 1009 costs = [g["cost"] for g in gens] 1010 if costs and all(c is not None for c in costs): 1011 gencost = np.zeros((len(costs), 4 + max(len(c["coeffs"]) for c in costs))) 1012 for i, c in enumerate(costs): 1013 gencost[i, :4] = ( 1014 c["model"], 1015 c["startup"], 1016 c["shutdown"], 1017 c["ncost"], 1018 ) 1019 gencost[i, 4 : 4 + len(c["coeffs"])] = c["coeffs"] 1020 ppc["gencost"] = gencost 1021 return ppc
PYPOWER case dict (ppc) with MATPOWER-style numpy tables.
Values are emitted as the model holds them, so a case read from a
file carries MW, MVAr, and degrees. A network from
to_normalized() holds per unit and radians, and those are what
its tables carry — PYPOWER reads a ppc dict as MW and degrees, so
build this from the raw network unless the consumer expects per unit.
Loads and shunts are summed onto their bus in the
PD/QD/GS/BS columns, the same aggregation as the
MATPOWER emitter. The bus table has no per element status
column, so an element the model marks out of service still
contributes its value, and a de-energized bus is carried as type 4.
gencost is present only when every generator carries cost data,
because MATPOWER requires cost rows for all generators or none.
from_ppc() reads the tables back.
Infinite branch ratings become PYPOWER's zero (no bound). A real
zero rating raises ValueError because those tables cannot state
a zero flow bound.
1023 def to_networkx(self): 1024 """Undirected networkx graph keyed by bus id. 1025 1026 In-service branches become edges carrying ``branch`` (index), ``r``, 1027 ``x``, and ``b``. 1028 """ 1029 nx = _require("networkx", "graph") 1030 g = nx.Graph() 1031 g.add_nodes_from(bus["id"] for bus in self._inner.buses) 1032 for k, br in enumerate(self._inner.branches): 1033 if br["in_service"]: 1034 g.add_edge( 1035 br["from_id"], 1036 br["to_id"], 1037 branch=k, 1038 r=br["r"], 1039 x=br["x"], 1040 b=br["b"], 1041 ) 1042 return g
Undirected networkx graph keyed by bus id.
In-service branches become edges carrying branch (index), r,
x, and b.
304@_guard_class 305class BusMerge: 306 """The result of :meth:`BalancedNetwork.merge_buses`. 307 308 ``network`` is the merged network. ``merged_buses`` maps every merged 309 bus to the bus that now carries it, and ``groups`` lists each joined set 310 as ``{"survivor", "members"}``. ``removed_branches`` and 311 ``removed_switches`` describe every element the merge removed: its source 312 ``row``, ``id``, ``from_id`` and ``to_id`` buses, ``survivor``, ``reason`` 313 (``"zero_impedance"``, ``"closed_switch"``, or ``"shorted"``), status, and 314 ratings. ``branch_rows`` and ``switch_rows`` map each source row to its 315 merged row, or ``None`` when removed, and ``charging_shunts`` lists the 316 merged shunt rows that hold removed branches' equivalent admittances. ``diagnostics`` holds the merge's 317 findings, which the merged network's module carries as well. 318 """ 319 320 def __init__(self, inner: "_powerio._BusMerge"): 321 self._inner = inner 322 323 def __repr__(self) -> str: 324 return repr(self._inner) 325 326 @property 327 def network(self) -> "BalancedNetwork": 328 return BalancedNetwork(self._inner.network) 329 330 @property 331 def rule(self) -> str: 332 return self._inner.rule 333 334 @property 335 def merged_buses(self) -> dict[int, int]: 336 return self._inner.merged_buses 337 338 @property 339 def groups(self) -> list[dict[str, Any]]: 340 return self._inner.groups 341 342 @property 343 def removed_branches(self) -> list[dict[str, Any]]: 344 return self._inner.removed_branches 345 346 @property 347 def removed_switches(self) -> list[dict[str, Any]]: 348 return self._inner.removed_switches 349 350 @property 351 def branch_rows(self) -> list[Optional[int]]: 352 return self._inner.branch_rows 353 354 @property 355 def switch_rows(self) -> list[Optional[int]]: 356 return self._inner.switch_rows 357 358 @property 359 def charging_shunts(self) -> list[int]: 360 return self._inner.charging_shunts 361 362 @property 363 def diagnostics(self) -> list[Diagnostic]: 364 return self._inner.diagnostics 365 366 def survivor(self, bus: int) -> int: 367 """The bus that carries ``bus`` in the merged network.""" 368 return self._inner.survivor(bus) 369 370 def calc_removed_flows( 371 self, 372 branch_p_from: Any, 373 branch_p_to: Any, 374 *, 375 generator_p: Any = None, 376 transformer_3w_p: Any = None, 377 ) -> dict[str, Any]: 378 """Recover the active power on every removed element. 379 380 ``branch_p_from`` and ``branch_p_to`` are the power entering each 381 merged network branch at its from and to ends; ``generator_p`` 382 replaces the stated generator outputs, and ``transformer_3w_p`` gives 383 the power entering each three winding transformer winding from its 384 bus, three values per transformer. Values are in the network's units 385 (MW for a parsed network). The result has ``branches`` and 386 ``switches``, one ``{"p_from", "method"}`` per removed element in the 387 order of :attr:`removed_branches` and :attr:`removed_switches`, and 388 ``diagnostics``. ``method`` is ``"tree"`` where Kirchhoff's current 389 law fixes the flow, ``"reactance"`` on a loop split by reactance, 390 ``"minimum_norm"`` on a loop of zero reactance elements, and 391 ``"out_of_service"`` for an element that carries none. 392 """ 393 return self._inner.calc_removed_flows( 394 [float(p) for p in branch_p_from], 395 [float(p) for p in branch_p_to], 396 generator_p=None 397 if generator_p is None 398 else [float(p) for p in generator_p], 399 transformer_3w_p=None 400 if transformer_3w_p is None 401 else [tuple(float(p) for p in row) for row in transformer_3w_p], 402 )
The result of BalancedNetwork.merge_buses().
network is the merged network. merged_buses maps every merged
bus to the bus that now carries it, and groups lists each joined set
as {"survivor", "members"}. removed_branches and
removed_switches describe every element the merge removed: its source
row, id, from_id and to_id buses, survivor, reason
("zero_impedance", "closed_switch", or "shorted"), status, and
ratings. branch_rows and switch_rows map each source row to its
merged row, or None when removed, and charging_shunts lists the
merged shunt rows that hold removed branches' equivalent admittances. diagnostics holds the merge's
findings, which the merged network's module carries as well.
366 def survivor(self, bus: int) -> int: 367 """The bus that carries ``bus`` in the merged network.""" 368 return self._inner.survivor(bus)
The bus that carries bus in the merged network.
370 def calc_removed_flows( 371 self, 372 branch_p_from: Any, 373 branch_p_to: Any, 374 *, 375 generator_p: Any = None, 376 transformer_3w_p: Any = None, 377 ) -> dict[str, Any]: 378 """Recover the active power on every removed element. 379 380 ``branch_p_from`` and ``branch_p_to`` are the power entering each 381 merged network branch at its from and to ends; ``generator_p`` 382 replaces the stated generator outputs, and ``transformer_3w_p`` gives 383 the power entering each three winding transformer winding from its 384 bus, three values per transformer. Values are in the network's units 385 (MW for a parsed network). The result has ``branches`` and 386 ``switches``, one ``{"p_from", "method"}`` per removed element in the 387 order of :attr:`removed_branches` and :attr:`removed_switches`, and 388 ``diagnostics``. ``method`` is ``"tree"`` where Kirchhoff's current 389 law fixes the flow, ``"reactance"`` on a loop split by reactance, 390 ``"minimum_norm"`` on a loop of zero reactance elements, and 391 ``"out_of_service"`` for an element that carries none. 392 """ 393 return self._inner.calc_removed_flows( 394 [float(p) for p in branch_p_from], 395 [float(p) for p in branch_p_to], 396 generator_p=None 397 if generator_p is None 398 else [float(p) for p in generator_p], 399 transformer_3w_p=None 400 if transformer_3w_p is None 401 else [tuple(float(p) for p in row) for row in transformer_3w_p], 402 )
Recover the active power on every removed element.
branch_p_from and branch_p_to are the power entering each
merged network branch at its from and to ends; generator_p
replaces the stated generator outputs, and transformer_3w_p gives
the power entering each three winding transformer winding from its
bus, three values per transformer. Values are in the network's units
(MW for a parsed network). The result has branches and
switches, one {"p_from", "method"} per removed element in the
order of removed_branches and removed_switches, and
diagnostics. method is "tree" where Kirchhoff's current
law fixes the flow, "reactance" on a loop split by reactance,
"minimum_norm" on a loop of zero reactance elements, and
"out_of_service" for an element that carries none.
25class Collection: 26 """A shared inventory. Closing it does not invalidate parsed modules. 27 28 Inspect returns metadata and suggested selection dictionaries without 29 electrical parsing. Pass one selection to parse. Candidates are not a 30 completeness or solver-readiness certificate. 31 """ 32 33 def __init__(self, native: Any) -> None: 34 self._native = native 35 36 @classmethod 37 @guard 38 def open(cls, path: str | os.PathLike[str], *, max_bytes: int = 64 << 20, 39 max_files: int = 4096) -> Collection: 40 return cls(_powerio._Collection._open(os.fspath(path), max_bytes, max_files)) 41 42 @classmethod 43 @guard 44 def from_zip(cls, data: bytes, *, name: str = "collection.zip", 45 max_bytes: int = 64 << 20, max_files: int = 4096) -> Collection: 46 return cls(_powerio._Collection._from_zip(name, data, max_bytes, max_files)) 47 48 @classmethod 49 @guard 50 def from_files(cls, files: Mapping[str, bytes], *, name: str = "collection", 51 max_bytes: int = 64 << 20, max_files: int = 4096) -> Collection: 52 return cls(_powerio._Collection._from_files(name, dict(files), max_bytes, max_files)) 53 54 @guard 55 def inspect(self) -> dict[str, Any]: 56 return self._native._inspect() 57 58 @guard 59 def parse(self, selection: Mapping[str, Any], *, 60 sincal_multiconductor: SincalReadOptions | None = None, 61 sincal_balanced: SincalBalancedReadOptions | None = None) -> CollectionResult: 62 from . import PioModule 63 from ._sincal import _native_selections 64 tx, mc = _native_selections(sincal_balanced, sincal_multiconductor) 65 module, dependencies, incomplete = self._native._parse(json.dumps(dict(selection)), mc, tx) 66 return CollectionResult(PioModule(module), tuple(dependencies), incomplete) 67 68 def close(self) -> None: 69 self._native.close() 70 71 def __enter__(self) -> Collection: 72 return self 73 74 def __exit__(self, *_: Any) -> None: 75 self.close()
A shared inventory. Closing it does not invalidate parsed modules.
Inspect returns metadata and suggested selection dictionaries without electrical parsing. Pass one selection to parse. Candidates are not a completeness or solver-readiness certificate.
58 @guard 59 def parse(self, selection: Mapping[str, Any], *, 60 sincal_multiconductor: SincalReadOptions | None = None, 61 sincal_balanced: SincalBalancedReadOptions | None = None) -> CollectionResult: 62 from . import PioModule 63 from ._sincal import _native_selections 64 tx, mc = _native_selections(sincal_balanced, sincal_multiconductor) 65 module, dependencies, incomplete = self._native._parse(json.dumps(dict(selection)), mc, tx) 66 return CollectionResult(PioModule(module), tuple(dependencies), incomplete)
18@dataclass(frozen=True) 19class CollectionResult: 20 module: PioModule 21 dependencies: tuple[str, ...] 22 incomplete: bool
1734@_guard_class 1735class ContingencySet(_TypedValue): 1736 """A PSS/E contingency description file: the cases to run, the automatic 1737 specifications that state cases by rule, and the ``SKIP`` rules. 1738 1739 :func:`parse` returns it for a ``.con`` file or for text declared as 1740 ``psse-con``, :func:`powerio.emit` writes it back under that token, and 1741 :func:`serialize` carries it through PowerIO IR. Bind a set to a case with 1742 ``network.resolve_contingencies(cases.text)`` and turn its automatic 1743 specifications into explicit cases with 1744 ``network.expand_contingencies(cases.text, groups.text)``. 1745 """ 1746 1747 @property 1748 def text(self) -> str: 1749 """The ``.con`` text for this set.""" 1750 return _emitted_text(self.module, "psse-con")
A PSS/E contingency description file: the cases to run, the automatic
specifications that state cases by rule, and the SKIP rules.
parse() returns it for a .con file or for text declared as
psse-con, powerio.emit() writes it back under that token, and
serialize() carries it through PowerIO IR. Bind a set to a case with
network.resolve_contingencies(cases.text) and turn its automatic
specifications into explicit cases with
network.expand_contingencies(cases.text, groups.text).
1747 @property 1748 def text(self) -> str: 1749 """The ``.con`` text for this set.""" 1750 return _emitted_text(self.module, "psse-con")
The .con text for this set.
Inherited Members
1422class DcOpfInstance(_BalancedCalculation): 1423 """A DC optimal power flow calculation instance."""
A DC optimal power flow calculation instance.
Inherited Members
1540class DcOpfSolution(_BalancedCalculation, _CalculationSolution): 1541 """A DC optimal power flow solution."""
A DC optimal power flow solution.
Inherited Members
A DC power flow calculation instance.
Inherited Members
1532class DcPfSolution(_BalancedCalculation, _CalculationSolution): 1533 """A DC power flow solution."""
A DC power flow solution.
Inherited Members
One coded, user facing finding from a parse, read, transform, or write
pass: the Python mirror of powerio_core::Diagnostic. Every module
carries a list of these; PioModule.diagnostics returns them natively
instead of the diagnostics_json string form.
204@dataclass(frozen=True) 205class EmitResult: 206 """Artifact inventory and diagnostics from an emission or serialization.""" 207 208 artifacts: tuple[Artifact, ...] 209 layout: str 210 fidelity: str 211 diagnostics: tuple[Diagnostic, ...] 212 213 @property 214 def text(self) -> Optional[str]: 215 """The sole UTF-8 memory artifact, or ``None`` for other inventories.""" 216 if len(self.artifacts) != 1 or self.artifacts[0].data is None: 217 return None 218 return self.artifacts[0].text
Artifact inventory and diagnostics from an emission or serialization.
213 @property 214 def text(self) -> Optional[str]: 215 """The sole UTF-8 memory artifact, or ``None`` for other inventories.""" 216 if len(self.artifacts) != 1 or self.artifacts[0].data is None: 217 return None 218 return self.artifacts[0].text
The sole UTF-8 memory artifact, or None for other inventories.
FormatInfo(token, extension, is_directory, can_emit)
1702@_guard_class 1703class GeoLayer(_TypedValue): 1704 """A standalone geographic document: element points and routes keyed by 1705 element identity, in one coordinate space. 1706 1707 :func:`parse` returns it for the canonical ``.geo.json``, GeoJSON, aliased 1708 CSV or JSON records, headerless buscoords CSV, and a PowerWorld ``.pwd`` 1709 display. :func:`powerio.emit` writes the canonical document as 1710 ``geo-json``, and :func:`serialize` carries the layer through PowerIO IR. 1711 Place a layer onto a case with 1712 ``network.apply_geo_layer(layer.geojson)``. 1713 """ 1714 1715 @property 1716 def geojson(self) -> str: 1717 """The canonical ``.geo.json`` document for this layer.""" 1718 result = emit(self.module, "geo-json") 1719 data = result.artifacts[0].data 1720 if data is None: 1721 raise ValueError("the layer emission returned no artifact bytes") 1722 return data.decode("utf-8")
A standalone geographic document: element points and routes keyed by element identity, in one coordinate space.
parse() returns it for the canonical .geo.json, GeoJSON, aliased
CSV or JSON records, headerless buscoords CSV, and a PowerWorld .pwd
display. powerio.emit() writes the canonical document as
geo-json, and serialize() carries the layer through PowerIO IR.
Place a layer onto a case with
network.apply_geo_layer(layer.geojson).
1715 @property 1716 def geojson(self) -> str: 1717 """The canonical ``.geo.json`` document for this layer.""" 1718 result = emit(self.module, "geo-json") 1719 data = result.artifacts[0].data 1720 if data is None: 1721 raise ValueError("the layer emission returned no artifact bytes") 1722 return data.decode("utf-8")
The canonical .geo.json document for this layer.
Inherited Members
1508@_guard_class 1509class LinDist3FlowOpfInstance(_MulticonductorCalculation): 1510 """A radial fixed-reference multiconductor linear OPF instance.""" 1511 1512 @property 1513 def metadata(self) -> dict[str, Any]: 1514 """Node and conductor axes, roots, and reference phasors in volts/radians.""" 1515 return self.module._inner._lindist3flow_metadata()
A radial fixed-reference multiconductor linear OPF instance.
1512 @property 1513 def metadata(self) -> dict[str, Any]: 1514 """Node and conductor axes, roots, and reference phasors in volts/radians.""" 1515 return self.module._inner._lindist3flow_metadata()
Node and conductor axes, roots, and reference phasors in volts/radians.
Inherited Members
1644@_guard_class 1645class LinDist3FlowOpfSolution(_MulticonductorCalculation, _CalculationSolution): 1646 """LinDist3Flow primal values in squared volts, watts, and vars.""" 1647 1648 @property 1649 def termination(self) -> str: 1650 """How the calculation ended.""" 1651 return self.module._inner._lindist3flow_solution_termination() 1652 1653 @property 1654 def objective(self) -> float: 1655 """The reported objective value.""" 1656 return self.module._inner._lindist3flow_solution_objective() 1657 1658 def __getitem__(self, quantity: str) -> list[float]: 1659 """Copy one named primal column in its physical instance order.""" 1660 return self.module._inner._lindist3flow_solution_values(quantity)
LinDist3Flow primal values in squared volts, watts, and vars.
1648 @property 1649 def termination(self) -> str: 1650 """How the calculation ended.""" 1651 return self.module._inner._lindist3flow_solution_termination()
How the calculation ended.
1653 @property 1654 def objective(self) -> float: 1655 """The reported objective value.""" 1656 return self.module._inner._lindist3flow_solution_objective()
The reported objective value.
Inherited Members
1498@_guard_class 1499class LinDist3FlowPfInstance(_MulticonductorCalculation): 1500 """A fixed-dispatch LinDist3Flow power-flow instance.""" 1501 1502 @property 1503 def metadata(self) -> dict[str, Any]: 1504 """Node/conductor axes, preparation actions, and reference phasors.""" 1505 return self.module._inner._lindist3flow_metadata()
A fixed-dispatch LinDist3Flow power-flow instance.
1502 @property 1503 def metadata(self) -> dict[str, Any]: 1504 """Node/conductor axes, preparation actions, and reference phasors.""" 1505 return self.module._inner._lindist3flow_metadata()
Node/conductor axes, preparation actions, and reference phasors.
Inherited Members
1625@_guard_class 1626class LinDist3FlowPfSolution(_MulticonductorCalculation, _CalculationSolution): 1627 """Fixed-dispatch LinDist3Flow values and monitored SI line limits.""" 1628 1629 @property 1630 def termination(self) -> str: 1631 """How the calculation ended.""" 1632 return self.module._inner._lindist3flow_solution_termination() 1633 1634 @property 1635 def limit_checks(self) -> list[dict[str, Any]]: 1636 """Monitored line ratings, values, loading ratios, and overload flags.""" 1637 return self.module._inner._lindist3flow_limit_checks() 1638 1639 def __getitem__(self, quantity: str) -> list[float]: 1640 """Copy one named primal column in its physical instance order.""" 1641 return self.module._inner._lindist3flow_solution_values(quantity)
Fixed-dispatch LinDist3Flow values and monitored SI line limits.
1629 @property 1630 def termination(self) -> str: 1631 """How the calculation ended.""" 1632 return self.module._inner._lindist3flow_solution_termination()
How the calculation ended.
1634 @property 1635 def limit_checks(self) -> list[dict[str, Any]]: 1636 """Monitored line ratings, values, loading ratios, and overload flags.""" 1637 return self.module._inner._lindist3flow_limit_checks()
Monitored line ratings, values, loading ratios, and overload flags.
Inherited Members
1518class McAcOpfInstance(_MulticonductorCalculation): 1519 """A multiconductor AC optimal power flow calculation instance."""
A multiconductor AC optimal power flow calculation instance.
Inherited Members
1663class McAcOpfSolution(_MulticonductorCalculation, _CalculationSolution): 1664 """A multiconductor AC optimal power flow solution."""
A multiconductor AC optimal power flow solution.
Inherited Members
1494class McAcPfInstance(_MulticonductorCalculation): 1495 """A multiconductor AC power flow calculation instance."""
A multiconductor AC power flow calculation instance.
Inherited Members
1621class McAcPfSolution(_MulticonductorCalculation, _CalculationSolution): 1622 """A multiconductor AC power flow solution."""
A multiconductor AC power flow solution.
Inherited Members
1769@_guard_class 1770class MonitoredSet(_TypedValue): 1771 """A PSS/E monitored element file: the branches, interfaces, and voltage 1772 scopes a contingency run reports on. 1773 1774 :func:`parse` returns it for a ``.mon`` file or for text declared as 1775 ``psse-mon``. 1776 """ 1777 1778 @property 1779 def text(self) -> str: 1780 """The ``.mon`` text for this set.""" 1781 return _emitted_text(self.module, "psse-mon")
A PSS/E monitored element file: the branches, interfaces, and voltage scopes a contingency run reports on.
parse() returns it for a .mon file or for text declared as
psse-mon.
1778 @property 1779 def text(self) -> str: 1780 """The ``.mon`` text for this set.""" 1781 return _emitted_text(self.module, "psse-mon")
The .mon text for this set.
Inherited Members
58@_guard_class 59class MulticonductorNetwork: 60 """A parsed multiconductor distribution network in wire coordinates. 61 62 Buses carry named terminals, lines carry conductor impedance matrices, and 63 transformers carry per winding connections. This type is distinct from the 64 positive sequence :class:`powerio.BalancedNetwork`; balanced matrix calculations do not 65 accept it. 66 """ 67 68 def __init__(self, inner) -> None: 69 self._inner = inner 70 71 @property 72 def name(self) -> Optional[str]: 73 """Distribution network name when the source format carries one.""" 74 return self._inner.name() 75 76 @property 77 def source_format(self) -> Optional[str]: 78 """Format parsed from: ``dss``, ``pmd-json``, ``pmd-math-json``, 79 ``bmopf-json``, ``ravens-json``, ``cim-dist``, ``pandapower-json``, or 80 ``sincal``; ``None`` for a network built in code.""" 81 return self._inner.source_format() 82 83 @property 84 def base_frequency(self) -> float: 85 """System base frequency in hertz.""" 86 return self._inner.base_frequency() 87 88 @property 89 def n_buses(self) -> int: 90 return self._inner.n_buses() 91 92 @property 93 def n_lines(self) -> int: 94 return self._inner.n_lines() 95 96 @property 97 def n_line_codes(self) -> int: 98 return self._inner.n_line_codes() 99 100 @property 101 def n_switches(self) -> int: 102 return self._inner.n_switches() 103 104 @property 105 def n_transformers(self) -> int: 106 return self._inner.n_transformers() 107 108 @property 109 def n_loads(self) -> int: 110 return self._inner.n_loads() 111 112 @property 113 def n_generators(self) -> int: 114 return self._inner.n_generators() 115 116 @property 117 def n_ibrs(self) -> int: 118 return self._inner.n_ibrs() 119 120 @property 121 def n_control_profiles(self) -> int: 122 return self._inner.n_control_profiles() 123 124 @property 125 def n_shunts(self) -> int: 126 return self._inner.n_shunts() 127 128 @property 129 def n_capacitors(self) -> int: 130 return self._inner.n_capacitors() 131 132 @property 133 def n_voltage_sources(self) -> int: 134 """Number of grid forming voltage sources.""" 135 return self._inner.n_voltage_sources() 136 137 @property 138 def n_untyped_objects(self) -> int: 139 return self._inner.n_untyped_objects() 140 141 # These properties are copies of the native model tables. Nested field 142 # names come from the Rust model's serialization, so this wrapper does not 143 # maintain a second distribution schema. 144 145 @property 146 def buses(self) -> "list[dict[str, Any]]": 147 return self._inner.buses() 148 149 @property 150 def line_codes(self) -> "list[dict[str, Any]]": 151 return self._inner.line_codes() 152 153 @property 154 def lines(self) -> "list[dict[str, Any]]": 155 return self._inner.lines() 156 157 @property 158 def switches(self) -> "list[dict[str, Any]]": 159 return self._inner.switches() 160 161 @property 162 def transformers(self) -> "list[dict[str, Any]]": 163 return self._inner.transformers() 164 165 @property 166 def loads(self) -> "list[dict[str, Any]]": 167 return self._inner.loads() 168 169 @property 170 def generators(self) -> "list[dict[str, Any]]": 171 return self._inner.generators() 172 173 @property 174 def ibrs(self) -> "list[dict[str, Any]]": 175 return self._inner.ibrs() 176 177 @property 178 def control_profiles(self) -> "list[dict[str, Any]]": 179 return self._inner.control_profiles() 180 181 @property 182 def shunts(self) -> "list[dict[str, Any]]": 183 return self._inner.shunts() 184 185 @property 186 def capacitors(self) -> "list[dict[str, Any]]": 187 return self._inner.capacitors() 188 189 @property 190 def voltage_sources(self) -> "list[dict[str, Any]]": 191 return self._inner.voltage_sources() 192 193 @property 194 def untyped_objects(self) -> "list[dict[str, Any]]": 195 return self._inner.untyped_objects() 196 197 def to_graph(self) -> Any: 198 """Transform the network to collapsed bus and terminal graph data.""" 199 return _json.loads(self._inner.graph_json()) 200 201 def to_geo_layer(self) -> Any: 202 """Transform coordinates to a canonical GeoJSON FeatureCollection. 203 204 A network without coordinates produces an empty feature collection. 205 """ 206 return _json.loads(self._inner.to_geo_layer_json()) 207 208 def apply_geo_layer( 209 self, text: str, name_hint: Optional[str] = None 210 ) -> tuple["MulticonductorNetwork", Any]: 211 """Apply a geographic sidecar and return ``(placed, report)``. 212 213 ``text`` is any form :func:`powerio.parse_geo` accepts. This network 214 is unchanged; the placed copy drops the retained source text, so a 215 same-format emission re-serializes. 216 """ 217 inner, report = self._inner.apply_geo_layer(text, name_hint) 218 return MulticonductorNetwork(inner), report 219 220 def __repr__(self) -> str: 221 return self._inner.__repr__()
A parsed multiconductor distribution network in wire coordinates.
Buses carry named terminals, lines carry conductor impedance matrices, and
transformers carry per winding connections. This type is distinct from the
positive sequence powerio.BalancedNetwork; balanced matrix calculations do not
accept it.
71 @property 72 def name(self) -> Optional[str]: 73 """Distribution network name when the source format carries one.""" 74 return self._inner.name()
Distribution network name when the source format carries one.
76 @property 77 def source_format(self) -> Optional[str]: 78 """Format parsed from: ``dss``, ``pmd-json``, ``pmd-math-json``, 79 ``bmopf-json``, ``ravens-json``, ``cim-dist``, ``pandapower-json``, or 80 ``sincal``; ``None`` for a network built in code.""" 81 return self._inner.source_format()
Format parsed from: dss, pmd-json, pmd-math-json,
bmopf-json, ravens-json, cim-dist, pandapower-json, or
sincal; None for a network built in code.
83 @property 84 def base_frequency(self) -> float: 85 """System base frequency in hertz.""" 86 return self._inner.base_frequency()
System base frequency in hertz.
132 @property 133 def n_voltage_sources(self) -> int: 134 """Number of grid forming voltage sources.""" 135 return self._inner.n_voltage_sources()
Number of grid forming voltage sources.
197 def to_graph(self) -> Any: 198 """Transform the network to collapsed bus and terminal graph data.""" 199 return _json.loads(self._inner.graph_json())
Transform the network to collapsed bus and terminal graph data.
201 def to_geo_layer(self) -> Any: 202 """Transform coordinates to a canonical GeoJSON FeatureCollection. 203 204 A network without coordinates produces an empty feature collection. 205 """ 206 return _json.loads(self._inner.to_geo_layer_json())
Transform coordinates to a canonical GeoJSON FeatureCollection.
A network without coordinates produces an empty feature collection.
208 def apply_geo_layer( 209 self, text: str, name_hint: Optional[str] = None 210 ) -> tuple["MulticonductorNetwork", Any]: 211 """Apply a geographic sidecar and return ``(placed, report)``. 212 213 ``text`` is any form :func:`powerio.parse_geo` accepts. This network 214 is unchanged; the placed copy drops the retained source text, so a 215 same-format emission re-serializes. 216 """ 217 inner, report = self._inner.apply_geo_layer(text, name_hint) 218 return MulticonductorNetwork(inner), report
Apply a geographic sidecar and return (placed, report).
text is any form powerio.parse_geo() accepts. This network
is unchanged; the placed copy drops the retained source text, so a
same-format emission re-serializes.
1361@_guard_class 1362class OperatingPoint(_TypedValue): 1363 """A possibly partial assignment over fixed equipment identities.""" 1364 1365 @property 1366 def network(self) -> "BalancedNetwork": 1367 """The balanced network this operating point is stated over. 1368 1369 The point's own values are applied to the returned copy, so it is the 1370 network a solver receives for this entry; the collection's shared 1371 base network is not changed. A multiconductor operating point raises 1372 :class:`PowerIOError`. 1373 1374 Net bus injection quantities have no balanced network field, so they 1375 are dropped here and the property reports nothing. Emit the 1376 collection when you need that omission reported: `emit` warns 1377 `EMIT.OPERATING_POINT.DATA_OMITTED` for the same point. 1378 """ 1379 return BalancedNetwork(self.module._inner._operating_point_network())
A possibly partial assignment over fixed equipment identities.
1365 @property 1366 def network(self) -> "BalancedNetwork": 1367 """The balanced network this operating point is stated over. 1368 1369 The point's own values are applied to the returned copy, so it is the 1370 network a solver receives for this entry; the collection's shared 1371 base network is not changed. A multiconductor operating point raises 1372 :class:`PowerIOError`. 1373 1374 Net bus injection quantities have no balanced network field, so they 1375 are dropped here and the property reports nothing. Emit the 1376 collection when you need that omission reported: `emit` warns 1377 `EMIT.OPERATING_POINT.DATA_OMITTED` for the same point. 1378 """ 1379 return BalancedNetwork(self.module._inner._operating_point_network())
The balanced network this operating point is stated over.
The point's own values are applied to the returned copy, so it is the
network a solver receives for this entry; the collection's shared
base network is not changed. A multiconductor operating point raises
PowerIOError.
Net bus injection quantities have no balanced network field, so they
are dropped here and the property reports nothing. Emit the
collection when you need that omission reported: emit warns
EMIT.OPERATING_POINT.DATA_OMITTED for the same point.
Inherited Members
1815@_guard_class 1816class PioModule: 1817 """One typed value with diagnostics, producer, sources, source mappings, 1818 history, and extensions. 1819 """ 1820 1821 def __init__(self, inner: "_powerio._PioModule"): 1822 self._inner = inner 1823 1824 def sever_source(self) -> "PioModule": 1825 """Copy this module without retained input bytes, forcing fresh emission. 1826 1827 The original module is unchanged. Values, diagnostics, source 1828 descriptors, and history are preserved; preparing the copy has a cost 1829 separate from emission. 1830 """ 1831 return PioModule(self._inner.sever_source()) 1832 1833 @classmethod 1834 def from_value(cls, value: Any) -> "PioModule": 1835 """Wrap an existing typed value without serializing it.""" 1836 if isinstance(value, BalancedNetwork): 1837 return cls(_powerio._PioModule.from_balanced_network(value._inner)) 1838 if isinstance(value, dist.MulticonductorNetwork): 1839 return cls(_powerio._PioModule.from_multiconductor_network(value._inner)) 1840 if isinstance(value, _TypedValue): 1841 location = value._collection_entry 1842 inner = value.module._inner 1843 if location is not None: 1844 inner = location.root._inner 1845 if location.scenario_id is not None: 1846 inner = inner._scenario_get(location.scenario_id) 1847 if location.time_index is not None: 1848 inner = inner._time_series_get(location.time_index) 1849 return cls(inner._copy()) 1850 raise TypeError("PioModule.from_value expects a typed PowerIO value") 1851 1852 @property 1853 def value(self) -> Any: 1854 """The contained typed value.""" 1855 type_name = self._inner._type_name 1856 if type_name == "powerio.BalancedNetwork": 1857 return BalancedNetwork(self._inner.as_balanced_network()) 1858 if type_name == "powerio.MulticonductorNetwork": 1859 return dist.MulticonductorNetwork(self._inner.as_multiconductor_network()) 1860 if type_name.startswith("powerio.TimeSeries<"): 1861 return TimeSeries._from_module(self) 1862 if type_name.startswith("powerio.ScenarioSet<"): 1863 return ScenarioSet._from_module(self) 1864 value_class = _VALUE_CLASSES.get(type_name) 1865 if value_class is None: 1866 raise RuntimeError(f"this binding has no Python class for {type_name}") 1867 return value_class(self) 1868 1869 @property 1870 def type_name(self) -> str: 1871 """The canonical structural name of the contained value, such as 1872 ``powerio.OperatingPoint<powerio.BalancedNetwork>``. The C ABI and 1873 PowerIO IR name the same type with the same string. 1874 """ 1875 return str(self._inner._type_name) 1876 1877 @property 1878 def diagnostics(self) -> list[Diagnostic]: 1879 """The diagnostics stored on this module, in encounter order.""" 1880 return list(self._inner.diagnostics) 1881 1882 @property 1883 def extension_keys(self) -> list[str]: 1884 """The namespaces of the extensions this module carries, sorted.""" 1885 return list(self._inner._extension_keys) 1886 1887 def extension(self, namespace: str) -> Any: 1888 """The JSON value stored under ``namespace``, or ``None``. 1889 1890 Only that value is decoded; the module is not serialized. 1891 """ 1892 text = self._inner._extension_json(namespace) 1893 return None if text is None else _json.loads(text) 1894 1895 def with_extension(self, namespace: str, value: Any) -> "PioModule": 1896 """A copy of this module carrying ``value`` under ``namespace``. 1897 1898 ``value`` must be JSON serializable. The copy keeps the typed value, 1899 diagnostics, sources, and history without serializing them; an 1900 extension already stored under ``namespace`` is replaced. The original 1901 module is unchanged. 1902 """ 1903 return PioModule(self._inner._with_extension_json(namespace, _json.dumps(value))) 1904 1905 def to_balanced_report(self, base_mva: float = 100.0) -> Any: 1906 """Report whether a multiconductor network can become balanced.""" 1907 return _json.loads(self._inner.lowering_readiness_json(base_mva)) 1908 1909 def to_balanced(self, base_mva: float = 100.0) -> "PioModule": 1910 """Transform a multiconductor network to a balanced module.""" 1911 return PioModule(self._inner.lower_to_balanced(base_mva)) 1912 1913 def to_dc_pf_instance(self) -> "PioModule": 1914 """Build a DC power flow instance from a balanced network module.""" 1915 return PioModule(self._inner._to_dc_pf_instance()) 1916 1917 def to_ac_pf_instance(self) -> "PioModule": 1918 """Build an AC power flow instance from a balanced network module.""" 1919 return PioModule(self._inner._to_ac_pf_instance()) 1920 1921 def to_dc_opf_instance(self) -> "PioModule": 1922 """Build a DC optimal power flow instance from a balanced network module.""" 1923 return PioModule(self._inner._to_dc_opf_instance()) 1924 1925 def to_ac_opf_instance(self) -> "PioModule": 1926 """Build an AC optimal power flow instance from a balanced network module.""" 1927 return PioModule(self._inner._to_ac_opf_instance()) 1928 1929 def to_ac_ots_instance( 1930 self, 1931 *, 1932 switchable: Union[str, Sequence[str], None] = None, 1933 switching_costs: Optional[Mapping[str, tuple[float, float]]] = None, 1934 islanding: Optional[str] = None, 1935 max_open: Optional[int] = None, 1936 max_switched: Optional[int] = None, 1937 current_limits: Optional[str] = None, 1938 stated_current_limits: Optional[ 1939 Mapping[str, tuple[Optional[float], Optional[float]]] 1940 ] = None, 1941 ) -> "PioModule": 1942 """Build an AC optimal transmission switching instance from a balanced 1943 network, AC optimal power flow, or AC optimal transmission switching 1944 module. 1945 1946 With no option, this gives the default instance: every initially 1947 in-service branch may switch, at zero cost, islanding is forbidden, 1948 there is no budget and no current limit, and the objective gains the 1949 switching cost term. An AC optimal transmission switching module comes 1950 back unchanged. 1951 1952 Any option makes the options explicit, as the C ABI's options struct 1953 and PowerIO.jl's ``AcOtsOptions`` do, and an option not given takes 1954 its explicit default: 1955 1956 - ``switchable``: ``"all"`` (the default, which includes initially 1957 open branches), ``"none"``, or a list of branch identities. 1958 - ``switching_costs``: ``{branch_id: (open_cost, close_cost)}``; a 1959 branch with no entry switches at zero cost. 1960 - ``islanding``: ``"forbidden"`` (the default) or ``"allowed"``. 1961 - ``max_open``: the most branches open in the final topology, 1962 counting fixed open rows; ``None`` is no budget. 1963 - ``max_switched``: the most status changes; ``None`` is no budget. 1964 - ``current_limits``: ``"skip"`` (the default), ``"stated"``, or 1965 ``"derive_from_rate_a"``. 1966 - ``stated_current_limits``: ``{branch_id: (from_pu, to_pu)}``, per 1967 unit; ``None`` on a side is unbounded. 1968 1969 The base problem and objective are kept, and the objective gains the 1970 switching cost term once. Refused options raise 1971 :class:`PowerIOError` with code 1972 ``BUILD.INSTANCE.SWITCHING_OPTIONS_INVALID``; an unknown policy name 1973 raises :class:`ValueError`. 1974 """ 1975 if ( 1976 switchable is None 1977 and switching_costs is None 1978 and islanding is None 1979 and max_open is None 1980 and max_switched is None 1981 and current_limits is None 1982 and stated_current_limits is None 1983 ): 1984 return PioModule(self._inner._to_ac_ots_instance()) 1985 if switchable is None: 1986 selection, identities = "all", [] 1987 elif isinstance(switchable, str): 1988 selection, identities = switchable, [] 1989 else: 1990 selection, identities = "only", [str(identity) for identity in switchable] 1991 for name, budget in (("max_open", max_open), ("max_switched", max_switched)): 1992 if budget is not None and ( 1993 isinstance(budget, bool) or not isinstance(budget, int) or budget < 0 1994 ): 1995 raise ValueError(f"{name} must be a nonnegative integer or None") 1996 costs = [ 1997 (str(identity), float(open_cost), float(close_cost)) 1998 for identity, (open_cost, close_cost) in (switching_costs or {}).items() 1999 ] 2000 limits = [ 2001 ( 2002 str(identity), 2003 None if from_pu is None else float(from_pu), 2004 None if to_pu is None else float(to_pu), 2005 ) 2006 for identity, (from_pu, to_pu) in (stated_current_limits or {}).items() 2007 ] 2008 return PioModule( 2009 self._inner._to_ac_ots_instance_with_options( 2010 selection, 2011 identities, 2012 costs, 2013 "forbidden" if islanding is None else islanding, 2014 max_open, 2015 max_switched, 2016 "skip" if current_limits is None else current_limits, 2017 limits, 2018 ) 2019 ) 2020 2021 def to_mc_ac_pf_instance(self) -> "PioModule": 2022 """Build a multiconductor AC power flow instance from a network module.""" 2023 return PioModule(self._inner._to_mc_ac_pf_instance()) 2024 2025 def to_mc_ac_opf_instance(self) -> "PioModule": 2026 """Build a multiconductor AC optimal power flow instance from a network module.""" 2027 return PioModule(self._inner._to_mc_ac_opf_instance()) 2028 2029 def to_lindist3flow_opf_instance(self) -> "PioModule": 2030 """Build a LinDist3Flow optimal power flow instance from a network module.""" 2031 return PioModule(self._inner._to_lindist3flow_opf_instance()) 2032 2033 def to_lindist3flow_pf_instance(self) -> "PioModule": 2034 """Build a fixed-dispatch LinDist3Flow instance from a network module.""" 2035 return PioModule(self._inner._to_lindist3flow_pf_instance()) 2036 2037 def __repr__(self) -> str: 2038 return repr(self._inner)
Abstract base class for generic types.
On Python 3.12 and newer, generic classes implicitly inherit from Generic when they declare a parameter list after the class's name::
class Mapping[KT, VT]:
def __getitem__(self, key: KT) -> VT:
...
# Etc.
On older versions of Python, however, generic classes have to explicitly inherit from Generic.
After a class has been declared to be generic, it can then be used as follows::
def lookup_name[KT, VT](mapping: Mapping[KT, VT], key: KT, default: VT) -> VT:
try:
return mapping[key]
except KeyError:
return default
1824 def sever_source(self) -> "PioModule": 1825 """Copy this module without retained input bytes, forcing fresh emission. 1826 1827 The original module is unchanged. Values, diagnostics, source 1828 descriptors, and history are preserved; preparing the copy has a cost 1829 separate from emission. 1830 """ 1831 return PioModule(self._inner.sever_source())
Copy this module without retained input bytes, forcing fresh emission.
The original module is unchanged. Values, diagnostics, source descriptors, and history are preserved; preparing the copy has a cost separate from emission.
1833 @classmethod 1834 def from_value(cls, value: Any) -> "PioModule": 1835 """Wrap an existing typed value without serializing it.""" 1836 if isinstance(value, BalancedNetwork): 1837 return cls(_powerio._PioModule.from_balanced_network(value._inner)) 1838 if isinstance(value, dist.MulticonductorNetwork): 1839 return cls(_powerio._PioModule.from_multiconductor_network(value._inner)) 1840 if isinstance(value, _TypedValue): 1841 location = value._collection_entry 1842 inner = value.module._inner 1843 if location is not None: 1844 inner = location.root._inner 1845 if location.scenario_id is not None: 1846 inner = inner._scenario_get(location.scenario_id) 1847 if location.time_index is not None: 1848 inner = inner._time_series_get(location.time_index) 1849 return cls(inner._copy()) 1850 raise TypeError("PioModule.from_value expects a typed PowerIO value")
Wrap an existing typed value without serializing it.
1852 @property 1853 def value(self) -> Any: 1854 """The contained typed value.""" 1855 type_name = self._inner._type_name 1856 if type_name == "powerio.BalancedNetwork": 1857 return BalancedNetwork(self._inner.as_balanced_network()) 1858 if type_name == "powerio.MulticonductorNetwork": 1859 return dist.MulticonductorNetwork(self._inner.as_multiconductor_network()) 1860 if type_name.startswith("powerio.TimeSeries<"): 1861 return TimeSeries._from_module(self) 1862 if type_name.startswith("powerio.ScenarioSet<"): 1863 return ScenarioSet._from_module(self) 1864 value_class = _VALUE_CLASSES.get(type_name) 1865 if value_class is None: 1866 raise RuntimeError(f"this binding has no Python class for {type_name}") 1867 return value_class(self)
The contained typed value.
1869 @property 1870 def type_name(self) -> str: 1871 """The canonical structural name of the contained value, such as 1872 ``powerio.OperatingPoint<powerio.BalancedNetwork>``. The C ABI and 1873 PowerIO IR name the same type with the same string. 1874 """ 1875 return str(self._inner._type_name)
The canonical structural name of the contained value, such as
powerio.OperatingPoint<powerio.BalancedNetwork>. The C ABI and
PowerIO IR name the same type with the same string.
1877 @property 1878 def diagnostics(self) -> list[Diagnostic]: 1879 """The diagnostics stored on this module, in encounter order.""" 1880 return list(self._inner.diagnostics)
The diagnostics stored on this module, in encounter order.
1882 @property 1883 def extension_keys(self) -> list[str]: 1884 """The namespaces of the extensions this module carries, sorted.""" 1885 return list(self._inner._extension_keys)
The namespaces of the extensions this module carries, sorted.
1887 def extension(self, namespace: str) -> Any: 1888 """The JSON value stored under ``namespace``, or ``None``. 1889 1890 Only that value is decoded; the module is not serialized. 1891 """ 1892 text = self._inner._extension_json(namespace) 1893 return None if text is None else _json.loads(text)
The JSON value stored under namespace, or None.
Only that value is decoded; the module is not serialized.
1895 def with_extension(self, namespace: str, value: Any) -> "PioModule": 1896 """A copy of this module carrying ``value`` under ``namespace``. 1897 1898 ``value`` must be JSON serializable. The copy keeps the typed value, 1899 diagnostics, sources, and history without serializing them; an 1900 extension already stored under ``namespace`` is replaced. The original 1901 module is unchanged. 1902 """ 1903 return PioModule(self._inner._with_extension_json(namespace, _json.dumps(value)))
1905 def to_balanced_report(self, base_mva: float = 100.0) -> Any: 1906 """Report whether a multiconductor network can become balanced.""" 1907 return _json.loads(self._inner.lowering_readiness_json(base_mva))
Report whether a multiconductor network can become balanced.
1909 def to_balanced(self, base_mva: float = 100.0) -> "PioModule": 1910 """Transform a multiconductor network to a balanced module.""" 1911 return PioModule(self._inner.lower_to_balanced(base_mva))
Transform a multiconductor network to a balanced module.
1913 def to_dc_pf_instance(self) -> "PioModule": 1914 """Build a DC power flow instance from a balanced network module.""" 1915 return PioModule(self._inner._to_dc_pf_instance())
Build a DC power flow instance from a balanced network module.
1917 def to_ac_pf_instance(self) -> "PioModule": 1918 """Build an AC power flow instance from a balanced network module.""" 1919 return PioModule(self._inner._to_ac_pf_instance())
Build an AC power flow instance from a balanced network module.
1921 def to_dc_opf_instance(self) -> "PioModule": 1922 """Build a DC optimal power flow instance from a balanced network module.""" 1923 return PioModule(self._inner._to_dc_opf_instance())
Build a DC optimal power flow instance from a balanced network module.
1925 def to_ac_opf_instance(self) -> "PioModule": 1926 """Build an AC optimal power flow instance from a balanced network module.""" 1927 return PioModule(self._inner._to_ac_opf_instance())
Build an AC optimal power flow instance from a balanced network module.
1929 def to_ac_ots_instance( 1930 self, 1931 *, 1932 switchable: Union[str, Sequence[str], None] = None, 1933 switching_costs: Optional[Mapping[str, tuple[float, float]]] = None, 1934 islanding: Optional[str] = None, 1935 max_open: Optional[int] = None, 1936 max_switched: Optional[int] = None, 1937 current_limits: Optional[str] = None, 1938 stated_current_limits: Optional[ 1939 Mapping[str, tuple[Optional[float], Optional[float]]] 1940 ] = None, 1941 ) -> "PioModule": 1942 """Build an AC optimal transmission switching instance from a balanced 1943 network, AC optimal power flow, or AC optimal transmission switching 1944 module. 1945 1946 With no option, this gives the default instance: every initially 1947 in-service branch may switch, at zero cost, islanding is forbidden, 1948 there is no budget and no current limit, and the objective gains the 1949 switching cost term. An AC optimal transmission switching module comes 1950 back unchanged. 1951 1952 Any option makes the options explicit, as the C ABI's options struct 1953 and PowerIO.jl's ``AcOtsOptions`` do, and an option not given takes 1954 its explicit default: 1955 1956 - ``switchable``: ``"all"`` (the default, which includes initially 1957 open branches), ``"none"``, or a list of branch identities. 1958 - ``switching_costs``: ``{branch_id: (open_cost, close_cost)}``; a 1959 branch with no entry switches at zero cost. 1960 - ``islanding``: ``"forbidden"`` (the default) or ``"allowed"``. 1961 - ``max_open``: the most branches open in the final topology, 1962 counting fixed open rows; ``None`` is no budget. 1963 - ``max_switched``: the most status changes; ``None`` is no budget. 1964 - ``current_limits``: ``"skip"`` (the default), ``"stated"``, or 1965 ``"derive_from_rate_a"``. 1966 - ``stated_current_limits``: ``{branch_id: (from_pu, to_pu)}``, per 1967 unit; ``None`` on a side is unbounded. 1968 1969 The base problem and objective are kept, and the objective gains the 1970 switching cost term once. Refused options raise 1971 :class:`PowerIOError` with code 1972 ``BUILD.INSTANCE.SWITCHING_OPTIONS_INVALID``; an unknown policy name 1973 raises :class:`ValueError`. 1974 """ 1975 if ( 1976 switchable is None 1977 and switching_costs is None 1978 and islanding is None 1979 and max_open is None 1980 and max_switched is None 1981 and current_limits is None 1982 and stated_current_limits is None 1983 ): 1984 return PioModule(self._inner._to_ac_ots_instance()) 1985 if switchable is None: 1986 selection, identities = "all", [] 1987 elif isinstance(switchable, str): 1988 selection, identities = switchable, [] 1989 else: 1990 selection, identities = "only", [str(identity) for identity in switchable] 1991 for name, budget in (("max_open", max_open), ("max_switched", max_switched)): 1992 if budget is not None and ( 1993 isinstance(budget, bool) or not isinstance(budget, int) or budget < 0 1994 ): 1995 raise ValueError(f"{name} must be a nonnegative integer or None") 1996 costs = [ 1997 (str(identity), float(open_cost), float(close_cost)) 1998 for identity, (open_cost, close_cost) in (switching_costs or {}).items() 1999 ] 2000 limits = [ 2001 ( 2002 str(identity), 2003 None if from_pu is None else float(from_pu), 2004 None if to_pu is None else float(to_pu), 2005 ) 2006 for identity, (from_pu, to_pu) in (stated_current_limits or {}).items() 2007 ] 2008 return PioModule( 2009 self._inner._to_ac_ots_instance_with_options( 2010 selection, 2011 identities, 2012 costs, 2013 "forbidden" if islanding is None else islanding, 2014 max_open, 2015 max_switched, 2016 "skip" if current_limits is None else current_limits, 2017 limits, 2018 ) 2019 )
Build an AC optimal transmission switching instance from a balanced network, AC optimal power flow, or AC optimal transmission switching module.
With no option, this gives the default instance: every initially in-service branch may switch, at zero cost, islanding is forbidden, there is no budget and no current limit, and the objective gains the switching cost term. An AC optimal transmission switching module comes back unchanged.
Any option makes the options explicit, as the C ABI's options struct
and PowerIO.jl's AcOtsOptions do, and an option not given takes
its explicit default:
switchable:"all"(the default, which includes initially open branches),"none", or a list of branch identities.switching_costs:{branch_id: (open_cost, close_cost)}; a branch with no entry switches at zero cost.islanding:"forbidden"(the default) or"allowed".max_open: the most branches open in the final topology, counting fixed open rows;Noneis no budget.max_switched: the most status changes;Noneis no budget.current_limits:"skip"(the default),"stated", or"derive_from_rate_a".stated_current_limits:{branch_id: (from_pu, to_pu)}, per unit;Noneon a side is unbounded.
The base problem and objective are kept, and the objective gains the
switching cost term once. Refused options raise
PowerIOError with code
BUILD.INSTANCE.SWITCHING_OPTIONS_INVALID; an unknown policy name
raises ValueError.
2021 def to_mc_ac_pf_instance(self) -> "PioModule": 2022 """Build a multiconductor AC power flow instance from a network module.""" 2023 return PioModule(self._inner._to_mc_ac_pf_instance())
Build a multiconductor AC power flow instance from a network module.
2025 def to_mc_ac_opf_instance(self) -> "PioModule": 2026 """Build a multiconductor AC optimal power flow instance from a network module.""" 2027 return PioModule(self._inner._to_mc_ac_opf_instance())
Build a multiconductor AC optimal power flow instance from a network module.
2029 def to_lindist3flow_opf_instance(self) -> "PioModule": 2030 """Build a LinDist3Flow optimal power flow instance from a network module.""" 2031 return PioModule(self._inner._to_lindist3flow_opf_instance())
Build a LinDist3Flow optimal power flow instance from a network module.
A well-formed case cannot satisfy a requested operation.
Core errors carry typed Diagnostic records. Refused conversion passes retain dictionary findings with code, severity, message, and target.
Base error from parsing, emission, or matrix calculations.
Rust core failures carry a diagnostic code and typed Diagnostic records. Refused conversion passes retain their existing dictionary findings. These attributes are populated when the exception is raised.
A case file is malformed or unparseable.
1298@_guard_class 1299class ScenarioSet(_TypedValue, Mapping): 1300 """Named alternatives of one type, with optional probabilities.""" 1301 1302 def __init__( 1303 self, 1304 values: Mapping[str, Any], 1305 *, 1306 probabilities: Optional[Mapping[str, float]] = None, 1307 ) -> None: 1308 if not isinstance(values, Mapping): 1309 raise TypeError("ScenarioSet values must be a mapping from IDs to values") 1310 if probabilities is not None and not isinstance(probabilities, Mapping): 1311 raise TypeError("probabilities must be a mapping from scenario IDs to numbers") 1312 ids = list(values) 1313 modules = [PioModule.from_value(values[id])._inner for id in ids] 1314 inner = _powerio._PioModule._from_scenario_set( 1315 modules, 1316 ids, 1317 None if probabilities is None else dict(probabilities), 1318 ) 1319 super().__init__(PioModule(inner)) 1320 1321 @classmethod 1322 def _from_module(cls, module: "PioModule") -> "ScenarioSet": 1323 value = object.__new__(cls) 1324 _TypedValue.__init__(value, module) 1325 return value 1326 1327 @property 1328 def scenarios(self) -> tuple[Scenario, ...]: 1329 return tuple(Scenario(*entry) for entry in self.module._inner._scenario_entries()) 1330 1331 def __len__(self) -> int: 1332 return len(self.scenarios) 1333 1334 def __iter__(self): 1335 return (scenario.id for scenario in self.scenarios) 1336 1337 def __contains__(self, scenario: object) -> bool: 1338 return isinstance(scenario, str) and any( 1339 entry.id == scenario for entry in self.scenarios 1340 ) 1341 1342 def __getitem__(self, scenario: str) -> Any: 1343 if not isinstance(scenario, str): 1344 raise TypeError("scenario keys must be strings") 1345 if scenario not in self: 1346 raise KeyError(scenario) 1347 current = self._collection_entry or _CollectionEntry(self.module) 1348 if current.scenario_id is not None: 1349 raise TypeError("nested ScenarioSet values are not supported") 1350 value = PioModule(self.module._inner._scenario_get(scenario)).value 1351 return _bind_collection_entry( 1352 value, 1353 _CollectionEntry( 1354 root=current.root, 1355 time_index=current.time_index, 1356 scenario_id=scenario, 1357 ), 1358 )
A Mapping is a generic container for associating key/value pairs.
This class provides concrete generic implementations of all methods except for __getitem__, __iter__, and __len__.
1302 def __init__( 1303 self, 1304 values: Mapping[str, Any], 1305 *, 1306 probabilities: Optional[Mapping[str, float]] = None, 1307 ) -> None: 1308 if not isinstance(values, Mapping): 1309 raise TypeError("ScenarioSet values must be a mapping from IDs to values") 1310 if probabilities is not None and not isinstance(probabilities, Mapping): 1311 raise TypeError("probabilities must be a mapping from scenario IDs to numbers") 1312 ids = list(values) 1313 modules = [PioModule.from_value(values[id])._inner for id in ids] 1314 inner = _powerio._PioModule._from_scenario_set( 1315 modules, 1316 ids, 1317 None if probabilities is None else dict(probabilities), 1318 ) 1319 super().__init__(PioModule(inner))
Inherited Members
16@dataclass(frozen=True) 17class SincalBalancedReadOptions: 18 """Native variant, daily snapshot and optional verified Access companion. 19 20 Use with ``parse(..., format="sincal-balanced", sincal_balanced=...)``. 21 Parsing never invokes an acquisition tool. The primary source remains the MDB. 22 """ 23 variant: Optional[int] = None 24 snapshot_hours: Optional[float] = None 25 acquired_tables: Optional[str] = None 26 27 def __post_init__(self): 28 _validate_selection(self)
Native variant, daily snapshot and optional verified Access companion.
Use with parse(..., format="sincal-balanced", sincal_balanced=...).
Parsing never invokes an acquisition tool. The primary source remains the MDB.
1617class SocwrOpfSolution(_BalancedCalculation, _CalculationSolution): 1618 """A PowerModels SOCWR relaxation solution and objective lower bound."""
A PowerModels SOCWR relaxation solution and objective lower bound.
Inherited Members
One source byte range a diagnostic points at: the Python mirror of
powerio_core::SourceSpan. source is the source ID string, not the
bytes themselves; a caller resolves it against the owning module's
sources.
1753@_guard_class 1754class SubsystemSet(_TypedValue): 1755 """A PSS/E subsystem description file: the named bus groups a contingency 1756 run and a monitored element file draw on. 1757 1758 :func:`parse` returns it for a ``.sub`` file or for text declared as 1759 ``psse-sub``, and ``network.select_subsystem_buses(groups.text, name)`` 1760 names the buses one subsystem selects. 1761 """ 1762 1763 @property 1764 def text(self) -> str: 1765 """The ``.sub`` text for this set.""" 1766 return _emitted_text(self.module, "psse-sub")
A PSS/E subsystem description file: the named bus groups a contingency run and a monitored element file draw on.
parse() returns it for a .sub file or for text declared as
psse-sub, and network.select_subsystem_buses(groups.text, name)
names the buses one subsystem selects.
1763 @property 1764 def text(self) -> str: 1765 """The ``.sub`` text for this set.""" 1766 return _emitted_text(self.module, "psse-sub")
The .sub text for this set.
Inherited Members
1231@_guard_class 1232class TimeSeries(_TypedValue, Sequence): 1233 """Values of one type ordered in time.""" 1234 1235 def __init__( 1236 self, 1237 values: Sequence[Any], 1238 *, 1239 time_points: Sequence[TimePoint], 1240 ) -> None: 1241 if isinstance(values, (str, bytes, bytearray)) or not isinstance( 1242 values, Sequence 1243 ): 1244 raise TypeError("TimeSeries values must be a sequence of PowerIO values") 1245 if not isinstance(time_points, Sequence): 1246 raise TypeError("time_points must be a sequence of TimePoint values") 1247 points = tuple(time_points) 1248 if not all(isinstance(point, TimePoint) for point in points): 1249 raise TypeError("time_points must contain only TimePoint values") 1250 modules = [PioModule.from_value(value)._inner for value in values] 1251 inner = _powerio._PioModule._from_time_series( 1252 modules, 1253 [(point.label, point.duration_seconds) for point in points], 1254 ) 1255 super().__init__(PioModule(inner)) 1256 1257 @classmethod 1258 def _from_module(cls, module: "PioModule") -> "TimeSeries": 1259 value = object.__new__(cls) 1260 _TypedValue.__init__(value, module) 1261 return value 1262 1263 @property 1264 def time_points(self) -> tuple[TimePoint, ...]: 1265 return tuple(TimePoint(*point) for point in self.module._inner._time_series_points()) 1266 1267 def __len__(self) -> int: 1268 return self.module._inner._time_series_len() 1269 1270 def __getitem__(self, index): 1271 if isinstance(index, slice): 1272 return [self[position] for position in range(*index.indices(len(self)))] 1273 try: 1274 position = _operator.index(index) 1275 except TypeError: 1276 raise TypeError("time series indices must be integers") from None 1277 if position < 0: 1278 position += len(self) 1279 if position < 0 or position >= len(self): 1280 raise IndexError("time series index out of range") 1281 current = self._collection_entry or _CollectionEntry(self.module) 1282 if current.time_index is not None: 1283 raise TypeError("nested TimeSeries values are not supported") 1284 value = PioModule(self.module._inner._time_series_get(position)).value 1285 return _bind_collection_entry( 1286 value, 1287 _CollectionEntry( 1288 root=current.root, 1289 time_index=position, 1290 scenario_id=current.scenario_id, 1291 ), 1292 ) 1293 1294 def __iter__(self): 1295 return (self[position] for position in range(len(self)))
All the operations on a read-only sequence.
Concrete subclasses must override __new__ or __init__, __getitem__, and __len__.
1235 def __init__( 1236 self, 1237 values: Sequence[Any], 1238 *, 1239 time_points: Sequence[TimePoint], 1240 ) -> None: 1241 if isinstance(values, (str, bytes, bytearray)) or not isinstance( 1242 values, Sequence 1243 ): 1244 raise TypeError("TimeSeries values must be a sequence of PowerIO values") 1245 if not isinstance(time_points, Sequence): 1246 raise TypeError("time_points must be a sequence of TimePoint values") 1247 points = tuple(time_points) 1248 if not all(isinstance(point, TimePoint) for point in points): 1249 raise TypeError("time_points must contain only TimePoint values") 1250 modules = [PioModule.from_value(value)._inner for value in values] 1251 inner = _powerio._PioModule._from_time_series( 1252 modules, 1253 [(point.label, point.duration_seconds) for point in points], 1254 ) 1255 super().__init__(PioModule(inner))
Inherited Members
2112@_guard 2113def apply_bus_load_active_power( 2114 module: PioModule, 2115 bus_id: int, 2116 total: ActivePower, 2117 *, 2118 allocation: str = "proportional_to_current_active_power", 2119) -> UpdateReport: 2120 """Replace aggregate bus demand through an explicit PowerIO allocation rule. 2121 2122 ``"proportional_to_current_active_power"`` preserves each participating 2123 load's current share. ``"equal"`` gives every participating load the same 2124 share, including when their current aggregate demand is zero. PowerIO 2125 requires stable load IDs and reports each load changed. 2126 """ 2127 if not isinstance(module, PioModule): 2128 raise TypeError("module must be a PioModule") 2129 if not isinstance(total, ActivePower): 2130 raise TypeError("total must be an ActivePower") 2131 return module._inner._apply_bus_load_active_power( 2132 bus_id, 2133 total, 2134 allocation=allocation, 2135 )
Replace aggregate bus demand through an explicit PowerIO allocation rule.
"proportional_to_current_active_power" preserves each participating
load's current share. "equal" gives every participating load the same
share, including when their current aggregate demand is zero. PowerIO
requires stable load IDs and reports each load changed.
2078@_guard 2079def apply_updates( 2080 target: Any, 2081 updates: Union[ 2082 Iterable[OperatingPointUpdate], 2083 Iterable[NetworkUpdate], 2084 Iterable[CalculationUpdate], 2085 ], 2086) -> UpdateReport: 2087 """Validate and apply one batch of typed updates atomically. 2088 2089 ``updates`` contains one update class: :class:`OperatingPointUpdate`, 2090 :class:`NetworkUpdate`, or :class:`CalculationUpdate`. Values are absolute 2091 replacements and power quantities carry their units in the typed value. 2092 ``target`` is a module or a value obtained by indexing a :class:`TimeSeries` 2093 or :class:`ScenarioSet`. If validation fails, the module is unchanged. 2094 """ 2095 batch = list(updates) 2096 if isinstance(target, PioModule): 2097 return target._inner._apply_updates(batch) 2098 location = getattr(target, "_collection_entry", None) 2099 if not isinstance(location, _CollectionEntry): 2100 raise TypeError( 2101 "target must be a PioModule or a TimeSeries/ScenarioSet entry" 2102 ) 2103 report = location.root._inner._apply_collection_updates( 2104 batch, 2105 time_index=location.time_index, 2106 scenario_id=location.scenario_id, 2107 ) 2108 _refresh_collection_entry(target, location) 2109 return report
Validate and apply one batch of typed updates atomically.
updates contains one update class: OperatingPointUpdate,
NetworkUpdate, or CalculationUpdate. Values are absolute
replacements and power quantities carry their units in the typed value.
target is a module or a value obtained by indexing a TimeSeries
or ScenarioSet. If validation fails, the module is unchanged.
2335@_guard 2336def deserialize(source: Any) -> PioModule: 2337 """Deserialize PowerIO IR from a path, file object, or bytes-like source.""" 2338 path = _path_from_source(source) 2339 if path is not None: 2340 return PioModule(_powerio._PioModule._deserialize_path(path)) 2341 data, _ = _memory_from_source(source, None) 2342 return PioModule(_powerio._PioModule._deserialize_memory(data))
Deserialize PowerIO IR from a path, file object, or bytes-like source.
2362@_guard 2363def diagnostic_record(diagnostic: Diagnostic) -> dict[str, Any]: 2364 """One diagnostic as a JSON-ready dictionary. 2365 2366 ``code``, ``severity``, ``message``, and ``target`` are always present, in 2367 that order. ``id``, ``suggested_action``, and ``related`` follow when the 2368 diagnostic sets them, ``details`` when it is not ``None``, and ``spans`` 2369 as ``source``, ``byte_start``, ``byte_end`` dictionaries when the 2370 diagnostic carries at least one span. 2371 """ 2372 record: dict[str, Any] = { 2373 "code": diagnostic.code, 2374 "severity": diagnostic.severity, 2375 "message": diagnostic.message, 2376 "target": diagnostic.target, 2377 } 2378 if diagnostic.id: 2379 record["id"] = diagnostic.id 2380 if diagnostic.suggested_action: 2381 record["suggested_action"] = diagnostic.suggested_action 2382 if diagnostic.related: 2383 record["related"] = list(diagnostic.related) 2384 if diagnostic.details is not None: 2385 record["details"] = diagnostic.details 2386 if diagnostic.spans: 2387 record["spans"] = [ 2388 { 2389 "source": span.source, 2390 "byte_start": span.byte_start, 2391 "byte_end": span.byte_end, 2392 } 2393 for span in diagnostic.spans 2394 ] 2395 return record
One diagnostic as a JSON-ready dictionary.
code, severity, message, and target are always present, in
that order. id, suggested_action, and related follow when the
diagnostic sets them, details when it is not None, and spans
as source, byte_start, byte_end dictionaries when the
diagnostic carries at least one span.
2398@_guard 2399def diagnostic_records(diagnostics: Iterable[Diagnostic]) -> list[dict[str, Any]]: 2400 """Every diagnostic as a JSON-ready dictionary, in the order given.""" 2401 return [diagnostic_record(item) for item in diagnostics]
Every diagnostic as a JSON-ready dictionary, in the order given.
2305@_guard 2306def emit(module: PioModule, format: str, destination: Optional[Any] = None) -> EmitResult: 2307 """Emit a module as one grid exchange format.""" 2308 from . import _sienna_files 2309 if format is not None and format in _sienna_files.FORMATS: 2310 return _sienna_files.emit(module, format, destination) 2311 from . import _pypsa_files 2312 if format in _pypsa_files.FORMATS: 2313 if not isinstance(module, PioModule): 2314 raise TypeError("module must be a PioModule") 2315 return _pypsa_files.emit(module, format, destination) 2316 return _emit_to_destination( 2317 module, 2318 destination, 2319 lambda: module._inner._emit_memory(format), 2320 lambda path: module._inner._emit_path(format, path), 2321 )
Emit a module as one grid exchange format.
2345@_guard 2346def features() -> dict[str, bool]: 2347 """The build-time features compiled into this powerio installation. 2348 2349 ``matrix``, ``dist``, and ``prob`` are unconditional dependencies of the 2350 extension and are always ``True``. ``gridfm`` reports whether GridFM 2351 Parquet parsing and emission were compiled in; the published wheel 2352 includes them, while a custom source build can omit them. 2353 """ 2354 return { 2355 "matrix": True, 2356 "gridfm": bool(getattr(_powerio, "_has_gridfm", False)), 2357 "dist": True, 2358 "prob": True, 2359 }
The build-time features compiled into this powerio installation.
matrix, dist, and prob are unconditional dependencies of the
extension and are always True. gridfm reports whether GridFM
Parquet parsing and emission were compiled in; the published wheel
includes them, while a custom source build can omit them.
1151@_guard 1152def from_ppc(ppc) -> BalancedNetwork: 1153 """Case from a PYPOWER dict (``ppc``); the inverse of :meth:`BalancedNetwork.to_ppc`. 1154 1155 The tables route through the MATPOWER reader, so the semantics match a 1156 ``.m`` case exactly: bus ``PD``/``QD`` become loads, ``GS``/``BS`` become 1157 shunts, and ``gencost`` is read when present. Result columns past the 1158 MATPOWER input widths are dropped. A 10 column ``gen`` table (the layout 1159 without the OPF capability columns) passes through at its own width, so 1160 the generators come back with no capability limits rather than eleven 1161 zero ones. Raises :class:`ValueError` when a required table is absent, 1162 when a ``bus`` or ``branch`` row is below its 13 column width, when a row 1163 is not a sequence of numbers, or when a cell is not numeric; the message 1164 names the table and the row. 1165 """ 1166 value = parse( 1167 _io.StringIO(_ppc_to_matpower_text(ppc)), 1168 format="matpower", 1169 name="from_ppc.m", 1170 ).value 1171 assert isinstance(value, BalancedNetwork) 1172 return value
Case from a PYPOWER dict (ppc); the inverse of BalancedNetwork.to_ppc().
The tables route through the MATPOWER reader, so the semantics match a
.m case exactly: bus PD/QD become loads, GS/BS become
shunts, and gencost is read when present. Result columns past the
MATPOWER input widths are dropped. A 10 column gen table (the layout
without the OPF capability columns) passes through at its own width, so
the generators come back with no capability limits rather than eleven
zero ones. Raises ValueError when a required table is absent,
when a bus or branch row is below its 13 column width, when a row
is not a sequence of numbers, or when a cell is not numeric; the message
names the table and the row.
2180@_guard 2181def parse( 2182 source: Any, 2183 *, 2184 format: Optional[str] = None, 2185 name: Optional[str] = None, 2186 sincal_multiconductor: Optional[dist.SincalReadOptions] = None, 2187 sincal_balanced: Optional[SincalBalancedReadOptions] = None, 2188 acquisition_root: Optional[Any] = None, 2189 named_buffers: Optional[Mapping[str, bytes]] = None, 2190 dss_max_include_bytes: Optional[int] = None, 2191 dss_max_properties: Optional[int] = None, 2192) -> PioModule: 2193 """Parse a path, file object, or bytes-like source. 2194 2195 A string is always a path. Pass raw text through ``io.StringIO`` or 2196 another file object. ``sincal_multiconductor`` requires explicit format 2197 ``sincal-multiconductor``; ``sincal_balanced`` requires ``sincal-balanced``. 2198 File companions stay beneath the file's parent, 2199 or an explicitly selected ``acquisition_root``. Memory sources use only 2200 ``named_buffers`` and never acquire companions from the filesystem. 2201 2202 ``dss_max_include_bytes`` and ``dss_max_properties`` raise two limits of 2203 an OpenDSS read for a case too large for the defaults: the bytes it may 2204 pull in through includes (64 MiB) and the property assignments and edit 2205 records it may retain (4,194,304). They have no effect on other formats. 2206 """ 2207 dss_limits = None 2208 for limit_name, limit in (("dss_max_include_bytes", dss_max_include_bytes), ("dss_max_properties", dss_max_properties)): 2209 if limit is None: 2210 continue 2211 if isinstance(limit, bool) or not isinstance(limit, int): 2212 raise TypeError(f"{limit_name} must be an integer") 2213 if limit < 0: 2214 raise ValueError(f"{limit_name} must not be negative") 2215 dss_limits = (dss_max_include_bytes, dss_max_properties) 2216 from . import _sienna_files 2217 if format is not None and format in _sienna_files.FORMATS: 2218 if sincal_balanced is not None or sincal_multiconductor is not None: 2219 raise ValueError("SINCAL options do not apply to Sienna bundles") 2220 return _sienna_files.parse(source, format, name=name, acquisition_root=acquisition_root, named_buffers=named_buffers) 2221 from . import _pypsa_files 2222 binary_format = _pypsa_files.detect(source, format) 2223 if binary_format is not None: 2224 if named_buffers is not None or acquisition_root is not None or sincal_balanced is not None or sincal_multiconductor is not None: 2225 raise ValueError("PyPSA binary containers are standalone sources") 2226 if name is not None and _path_from_source(source) is not None: 2227 raise ValueError("name is only valid for memory and file object sources") 2228 return _pypsa_files.parse(source, binary_format, name=name) 2229 balanced_selection, selection = _native_selections(sincal_balanced, sincal_multiconductor) 2230 path = _path_from_source(source) 2231 if path is not None: 2232 if name is not None: 2233 raise ValueError("name is only valid for memory and file object sources") 2234 if named_buffers is not None: 2235 raise ValueError("named_buffers applies only to memory and file object sources") 2236 root = _path_from_source(acquisition_root) if acquisition_root is not None else None 2237 if acquisition_root is not None and root is None: 2238 raise TypeError("acquisition_root must be a path") 2239 return PioModule(_powerio._PioModule._parse_path(path, format, selection, root, balanced_selection, dss_limits)) 2240 if acquisition_root is not None: 2241 raise ValueError("acquisition_root applies only to path sources") 2242 buffers = None 2243 if named_buffers is not None: 2244 if not isinstance(named_buffers, Mapping): 2245 raise TypeError("named_buffers must map relative names to bytes-like data") 2246 buffers = [] 2247 for buffer_name, buffer_data in named_buffers.items(): 2248 if not isinstance(buffer_name, str) or not isinstance(buffer_data, (bytes, bytearray, memoryview)): 2249 raise TypeError("named_buffers must map relative names to bytes-like data") 2250 buffers.append((buffer_name, bytes(buffer_data))) 2251 data, source_name = _memory_from_source(source, name) 2252 return PioModule(_powerio._PioModule._parse_memory(data, source_name, format, selection, buffers, balanced_selection, dss_limits))
Parse a path, file object, or bytes-like source.
A string is always a path. Pass raw text through io.StringIO or
another file object. sincal_multiconductor requires explicit format
sincal-multiconductor; sincal_balanced requires sincal-balanced.
File companions stay beneath the file's parent,
or an explicitly selected acquisition_root. Memory sources use only
named_buffers and never acquire companions from the filesystem.
dss_max_include_bytes and dss_max_properties raise two limits of
an OpenDSS read for a case too large for the defaults: the bytes it may
pull in through includes (64 MiB) and the property assignments and edit
records it may retain (4,194,304). They have no effect on other formats.
1052@_guard 1053def parse_geo(text: str, name_hint: Optional[str] = None) -> dict[str, Any]: 1054 """Tolerantly read a geographic sidecar and return its canonical form. 1055 1056 Accepts headerless buscoords CSV, aliased CSV/JSON records, and GeoJSON 1057 Point/LineString features. Returns ``{"geojson": <FeatureCollection dict>, 1058 "diagnostics": [...]}``; ``name_hint`` (a file name) picks CSV against JSON 1059 when the content alone is ambiguous. Input with no usable coordinates 1060 raises :class:`PowerIOParseError`. 1061 """ 1062 parsed = _powerio.parse_geo(text, name_hint) 1063 parsed["geojson"] = _json.loads(parsed["geojson"]) 1064 return parsed
Tolerantly read a geographic sidecar and return its canonical form.
Accepts headerless buscoords CSV, aliased CSV/JSON records, and GeoJSON
Point/LineString features. Returns {"geojson": <FeatureCollection dict>,
"diagnostics": [...]}; name_hint (a file name) picks CSV against JSON
when the content alone is ambiguous. Input with no usable coordinates
raises PowerIOParseError.
1045@_guard 1046def resolve_format(name: str) -> Optional[FormatInfo]: 1047 """Resolve a format token or common alias to its canonical metadata.""" 1048 resolved = _powerio.resolve_format(name) 1049 return None if resolved is None else FormatInfo(*resolved)
Resolve a format token or common alias to its canonical metadata.
2324@_guard 2325def serialize(module: PioModule, destination: Optional[Any] = None) -> EmitResult: 2326 """Serialize a module as PowerIO IR.""" 2327 return _emit_to_destination( 2328 module, 2329 destination, 2330 module._inner._serialize_memory, 2331 module._inner._serialize_path, 2332 )
Serialize a module as PowerIO IR.
1180@_guard 1181def versions() -> Any: 1182 """Return the PowerIO release, the PowerIO IR identity, and BMOPF schema. 1183 1184 ``powerio_ir`` is ``{"schema": "pio-ir", "version": <release>}``: the 1185 release whose schema the documents this build writes follow. 1186 ``bmopf_schema`` is the ``$id`` of the one BMOPF schema PowerIO writes. 1187 """ 1188 return _json.loads(_powerio.versions_json())
Return the PowerIO release, the PowerIO IR identity, and BMOPF schema.
powerio_ir is {"schema": "pio-ir", "version": <release>}: the
release whose schema the documents this build writes follow.
bmopf_schema is the $id of the one BMOPF schema PowerIO writes.