zepben.ewb 1.0.0__py3-none-any.whl

zepben/ewb/model/cim/__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/model/cim/extensions/__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/model/cim/extensions/iec61968/__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/model/cim/extensions/iec61968/assetinfo/__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/iec61968/assetinfo/relay_info.py

@@ -0,0 +1,128 @@
+#  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__ = ["RelayInfo"]
+
+from typing import Optional, List, Generator, Callable
+
+from zepben.ewb.model.cim.extensions.zbex import zbex
+from zepben.ewb.model.cim.iec61968.assets.asset_info import AssetInfo
+from zepben.ewb.util import ngen, nlen, safe_remove, require
+
+
+@zbex
+class RelayInfo(AssetInfo):
+    """Relay Datasheet Information."""
+
+    curve_setting: Optional[str] = None
+    """The type of curve used for the Relay."""
+
+    reclose_fast: Optional[bool] = None
+    """True if reclose_delays are associated with a fast Curve, false otherwise."""
+
+    _reclose_delays: Optional[List[float]] = None
+
+    def __init__(self, reclose_delays: Optional[List[float]] = None, **kwargs):
+        super(RelayInfo, self).__init__(**kwargs)
+        if reclose_delays:
+            for index, delay in enumerate(reclose_delays):
+                self.add_delay(delay, index)
+
+    @property
+    def reclose_delays(self) -> Generator[float, None, None]:
+        """
+        The reclose delays for this curve and relay type. The index of the list is the reclose step, and the value is the overall delay time.
+        """
+        return ngen(self._reclose_delays)
+
+    def num_delays(self) -> int:
+        """
+        Get the number of reclose delays for this :class:`RelayInfo`
+        """
+        return nlen(self._reclose_delays)
+
+    def get_delay(self, index: int) -> float:
+        """
+        Get the reclose delay at the specified index, if it exists. Otherwise, this returns
+
+        :param index: The index of the delay to retrieve.
+        :return: The reclose delay at `index` if it exists, otherwise None.
+        """
+        if self._reclose_delays:
+            return self._reclose_delays[index]
+        else:
+            raise IndexError(index)
+
+    def for_each_delay(self, action: Callable[[int, float], None]):
+        """
+        Call the `action` on each delay in the `reclose_delays` collection
+
+        :param action: An action to apply to each delay in the `reclose_delays` collection, taking the index of the delay, and the delay itself.
+        """
+        for index, point in enumerate(self._reclose_delays):
+            action(index, point)
+
+    def add_delay(self, delay: float, index: int = None) -> RelayInfo:
+        """
+        Add a reclose delay.
+
+        :param delay: The delay in seconds to add.
+        :param index: The index into the list to add the delay at. Defaults to the end of the list.
+        :return: A reference to this :class:`RelayInfo` to allow fluent use.
+        """
+        if index is None:
+            index = self.num_delays()
+        require(0 <= index <= self.num_delays(),
+                lambda: f"Unable to add float to {str(self)}. Index number {index} "
+                        f"is invalid. Expected a value between 0 and {self.num_delays()}. Make sure you are "
+                        f"adding the items in order and there are no gaps in the numbering.")
+        self._reclose_delays = list() if self._reclose_delays is None else self._reclose_delays
+        self._reclose_delays.insert(index, delay)
+        return self
+
+    def set_delays(self, delays: List[float]) -> RelayInfo:
+        """
+        Set the reclose delays for this :class:`RelayInfo`.
+
+        :param delays: The delays to set. The provided list will be copied.
+        :return: A reference to this :class:`RelayInfo` to allow fluent use.
+        """
+        self._reclose_delays = delays.copy()
+        return self
+
+    def remove_delay(self, delay: float) -> RelayInfo:
+        """
+        Remove a delay from the list.
+
+        :param delay: The delay to remove.
+        :return: A reference to this :class:`RelayInfo` to allow fluent use.
+        """
+        self._reclose_delays = safe_remove(self._reclose_delays, delay)
+        return self
+
+    def remove_delay_at(self, index: int) -> float:
+        """
+        Remove a delay from the list.
+
+        :param index: The index of the delay to remove.
+        :return: The delay that was removed, or `None` if no delay was present at `index`.
+        :raises IndexError: If `sequence_number` is out of range.
+        """
+        if self._reclose_delays:
+            delay = self._reclose_delays.pop(index)
+            self._reclose_delays = self._reclose_delays if self._reclose_delays else None
+            return delay
+        raise IndexError(index)
+
+    def clear_delays(self) -> RelayInfo:
+        """
+        Clear all reclose delays.
+
+        :return: A reference to this :class:`RelayInfo` to allow fluent use.
+        """
+        self._reclose_delays = None
+        return self

zepben/ewb/model/cim/extensions/iec61968/metering/__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/model/cim/extensions/iec61968/metering/pan_demand_reponse_function.py

@@ -0,0 +1,112 @@
+#  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/.
+
+__all__ = ["PanDemandResponseFunction"]
+
+from typing import Optional, List, Union
+
+from zepben.ewb.model.cim.extensions.zbex import zbex
+from zepben.ewb.model.cim.iec61968.metering.controlled_appliance import ControlledAppliance, Appliance
+from zepben.ewb.model.cim.iec61968.metering.end_device_function import EndDeviceFunction
+from zepben.ewb.model.cim.iec61968.metering.end_device_function_kind import EndDeviceFunctionKind
+from zepben.ewb.util import require
+
+
+@zbex
+class PanDemandResponseFunction(EndDeviceFunction):
+    """
+    [ZBEX] PAN function that an end device supports, distinguished by 'kind'.
+    """
+
+    kind: EndDeviceFunctionKind = EndDeviceFunctionKind.UNKNOWN
+    """[ZBEX] `zepben.ewb.model.cim.iec61968.metering.metering.EndDeviceFunctionKind` of this `PanDemandResponseFunction`"""
+
+    _appliance_bitmask: Optional[int] = None
+
+    def __init__(self, appliances: Union[int, ControlledAppliance] = None, **kwargs):
+        super(PanDemandResponseFunction, self).__init__(**kwargs)
+        if appliances is not None:
+            self.appliance = appliances
+
+    @property
+    def appliance(self) -> Optional[ControlledAppliance]:
+        """
+        [ZBEX]
+        The `ControlledAppliance`s being controlled by this `PanDemandResponseFunction`.
+        """
+        if self._appliance_bitmask is None:
+            return None
+        else:
+            return ControlledAppliance(self._appliance_bitmask)
+
+    @appliance.setter
+    def appliance(self, appliance: Optional[Union[int, ControlledAppliance]]):
+        if isinstance(appliance, int):
+            self._appliance_bitmask = appliance
+        elif isinstance(appliance, ControlledAppliance):
+            if appliance:
+                self._appliance_bitmask = appliance.bitmask
+        else:
+            if appliance:
+                raise ValueError(f"Unsupported type for appliance: {appliance}. Must be either an int or ControlledAppliance")
+            else:
+                self._appliance_bitmask = None
+
+    def add_appliance(self, appliance: Appliance) -> bool:
+        """
+        Add an appliance to the appliances being controlled.
+        :param appliance: The appliance to add.
+        :return: True if the controlled appliances were updated.
+        """
+        previous = self._appliance_bitmask
+        bm = self._appliance_bitmask if self._appliance_bitmask else 0
+        self._appliance_bitmask = bm | appliance.bitmask
+        return self._appliance_bitmask != previous
+
+    def add_appliances(self, appliances: List[Appliance]) -> bool:
+        """
+        Add appliances to the appliances being controlled.
+        :param appliances: The appliances to add.
+        :return: True if the controlled appliances were updated.
+        """
+        require(len(appliances) > 0, lambda: "You must provide at least one appliance to add")
+        previous = self._appliance_bitmask
+
+        def f(bitmask: int, nxt: Appliance) -> int:
+            return bitmask | nxt.bitmask
+
+        acc = self._appliance_bitmask if self._appliance_bitmask is not None else 0
+        _ = [acc := f(acc, app) for app in appliances]
+        self._appliance_bitmask = acc
+        return self._appliance_bitmask != previous
+
+    def remove_appliance(self, appliance: Appliance) -> bool:
+        """
+        Remove an appliance from the appliances being controlled.
+        :param appliance: The appliance to remove.
+        :return: True if the controlled appliances were updated.
+        """
+        previous = self._appliance_bitmask
+        bm = self._appliance_bitmask if self._appliance_bitmask else 0
+        self._appliance_bitmask = bm & ~appliance.bitmask
+        return self._appliance_bitmask != previous
+
+    def remove_appliances(self, appliances: List[Appliance]) -> bool:
+        """
+        Remove appliances from the appliances being controlled.
+        :param appliances: Additional appliances to remove.
+        :return: True if the controlled appliances were updated.
+        """
+        require(len(appliances) > 0, lambda: "You must provide at least one appliance to remove")
+        previous = self._appliance_bitmask
+
+        def f(bitmask: int, nxt: Appliance) -> int:
+            return bitmask | nxt.bitmask
+
+        acc = 0
+        current = self._appliance_bitmask if self._appliance_bitmask is not None else 0
+        _ = [acc := f(acc, app) for app in appliances]
+        self._appliance_bitmask = current & ~acc
+        return self._appliance_bitmask != previous

zepben/ewb/model/cim/extensions/iec61970/__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/model/cim/extensions/iec61970/base/__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/model/cim/extensions/iec61970/base/core/__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/core/site.py

@@ -0,0 +1,37 @@
+#  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__ = ["Site"]
+
+from typing import Iterable, Type, Generator, TYPE_CHECKING
+
+from zepben.ewb.model.cim.extensions.zbex import zbex
+from zepben.ewb.model.cim.iec61970.base.core.equipment_container import EquipmentContainer
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.iec61970.base.core.conducting_equipment import ConductingEquipment
+    from zepben.ewb.model.cim.extensions.iec61970.base.feeder.lv_feeder import LvFeeder
+    from zepben.ewb.services.network.tracing.networktrace.operators.network_state_operators import NetworkStateOperators
+
+@zbex
+class Site(EquipmentContainer):
+    """
+    [ZBEX]
+    A collection of equipment for organizational purposes, used for grouping distribution resources located at a site.
+    Note this is not a CIM concept - however represents an `EquipmentContainer` in CIM. This is to avoid the use of `EquipmentContainer` as a concrete class.
+    """
+
+    def find_lv_feeders(
+        self,
+        lv_feeder_start_points: Iterable['ConductingEquipment'],
+        state_operators: Type['NetworkStateOperators']
+    ) -> Generator['LvFeeder', None, None]:
+        from zepben.ewb.model.cim.iec61970.base.core.conducting_equipment import ConductingEquipment
+        for ce in state_operators.get_equipment(self):
+            if isinstance(ce, ConductingEquipment):
+                if ce in lv_feeder_start_points:
+                    if not state_operators.is_open(ce):  # Exclude any open switch that might be energised by a different feeder on the other side
+                        for lv_feeder in ce.lv_feeders(state_operators):
+                            yield lv_feeder

zepben/ewb/model/cim/extensions/iec61970/base/feeder/__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/feeder/loop.py

@@ -0,0 +1,207 @@
+#  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__ = ["Loop"]
+
+from typing import Optional, List, Generator, TYPE_CHECKING
+
+from zepben.ewb.model.cim.extensions.zbex import zbex
+from zepben.ewb.model.cim.iec61970.base.core.identified_object import IdentifiedObject
+from zepben.ewb.util import safe_remove, ngen, nlen, get_by_mrid
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.iec61970.base.core.substation import Substation
+    from zepben.ewb.model.cim.iec61970.infiec61970.feeder.circuit import Circuit
+
+
+@zbex
+class Loop(IdentifiedObject):
+    """
+    [ZBEX]
+    Sub-transmission circuits are usually arranged in loops so that a single line failure does not cut off service
+    to many customers for more than a short time.
+    """
+
+    _circuits: Optional[List[Circuit]] = None
+    _substations: Optional[List[Substation]] = None
+    _energizing_substations: Optional[List[Substation]] = None
+
+    def __init__(self, circuits: List[Circuit] = None, substations: List[Substation] = None, energizing_substations: List[Substation] = None, **kwargs):
+        super(Loop, self).__init__(**kwargs)
+        if circuits:
+            for term in circuits:
+                self.add_circuit(term)
+
+        if substations:
+            for sub in substations:
+                self.add_substation(sub)
+
+        if energizing_substations:
+            for sub in energizing_substations:
+                self.add_energizing_substation(sub)
+
+    @property
+    def circuits(self) -> Generator[Circuit, None, None]:
+        """
+        [ZBEX] Sub-transmission `Circuit`s that form part of this loop.
+        """
+        return ngen(self._circuits)
+
+    @property
+    def substations(self) -> Generator[Substation, None, None]:
+        """
+        [ZBEX] The `Substation`s that are powered by this `Loop`.
+        """
+        return ngen(self._substations)
+
+    @property
+    def energizing_substations(self) -> Generator[Substation, None, None]:
+        """
+        [ZBEX] The `Substation`s that normally energize this `Loop`.
+        """
+        return ngen(self._energizing_substations)
+
+    def num_circuits(self):
+        """Return the number of end `Circuit`s associated with this `Loop`"""
+        return nlen(self._circuits)
+
+    def get_circuit(self, mrid: str) -> Circuit:
+        """
+        Get the `Circuit` for this `Loop` identified by `mrid`
+
+        `mrid` the mRID of the required `Circuit`
+        Returns The `Circuit` with the specified `mrid` if it exists
+        Raises `KeyError` if `mrid` wasn't present.
+        """
+        return get_by_mrid(self._circuits, mrid)
+
+    def add_circuit(self, circuit: Circuit) -> Loop:
+        """
+        Associate an `Circuit` with this `Loop`
+
+        `circuit` the `Circuit` to associate with this `Loop`.
+        Returns A reference to this `Loop` to allow fluent use.
+        Raises `ValueError` if another `Circuit` with the same `mrid` already exists for this `Loop`.
+        """
+        if self._validate_reference(circuit, self.get_circuit, "An Circuit"):
+            return self
+        self._circuits = list() if self._circuits is None else self._circuits
+        self._circuits.append(circuit)
+        return self
+
+    def remove_circuit(self, circuit: Circuit) -> Loop:
+        """
+        Disassociate `circuit` from this `Loop`
+
+        `circuit` the `Circuit` to disassociate from this `Loop`.
+        Returns A reference to this `Loop` to allow fluent use.
+        Raises `ValueError` if `circuit` was not associated with this `Loop`.
+        """
+        self._circuits = safe_remove(self._circuits, circuit)
+        return self
+
+    def clear_circuits(self) -> Loop:
+        """
+        Clear all end circuits.
+        Returns A reference to this `Loop` to allow fluent use.
+        """
+        self._circuits = None
+        return self
+
+    def num_substations(self):
+        """Return the number of end `Substation`s associated with this `Loop`"""
+        return nlen(self._substations)
+
+    def get_substation(self, mrid: str) -> Substation:
+        """
+        Get the `Substation` for this `Loop` 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._substations, mrid)
+
+    def add_substation(self, substation: Substation) -> Loop:
+        """
+        Associate an `Substation` with this `Loop`
+
+        `substation` the `Substation` to associate with this `Loop`.
+        Returns A reference to this `Loop` to allow fluent use.
+        Raises `ValueError` if another `Substation` with the same `mrid` already exists for this `Loop`.
+        """
+        if self._validate_reference(substation, self.get_substation, "An Substation"):
+            return self
+        self._substations = list() if self._substations is None else self._substations
+        self._substations.append(substation)
+        return self
+
+    def remove_substation(self, substation: Substation) -> Loop:
+        """
+        Disassociate `substation` from this `Loop`
+
+        `substation` the `Substation` to disassociate from this `Loop`.
+        Returns A reference to this `Loop` to allow fluent use.
+        Raises `ValueError` if `substation` was not associated with this `Loop`.
+        """
+        self._substations = safe_remove(self._substations, substation)
+        return self
+
+    def clear_substations(self) -> Loop:
+        """
+        Clear all end substations.
+        Returns A reference to this `Loop` to allow fluent use.
+        """
+        self._substations = None
+        return self
+
+    def num_energizing_substations(self):
+        """Return the number of end `Substation`s associated with this `Loop`"""
+        return nlen(self._energizing_substations)
+
+    def get_energizing_substation(self, mrid: str) -> Substation:
+        """
+        Get the `Substation` for this `Loop` 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._energizing_substations, mrid)
+
+    def add_energizing_substation(self, substation: Substation) -> Loop:
+        """
+        Associate an `Substation` with this `Loop`
+
+        `substation` the `Substation` to associate with this `Loop`.
+        Returns A reference to this `Loop` to allow fluent use.
+        Raises `ValueError` if another `Substation` with the same `mrid` already exists for this `Loop`.
+        """
+        if self._validate_reference(substation, self.get_energizing_substation, "An Substation"):
+            return self
+        self._energizing_substations = list() if self._energizing_substations is None else self._energizing_substations
+        self._energizing_substations.append(substation)
+        return self
+
+    def remove_energizing_substation(self, substation: Substation) -> Loop:
+        """
+        Disassociate `substation` from this `Loop`
+
+        `substation` the `Substation` to disassociate from this `Loop`.
+        Returns A reference to this `Loop` to allow fluent use.
+        Raises `ValueError` if `substation` was not associated with this `Loop`.
+        """
+        self._energizing_substations = safe_remove(self._energizing_substations, substation)
+        return self
+
+    def clear_energizing_substations(self) -> Loop:
+        """
+        Clear all end energizing_substations.
+        Returns A reference to this `Loop` to allow fluent use.
+        """
+        self._energizing_substations = None
+        return self