zepben.ewb 1.0.0__py3-none-any.whl

zepben/ewb/services/network/network_state.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__ = ["NetworkState"]
+
+from enum import Enum
+
+from zepben.ewb import unique
+
+
+@unique
+class NetworkState(Enum):
+    """
+    Indicates which state of the network an operation should be performed on.
+    """
+
+    ALL = 0
+    """
+    The operation should be performed on all states of the network.
+    """
+
+    NORMAL = 1
+    """
+    The operation should be performed on the normal state of the network.
+    """
+
+    CURRENT = 2
+    """
+    The operation should be performed on the current state of the network.
+    """
+
+    @property
+    def short_name(self):
+        return str(self)[13:]

zepben/ewb/services/network/tracing/__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/network/tracing/busbranch_trace.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/.
+
+from typing_extensions import TypeVar
+
+from zepben.ewb.services.network.tracing.networktrace.network_trace_tracker import NetworkTraceTracker
+from zepben.ewb.services.network.tracing.traversal.step_context import StepContext
+from zepben.ewb.services.network.tracing.traversal.traversal import Traversal, TraversalQueue
+
+T = TypeVar('T')
+
+
+class BusBranchTraceStep:
+    def __init__(self, identified_object: T):
+        self.identified_object = identified_object
+
+class BusBranchTrace(Traversal):
+    def __init__(self, queue_next: Traversal.QueueNext):
+        self._tracker = NetworkTraceTracker()
+        queue_type = Traversal.BasicQueueType(
+            queue_next=queue_next,
+            queue=TraversalQueue.depth_first()
+        )
+        super().__init__(queue_type)
+
+    def on_reset(self) -> None:
+        self._tracker.clear()
+
+    def can_visit_item(self, item: BusBranchTraceStep, context: StepContext) -> bool:
+        return self._tracker.visit(item.identified_object)
+
+    def add_start_item(self, item: T) -> 'BusBranchTrace':
+        super().add_start_item(BusBranchTraceStep(item))
+        return self

zepben/ewb/services/network/tracing/connectivity/__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/network/tracing/connectivity/connectivity_result.py

@@ -0,0 +1,105 @@
+#  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__ = ["ConnectivityResult", "terminal_compare"]
+
+from operator import attrgetter
+from typing import List, Optional, Tuple, TYPE_CHECKING, Iterable
+
+from zepben.ewb.dataclassy import dataclass
+from zepben.ewb.model.cim.iec61970.base.core.conducting_equipment import ConductingEquipment
+from zepben.ewb.model.cim.iec61970.base.core.terminal import Terminal
+from zepben.ewb.model.cim.iec61970.base.wires.single_phase_kind import SinglePhaseKind
+
+if TYPE_CHECKING:
+    from zepben.ewb import NominalPhasePath
+
+
+def terminal_compare(terminal: Terminal, other: Terminal):
+    """
+    This definition should only be used for sorting within a `PriorityQueue`
+    `terminal` The terminal to compare
+    `other` The terminal to compare against
+    Returns True if `terminal` has more phases than `other`, False otherwise.
+    """
+    return terminal.phases.num_phases > other.phases.num_phases
+
+
+Terminal.__lt__ = terminal_compare
+
+
+@dataclass(slots=True, init=False)
+class ConnectivityResult:
+    """
+    Stores the connectivity between two terminals, including the mapping between the nominal phases.
+    This class is intended to be used in an immutable way. You should avoid modifying it after it has been created.
+    """
+
+    from_terminal: Terminal
+    """The terminal from which the connectivity was requested."""
+
+    to_terminal: Terminal
+    """The terminal which is connected to the requested terminal."""
+
+    nominal_phase_paths: Tuple[NominalPhasePath]
+    """The mapping of nominal phase paths between the from and to terminals."""
+
+    def __init__(self, from_terminal: Terminal, to_terminal: Terminal, nominal_phase_paths: Iterable[NominalPhasePath]):
+        self.nominal_phase_paths = tuple(sorted(nominal_phase_paths, key=attrgetter('from_phase', 'to_phase')))
+        self.from_terminal = from_terminal
+        self.to_terminal = to_terminal
+
+    def __eq__(self, other: ConnectivityResult):
+        if self is other:
+            return True
+
+        # noinspection PyBroadException
+        try:
+            return self.from_terminal is other.from_terminal and self.to_terminal is other.to_terminal and self.nominal_phase_paths == other.nominal_phase_paths
+        except Exception:
+            return False
+
+    def __ne__(self, other):
+        if self is other:
+            return False
+        # noinspection PyBroadException
+        try:
+            return self.from_terminal is not other.from_terminal \
+                or self.to_terminal is not other.to_terminal \
+                or self.nominal_phase_paths != other.nominal_phase_paths
+        except Exception:
+            return True
+
+    def __str__(self):
+        return (f"ConnectivityResult(from_terminal={self.from_equip.mrid}-t{self.from_terminal.sequence_number}"
+                f", to_terminal={self.to_equip.mrid}-t{self.to_terminal.sequence_number}, core_paths={self.nominal_phase_paths})")
+
+    def __hash__(self):
+        res = self.from_terminal.mrid.__hash__()
+        res = 31 * res + self.to_terminal.mrid.__hash__()
+        res = 31 * res + self.nominal_phase_paths.__hash__()
+        return res
+
+    @property
+    def from_equip(self) -> Optional[ConductingEquipment]:
+        """The conducting equipment that owns the `from_terminal."""
+        return self.from_terminal.conducting_equipment
+
+    @property
+    def to_equip(self) -> Optional[ConductingEquipment]:
+        """The conducting equipment that owns the `to_terminal`."""
+        return self.to_terminal.conducting_equipment
+
+    @property
+    def from_nominal_phases(self) -> List[SinglePhaseKind]:
+        """The nominal phases that are connected in the `from_terminal`."""
+        return [npp.from_phase for npp in self.nominal_phase_paths]
+
+    @property
+    def to_nominal_phases(self) -> List[SinglePhaseKind]:
+        """The nominal phases that are connected in the `to_terminal`."""
+        return [npp.to_phase for npp in self.nominal_phase_paths]

zepben/ewb/services/network/tracing/connectivity/nominal_phase_path.py

@@ -0,0 +1,23 @@
+#  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__ = ["NominalPhasePath"]
+
+from dataclasses import dataclass
+
+from zepben.ewb import SinglePhaseKind
+
+
+@dataclass(frozen=True)
+class NominalPhasePath(object):
+    """
+    Defines how a nominal phase is wired through a connectivity node between two terminals
+    """
+
+    from_phase: SinglePhaseKind
+    """The nominal phase where the path comes from."""
+
+    to_phase: SinglePhaseKind
+    """The nominal phase where the path goes to."""

zepben/ewb/services/network/tracing/connectivity/phase_paths.py

@@ -0,0 +1,70 @@
+#  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__ = ["straight_phase_connectivity", "viable_inferred_phase_connectivity"]
+
+from typing import Dict, List
+
+from zepben.ewb import PhaseCode, SinglePhaseKind
+from zepben.ewb.services.network.tracing.connectivity.nominal_phase_path import NominalPhasePath
+
+# noinspection PyArgumentList
+_STRAIGHT_PHASE_PATHS = {
+    SinglePhaseKind.A: NominalPhasePath(SinglePhaseKind.A, SinglePhaseKind.A),
+    SinglePhaseKind.B: NominalPhasePath(SinglePhaseKind.B, SinglePhaseKind.B),
+    SinglePhaseKind.C: NominalPhasePath(SinglePhaseKind.C, SinglePhaseKind.C),
+    SinglePhaseKind.N: NominalPhasePath(SinglePhaseKind.N, SinglePhaseKind.N),
+    SinglePhaseKind.X: NominalPhasePath(SinglePhaseKind.X, SinglePhaseKind.X),
+    SinglePhaseKind.Y: NominalPhasePath(SinglePhaseKind.Y, SinglePhaseKind.Y),
+}
+
+_KNOWN_PHASE_CODES = [pc for pc in PhaseCode if any(it in PhaseCode.ABC.single_phases for it in pc.single_phases) or (pc == PhaseCode.N)]
+_UNKNOWN_PHASE_CODES = [pc for pc in PhaseCode if any(it in PhaseCode.XY.single_phases for it in pc.single_phases)]
+
+straight_phase_connectivity: Dict[PhaseCode, Dict[PhaseCode, List[NominalPhasePath]]] = {
+    from_phases: {
+        to_phases: [
+            _STRAIGHT_PHASE_PATHS[phase] for phase in from_phases.single_phases if phase in to_phases.single_phases
+        ] for to_phases in _KNOWN_PHASE_CODES
+    } for from_phases in _KNOWN_PHASE_CODES
+}
+straight_phase_connectivity.update({
+    from_phases: {
+        to_phases: [
+            _STRAIGHT_PHASE_PATHS[phase] for phase in from_phases.single_phases if phase in to_phases.single_phases
+        ] for to_phases in _UNKNOWN_PHASE_CODES
+    } for from_phases in _UNKNOWN_PHASE_CODES
+})
+
+viable_inferred_phase_connectivity: Dict[PhaseCode, Dict[PhaseCode, Dict[SinglePhaseKind, List[SinglePhaseKind]]]] = {
+    PhaseCode.XY: {
+        PhaseCode.ABC: {SinglePhaseKind.X: [SinglePhaseKind.A, SinglePhaseKind.B, SinglePhaseKind.C],
+                        SinglePhaseKind.Y: [SinglePhaseKind.B, SinglePhaseKind.C]},
+        PhaseCode.AB: {SinglePhaseKind.X: [SinglePhaseKind.A, SinglePhaseKind.B], SinglePhaseKind.Y: [SinglePhaseKind.B]},
+        PhaseCode.AC: {SinglePhaseKind.X: [SinglePhaseKind.A, SinglePhaseKind.C], SinglePhaseKind.Y: [SinglePhaseKind.C]},
+        PhaseCode.BC: {SinglePhaseKind.X: [SinglePhaseKind.B, SinglePhaseKind.C], SinglePhaseKind.Y: [SinglePhaseKind.B, SinglePhaseKind.C]},
+        PhaseCode.A: {SinglePhaseKind.X: [SinglePhaseKind.A]},
+        PhaseCode.B: {SinglePhaseKind.X: [SinglePhaseKind.B], SinglePhaseKind.Y: [SinglePhaseKind.B]},
+        PhaseCode.C: {SinglePhaseKind.X: [SinglePhaseKind.C], SinglePhaseKind.Y: [SinglePhaseKind.C]}
+    },
+    PhaseCode.X: {
+        PhaseCode.ABC: {SinglePhaseKind.X: [SinglePhaseKind.A, SinglePhaseKind.B, SinglePhaseKind.C]},
+        PhaseCode.AB: {SinglePhaseKind.X: [SinglePhaseKind.A, SinglePhaseKind.B]},
+        PhaseCode.AC: {SinglePhaseKind.X: [SinglePhaseKind.A, SinglePhaseKind.C]},
+        PhaseCode.BC: {SinglePhaseKind.X: [SinglePhaseKind.B, SinglePhaseKind.C]},
+        PhaseCode.A: {SinglePhaseKind.X: [SinglePhaseKind.A]},
+        PhaseCode.B: {SinglePhaseKind.X: [SinglePhaseKind.B]},
+        PhaseCode.C: {SinglePhaseKind.X: [SinglePhaseKind.C]}
+    },
+    PhaseCode.Y: {
+        PhaseCode.ABC: {SinglePhaseKind.Y: [SinglePhaseKind.B, SinglePhaseKind.C]},
+        PhaseCode.AB: {SinglePhaseKind.Y: [SinglePhaseKind.B]},
+        PhaseCode.AC: {SinglePhaseKind.Y: [SinglePhaseKind.C]},
+        PhaseCode.BC: {SinglePhaseKind.Y: [SinglePhaseKind.B, SinglePhaseKind.C]},
+        PhaseCode.A: {},
+        PhaseCode.B: {SinglePhaseKind.Y: [SinglePhaseKind.B]},
+        PhaseCode.C: {SinglePhaseKind.Y: [SinglePhaseKind.C]}
+    }
+}

zepben/ewb/services/network/tracing/connectivity/terminal_connectivity_connected.py

@@ -0,0 +1,226 @@
+#  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__ = ["TerminalConnectivityConnected"]
+
+from typing import List, Iterable, Optional, Set, Dict, Callable
+
+from zepben.ewb import Terminal, PhaseCode, SinglePhaseKind, Switch
+from zepben.ewb.services.network.tracing.connectivity.connectivity_result import ConnectivityResult
+from zepben.ewb.services.network.tracing.connectivity.nominal_phase_path import NominalPhasePath
+from zepben.ewb.services.network.tracing.connectivity.phase_paths import viable_inferred_phase_connectivity, straight_phase_connectivity
+from zepben.ewb.services.network.tracing.connectivity.xy_candidate_phase_paths import XyCandidatePhasePaths
+from zepben.ewb.services.network.tracing.connectivity.xy_phase_step import XyPhaseStep
+from zepben.ewb.services.network.tracing.traversal.queue import LIFODeque
+
+
+class TerminalConnectivityConnected:
+    """
+    A class that can be used to find the phase connectivity between terminals.
+    """
+
+    _create_candidate_phases: Callable[[], XyCandidatePhasePaths]
+
+    def __init__(self, create_candidate_phases: Callable[[], XyCandidatePhasePaths] = XyCandidatePhasePaths):
+        self._create_candidate_phases = create_candidate_phases
+
+    def connected_terminals(
+        self,
+        terminal: Terminal,
+        phases: Optional[Iterable[SinglePhaseKind]] = None
+    ) -> List[ConnectivityResult]:
+        """
+        Find the terminals that are connected to `terminal`, and the phase paths between them.
+
+        :param terminal: The `Terminal` to find connectivity for.
+        :param phases: An `Iterable` of `SinglePhaseKind` to limit the included phase paths to check. Defaults to None (all phases).
+        :return: A `List` of `ConnectivityResult` defining the connected terminals, or an empty list if there are no connected terminals.
+        """
+        phases = set(phases or terminal.phases.single_phases)
+        include_phases = phases.intersection(terminal.phases.single_phases)
+        connectivity_node = terminal.connectivity_node
+        if connectivity_node is None:
+            return []
+
+        results = []
+        for connected_terminal in connectivity_node.terminals:
+            if connected_terminal != terminal:
+                cr = self.terminal_connectivity(terminal, connected_terminal, include_phases)
+                if cr.nominal_phase_paths:
+                    results.append(cr)
+
+        return results
+
+    def terminal_connectivity(
+        self,
+        terminal: Terminal,
+        connected_terminal: Terminal,
+        include_phases: Set[SinglePhaseKind]
+    ) -> ConnectivityResult:
+        return ConnectivityResult(
+            from_terminal=terminal,
+            to_terminal=connected_terminal,
+            nominal_phase_paths=[
+                path for path in (
+                    self._find_straight_phase_paths(terminal, connected_terminal)
+                    or self._find_xy_phase_paths(terminal, connected_terminal)
+                ) if (path.from_phase in include_phases) and (path.to_phase in connected_terminal.phases)
+            ]
+        )
+
+    @staticmethod
+    def _find_straight_phase_paths(terminal: Terminal, connected_terminal: Terminal) -> Optional[List[NominalPhasePath]]:
+        paths = straight_phase_connectivity.get(terminal.phases, None)
+
+        return paths and paths.get(connected_terminal.phases)
+
+    def _find_xy_phase_paths(self, terminal: Terminal, connected_terminal: Terminal) -> List[NominalPhasePath]:
+        xy_phases = _find_xy_phases(terminal)
+
+        nominal_phase_paths = []
+        if SinglePhaseKind.N in terminal.phases and SinglePhaseKind.N in connected_terminal.phases:
+            # noinspection PyArgumentList
+            nominal_phase_paths.append(NominalPhasePath(SinglePhaseKind.N, SinglePhaseKind.N))
+
+        def add_from_to(from_phase, to_phase):
+            # noinspection PyArgumentList
+            nominal_phase_paths.append(NominalPhasePath(from_phase, to_phase))
+
+        def add_to_from(from_phase, to_phase):
+            # noinspection PyArgumentList
+            nominal_phase_paths.append(NominalPhasePath(to_phase, from_phase))
+
+        if _is_not_none(xy_phases):
+            self._add_xy_phase_paths(terminal, add_from_to)
+        else:
+            self._add_xy_phase_paths(terminal, add_to_from)
+
+        return nominal_phase_paths
+
+    def _add_xy_phase_paths(self, terminal: Terminal, add_path: Callable[[SinglePhaseKind, SinglePhaseKind], None]):
+        """
+                val xyPhases = cn.terminals.associateWith { it.findXyPhases() }.filterValues { it.isNotNone() }
+                val primaryPhases = cn.terminals.associateWith { it.findPrimaryPhases() }.filterValues { it.isNotNone() }
+
+                findXyCandidatePhases(xyPhases, primaryPhases).apply {
+                    calculatePaths()
+                        .asSequence()
+                        .filter { (_, to) -> to != SPK.NONE }
+                        .filter { (from, to) -> (from in terminal.phases.singlePhases) || (to in terminal.phases.singlePhases) }
+                        .forEach { (from, to) -> addPath(from, to) }
+                }
+        """
+        cn = terminal.connectivity_node
+
+        xy_phases = {it: _find_xy_phases(it) for it in cn.terminals if _is_not_none(_find_xy_phases(it))}
+        primary_phases = {it: _find_primary_phases(it) for it in cn.terminals if _is_not_none(_find_primary_phases(it))}
+
+        candidate_phases = self._find_xy_candidate_phases(xy_phases, primary_phases)
+        for from_phase, to_phase in candidate_phases.calculate_paths().items():
+            if (to_phase != SinglePhaseKind.NONE) and ((from_phase in terminal.phases.single_phases) or (to_phase in terminal.phases.single_phases)):
+                add_path(from_phase, to_phase)
+
+    def _find_xy_candidate_phases(self, xy_phases: Dict[Terminal, PhaseCode], primary_phases: Dict[Terminal, PhaseCode]) -> XyCandidatePhasePaths:
+        queue = LIFODeque[XyPhaseStep]()
+        visited = set()
+        candidate_phases = self._create_candidate_phases()
+
+        for terminal, xy_phase_code in xy_phases.items():
+            for primary_phase_code in primary_phases.values():
+                for phase, candidates in viable_inferred_phase_connectivity.get(xy_phase_code, {}).get(primary_phase_code, {}).items():
+                    candidate_phases.add_candidates(phase, candidates)
+
+            # noinspection PyArgumentList
+            self._find_more_xy_candidate_phases(XyPhaseStep(terminal, xy_phase_code), visited, queue, candidate_phases)
+
+        while len(queue) > 0:
+            self._find_more_xy_candidate_phases(queue.pop(), visited, queue, candidate_phases)
+
+        return candidate_phases
+
+    def _find_more_xy_candidate_phases(
+        self,
+        step: XyPhaseStep,
+        visited: Set[XyPhaseStep],
+        queue: LIFODeque[XyPhaseStep],
+        candidate_phases: XyCandidatePhasePaths
+    ):
+        if step in visited:
+            return
+
+        visited.add(step)
+
+        without_neutral = step.terminal.phases.without_neutral
+        if (SinglePhaseKind.X in without_neutral) or (SinglePhaseKind.Y in without_neutral):
+            if not self._check_traced_phases(step, candidate_phases):
+                self._queue_next(step.terminal, without_neutral, queue)
+        else:
+            for (phase, candidates) in viable_inferred_phase_connectivity.get(step.phase_code, {}).get(without_neutral, {}).items():
+                candidate_phases.add_candidates(phase, candidates)
+
+    @staticmethod
+    def _check_traced_phases(step: XyPhaseStep, candidate_phases: XyCandidatePhasePaths) -> bool:
+        found_traced = False
+        normal_x = step.terminal.normal_phases[SinglePhaseKind.X]
+        if normal_x != SinglePhaseKind.NONE:
+            candidate_phases.add_known(SinglePhaseKind.X, normal_x)
+            found_traced = True
+
+        normal_y = step.terminal.normal_phases[SinglePhaseKind.Y]
+        if normal_y != SinglePhaseKind.NONE:
+            candidate_phases.add_known(SinglePhaseKind.Y, normal_y)
+            found_traced = True
+
+        return found_traced
+
+    @staticmethod
+    def _queue_next(terminal: Terminal, phase_code: PhaseCode, queue: LIFODeque[XyPhaseStep]):
+        ce = terminal.conducting_equipment
+        if not ce:
+            return
+
+        if not isinstance(ce, Switch) or not ce.is_normally_open:
+            for other in ce.terminals:
+                if (other != terminal) and other.connectivity_node:
+                    for connected in other.connectivity_node.terminals:
+                        if connected.conducting_equipment != ce:
+                            # noinspection PyArgumentList
+                            queue.append(XyPhaseStep(connected, phase_code))
+
+
+def _find_xy_phases(terminal: Terminal):
+    if terminal.phases in (PhaseCode.XY, PhaseCode.XYN):
+        return PhaseCode.XY
+    elif terminal.phases in (PhaseCode.X, PhaseCode.XN):
+        return PhaseCode.X
+    elif terminal.phases in (PhaseCode.Y, PhaseCode.YN):
+        return PhaseCode.Y
+    else:
+        return PhaseCode.NONE
+
+
+def _find_primary_phases(terminal: Terminal):
+    if terminal.phases in (PhaseCode.ABC, PhaseCode.ABCN):
+        primary_phases = PhaseCode.ABC
+    elif terminal.phases in (PhaseCode.AB, PhaseCode.ABN):
+        primary_phases = PhaseCode.AB
+    elif terminal.phases in (PhaseCode.AC, PhaseCode.ACN):
+        primary_phases = PhaseCode.AC
+    elif terminal.phases in (PhaseCode.BC, PhaseCode.BCN):
+        primary_phases = PhaseCode.BC
+    elif terminal.phases in (PhaseCode.A, PhaseCode.AN):
+        primary_phases = PhaseCode.A
+    elif terminal.phases in (PhaseCode.B, PhaseCode.BN):
+        primary_phases = PhaseCode.B
+    elif terminal.phases in (PhaseCode.C, PhaseCode.CN):
+        primary_phases = PhaseCode.C
+    else:
+        primary_phases = PhaseCode.NONE
+
+    return primary_phases
+
+
+def _is_not_none(phase_code: PhaseCode) -> bool:
+    return phase_code != PhaseCode.NONE

zepben/ewb/services/network/tracing/connectivity/terminal_connectivity_internal.py

@@ -0,0 +1,64 @@
+#  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__ = ["TerminalConnectivityInternal"]
+
+from typing import Set, Optional
+
+from zepben.ewb import Terminal, PowerTransformer, SinglePhaseKind, ConnectivityResult, NominalPhasePath
+from zepben.ewb.services.network.tracing.connectivity.transformer_phase_paths import transformer_phase_paths
+
+
+class TerminalConnectivityInternal:
+    """
+    Helper class for finding the paths through equipment.
+    """
+
+    def between(
+        self,
+        terminal: Terminal,
+        other_terminal: Terminal,
+        include_phases: Optional[Set[SinglePhaseKind]] = None
+    ) -> ConnectivityResult:
+        """
+         * Find the connectivity between the two terminals. The function assumes they are on the same conducting equipment.
+         *
+         * @param terminal The terminal you are moving from
+         * @param other_terminal The terminal you are moving to
+         * @param include_phases The nominal phases on the [terminal] you want to use.
+         *
+         * @return The connectivity between [terminal] and [other_terminal]. If the conducting equipment is a power transformer the nominal phase paths may
+         *         contain an entry with the 'from' phase set to NONE and the 'to' phase set to N, indicating a neutral has been added by the transformer1.
+        """
+        if include_phases is None:
+            include_phases = set(terminal.phases.single_phases)
+
+        if isinstance(terminal.conducting_equipment, PowerTransformer):
+            return self._transformer_terminal_connectivity(terminal, other_terminal, include_phases)
+
+        return self._straight_terminal_connectivity(terminal, other_terminal, include_phases)
+
+    @staticmethod
+    def _transformer_terminal_connectivity(
+        terminal: Terminal,
+        other_terminal: Terminal,
+        include_phases: Set[SinglePhaseKind]
+    ) -> ConnectivityResult:
+        paths = [it for it in transformer_phase_paths.get(terminal.phases, {}).get(other_terminal.phases, [])
+                 if (it.from_phase in include_phases) or (it.from_phase == SinglePhaseKind.NONE)]
+
+        return ConnectivityResult(terminal, other_terminal, paths)
+
+    @staticmethod
+    def _straight_terminal_connectivity(
+        terminal: Terminal,
+        other_terminal: Terminal,
+        include_phases: Set[SinglePhaseKind]
+    ) -> ConnectivityResult:
+        # noinspection PyArgumentList
+        paths = [NominalPhasePath(it, it) for it in set(terminal.phases.single_phases).intersection(set(other_terminal.phases.single_phases))
+                 if it in include_phases]
+
+        return ConnectivityResult(terminal, other_terminal, paths)