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__()
class MulticonductorNetwork:
 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.

MulticonductorNetwork(inner)
68    def __init__(self, inner) -> None:
69        self._inner = inner
name: Optional[str]
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.

source_format: Optional[str]
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.

base_frequency: float
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.

n_buses: int
88    @property
89    def n_buses(self) -> int:
90        return self._inner.n_buses()
n_lines: int
92    @property
93    def n_lines(self) -> int:
94        return self._inner.n_lines()
n_line_codes: int
96    @property
97    def n_line_codes(self) -> int:
98        return self._inner.n_line_codes()
n_switches: int
100    @property
101    def n_switches(self) -> int:
102        return self._inner.n_switches()
n_transformers: int
104    @property
105    def n_transformers(self) -> int:
106        return self._inner.n_transformers()
n_loads: int
108    @property
109    def n_loads(self) -> int:
110        return self._inner.n_loads()
n_generators: int
112    @property
113    def n_generators(self) -> int:
114        return self._inner.n_generators()
n_ibrs: int
116    @property
117    def n_ibrs(self) -> int:
118        return self._inner.n_ibrs()
n_control_profiles: int
120    @property
121    def n_control_profiles(self) -> int:
122        return self._inner.n_control_profiles()
n_shunts: int
124    @property
125    def n_shunts(self) -> int:
126        return self._inner.n_shunts()
n_capacitors: int
128    @property
129    def n_capacitors(self) -> int:
130        return self._inner.n_capacitors()
n_voltage_sources: int
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.

n_untyped_objects: int
137    @property
138    def n_untyped_objects(self) -> int:
139        return self._inner.n_untyped_objects()
buses: list[dict[str, typing.Any]]
145    @property
146    def buses(self) -> "list[dict[str, Any]]":
147        return self._inner.buses()
line_codes: list[dict[str, typing.Any]]
149    @property
150    def line_codes(self) -> "list[dict[str, Any]]":
151        return self._inner.line_codes()
lines: list[dict[str, typing.Any]]
153    @property
154    def lines(self) -> "list[dict[str, Any]]":
155        return self._inner.lines()
switches: list[dict[str, typing.Any]]
157    @property
158    def switches(self) -> "list[dict[str, Any]]":
159        return self._inner.switches()
transformers: list[dict[str, typing.Any]]
161    @property
162    def transformers(self) -> "list[dict[str, Any]]":
163        return self._inner.transformers()
loads: list[dict[str, typing.Any]]
165    @property
166    def loads(self) -> "list[dict[str, Any]]":
167        return self._inner.loads()
generators: list[dict[str, typing.Any]]
169    @property
170    def generators(self) -> "list[dict[str, Any]]":
171        return self._inner.generators()
ibrs: list[dict[str, typing.Any]]
173    @property
174    def ibrs(self) -> "list[dict[str, Any]]":
175        return self._inner.ibrs()
control_profiles: list[dict[str, typing.Any]]
177    @property
178    def control_profiles(self) -> "list[dict[str, Any]]":
179        return self._inner.control_profiles()
shunts: list[dict[str, typing.Any]]
181    @property
182    def shunts(self) -> "list[dict[str, Any]]":
183        return self._inner.shunts()
capacitors: list[dict[str, typing.Any]]
185    @property
186    def capacitors(self) -> "list[dict[str, Any]]":
187        return self._inner.capacitors()
voltage_sources: list[dict[str, typing.Any]]
189    @property
190    def voltage_sources(self) -> "list[dict[str, Any]]":
191        return self._inner.voltage_sources()
untyped_objects: list[dict[str, typing.Any]]
193    @property
194    def untyped_objects(self) -> "list[dict[str, Any]]":
195        return self._inner.untyped_objects()
def to_graph(self) -> Any:
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.

def to_geo_layer(self) -> Any:
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.

def apply_geo_layer( self, text: str, name_hint: Optional[str] = None) -> tuple[MulticonductorNetwork, typing.Any]:
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.

@dataclass(frozen=True)
class SincalReadOptions:
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.

SincalReadOptions( variant: Optional[int] = None, snapshot_hours: Optional[float] = None, acquired_tables: Optional[str] = None, assume_inactive_source_controls: bool = False)
variant: Optional[int] = None
snapshot_hours: Optional[float] = None
acquired_tables: Optional[str] = None
assume_inactive_source_controls: bool = False