powerio.dist
Multiconductor distribution network values.
The typed model uses wire coordinates. Supported formats are OpenDSS .dss,
PowerModelsDistribution ENGINEERING JSON (pmd-json) and MATHEMATICAL JSON
(pmd-math-json), BMOPF JSON (bmopf-json), the multiconductor MG-RAVENS
JSON profile (ravens-json), distribution CIM (cim-dist, CIM100 RDF/XML),
three-phase pandapower JSON (pandapower-json, read only, written as the
retained source) and the explicit sincal-multiconductor profile. Same format emissions can return
retained source bytes. Cross
format emissions report unsupported fields as diagnostics.
import powerio
module = powerio.parse("feeder.dss")
net = module.value
for diagnostic in module.diagnostics:
print("parse:", diagnostic)
conv = powerio.emit(module, "pmd-json")
1"""Multiconductor distribution network values. 2 3The typed model uses wire coordinates. Supported formats are OpenDSS ``.dss``, 4PowerModelsDistribution ENGINEERING JSON (``pmd-json``) and MATHEMATICAL JSON 5(``pmd-math-json``), BMOPF JSON (``bmopf-json``), the multiconductor MG-RAVENS 6JSON profile (``ravens-json``), distribution CIM (``cim-dist``, CIM100 RDF/XML), 7three-phase pandapower JSON (``pandapower-json``, read only, written as the 8retained source) and the explicit ``sincal-multiconductor`` profile. Same format emissions can return 9retained source bytes. Cross 10format emissions report unsupported fields as diagnostics. 11 12 import powerio 13 14 module = powerio.parse("feeder.dss") 15 net = module.value 16 for diagnostic in module.diagnostics: 17 print("parse:", diagnostic) 18 conv = powerio.emit(module, "pmd-json") 19""" 20 21from __future__ import annotations 22 23import json as _json 24from dataclasses import dataclass 25from typing import Any, Optional 26 27from ._guard import guard_class as _guard_class 28from ._sincal import _validate_selection 29 30__all__ = ["MulticonductorNetwork", "SincalReadOptions"] 31 32 33@dataclass(frozen=True) 34class SincalReadOptions: 35 """Explicit conductor-resolved SINCAL selection for :func:`powerio.parse`. 36 37 ``variant`` is a native variant ID. ``snapshot_hours`` selects an explicit 38 daily snapshot. ``acquired_tables`` is a relative companion name for the 39 optional Access acquisition helper's output; the primary remains the MDB. 40 The original MDB length and hash must match the acquisition metadata. 41 No external acquisition tool is run by parsing. 42 """ 43 44 variant: Optional[int] = None 45 snapshot_hours: Optional[float] = None 46 acquired_tables: Optional[str] = None 47 48 # Experimental legacy NULL controls; each applied assumption is diagnosed. 49 assume_inactive_source_controls: bool = False 50 51 def __post_init__(self): 52 _validate_selection(self) 53 if not isinstance(self.assume_inactive_source_controls, bool): 54 raise TypeError("assume_inactive_source_controls must be bool") 55 56 57@_guard_class 58class MulticonductorNetwork: 59 """A parsed multiconductor distribution network in wire coordinates. 60 61 Buses carry named terminals, lines carry conductor impedance matrices, and 62 transformers carry per winding connections. This type is distinct from the 63 positive sequence :class:`powerio.BalancedNetwork`; balanced matrix calculations do not 64 accept it. 65 """ 66 67 def __init__(self, inner) -> None: 68 self._inner = inner 69 70 @property 71 def name(self) -> Optional[str]: 72 """Distribution network name when the source format carries one.""" 73 return self._inner.name() 74 75 @property 76 def source_format(self) -> Optional[str]: 77 """Format parsed from: ``dss``, ``pmd-json``, ``pmd-math-json``, 78 ``bmopf-json``, ``ravens-json``, ``cim-dist``, ``pandapower-json``, or 79 ``sincal``; ``None`` for a network built in code.""" 80 return self._inner.source_format() 81 82 @property 83 def base_frequency(self) -> float: 84 """System base frequency in hertz.""" 85 return self._inner.base_frequency() 86 87 @property 88 def n_buses(self) -> int: 89 return self._inner.n_buses() 90 91 @property 92 def n_lines(self) -> int: 93 return self._inner.n_lines() 94 95 @property 96 def n_line_codes(self) -> int: 97 return self._inner.n_line_codes() 98 99 @property 100 def n_switches(self) -> int: 101 return self._inner.n_switches() 102 103 @property 104 def n_transformers(self) -> int: 105 return self._inner.n_transformers() 106 107 @property 108 def n_loads(self) -> int: 109 return self._inner.n_loads() 110 111 @property 112 def n_generators(self) -> int: 113 return self._inner.n_generators() 114 115 @property 116 def n_ibrs(self) -> int: 117 return self._inner.n_ibrs() 118 119 @property 120 def n_control_profiles(self) -> int: 121 return self._inner.n_control_profiles() 122 123 @property 124 def n_shunts(self) -> int: 125 return self._inner.n_shunts() 126 127 @property 128 def n_capacitors(self) -> int: 129 return self._inner.n_capacitors() 130 131 @property 132 def n_voltage_sources(self) -> int: 133 """Number of grid forming voltage sources.""" 134 return self._inner.n_voltage_sources() 135 136 @property 137 def n_untyped_objects(self) -> int: 138 return self._inner.n_untyped_objects() 139 140 # These properties are copies of the native model tables. Nested field 141 # names come from the Rust model's serialization, so this wrapper does not 142 # maintain a second distribution schema. 143 144 @property 145 def buses(self) -> "list[dict[str, Any]]": 146 return self._inner.buses() 147 148 @property 149 def line_codes(self) -> "list[dict[str, Any]]": 150 return self._inner.line_codes() 151 152 @property 153 def lines(self) -> "list[dict[str, Any]]": 154 return self._inner.lines() 155 156 @property 157 def switches(self) -> "list[dict[str, Any]]": 158 return self._inner.switches() 159 160 @property 161 def transformers(self) -> "list[dict[str, Any]]": 162 return self._inner.transformers() 163 164 @property 165 def loads(self) -> "list[dict[str, Any]]": 166 return self._inner.loads() 167 168 @property 169 def generators(self) -> "list[dict[str, Any]]": 170 return self._inner.generators() 171 172 @property 173 def ibrs(self) -> "list[dict[str, Any]]": 174 return self._inner.ibrs() 175 176 @property 177 def control_profiles(self) -> "list[dict[str, Any]]": 178 return self._inner.control_profiles() 179 180 @property 181 def shunts(self) -> "list[dict[str, Any]]": 182 return self._inner.shunts() 183 184 @property 185 def capacitors(self) -> "list[dict[str, Any]]": 186 return self._inner.capacitors() 187 188 @property 189 def voltage_sources(self) -> "list[dict[str, Any]]": 190 return self._inner.voltage_sources() 191 192 @property 193 def untyped_objects(self) -> "list[dict[str, Any]]": 194 return self._inner.untyped_objects() 195 196 def to_graph(self) -> Any: 197 """Transform the network to collapsed bus and terminal graph data.""" 198 return _json.loads(self._inner.graph_json()) 199 200 def to_geo_layer(self) -> Any: 201 """Transform coordinates to a canonical GeoJSON FeatureCollection. 202 203 A network without coordinates produces an empty feature collection. 204 """ 205 return _json.loads(self._inner.to_geo_layer_json()) 206 207 def apply_geo_layer( 208 self, text: str, name_hint: Optional[str] = None 209 ) -> tuple["MulticonductorNetwork", Any]: 210 """Apply a geographic sidecar and return ``(placed, report)``. 211 212 ``text`` is any form :func:`powerio.parse_geo` accepts. This network 213 is unchanged; the placed copy drops the retained source text, so a 214 same-format emission re-serializes. 215 """ 216 inner, report = self._inner.apply_geo_layer(text, name_hint) 217 return MulticonductorNetwork(inner), report 218 219 def __repr__(self) -> str: 220 return self._inner.__repr__()
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.
34@dataclass(frozen=True) 35class SincalReadOptions: 36 """Explicit conductor-resolved SINCAL selection for :func:`powerio.parse`. 37 38 ``variant`` is a native variant ID. ``snapshot_hours`` selects an explicit 39 daily snapshot. ``acquired_tables`` is a relative companion name for the 40 optional Access acquisition helper's output; the primary remains the MDB. 41 The original MDB length and hash must match the acquisition metadata. 42 No external acquisition tool is run by parsing. 43 """ 44 45 variant: Optional[int] = None 46 snapshot_hours: Optional[float] = None 47 acquired_tables: Optional[str] = None 48 49 # Experimental legacy NULL controls; each applied assumption is diagnosed. 50 assume_inactive_source_controls: bool = False 51 52 def __post_init__(self): 53 _validate_selection(self) 54 if not isinstance(self.assume_inactive_source_controls, bool): 55 raise TypeError("assume_inactive_source_controls must be bool")
Explicit conductor-resolved SINCAL selection for powerio.parse().
variant is a native variant ID. snapshot_hours selects an explicit
daily snapshot. acquired_tables is a relative companion name for the
optional Access acquisition helper's output; the primary remains the MDB.
The original MDB length and hash must match the acquisition metadata.
No external acquisition tool is run by parsing.