powerio.dist

  1"""Multiconductor distribution networks in wire coordinates.
  2
  3Three formats, lossless three way conversion: OpenDSS ``.dss``,
  4PowerModelsDistribution ENGINEERING JSON (``pmd-json``), and the draft BMOPF
  5task force JSON (``bmopf-json``). The fidelity rules match the
  6transmission surface: writing back to the source format echoes the retained
  7source text byte for byte, and every cross format write reports each loss in
  8the :class:`~powerio.Conversion` warnings instead of dropping it silently.
  9
 10    import powerio.dist as dist
 11
 12    net = dist.parse_file("feeder.dss")
 13    for w in net.warnings:
 14        print("parse:", w)
 15    conv = net.to_format("pmd-json")
 16"""
 17
 18from __future__ import annotations
 19
 20from typing import Any, Optional
 21
 22from . import Conversion, _powerio
 23
 24__all__ = [
 25    "DistNetwork",
 26    "MulticonductorNetwork",
 27    "parse_file",
 28    "parse_str",
 29    "convert_file",
 30    "convert_str",
 31]
 32
 33
 34class DistNetwork:
 35    """A parsed multiconductor distribution network.
 36
 37    Buses carry named terminals, lines carry conductor impedance matrices, and
 38    transformers carry per winding connections; nothing is collapsed to
 39    positive sequence. Distinct from :class:`powerio.Network` (the
 40    transmission model); the matrix builders do not accept it.
 41    """
 42
 43    def __init__(self, inner) -> None:
 44        self._inner = inner
 45
 46    @property
 47    def name(self) -> Optional[str]:
 48        """Distribution network name when the source format carries one."""
 49        return self._inner.name()
 50
 51    @property
 52    def source_format(self) -> Optional[str]:
 53        """Format parsed from: ``dss``, ``pmd-json``, or ``bmopf-json``."""
 54        return self._inner.source_format()
 55
 56    @property
 57    def warnings(self) -> "list[str]":
 58        """Parse warnings: everything the reader could not represent or had to assume."""
 59        return self._inner.warnings()
 60
 61    @property
 62    def n_buses(self) -> int:
 63        return self._inner.n_buses()
 64
 65    @property
 66    def n_lines(self) -> int:
 67        return self._inner.n_lines()
 68
 69    @property
 70    def n_transformers(self) -> int:
 71        return self._inner.n_transformers()
 72
 73    @property
 74    def n_loads(self) -> int:
 75        return self._inner.n_loads()
 76
 77    @property
 78    def n_generators(self) -> int:
 79        return self._inner.n_generators()
 80
 81    @property
 82    def n_sources(self) -> int:
 83        return self._inner.n_sources()
 84
 85    def to_format(self, to: str) -> Conversion:
 86        """Serialize to ``to`` (``dss``, ``pmd-json``, ``bmopf-json``).
 87
 88        Writing back to the source format echoes the retained source text byte
 89        for byte; a cross format write regenerates from the typed model and
 90        reports every fidelity loss in the warnings.
 91        """
 92        text, warnings = self._inner.to_format(to)
 93        return Conversion(text, warnings)
 94
 95    def __repr__(self) -> str:
 96        return self._inner.__repr__()
 97
 98
 99# v1 name for the wire coordinate distribution model. ``DistNetwork`` remains
100# available in 0.4 because it is the existing handle name.
101MulticonductorNetwork = DistNetwork
102
103
104def parse_file(path: Any, from_: Optional[str] = None) -> MulticonductorNetwork:
105    """Parse a distribution network file.
106
107    The format comes from ``from_`` when given, else from the file itself:
108    ``.dss`` is OpenDSS, and ``.json`` holding the ENGINEERING ``data_model``
109    key is PMD JSON, otherwise BMOPF JSON.
110    """
111    return DistNetwork(_powerio.dist_parse_file(str(path), from_))
112
113
114def parse_str(text: str, format: str) -> MulticonductorNetwork:
115    """Parse an in-memory distribution network of the named ``format``."""
116    return DistNetwork(_powerio.dist_parse_str(text, format))
117
118
119def convert_file(path: Any, to: str, from_: Optional[str] = None) -> Conversion:
120    """Convert a distribution network file to ``to`` in one call.
121
122    The warnings carry both the parse warnings and the writer's fidelity
123    losses (there is no :class:`DistNetwork` to query them from).
124    """
125    text, warnings = _powerio.dist_convert_file(str(path), to, from_)
126    return Conversion(text, warnings)
127
128
129def convert_str(text: str, to: str, format: str) -> Conversion:
130    """Convert an in-memory distribution network of the named ``format`` to ``to``.
131
132    The signature matches :func:`powerio.convert_str`: input, target, source,
133    except ``format`` is required (there is no extension to infer from and no
134    default). The warnings carry both the parse warnings and the writer's
135    fidelity losses (there is no :class:`DistNetwork` to query them from).
136    """
137    text, warnings = _powerio.dist_convert_str(text, to, format)
138    return Conversion(text, warnings)