zepben.ewb 1.0.0b1__py3-none-any.whl

zepben/ewb/model/cim/iec61970/base/core/power_system_resource.py

@@ -0,0 +1,106 @@
+#  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__ = ['PowerSystemResource']
+
+from typing import Optional, TYPE_CHECKING, List, Generator, Iterable
+
+from zepben.ewb.model.cim.iec61970.base.core.identified_object import IdentifiedObject
+from zepben.ewb.util import get_by_mrid, nlen, ngen, safe_remove
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.iec61968.assets.asset import Asset
+    from zepben.ewb.model.cim.iec61968.assets.asset_info import AssetInfo
+    from zepben.ewb.model.cim.iec61968.common.location import Location
+
+
+class PowerSystemResource(IdentifiedObject):
+    """
+    Abstract class, should only be used through subclasses.
+    A power system resource can be an item of equipment such as a switch, an equipment container containing many individual
+    items of equipment such as a substation, or an organisational entity such as sub-control area. Power system resources
+    can have measurements associated.
+    """
+
+    location: Optional[Location] = None
+    """A `zepben.ewb.model.cim.iec61968.common.location.Location` for this resource."""
+
+    asset_info: Optional[AssetInfo] = None
+    """A subclass of `zepben.ewb.model.cim.iec61968.assets.asset_info.AssetInfo` providing information about the asset associated with this PowerSystemResource."""
+
+    num_controls: int = 0
+    """Number of Control's known to associate with this [PowerSystemResource]"""
+
+    _assets: Optional[List[Asset]] = None
+
+    def __init__(self, assets: Iterable[Asset] = None, **kwargs):
+        super(PowerSystemResource, self).__init__(**kwargs)
+        if assets:
+            for asset in assets:
+                self.add_asset(asset)
+
+    @property
+    def has_controls(self) -> bool:
+        """
+        * :return: True if this [PowerSystemResource] has at least 1 Control associated with it, false otherwise.
+        """
+        return self.num_controls > 0
+
+    def num_assets(self) -> int:
+        """
+        Get the number of `Asset`s associated with this `PowerSystemResource`.
+        """
+        return nlen(self._assets)
+
+    @property
+    def assets(self) -> Generator[Asset, None, None]:
+        """
+        The `Asset`s of this `PowerSystemResource`.
+        """
+        return ngen(self._assets)
+
+    def get_asset(self, mrid: str) -> Asset:
+        """
+        Get the `Asset` associated with this `PowerSystemResource` identified by `mrid`.
+
+        `mrid` the mRID of the required `Asset`
+        Returns The `Asset` with the specified `mrid`.
+        Raises `KeyError` if `mrid` wasn't present.
+        """
+        return get_by_mrid(self._assets, mrid)
+
+    def add_asset(self, asset: Asset) -> PowerSystemResource:
+        """
+        `asset` The `Asset` to associate with this `PowerSystemResource`.
+        Returns A reference to this `PowerSystemResource` to allow fluent use.
+        Raises `ValueError` if another `Asset` with the same `mrid` already exists in this `PowerSystemResource`
+        """
+        if self._validate_reference(asset, self.get_asset, "An Asset"):
+            return self
+
+        self._assets = list() if self._assets is None else self._assets
+        self._assets.append(asset)
+        return self
+
+    def remove_asset(self, asset: Asset) -> PowerSystemResource:
+        """
+        Disassociate an `Asset` from this `PowerSystemResource`.
+
+        `asset` the `Asset` to disassociate from this `PowerSystemResource`.
+        Raises `ValueError` if `asset` was not associated with this `PowerSystemResource`.
+        Returns A reference to this `PowerSystemResource` to allow fluent use.
+        """
+        self._assets = safe_remove(self._assets, asset)
+        return self
+
+    def clear_assets(self) -> PowerSystemResource:
+        """
+        Clear all assets.
+        Returns self
+        """
+        self._assets = None
+        return self

zepben/ewb/model/cim/iec61970/base/core/sub_geographical_region.py

@@ -0,0 +1,93 @@
+#  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__ = ["SubGeographicalRegion"]
+
+from typing import Optional, List, Generator, TYPE_CHECKING
+
+from zepben.ewb.model.cim.iec61970.base.core.identified_object import IdentifiedObject
+from zepben.ewb.util import nlen, ngen, get_by_mrid, safe_remove
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.iec61970.base.core.geographical_region import GeographicalRegion
+    from zepben.ewb.model.cim.iec61970.base.core.substation import Substation
+
+
+class SubGeographicalRegion(IdentifiedObject):
+    """
+    A subset of a geographical region of a power system network model.
+    """
+
+    geographical_region: Optional[GeographicalRegion] = None
+    """The geographical region to which this sub-geographical region is within."""
+
+    _substations: Optional[List[Substation]] = None
+
+    def __init__(self, substations: List[Substation] = None, **kwargs):
+        super(SubGeographicalRegion, self).__init__(**kwargs)
+        if substations:
+            for sub in substations:
+                self.add_substation(sub)
+
+    def num_substations(self) -> int:
+        """
+        Returns The number of `Substation`s associated with this `SubGeographicalRegion`
+        """
+        return nlen(self._substations)
+
+    @property
+    def substations(self) -> Generator[Substation, None, None]:
+        """
+        All substations belonging to this sub geographical region.
+        """
+        return ngen(self._substations)
+
+    def get_substation(self, mrid: str) -> Substation:
+        """
+        Get the `Substation` for this `SubGeographicalRegion` 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) -> SubGeographicalRegion:
+        """
+        Associate a `Substation` with this `GeographicalRegion`
+
+        `substation` the `Substation` to associate with this `SubGeographicalRegion`.
+
+        Returns A reference to this `SubGeographicalRegion` to allow fluent use.
+
+        Raises `ValueError` if another `Substation` with the same `mrid` already exists for this
+        `GeographicalRegion`.
+        """
+        if self._validate_reference(substation, self.get_substation, "A 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) -> SubGeographicalRegion:
+        """
+        Disassociate `substation` from this `GeographicalRegion`
+
+        `substation` The `Substation` to disassociate from this `SubGeographicalRegion`.
+        Returns A reference to this `SubGeographicalRegion` to allow fluent use.
+        Raises `ValueError` if `substation` was not associated with this `SubGeographicalRegion`.
+        """
+        self._substations = safe_remove(self._substations, substation)
+        return self
+
+    def clear_substations(self) -> SubGeographicalRegion:
+        """
+        Clear all `Substations`.
+        Returns A reference to this `SubGeographicalRegion` to allow fluent use.
+        """
+        self._substations = None
+        return self

zepben/ewb/model/cim/iec61970/base/core/substation.py

@@ -0,0 +1,277 @@
+#  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__ = ["Substation"]
+
+from typing import Optional, Generator, List, TYPE_CHECKING
+
+from zepben.ewb.model.cim.iec61970.base.core.equipment_container import EquipmentContainer
+from zepben.ewb.util import nlen, get_by_mrid, ngen, safe_remove
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.extensions.iec61970.base.feeder.loop import Loop
+    from zepben.ewb.model.cim.iec61970.base.core.feeder import Feeder
+    from zepben.ewb.model.cim.iec61970.base.core.sub_geographical_region import SubGeographicalRegion
+    from zepben.ewb.model.cim.iec61970.infiec61970.feeder.circuit import Circuit
+
+
+class Substation(EquipmentContainer):
+    """
+    A collection of equipment for purposes other than generation or utilization, through which electric energy in bulk
+    is passed for the purposes of switching or modifying its characteristics.
+    """
+
+    sub_geographical_region: Optional[SubGeographicalRegion] = None
+    """The SubGeographicalRegion containing the substation."""
+
+    _normal_energized_feeders: Optional[List[Feeder]] = None
+
+    _loops: Optional[List[Loop]] = None
+
+    _energized_loops: Optional[List[Loop]] = None
+
+    _circuits: Optional[List[Circuit]] = None
+
+    def __init__(self, normal_energized_feeders: List[Feeder] = None, loops: List[Loop] = None, energized_loops: List[Loop] = None,
+                 circuits: List[Circuit] = None, **kwargs):
+        super(Substation, self).__init__(**kwargs)
+        if normal_energized_feeders:
+            for feeder in normal_energized_feeders:
+                self.add_feeder(feeder)
+        if loops:
+            for loop in loops:
+                self.add_loop(loop)
+        if energized_loops:
+            for loop in energized_loops:
+                self.add_energized_loop(loop)
+        if circuits:
+            for circuit in circuits:
+                self.add_circuit(circuit)
+
+    @property
+    def circuits(self) -> Generator[Circuit, None, None]:
+        """
+        The `Circuit`s originating from this substation.
+        """
+        return ngen(self._circuits)
+
+    @property
+    def loops(self) -> Generator[Loop, None, None]:
+        """
+        The `Loop` originating from this substation.
+        """
+        return ngen(self._loops)
+
+    @property
+    def energized_loops(self) -> Generator[Loop, None, None]:
+        """
+        The `Loop`s originating from this substation that are energised.
+        """
+        return ngen(self._energized_loops)
+
+    @property
+    def feeders(self) -> Generator[Feeder, None, None]:
+        """
+        The normal energized feeders of the substation. Also used for naming purposes.
+        """
+        return ngen(self._normal_energized_feeders)
+
+    def num_feeders(self):
+        """
+        Returns The number of `Feeder`s associated with this `Substation`
+        """
+        return nlen(self._normal_energized_feeders)
+
+    def get_feeder(self, mrid: str) -> Feeder:
+        """
+        Get the `Feeder` for this `Substation` identified by `mrid`
+
+        `mrid` The mRID of the required `Feeder`
+        Returns The `Feeder` with the specified `mrid` if it exists
+        Raises `KeyError` if `mrid` wasn't present.
+        """
+        return get_by_mrid(self._normal_energized_feeders, mrid)
+
+    def add_feeder(self, feeder: Feeder) -> Substation:
+        """
+        Associate a `Feeder` with this `Substation`
+
+        `feeder` The `Feeder` to associate with this `Substation`.
+        Returns A reference to this `Substation` to allow fluent use.
+        Raises `ValueError` if another `Feeder` with the same `mrid` already exists for this `Substation`.
+        """
+        if self._validate_reference(feeder, self.get_feeder, "A Feeder"):
+            return self
+        self._normal_energized_feeders = list() if self._normal_energized_feeders is None else self._normal_energized_feeders
+        self._normal_energized_feeders.append(feeder)
+        return self
+
+    def remove_feeder(self, feeder: Feeder) -> Substation:
+        """
+        Disassociate `feeder` from this `Substation`
+
+        `feeder` The `Feeder` to disassociate from this `Substation`.
+        Returns A reference to this `Substation` to allow fluent use.
+        Raises `ValueError` if `feeder` was not associated with this `Substation`.
+        """
+        self._normal_energized_feeders = safe_remove(self._normal_energized_feeders, feeder)
+        return self
+
+    def clear_feeders(self) -> Substation:
+        """
+        Clear all current `Feeder`s.
+        Returns A reference to this `Substation` to allow fluent use.
+        """
+        self._normal_energized_feeders = None
+        return self
+
+    def num_loops(self):
+        """
+        Returns The number of `Loop`s associated with this `Substation`
+        """
+        return nlen(self._loops)
+
+    def get_loop(self, mrid: str) -> Loop:
+        """
+        Get the `Loop` for this `Substation` identified by `mrid`
+
+        `mrid` The mRID of the required `Loop`
+        Returns The `Loop` with the specified `mrid` if it exists
+        Raises `KeyError` if `mrid` wasn't present.
+        """
+        return get_by_mrid(self._loops, mrid)
+
+    def add_loop(self, loop: Loop) -> Substation:
+        """
+        Associate a `Loop` with this `Substation`
+
+        `loop` The `Loop` to associate with this `Substation`.
+        Returns A reference to this `Substation` to allow fluent use.
+        Raises `ValueError` if another `Loop` with the same `mrid` already exists for this `Substation`.
+        """
+        if self._validate_reference(loop, self.get_loop, "A Loop"):
+            return self
+        self._loops = list() if self._loops is None else self._loops
+        self._loops.append(loop)
+        return self
+
+    def remove_loop(self, loop: Loop) -> Substation:
+        """
+        Disassociate `loop` from this `Substation`
+
+        `loop` The `Loop` to disassociate from this `Substation`.
+        Returns A reference to this `Substation` to allow fluent use.
+        Raises `ValueError` if `loop` was not associated with this `Substation`.
+        """
+        self._loops = safe_remove(self._loops, loop)
+        return self
+
+    def clear_loops(self) -> Substation:
+        """
+        Clear all current `Loop`s.
+        Returns A reference to this `Substation` to allow fluent use.
+        """
+        self._loops = None
+        return self
+
+    def num_energized_loops(self):
+        """
+        Returns The number of `Loop`s associated with this `Substation`
+        """
+        return nlen(self._energized_loops)
+
+    def get_energized_loop(self, mrid: str) -> Loop:
+        """
+        Get the `Loop` for this `Substation` identified by `mrid`
+
+        `mrid` The mRID of the required `Loop`
+        Returns The `Loop` with the specified `mrid` if it exists
+        Raises `KeyError` if `mrid` wasn't present.
+        """
+        return get_by_mrid(self._energized_loops, mrid)
+
+    def add_energized_loop(self, loop: Loop) -> Substation:
+        """
+        Associate a `Loop` with this `Substation`
+
+        `loop` The `Loop` to associate with this `Substation`.
+        Returns A reference to this `Substation` to allow fluent use.
+        Raises `ValueError` if another `Loop` with the same `mrid` already exists for this `Substation`.
+        """
+        if self._validate_reference(loop, self.get_energized_loop, "A Loop"):
+            return self
+        self._energized_loops = list() if self._energized_loops is None else self._energized_loops
+        self._energized_loops.append(loop)
+        return self
+
+    def remove_energized_loop(self, loop: Loop) -> Substation:
+        """
+        Disassociate `loop` from this `Substation`
+
+        `loop` The `Loop` to disassociate from this `Substation`.
+        Returns A reference to this `Substation` to allow fluent use.
+        Raises `ValueError` if `loop` was not associated with this `Substation`.
+        """
+        self._energized_loops = safe_remove(self._energized_loops, loop)
+        return self
+
+    def clear_energized_loops(self) -> Substation:
+        """
+        Clear all current `Loop`s.
+        Returns A reference to this `Substation` to allow fluent use.
+        """
+        self._energized_loops = None
+        return self
+
+    def num_circuits(self):
+        """
+        Returns The number of `Circuit`s associated with this `Substation`
+        """
+        return nlen(self._circuits)
+
+    def get_circuit(self, mrid: str) -> Circuit:
+        """
+        Get the `Circuit` for this `Substation` 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) -> Substation:
+        """
+        Associate a `Circuit` with this `Substation`
+
+        `circuit` The `Circuit` to associate with this `Substation`.
+        Returns A reference to this `Substation` to allow fluent use.
+        Raises `ValueError` if another `Circuit` with the same `mrid` already exists for this `Substation`.
+        """
+        if self._validate_reference(circuit, self.get_circuit, "A 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) -> Substation:
+        """
+        Disassociate `circuit` from this `Substation`
+
+        `circuit` The `Circuit` to disassociate from this `Substation`.
+        Returns A reference to this `Substation` to allow fluent use.
+        Raises `ValueError` if `circuit` was not associated with this `Substation`.
+        """
+        self._circuits = safe_remove(self._circuits, circuit)
+        return self
+
+    def clear_circuits(self) -> Substation:
+        """
+        Clear all current `Circuit`s.
+        Returns A reference to this `Substation` to allow fluent use.
+        """
+        self._circuits = None
+        return self

zepben/ewb/model/cim/iec61970/base/core/terminal.py

@@ -0,0 +1,171 @@
+#  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
+
+from typing import Optional, Generator
+from typing import TYPE_CHECKING
+from weakref import ref, ReferenceType
+
+from zepben.ewb.model.cim.iec61970.base.core.ac_dc_terminal import AcDcTerminal
+from zepben.ewb.model.cim.iec61970.base.core.feeder import Feeder
+from zepben.ewb.model.cim.iec61970.base.core.phase_code import PhaseCode
+from zepben.ewb.model.cim.iec61970.base.wires.busbar_section import BusbarSection
+from zepben.ewb.model.phases import TracedPhases
+from zepben.ewb.services.network.tracing.feeder.feeder_direction import FeederDirection
+from zepben.ewb.services.network.tracing.phases.phase_status import PhaseStatus, NormalPhases, CurrentPhases
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.iec61970.base.core.conducting_equipment import ConductingEquipment
+    from zepben.ewb.model.cim.iec61970.base.core.connectivity_node import ConnectivityNode
+
+__all__ = ["Terminal"]
+
+
+class Terminal(AcDcTerminal):
+    """
+    An AC electrical connection point to a piece of conducting equipment. Terminals are connected at physical connection points called connectivity nodes.
+    """
+
+    _conducting_equipment: Optional[ConductingEquipment] = None
+    """The conducting equipment of the terminal. Conducting equipment have terminals that may be connected to other conducting equipment terminals via
+    connectivity nodes."""
+
+    phases: PhaseCode = PhaseCode.ABC
+    """Represents the normal network phasing condition. If the attribute is missing three phases (ABC) shall be assumed."""
+
+    traced_phases: TracedPhases = TracedPhases()
+    """the phase object representing the traced phases in both the normal and current network. If properly configured you would expect the normal state phases 
+    to match those in `phases`"""
+
+    sequence_number: int = 0
+    """The orientation of the terminal connections for a multiple terminal conducting equipment. The sequence numbering starts with 1 and additional
+    terminals should follow in increasing order. The first terminal is the "starting point" for a two terminal branch."""
+
+    normal_feeder_direction: FeederDirection = FeederDirection.NONE
+    """ Stores the direction of the feeder head relative to this [Terminal] in the normal state of the network.
+    """
+
+    current_feeder_direction: FeederDirection = FeederDirection.NONE
+    """ Stores the direction of the feeder head relative to this [Terminal] in the current state of the network.
+    """
+
+    _cn: Optional[ReferenceType] = None
+    """This is a weak reference to the connectivity node so if a Network object goes out of scope, holding a single conducting equipment
+    reference does not cause everything connected to it in the network to stay in memory."""
+
+    def __init__(self, conducting_equipment: ConductingEquipment = None, connectivity_node: ConnectivityNode = None, **kwargs):
+        super(Terminal, self).__init__(**kwargs)
+        if conducting_equipment:
+            self.conducting_equipment = conducting_equipment
+
+        # We set the connectivity node to itself if the name parameter is not used to make sure the positional argument is wrapped in a reference.
+        if connectivity_node:
+            self.connectivity_node = connectivity_node
+        else:
+            self.connectivity_node = self._cn
+
+    @property
+    def normal_phases(self) -> PhaseStatus:
+        """ Convenience method for accessing the normal phases"""
+        return NormalPhases(self)
+
+    @property
+    def current_phases(self) -> PhaseStatus:
+        """ Convenience method for accessing the current phases"""
+        return CurrentPhases(self)
+
+    @property
+    def conducting_equipment(self):
+        """
+        The conducting equipment of the terminal. Conducting equipment have terminals that may be connected to other conducting equipment terminals via
+        connectivity nodes.
+        """
+        return self._conducting_equipment
+
+    @conducting_equipment.setter
+    def conducting_equipment(self, ce):
+        if self._conducting_equipment is None or self._conducting_equipment is ce:
+            self._conducting_equipment = ce
+        else:
+            raise ValueError(f"conducting_equipment for {str(self)} has already been set to {self._conducting_equipment}, cannot reset this field to {ce}")
+
+    @property
+    def connectivity_node(self) -> Optional[ConnectivityNode]:
+        if self._cn:
+            return self._cn()
+        else:
+            return None
+
+    @connectivity_node.setter
+    def connectivity_node(self, cn: Optional[ConnectivityNode]):
+        if cn:
+            self._cn = ref(cn)
+        else:
+            self._cn = None
+
+    @property
+    def connected(self) -> bool:
+        if self.connectivity_node:
+            return True
+        return False
+
+    @property
+    def connectivity_node_id(self):
+        return self.connectivity_node.mrid if self.connectivity_node is not None else None
+
+    def __repr__(self):
+        return f"Terminal{{{self.mrid}}}"
+
+    def get_switch(self):
+        """
+        Get any associated switch for this Terminal
+        Returns Switch if present in this terminals ConnectivityNode, else None
+        """
+        return self.connectivity_node.get_switch()
+
+    @property
+    def base_voltage(self):
+        return self.conducting_equipment.get_base_voltage(self)
+
+    def connected_terminals(self) -> Generator[Terminal]:
+        """
+        Get the terminals that are connected to this `Terminal`.
+
+        :return: A `Generator` of terminals that are connected to this `Terminal`.
+        """
+        for t in self.connectivity_node.terminals if self.connectivity_node else []:
+            if t is not self:
+                yield t
+
+    def other_terminals(self) -> Generator[Terminal]:
+        """
+        * Get the terminals that share the same `ConductingEquipment` as this `Terminal`.
+        *
+        :return: A `Generator` of terminals that share the same `ConductingEquipment` as this `Terminal`.
+        """
+        for t in self.conducting_equipment.terminals:
+            if t is not self:
+                yield t
+
+    def connect(self, connectivity_node: ConnectivityNode):
+        self.connectivity_node = connectivity_node
+
+    def disconnect(self):
+        self.connectivity_node = None
+
+    def is_feeder_head_terminal(self):
+        if self.conducting_equipment is None:
+            return False
+
+        for feeder in filter(lambda c: isinstance(c, Feeder), self.conducting_equipment.containers):
+            if feeder.normal_head_terminal == self:
+                return True
+
+    def has_connected_busbars(self):
+        try:
+            return any(it != self and isinstance(it.conducting_equipment, BusbarSection) for it in self.connectivity_node.terminals) == True
+        except AttributeError:
+            return False

zepben/ewb/model/cim/iec61970/base/diagramlayout/__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/.