zepben.ewb 1.0.0__py3-none-any.whl

zepben/ewb/model/cim/iec61970/infiec61970/feeder/circuit.py

@@ -0,0 +1,144 @@
+#  Copyright 2024 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+from __future__ import annotations
+
+__all__ = ["Circuit"]
+
+from typing import Optional, Generator, List, TYPE_CHECKING
+
+from zepben.ewb.model.cim.iec61970.base.wires.line import Line
+from zepben.ewb.util import ngen, get_by_mrid, safe_remove, nlen
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.extensions.iec61970.base.feeder.loop import Loop
+    from zepben.ewb.model.cim.iec61970.base.core.substation import Substation
+    from zepben.ewb.model.cim.iec61970.base.core.terminal import Terminal
+
+
+class Circuit(Line):
+    """Missing description"""
+
+    loop: Optional[Loop] = None
+    _end_terminals: Optional[List[Terminal]] = None
+    _end_substations: Optional[List[Substation]] = None
+
+    def __init__(self, end_terminals: List[Terminal] = None, end_substations: List[Substation] = None, **kwargs):
+        super(Circuit, self).__init__(**kwargs)
+        if end_terminals:
+            for term in end_terminals:
+                self.add_end_terminal(term)
+
+        if end_substations:
+            for sub in end_substations:
+                self.add_end_substation(sub)
+
+    @property
+    def end_terminals(self) -> Generator[Terminal, None, None]:
+        """
+        The `Terminal`s representing the ends for this `Circuit`.
+        """
+        return ngen(self._end_terminals)
+
+    @property
+    def end_substations(self) -> Generator[Substation, None, None]:
+        """
+        The `Substations`s representing the ends for this `Circuit`.
+        """
+        return ngen(self._end_substations)
+
+    def num_end_terminals(self):
+        """Return the number of end `Terminal`s associated with this `Circuit`"""
+        return nlen(self._end_terminals)
+
+    def get_end_terminal(self, mrid: str) -> Terminal:
+        """
+        Get the `Terminal` for this `Circuit` identified by `mrid`
+
+        `mrid` the mRID of the required `Terminal`
+        Returns The `Terminal` with the specified `mrid` if it exists
+        Raises `KeyError` if `mrid` wasn't present.
+        """
+        return get_by_mrid(self._end_terminals, mrid)
+
+    def add_end_terminal(self, terminal: Terminal) -> Circuit:
+        """
+        Associate an `Terminal` with this `Circuit`
+
+        `terminal` the `Terminal` to associate with this `Circuit`.
+        Returns A reference to this `Circuit` to allow fluent use.
+        Raises `ValueError` if another `Terminal` with the same `mrid` already exists for this `Circuit`.
+        """
+        if self._validate_reference(terminal, self.get_end_terminal, "An Terminal"):
+            return self
+        self._end_terminals = list() if self._end_terminals is None else self._end_terminals
+        self._end_terminals.append(terminal)
+        return self
+
+    def remove_end_terminal(self, terminal: Terminal) -> Circuit:
+        """
+        Disassociate `terminal` from this `Circuit`
+
+        `terminal` the `Terminal` to disassociate from this `Circuit`.
+        Returns A reference to this `Circuit` to allow fluent use.
+        Raises `ValueError` if `terminal` was not associated with this `Circuit`.
+        """
+        self._end_terminals = safe_remove(self._end_terminals, terminal)
+        return self
+
+    def clear_end_terminals(self) -> Circuit:
+        """
+        Clear all end terminals.
+        Returns A reference to this `Circuit` to allow fluent use.
+        """
+        self._end_terminals = None
+        return self
+
+    def num_end_substations(self):
+        """Return the number of end `Substation`s associated with this `Circuit`"""
+        return nlen(self._end_substations)
+
+    def get_end_substation(self, mrid: str) -> Substation:
+        """
+        Get the `Substation` for this `Circuit` identified by `mrid`
+
+        `mrid` the mRID of the required `Substation`
+        Returns The `Substation` with the specified `mrid` if it exists
+        Raises `KeyError` if `mrid` wasn't present.
+        """
+        return get_by_mrid(self._end_substations, mrid)
+
+    def add_end_substation(self, substation: Substation) -> Circuit:
+        """
+        Associate an `Substation` with this `Circuit`
+
+        `substation` the `Substation` to associate with this `Circuit`.
+        Returns A reference to this `Circuit` to allow fluent use.
+        Raises `ValueError` if another `Substation` with the same `mrid` already exists for this `Circuit`.
+        """
+        if self._validate_reference(substation, self.get_end_substation, "An Substation"):
+            return self
+        self._end_substations = list() if self._end_substations is None else self._end_substations
+        self._end_substations.append(substation)
+        return self
+
+    def remove_end_substation(self, substation: Substation) -> Circuit:
+        """
+        Disassociate `substation` from this `Circuit`
+
+        `substation` the `Substation` to disassociate from this `Circuit`.
+        Returns A reference to this `Circuit` to allow fluent use.
+        Raises `ValueError` if `substation` was not associated with this `Circuit`.
+        """
+        self._end_substations = safe_remove(self._end_substations, substation)
+        return self
+
+    def clear_end_substations(self) -> Circuit:
+        """
+        Clear all end substations.
+        Returns A reference to this `Circuit` to allow fluent use.
+        """
+        self._end_substations = None
+        return self

zepben/ewb/model/phases.py

@@ -0,0 +1,168 @@
+#  Copyright 2024 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+from __future__ import annotations
+
+__all__ = ["get_phase", "set_phase", "TracedPhases"]
+
+from collections import defaultdict
+from dataclasses import dataclass
+
+from zepben.ewb.exceptions import PhaseException
+from zepben.ewb.model.cim.iec61970.base.core.phase_code import PhaseCode
+from zepben.ewb.model.cim.iec61970.base.wires.single_phase_kind import SinglePhaseKind
+
+BITS_TO_PHASE = defaultdict(lambda: SinglePhaseKind.NONE)
+BITS_TO_PHASE[0b0001] = SinglePhaseKind.A
+BITS_TO_PHASE[0b0010] = SinglePhaseKind.B
+BITS_TO_PHASE[0b0100] = SinglePhaseKind.C
+BITS_TO_PHASE[0b1000] = SinglePhaseKind.N
+
+PHASE_TO_BITS = defaultdict(lambda: 0)
+PHASE_TO_BITS[SinglePhaseKind.A] = 0b0001
+PHASE_TO_BITS[SinglePhaseKind.B] = 0b0010
+PHASE_TO_BITS[SinglePhaseKind.C] = 0b0100
+PHASE_TO_BITS[SinglePhaseKind.N] = 0b1000
+
+NOMINAL_PHASE_MASKS = [0x000f, 0x00f0, 0x0f00, 0xf000]
+
+
+def _valid_phase_check(nominal_phase):
+    if nominal_phase == SinglePhaseKind.NONE or nominal_phase == SinglePhaseKind.INVALID:
+        raise ValueError(f"INTERNAL ERROR: Phase {nominal_phase.name} is invalid. Must not be NONE or INVALID.")
+
+
+def get_phase(status: int, nominal_phase: SinglePhaseKind):
+    return BITS_TO_PHASE[(status >> _byte_selector(nominal_phase)) & 0x0f]
+
+
+def set_phase(status: int, nominal_phase: SinglePhaseKind, traced_phase: SinglePhaseKind) -> int:
+    if traced_phase == SinglePhaseKind.NONE:
+        return status & ~NOMINAL_PHASE_MASKS[nominal_phase.mask_index]
+    else:
+        return (status & ~NOMINAL_PHASE_MASKS[nominal_phase.mask_index]) | _shifted_value(nominal_phase, traced_phase)
+
+
+def _byte_selector(nominal_phase: SinglePhaseKind) -> int:
+    return nominal_phase.mask_index * 4
+
+
+def _shifted_value(nominal_phase: SinglePhaseKind, traced_phase: SinglePhaseKind) -> int:
+    return PHASE_TO_BITS[traced_phase] << _byte_selector(nominal_phase)
+
+
+# todo split file into correct packages
+
+@dataclass
+class TracedPhases(object):
+    """
+    Class that holds the traced phase statuses for the current and normal state of the network.
+
+    Traced phase status:
+    |     integer      |
+    | 16 bits |16 bits |
+    | current | normal |
+
+    See [TracedPhasesBitManipulation] for details on bit representation for normal and current status.
+    """
+
+    phase_status: int = 0
+    """
+    The underlying implementation value tracking the phase statuses for the current and normal state of the network.
+    It is primarily used for data serialisation and debugging within official evolve libraries and utilities.
+
+    NOTE: This property should be considered evolve internal and not for public use as the underlying
+          data structure to store the status could change at any time (and thus be a breaking change).
+          Use at your own risk.
+    """
+
+    _NORMAL_MASK = 0x0000ffff
+    _CURRENT_MASK = 0xffff0000
+    _CURRENT_SHIFT = 16
+
+    def __str__(self):
+        def to_string(select_phase):
+            return ', '.join([select_phase(phs).short_name for phs in PhaseCode.ABCN.single_phases])
+
+        return f"TracedPhases(normal={{{to_string(self.normal)}}}, current={{{to_string(self.current)}}})"
+
+    def normal(self, nominal_phase: SinglePhaseKind) -> SinglePhaseKind:
+        """
+        Get the phase that was traced in the normal state of the network on this nominal phase.
+
+        `nominal_phase` The nominal phase to check.
+
+        Returns The `zepben.protobuf.cim.iec61970.base.wires.SinglePhaseKind` traced in the normal state of the network for the nominal phase, or
+        SinglePhaseKind.NONE if the nominal phase is de-energised.
+
+        Raises `NominalPhaseException` if the nominal phase is invalid.
+        """
+        _valid_phase_check(nominal_phase)
+        return get_phase(self.phase_status, nominal_phase)
+
+    def current(self, nominal_phase: SinglePhaseKind) -> SinglePhaseKind:
+        """
+        Get the phase that was traced in the current state of the network on this nominal phase.
+
+        `nominal_phase` The nominal phase to check.
+
+        Returns The `zepben.protobuf.cim.iec61970.base.wires.SinglePhaseKind` traced in the current state of the network for the nominal phase, or
+        SinglePhaseKind.NONE if the nominal phase is de-energised.
+
+        Raises `NominalPhaseException` if the nominal phase is invalid.
+        """
+        _valid_phase_check(nominal_phase)
+        return get_phase(self.phase_status >> self._CURRENT_SHIFT, nominal_phase)
+
+    def set_normal(self, nominal_phase: SinglePhaseKind, traced_phase: SinglePhaseKind) -> bool:
+        """
+        Set the phase that was traced in the normal state of the network on this nominal phase.
+
+        `nominal_phase` The nominal phase to use.
+
+        `traced_phase` The traced phase to apply to the nominal phase.
+
+        Returns True if there was a change, otherwise False.
+
+        Raises `PhaseException` if phases cross. i.e. you try to apply more than one phase to a nominal phase.
+
+        Raises `NominalPhaseException` if the nominal phase is invalid.
+        """
+        it = self.normal(nominal_phase)
+        if it == traced_phase:
+            return False
+        elif (it == SinglePhaseKind.NONE) or (traced_phase == SinglePhaseKind.NONE):
+            self.phase_status = (self.phase_status & self._CURRENT_MASK) | set_phase(self.phase_status, nominal_phase, traced_phase)
+            return True
+        else:
+            raise PhaseException("Crossing Phases.")
+
+    def set_current(self, nominal_phase: SinglePhaseKind, traced_phase: SinglePhaseKind) -> bool:
+        """
+        Set the phase that was traced in the current state of the network on this nominal phase.
+
+        `nominal_phase` The nominal phase to use.
+
+        `traced_phase` The traced phase to apply to the nominal phase.
+
+        Returns True if there was a change, otherwise False.
+
+        Raises `PhaseException` if phases cross. i.e. you try to apply more than one phase to a nominal phase.
+
+        Raises `NominalPhaseException` if the nominal phase is invalid.
+        """
+        it = self.current(nominal_phase)
+        if it == traced_phase:
+            return False
+        elif (it == SinglePhaseKind.NONE) or (traced_phase == SinglePhaseKind.NONE):
+            self.phase_status = (self.phase_status & self._NORMAL_MASK) | (
+                set_phase(self.phase_status >> self._CURRENT_SHIFT, nominal_phase, traced_phase) << self._CURRENT_SHIFT)
+            return True
+        else:
+            raise PhaseException("Crossing Phases.")
+
+    @staticmethod
+    def copy():
+        return TracedPhases()

zepben/ewb/model/resistance_reactance.py

@@ -0,0 +1,40 @@
+#  Copyright 2024 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+from __future__ import annotations
+
+__all__ = ["ResistanceReactance"]
+
+from dataclasses import dataclass
+from typing import Optional, Callable
+
+
+@dataclass
+class ResistanceReactance(object):
+    r: Optional[float] = None
+    x: Optional[float] = None
+    r0: Optional[float] = None
+    x0: Optional[float] = None
+
+    def is_complete(self) -> bool:
+        return self.r is not None and self.x is not None and self.r0 is not None and self.x0 is not None
+
+    def is_empty(self) -> bool:
+        return self.r is None and self.x is None and self.r0 is None and self.x0 is None
+
+    def merge_if_incomplete(self, to_merge: Callable[[], Optional[ResistanceReactance]]) -> ResistanceReactance:
+        if self.is_complete():
+            return self
+        else:
+            rr = to_merge()
+            if rr is not None:
+                return ResistanceReactance(
+                    self.r if self.r is not None else rr.r,
+                    self.x if self.x is not None else rr.x,
+                    self.r0 if self.r0 is not None else rr.r0,
+                    self.x0 if self.x0 is not None else rr.x0
+                )
+            else:
+                return self

zepben/ewb/services/__init__.py

@@ -0,0 +1,4 @@
+#  Copyright 2024 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.

zepben/ewb/services/common/__init__.py

@@ -0,0 +1,16 @@
+#  Copyright 2024 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+from zepben.protobuf.cim.iec61968.common.Document_pb2 import Document as PBDocument
+from zepben.protobuf.cim.iec61968.common.OrganisationRole_pb2 import OrganisationRole as PBOrganisationRole
+from zepben.protobuf.cim.iec61968.common.Organisation_pb2 import Organisation as PBOrganisation
+from zepben.protobuf.cim.iec61970.base.core.IdentifiedObject_pb2 import IdentifiedObject as PBIdentifiedObject
+
+
+PBOrganisationRole.mrid = lambda self: self.io.mRID
+PBDocument.mrid = lambda self: self.io.mRID
+PBOrganisation.mrid = lambda self: self.io.mRID
+PBIdentifiedObject.name_and_mrid = lambda self: f"{self.mRID}{f' [{self.name}]' if self.name else ''}"
+PBDocument.name_and_mrid = lambda self: self.io.name_and_mrid()