zepben.ewb 1.0.0__py3-none-any.whl

zepben/ewb/model/cim/extensions/iec61970/base/feeder/lv_feeder.py

@@ -0,0 +1,258 @@
+#  Copyright 2025 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__ = ["LvFeeder"]
+
+import typing
+from typing import Generator, Optional, Dict, List
+
+from zepben.ewb.model.cim.extensions.zbex import zbex
+from zepben.ewb.model.cim.iec61970.base.core.equipment_container import EquipmentContainer
+from zepben.ewb.util import safe_remove_by_id, nlen, ngen
+
+if typing.TYPE_CHECKING:
+    from zepben.ewb.model.cim.iec61970.base.core.equipment import Equipment
+    from zepben.ewb.model.cim.iec61970.base.core.feeder import Feeder
+    from zepben.ewb.model.cim.iec61970.base.core.terminal import Terminal
+
+
+@zbex
+class LvFeeder(EquipmentContainer):
+    """
+    [ZBEX]
+    A branch of LV network starting at a distribution substation and continuing until the end of the LV network.
+    """
+
+    _normal_head_terminal: Optional[Terminal] = None
+    """The normal head terminal or terminals of this LvFeeder"""
+
+    _normal_energizing_feeders: Optional[Dict[str, Feeder]] = None
+    """The feeders that energize this LV feeder in the normal state of the network."""
+
+    _current_equipment: Optional[Dict[str, Equipment]] = None
+    """The equipment contained in this LvFeeder in the current state of the network."""
+
+    _current_energizing_feeders: Optional[Dict[str, Feeder]] = None
+    """The feeders that energize this LV feeder in the current state of the network."""
+
+    def __init__(
+        self,
+        normal_head_terminal: Terminal = None,
+        normal_energizing_feeders: List[Feeder] = None,
+        current_equipment: List[Equipment] = None,
+        current_energizing_feeders: List[Feeder] = None,
+        **kwargs
+    ):
+        super(LvFeeder, self).__init__(**kwargs)
+        if normal_head_terminal:
+            self.normal_head_terminal = normal_head_terminal
+        if normal_energizing_feeders:
+            for feeder in normal_energizing_feeders:
+                self.add_normal_energizing_feeder(feeder)
+        if current_equipment:
+            for eq in current_equipment:
+                self.add_current_equipment(eq)
+        if current_energizing_feeders:
+            for feeder in current_energizing_feeders:
+                self.add_current_energizing_feeder(feeder)
+
+    @property
+    def normal_head_terminal(self) -> Optional[Terminal]:
+        """
+        [ZBEX] The normal head terminal or terminals of the feeder.
+        """
+        return self._normal_head_terminal
+
+    @normal_head_terminal.setter
+    def normal_head_terminal(self, term: Optional[Terminal]):
+        if self._normal_head_terminal is None or self._normal_head_terminal is term:
+            self._normal_head_terminal = term
+        else:
+            raise ValueError(f"normal_head_terminal for {str(self)} has already been set to {self._normal_head_terminal}, cannot reset this field to {term}")
+
+    @property
+    def normal_energizing_feeders(self) -> Generator[Feeder, None, None]:
+        """
+        [ZBEX] The HV/MV feeders that normally energize this LV feeder.
+        """
+        return ngen(self._normal_energizing_feeders.values() if self._normal_energizing_feeders is not None else None)
+
+    def num_normal_energizing_feeders(self) -> int:
+        """
+        Get the number of HV/MV feeders that normally energize this LV feeder.
+        """
+        return nlen(self._normal_energizing_feeders)
+
+    def get_normal_energizing_feeder(self, mrid: str) -> Feeder:
+        """
+        Energizing feeder using the normal state of the network.
+
+        @param mrid: The mrid of the `Feeder`.
+        @return A matching `Feeder` that energizes this `LvFeeder` in the normal state of the network.
+        @raise A `KeyError` if no matching `Feeder` was found.
+        """
+        if not self._normal_energizing_feeders:
+            raise KeyError(mrid)
+        try:
+            return self._normal_energizing_feeders[mrid]
+        except AttributeError:
+            raise KeyError(mrid)
+
+    def add_normal_energizing_feeder(self, feeder: Feeder) -> LvFeeder:
+        """
+        Associate this `LvFeeder` with a `Feeder` in the normal state of the network.
+
+        @param feeder: the HV/MV feeder to associate with this LV feeder in the normal state of the network.
+        @return: This `LvFeeder` for fluent use.
+        """
+        if self._validate_reference(feeder, self.get_normal_energizing_feeder, "A Feeder"):
+            return self
+        self._normal_energizing_feeders = dict() if self._normal_energizing_feeders is None else self._normal_energizing_feeders
+        self._normal_energizing_feeders[feeder.mrid] = feeder
+        return self
+
+    def remove_normal_energizing_feeder(self, feeder: Feeder) -> LvFeeder:
+        """
+        Disassociate this `LvFeeder` from a `Feeder` in the normal state of the network.
+
+        @param feeder: the HV/MV feeder to disassociate from this LV feeder in the normal state of the network.
+        @return: This `LvFeeder` for fluent use.
+        @raise: A `ValueError` if `feeder` is not found in the normal energizing feeders collection.
+        """
+        self._normal_energizing_feeders = safe_remove_by_id(self._normal_energizing_feeders, feeder)
+        return self
+
+    def clear_normal_energizing_feeders(self) -> LvFeeder:
+        """
+        Clear all `Feeder`s associated with `LvFeeder` in the normal state of the network.
+
+        @return: This `LvFeeder` for fluent use.
+        """
+        self._normal_energizing_feeders = None
+        return self
+
+    @property
+    def current_energizing_feeders(self) -> Generator[Feeder, None, None]:
+        """
+        [ZBEX] The HV/MV feeders that currently energize this LV feeder.
+        """
+        return ngen(self._current_energizing_feeders.values() if self._current_energizing_feeders is not None else None)
+
+    def num_current_energizing_feeders(self) -> int:
+        """
+        Get the number of HV/MV feeders that currently energize this LV feeder.
+        """
+        return nlen(self._current_energizing_feeders)
+
+    def get_current_energizing_feeder(self, mrid: str) -> Feeder:
+        """
+        Energizing feeder using the current state of the network.
+
+        @param mrid: The mrid of the `Feeder`.
+        @return A matching `Feeder` that energizes this `LvFeeder` in the current state of the network.
+        @raise A `KeyError` if no matching `Feeder` was found.
+        """
+        if not self._current_energizing_feeders:
+            raise KeyError(mrid)
+        try:
+            return self._current_energizing_feeders[mrid]
+        except AttributeError:
+            raise KeyError(mrid)
+
+    def add_current_energizing_feeder(self, feeder: Feeder) -> LvFeeder:
+        """
+        Associate this `LvFeeder` with a `Feeder` in the current state of the network.
+
+        @param feeder: the HV/MV feeder to associate with this LV feeder in the current state of the network.
+        @return: This `LvFeeder` for fluent use.
+        """
+        if self._validate_reference(feeder, self.get_current_energizing_feeder, "A Feeder"):
+            return self
+        self._current_energizing_feeders = dict() if self._current_energizing_feeders is None else self._current_energizing_feeders
+        self._current_energizing_feeders[feeder.mrid] = feeder
+        return self
+
+    def remove_current_energizing_feeder(self, feeder: Feeder) -> LvFeeder:
+        """
+        Disassociate this `LvFeeder` from a `Feeder` in the current state of the network.
+
+        @param feeder: the HV/MV feeder to disassociate from this LV feeder in the current state of the network.
+        @return: This `LvFeeder` for fluent use.
+        @raise: A `ValueError` if `feeder` is not found in the current energizing feeders collection.
+        """
+        self._current_energizing_feeders = safe_remove_by_id(self._current_energizing_feeders, feeder)
+        return self
+
+    def clear_current_energizing_feeders(self) -> LvFeeder:
+        """
+        Clear all `Feeder`s associated with `LvFeeder` in the current state of the network.
+
+        @return: This `LvFeeder` for fluent use.
+        """
+        self._current_energizing_feeders = None
+        return self
+
+    @property
+    def current_equipment(self) -> Generator[Equipment, None, None]:
+        """
+        Contained `Equipment` using the current state of the network.
+        """
+        return ngen(self._current_equipment.values() if self._current_equipment is not None else None)
+
+    def num_current_equipment(self):
+        """
+        Returns The number of `Equipment` associated with this `LvFeeder` in the current state of the network.
+        """
+        return nlen(self._current_equipment)
+
+    def get_current_equipment(self, mrid: str) -> Equipment:
+        """
+        Get the `Equipment` contained in this `LvFeeder` in the current state of the network, identified by `mrid`
+
+        `mrid` The mRID of the required `Equipment`
+        Returns The `Equipment` with the specified `mrid` if it exists
+        Raises `KeyError` if `mrid` wasn't present.
+        """
+        if not self._current_equipment:
+            raise KeyError(mrid)
+        try:
+            return self._current_equipment[mrid]
+        except AttributeError:
+            raise KeyError(mrid)
+
+    def add_current_equipment(self, equipment: Equipment) -> LvFeeder:
+        """
+        Associate `equipment` with this `LvFeeder` in the current state of the network.
+
+        `equipment` the `Equipment` to associate with this `LvFeeder` in the current state of the network.
+        Returns A reference to this `LvFeeder` to allow fluent use.
+        Raises `ValueError` if another `Equipment` with the same `mrid` already exists for this `LvFeeder`.
+        """
+        if self._validate_reference(equipment, self.get_current_equipment, "An Equipment"):
+            return self
+        self._current_equipment = dict() if self._current_equipment is None else self._current_equipment
+        self._current_equipment[equipment.mrid] = equipment
+        return self
+
+    def remove_current_equipment(self, equipment: Equipment) -> LvFeeder:
+        """
+        Disassociate `equipment` from this `LvFeeder` in the current state of the network.
+
+        `equipment` The `Equipment` to disassociate from this `LvFeeder` in the current state of the network.
+        Returns A reference to this `LvFeeder` to allow fluent use.
+        Raises `KeyError` if `equipment` was not associated with this `LvFeeder`.
+        """
+        self._current_equipment = safe_remove_by_id(self._current_equipment, equipment)
+        return self
+
+    def clear_current_equipment(self) -> LvFeeder:
+        """
+        Clear all `Equipment` from this `LvFeeder` in the current state of the network.
+        Returns A reference to this `LvFeeder` to allow fluent use.
+        """
+        self._current_equipment = None
+        return self

zepben/ewb/model/cim/extensions/iec61970/base/generation/__init__.py

@@ -0,0 +1,4 @@
+#  Copyright 2025 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/model/cim/extensions/iec61970/base/generation/production/__init__.py

@@ -0,0 +1,4 @@
+#  Copyright 2025 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/model/cim/extensions/iec61970/base/generation/production/ev_charging_unit.py

@@ -0,0 +1,18 @@
+#  Copyright 2025 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/.
+
+__all__ = ["EvChargingUnit"]
+
+from zepben.ewb.model.cim.iec61970.base.generation.production.power_electronics_unit import PowerElectronicsUnit
+from zepben.ewb.model.cim.extensions.zbex import zbex
+
+
+@zbex
+class EvChargingUnit(PowerElectronicsUnit):
+    """
+    [ZBEX]
+    An electric vehicle charging station.
+    """
+    pass

zepben/ewb/model/cim/extensions/iec61970/base/protection/__init__.py

@@ -0,0 +1,4 @@
+#  Copyright 2025 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/model/cim/extensions/iec61970/base/protection/distance_relay.py

@@ -0,0 +1,69 @@
+#  Copyright 2025 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/.
+
+__all__ = ["DistanceRelay"]
+
+from typing import Optional
+
+from zepben.ewb.model.cim.extensions.iec61970.base.protection.protection_relay_function import ProtectionRelayFunction
+from zepben.ewb.model.cim.extensions.zbex import zbex
+
+
+@zbex
+class DistanceRelay(ProtectionRelayFunction):
+    """
+    [ZBEX]
+    A protective device used in power systems that measures the impedance of a transmission line to determine the distance to a fault, and initiates
+    circuit breaker tripping to isolate the faulty section and safeguard the power system.
+    """
+
+    backward_blind: Optional[float] = None
+    """
+    [ZBEX] The reverse blind impedance (in ohms) that defines the area to be blinded in the opposite direction of the power flow.
+    """
+
+    backward_reach: Optional[float] = None
+    """
+    [ZBEX] The reverse reach impedance (in ohms) that determines the maximum distance along the transmission line in the opposite direction of power flow for 
+    which the relay will provide protection.
+    """
+
+    backward_reactance: Optional[float] = None
+    """
+    [ZBEX] The reverse reactance (in ohms) that determines the maximum distance along the transmission line in the opposite direction of power flow for which the 
+    relay will provide protection.
+    """
+
+    forward_blind: Optional[float] = None
+    """
+    [ZBEX] The forward blind impedance (in ohms) that defines the area to be blinded in the opposite direction of the power flow.
+    """
+
+    forward_reach: Optional[float] = None
+    """
+    [ZBEX] The forward reach impedance (in ohms) that determines the maximum distance along the transmission line in the opposite direction of power flow for 
+    which the relay will provide protection.
+    """
+
+    forward_reactance: Optional[float] = None
+    """
+    [ZBEX] The forward reactance (in ohms) that determines the maximum distance along the transmission line in the opposite direction of power flow for which the 
+    relay will provide protection.
+    """
+
+    operation_phase_angle1: Optional[float] = None
+    """
+    [ZBEX] The phase angle (in degrees) between voltage and current during normal operating conditions for zone 1 relay.
+    """
+
+    operation_phase_angle2: Optional[float] = None
+    """
+    [ZBEX] The phase angle (in degrees) between voltage and current during normal operating conditions for zone 2 relay.
+    """
+
+    operation_phase_angle3: Optional[float] = None
+    """
+    [ZBEX] The phase angle (in degrees) between voltage and current during normal operating conditions for zone 3 relay.
+    """

zepben/ewb/model/cim/extensions/iec61970/base/protection/power_direction_kind.py

@@ -0,0 +1,36 @@
+#  Copyright 2025 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/.
+
+__all__ = ["PowerDirectionKind"]
+
+from enum import Enum
+
+from zepben.ewb.model.cim.extensions.zbex import zbex
+from zepben.ewb.util import unique
+
+
+@zbex
+@unique
+class PowerDirectionKind(Enum):
+    """
+    [ZBEX]
+    The flow of power direction used by a ProtectionEquipment.
+    """
+
+    UNKNOWN = 0
+    """[ZBEX] Unknown power direction flow."""
+
+    UNDIRECTED = 1
+    """[ZBEX] Power direction flow type is not specified."""
+
+    FORWARD = 2
+    """[ZBEX] Power direction forward flow is used."""
+
+    REVERSE = 3
+    """[ZBEX] Power direction reverse flow is used."""
+
+    @property
+    def short_name(self):
+        return str(self)[19:]

zepben/ewb/model/cim/extensions/iec61970/base/protection/protection_kind.py

@@ -0,0 +1,112 @@
+#  Copyright 2025 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/.
+
+__all__ = ["ProtectionKind"]
+
+from enum import Enum
+
+from zepben.ewb.model.cim.extensions.zbex import zbex
+
+
+@zbex
+class ProtectionKind(Enum):
+    """
+    [ZBEX]
+    The kind of protection being provided by this protection equipment.
+    """
+
+    UNKNOWN = 0
+    """[ZBEX] Unknown"""
+
+    JG = 1
+    """[ZBEX] Overcurrent"""
+
+    JGG = 2
+    """[ZBEX] Instantaneous"""
+
+    JGGG = 3
+    """[ZBEX] Instantaneous"""
+
+    JT = 4
+    """[ZBEX] Thermal overload"""
+
+    J0 = 5
+    """[ZBEX] Ground overcurrent"""
+
+    J0GG = 6
+    """[ZBEX] Instantaneous ground overcurrent"""
+
+    SEF = 7
+    """[ZBEX] Sensitive earth fault"""
+
+    VG = 8
+    """[ZBEX] Overvoltage"""
+
+    VGG = 9
+    """[ZBEX] Instantaneous overvoltage"""
+
+    VL = 10
+    """[ZBEX] Undervoltage"""
+
+    VLL = 11
+    """[ZBEX] Instantaneous"""
+
+    V0G = 12
+    """[ZBEX] Zero-sequence overvoltage"""
+
+    V0GG = 13
+    """[ZBEX] Instantaneous zero-sequence overvoltage"""
+
+    JDIFF = 14
+    """[ZBEX] Differential Current"""
+
+    FREQ = 15
+    """[ZBEX] Under frequency"""
+
+    FREQG = 16
+    """[ZBEX] Over frequency"""
+
+    ZL = 17
+    """[ZBEX] Phase distance"""
+
+    Z0L = 18
+    """[ZBEX] Ground distance"""
+
+    LE = 19
+    """[ZBEX] Load encroachment"""
+
+    J2G = 20
+    """[ZBEX] Negative-sequence overcurrent"""
+
+    MULTI_FUNCTION = 21
+    """[ZBEX] A multifunctional relay for universal usages"""
+
+    GROUND_CURRENT = 22
+    """[ZBEX] A device used to monitor and protect electrical equipment from damage caused by ground faults"""
+
+    GROUND_VOLTAGE = 23
+    """[ZBEX] A device used to detect contact accidents between an electric path and ground caused by arc ground faults"""
+
+    NETWORK_PROTECTOR = 24
+    """[ZBEX] Is a special self-contained air breaker or switching unit having a full complement of current, potential and control transformers, as well as relay functionality."""
+
+    DISTANCE = 25
+    """[ZBEX] A device used to detect faults on long-distance lines, pinpointing not only the fault condition but also measuring the distance between the current sensing mechanism and the fault location in the wire."""
+
+    NEGATIVE_OVERCURRENT = 26
+    """[ZBEX] A device used to protect generators from the unbalanced load by detecting negative sequence current."""
+
+    POWER = 27
+    """[ZBEX] A device that uses an electromagnet to open or close a circuit when the input (coil) is correctly excited"""
+
+    SECTIONALIZER = 28
+    """[ZBEX] A device that automatically isolates a faulted section of line from the rest of the distribution system"""
+
+    AUTO_TRANSFORMER = 29
+    """[ZBEX] A device used to regulate the voltage of transmission lines and can also be used to transform voltages."""
+
+    @property
+    def short_name(self):
+        return str(self)[15:]