zepben.ewb 1.0.0b1__py3-none-any.whl

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

@@ -0,0 +1,202 @@
+#  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__ = ["transformer_phase_paths", "add_neutral"]
+
+from typing import Dict, List
+
+from zepben.ewb import SinglePhaseKind as Phase, NominalPhasePath, PhaseCode
+
+
+def _path(from_phase: Phase, to_phase: Phase) -> NominalPhasePath:
+    # noinspection PyArgumentList
+    return NominalPhasePath(from_phase, to_phase)
+
+
+# This is used to indicate that a transformer adds a neutral, and it should be energised from the transformer.
+add_neutral = _path(Phase.NONE, Phase.N)
+
+transformer_phase_paths: Dict[PhaseCode, Dict[PhaseCode, List[NominalPhasePath]]] = {
+    PhaseCode.ABCN: {
+        PhaseCode.ABCN: [_path(Phase.A, Phase.A), _path(Phase.B, Phase.B), _path(Phase.C, Phase.C), _path(Phase.N, Phase.N)],
+        PhaseCode.ABC: [_path(Phase.A, Phase.A), _path(Phase.B, Phase.B), _path(Phase.C, Phase.C)],
+    },
+    PhaseCode.AN: {
+        PhaseCode.AN: [_path(Phase.A, Phase.A), _path(Phase.N, Phase.N)],
+        PhaseCode.XN: [_path(Phase.A, Phase.X), _path(Phase.N, Phase.N)],
+        PhaseCode.AB: [_path(Phase.A, Phase.A), _path(Phase.NONE, Phase.B)],
+        PhaseCode.XY: [_path(Phase.A, Phase.X), _path(Phase.NONE, Phase.Y)],
+        PhaseCode.X: [_path(Phase.A, Phase.X)],
+        PhaseCode.A: [_path(Phase.A, Phase.A)],
+    },
+    PhaseCode.BN: {
+        PhaseCode.BN: [_path(Phase.B, Phase.B), _path(Phase.N, Phase.N)],
+        PhaseCode.XN: [_path(Phase.B, Phase.X), _path(Phase.N, Phase.N)],
+        PhaseCode.BC: [_path(Phase.B, Phase.B), _path(Phase.NONE, Phase.C)],
+        PhaseCode.XY: [_path(Phase.B, Phase.X), _path(Phase.NONE, Phase.Y)],
+        PhaseCode.B: [_path(Phase.B, Phase.B)],
+        PhaseCode.X: [_path(Phase.B, Phase.X)],
+    },
+    PhaseCode.CN: {
+        PhaseCode.CN: [_path(Phase.C, Phase.C), _path(Phase.N, Phase.N)],
+        PhaseCode.XN: [_path(Phase.C, Phase.X), _path(Phase.N, Phase.N)],
+        PhaseCode.AC: [_path(Phase.C, Phase.C), _path(Phase.NONE, Phase.A)],
+        PhaseCode.XY: [_path(Phase.C, Phase.X), _path(Phase.NONE, Phase.Y)],
+        PhaseCode.C: [_path(Phase.C, Phase.C)],
+        PhaseCode.X: [_path(Phase.C, Phase.X)],
+    },
+    PhaseCode.XN: {
+        PhaseCode.AN: [_path(Phase.X, Phase.A), _path(Phase.N, Phase.N)],
+        PhaseCode.BN: [_path(Phase.X, Phase.B), _path(Phase.N, Phase.N)],
+        PhaseCode.CN: [_path(Phase.X, Phase.C), _path(Phase.N, Phase.N)],
+        PhaseCode.XN: [_path(Phase.X, Phase.X), _path(Phase.N, Phase.N)],
+        PhaseCode.AB: [_path(Phase.X, Phase.A), _path(Phase.NONE, Phase.B)],
+        PhaseCode.BC: [_path(Phase.X, Phase.B), _path(Phase.NONE, Phase.C)],
+        PhaseCode.AC: [_path(Phase.X, Phase.C), _path(Phase.NONE, Phase.A)],
+        PhaseCode.XY: [_path(Phase.X, Phase.X), _path(Phase.NONE, Phase.Y)],
+        PhaseCode.A: [_path(Phase.X, Phase.A)],
+        PhaseCode.B: [_path(Phase.X, Phase.B)],
+        PhaseCode.C: [_path(Phase.X, Phase.C)],
+        PhaseCode.X: [_path(Phase.X, Phase.X)],
+    },
+    PhaseCode.ABC: {
+        PhaseCode.ABCN: [_path(Phase.A, Phase.A), _path(Phase.B, Phase.B), _path(Phase.C, Phase.C), add_neutral],
+        PhaseCode.ABC: [_path(Phase.A, Phase.A), _path(Phase.B, Phase.B), _path(Phase.C, Phase.C)],
+    },
+    PhaseCode.ABN: {
+        PhaseCode.ABN: [_path(Phase.A, Phase.A), _path(Phase.B, Phase.B), _path(Phase.N, Phase.N)],
+        PhaseCode.XYN: [_path(Phase.A, Phase.X), _path(Phase.B, Phase.Y), _path(Phase.N, Phase.N)],
+        PhaseCode.AB: [_path(Phase.A, Phase.A), _path(Phase.B, Phase.B)],
+        PhaseCode.XY: [_path(Phase.A, Phase.X), _path(Phase.B, Phase.Y)],
+        PhaseCode.A: [_path(Phase.A, Phase.A)],
+        PhaseCode.X: [_path(Phase.A, Phase.X)],
+    },
+    PhaseCode.BCN: {
+        PhaseCode.BCN: [_path(Phase.B, Phase.B), _path(Phase.C, Phase.C), _path(Phase.N, Phase.N)],
+        PhaseCode.XYN: [_path(Phase.B, Phase.X), _path(Phase.C, Phase.Y), _path(Phase.N, Phase.N)],
+        PhaseCode.BC: [_path(Phase.B, Phase.B), _path(Phase.C, Phase.C)],
+        PhaseCode.XY: [_path(Phase.B, Phase.X), _path(Phase.C, Phase.Y)],
+        PhaseCode.B: [_path(Phase.B, Phase.B)],
+        PhaseCode.X: [_path(Phase.B, Phase.X)],
+    },
+    PhaseCode.ACN: {
+        PhaseCode.ACN: [_path(Phase.A, Phase.A), _path(Phase.C, Phase.C), _path(Phase.N, Phase.N)],
+        PhaseCode.XYN: [_path(Phase.A, Phase.X), _path(Phase.C, Phase.Y), _path(Phase.N, Phase.N)],
+        PhaseCode.AC: [_path(Phase.A, Phase.A), _path(Phase.C, Phase.C)],
+        PhaseCode.XY: [_path(Phase.A, Phase.X), _path(Phase.C, Phase.Y)],
+        PhaseCode.C: [_path(Phase.C, Phase.C)],
+        PhaseCode.X: [_path(Phase.C, Phase.X)],
+    },
+    PhaseCode.XYN: {
+        PhaseCode.ABN: [_path(Phase.X, Phase.A), _path(Phase.Y, Phase.B), _path(Phase.N, Phase.N)],
+        PhaseCode.BCN: [_path(Phase.X, Phase.B), _path(Phase.Y, Phase.C), _path(Phase.N, Phase.N)],
+        PhaseCode.ACN: [_path(Phase.X, Phase.A), _path(Phase.Y, Phase.C), _path(Phase.N, Phase.N)],
+        PhaseCode.XYN: [_path(Phase.X, Phase.X), _path(Phase.Y, Phase.Y), _path(Phase.N, Phase.N)],
+        PhaseCode.AB: [_path(Phase.X, Phase.A), _path(Phase.Y, Phase.B)],
+        PhaseCode.BC: [_path(Phase.X, Phase.B), _path(Phase.Y, Phase.C)],
+        PhaseCode.AC: [_path(Phase.X, Phase.A), _path(Phase.Y, Phase.C)],
+        PhaseCode.XY: [_path(Phase.X, Phase.X), _path(Phase.Y, Phase.Y)],
+        PhaseCode.A: [_path(Phase.X, Phase.A)],
+        PhaseCode.B: [_path(Phase.X, Phase.B)],
+        PhaseCode.C: [_path(Phase.X, Phase.C)],
+        PhaseCode.X: [_path(Phase.X, Phase.X)],
+    },
+    PhaseCode.AB: {
+        PhaseCode.ABN: [_path(Phase.A, Phase.A), _path(Phase.B, Phase.B), add_neutral],
+        PhaseCode.XYN: [_path(Phase.A, Phase.X), _path(Phase.B, Phase.Y), add_neutral],
+        PhaseCode.AN: [_path(Phase.A, Phase.A), add_neutral],
+        PhaseCode.XN: [_path(Phase.A, Phase.X), add_neutral],
+        PhaseCode.AB: [_path(Phase.A, Phase.A), _path(Phase.B, Phase.B)],
+        PhaseCode.XY: [_path(Phase.A, Phase.X), _path(Phase.B, Phase.Y)],
+        PhaseCode.A: [_path(Phase.A, Phase.A)],
+        PhaseCode.X: [_path(Phase.A, Phase.X)],
+    },
+    PhaseCode.BC: {
+        PhaseCode.BCN: [_path(Phase.B, Phase.B), _path(Phase.C, Phase.C), add_neutral],
+        PhaseCode.XYN: [_path(Phase.B, Phase.X), _path(Phase.C, Phase.Y), add_neutral],
+        PhaseCode.BN: [_path(Phase.B, Phase.B), add_neutral],
+        PhaseCode.XN: [_path(Phase.B, Phase.X), add_neutral],
+        PhaseCode.BC: [_path(Phase.B, Phase.B), _path(Phase.C, Phase.C)],
+        PhaseCode.XY: [_path(Phase.B, Phase.X), _path(Phase.C, Phase.Y)],
+        PhaseCode.B: [_path(Phase.B, Phase.B)],
+        PhaseCode.X: [_path(Phase.B, Phase.X)],
+    },
+    PhaseCode.AC: {
+        PhaseCode.ACN: [_path(Phase.A, Phase.A), _path(Phase.C, Phase.C), add_neutral],
+        PhaseCode.XYN: [_path(Phase.A, Phase.X), _path(Phase.C, Phase.Y), add_neutral],
+        PhaseCode.CN: [_path(Phase.C, Phase.C), add_neutral],
+        PhaseCode.XN: [_path(Phase.C, Phase.X), add_neutral],
+        PhaseCode.AC: [_path(Phase.A, Phase.A), _path(Phase.C, Phase.C)],
+        PhaseCode.XY: [_path(Phase.A, Phase.X), _path(Phase.C, Phase.Y)],
+        PhaseCode.C: [_path(Phase.C, Phase.C)],
+        PhaseCode.X: [_path(Phase.C, Phase.X)],
+    },
+    PhaseCode.XY: {
+        PhaseCode.ABN: [_path(Phase.X, Phase.A), _path(Phase.Y, Phase.B), add_neutral],
+        PhaseCode.BCN: [_path(Phase.X, Phase.B), _path(Phase.Y, Phase.C), add_neutral],
+        PhaseCode.ACN: [_path(Phase.X, Phase.A), _path(Phase.Y, Phase.C), add_neutral],
+        PhaseCode.XYN: [_path(Phase.X, Phase.X), _path(Phase.Y, Phase.Y), add_neutral],
+        PhaseCode.AN: [_path(Phase.X, Phase.A), add_neutral],
+        PhaseCode.BN: [_path(Phase.X, Phase.B), add_neutral],
+        PhaseCode.CN: [_path(Phase.X, Phase.C), add_neutral],
+        PhaseCode.XN: [_path(Phase.X, Phase.X), add_neutral],
+        PhaseCode.AB: [_path(Phase.X, Phase.A), _path(Phase.Y, Phase.B)],
+        PhaseCode.BC: [_path(Phase.X, Phase.B), _path(Phase.Y, Phase.C)],
+        PhaseCode.AC: [_path(Phase.X, Phase.A), _path(Phase.Y, Phase.C)],
+        PhaseCode.XY: [_path(Phase.X, Phase.X), _path(Phase.Y, Phase.Y)],
+        PhaseCode.A: [_path(Phase.X, Phase.A)],
+        PhaseCode.B: [_path(Phase.X, Phase.B)],
+        PhaseCode.C: [_path(Phase.X, Phase.C)],
+        PhaseCode.X: [_path(Phase.X, Phase.X)],
+    },
+    PhaseCode.A: {
+        PhaseCode.AN: [_path(Phase.A, Phase.A), add_neutral],
+        PhaseCode.XN: [_path(Phase.A, Phase.X), add_neutral],
+        PhaseCode.AB: [_path(Phase.A, Phase.A), _path(Phase.NONE, Phase.B)],
+        PhaseCode.XY: [_path(Phase.A, Phase.X), _path(Phase.NONE, Phase.Y)],
+        PhaseCode.A: [_path(Phase.A, Phase.A)],
+        PhaseCode.X: [_path(Phase.A, Phase.X)],
+        PhaseCode.ABN: [_path(Phase.A, Phase.A), _path(Phase.NONE, Phase.B), add_neutral],
+        PhaseCode.XYN: [_path(Phase.A, Phase.X), _path(Phase.NONE, Phase.Y), add_neutral],
+    },
+    PhaseCode.B: {
+        PhaseCode.BN: [_path(Phase.B, Phase.B), add_neutral],
+        PhaseCode.XN: [_path(Phase.B, Phase.X), add_neutral],
+        PhaseCode.BC: [_path(Phase.B, Phase.B), _path(Phase.NONE, Phase.C)],
+        PhaseCode.XY: [_path(Phase.B, Phase.X), _path(Phase.NONE, Phase.Y)],
+        PhaseCode.B: [_path(Phase.B, Phase.B)],
+        PhaseCode.X: [_path(Phase.B, Phase.X)],
+        PhaseCode.BCN: [_path(Phase.B, Phase.B), _path(Phase.NONE, Phase.C), add_neutral],
+        PhaseCode.XYN: [_path(Phase.B, Phase.X), _path(Phase.NONE, Phase.Y), add_neutral],
+    },
+    PhaseCode.C: {
+        PhaseCode.CN: [_path(Phase.C, Phase.C), add_neutral],
+        PhaseCode.XN: [_path(Phase.C, Phase.X), add_neutral],
+        PhaseCode.AC: [_path(Phase.C, Phase.C), _path(Phase.NONE, Phase.A)],
+        PhaseCode.XY: [_path(Phase.C, Phase.X), _path(Phase.NONE, Phase.Y)],
+        PhaseCode.C: [_path(Phase.C, Phase.C)],
+        PhaseCode.X: [_path(Phase.C, Phase.X)],
+        PhaseCode.ACN: [_path(Phase.C, Phase.C), _path(Phase.NONE, Phase.A), add_neutral],
+        PhaseCode.XYN: [_path(Phase.C, Phase.X), _path(Phase.NONE, Phase.Y), add_neutral],
+    },
+    PhaseCode.X: {
+        PhaseCode.AN: [_path(Phase.X, Phase.A), add_neutral],
+        PhaseCode.BN: [_path(Phase.X, Phase.B), add_neutral],
+        PhaseCode.CN: [_path(Phase.X, Phase.C), add_neutral],
+        PhaseCode.XN: [_path(Phase.X, Phase.X), add_neutral],
+        PhaseCode.AB: [_path(Phase.X, Phase.A), _path(Phase.NONE, Phase.B)],
+        PhaseCode.BC: [_path(Phase.X, Phase.B), _path(Phase.NONE, Phase.C)],
+        PhaseCode.AC: [_path(Phase.X, Phase.C), _path(Phase.NONE, Phase.A)],
+        PhaseCode.XY: [_path(Phase.X, Phase.X), _path(Phase.NONE, Phase.Y)],
+        PhaseCode.A: [_path(Phase.X, Phase.A)],
+        PhaseCode.B: [_path(Phase.X, Phase.B)],
+        PhaseCode.C: [_path(Phase.X, Phase.C)],
+        PhaseCode.X: [_path(Phase.X, Phase.X)],
+        PhaseCode.ABN: [_path(Phase.X, Phase.A), _path(Phase.NONE, Phase.B), add_neutral],
+        PhaseCode.BCN: [_path(Phase.X, Phase.B), _path(Phase.NONE, Phase.C), add_neutral],
+        PhaseCode.ACN: [_path(Phase.X, Phase.C), _path(Phase.NONE, Phase.A), add_neutral],
+        PhaseCode.XYN: [_path(Phase.X, Phase.X), _path(Phase.NONE, Phase.Y), add_neutral],
+    },
+}

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

@@ -0,0 +1,235 @@
+#  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__ = ["X_PRIORITY", "Y_PRIORITY", "XyCandidatePhasePaths", "is_before", "is_after"]
+
+from collections import Counter
+from itertools import takewhile
+from typing import List, Dict, Tuple, Optional, Counter as CounterType
+
+from zepben.ewb import SinglePhaseKind, PhaseCode
+from zepben.ewb.dataclassy import dataclass
+
+X_PRIORITY = [SinglePhaseKind.A, SinglePhaseKind.B, SinglePhaseKind.C]
+"""
+The pathing priority for nominal phase X
+ """
+
+Y_PRIORITY = [SinglePhaseKind.C, SinglePhaseKind.B]
+"""
+The pathing priority for nominal phase X
+ """
+
+
+def is_before(phase: SinglePhaseKind, before: Optional[SinglePhaseKind]) -> bool:
+    if (before is None) or (before == SinglePhaseKind.NONE):
+        return True
+    elif before == SinglePhaseKind.A:
+        return False
+    elif before == SinglePhaseKind.B:
+        return phase == SinglePhaseKind.A
+    elif before == SinglePhaseKind.C:
+        return (phase == SinglePhaseKind.A) or (phase == SinglePhaseKind.B)
+    else:
+        raise ValueError("INTERNAL ERROR: is_before should only ever be checking against valid Y phases. If you get this message you need to ask the dev "
+                         "team to go put the planets back into alignment as they stuffed something up!")
+
+
+def is_after(phase: SinglePhaseKind, after: Optional[SinglePhaseKind]) -> bool:
+    if (after is None) or (after == SinglePhaseKind.NONE):
+        return True
+    elif after == SinglePhaseKind.C:
+        return False
+    elif after == SinglePhaseKind.B:
+        return phase == SinglePhaseKind.C
+    elif after == SinglePhaseKind.A:
+        return (phase == SinglePhaseKind.C) or (phase == SinglePhaseKind.B)
+    else:
+        raise ValueError("INTERNAL ERROR: is_after should only ever be checking against valid X phases. If you get this message you need to ask the dev "
+                         "team to go put the planets back into alignment as they stuffed something up!")
+
+
+@dataclass(slots=True)
+class XyCandidatePhasePaths:
+    """
+    Used to track the candidate and know paths for XY phase connectivity.
+    """
+
+    _known_tracking: Dict[SinglePhaseKind, SinglePhaseKind] = {}
+    """
+    Map of nominal phase to known phase.
+    """
+
+    _candidate_tracking: Dict[SinglePhaseKind, List[SinglePhaseKind]] = {}
+    """
+    Map of nominal phase to list of candidate phases.
+    """
+
+    def add_known(self, xy_phase: SinglePhaseKind, known_phase: SinglePhaseKind):
+        """
+        Add a `known_phase` for the specified `xy_phase`. If there is already a `known_phase` the new value will be ignored.
+
+        `xy_phase` The phase that is being tracked.
+
+        `known_phase` The phase that should be allocated to the tracked phase.
+
+        Raises `NominalPhaseException` if the `xy_phase` is invalid.
+        """
+        _validate_for_tracking(xy_phase)
+        if xy_phase not in self._known_tracking:
+            self._known_tracking[xy_phase] = known_phase
+
+    def add_candidates(self, xy_phase: SinglePhaseKind, candidate_phases: List[SinglePhaseKind]):
+        """
+        Add `candidate_phases` for the specified `xy_phase`. If the same candidate has been found from more than
+        one path it should be added multiple times
+
+        `xy_phase` The phase that is being tracked.
+
+        `candidate_phases` The phases that could be allocated to the tracked phase.
+
+        Raises `NominalPhaseException` if the `xy_phase` is invalid.
+
+        Raises `PhaseException` if the `candidate_phases` is invalid.
+         """
+        _validate_for_tracking(xy_phase)
+        if xy_phase not in self._candidate_tracking:
+            self._candidate_tracking[xy_phase] = []
+
+        self._candidate_tracking[xy_phase].extend([it for it in candidate_phases if _is_valid_candidate(it, xy_phase)])
+
+    def calculate_paths(self) -> Dict[SinglePhaseKind, SinglePhaseKind]:
+        """
+        Calculate the paths for the tracked phases taking into account the following:
+        1. Known phases take preference.
+        2. X is always a "lower" phase than Y.
+        3. If multiple candidates are valid then the one with the most occurrences will be chosen.
+        4. If multiple candidates are valid and are equally common, the phases will be chosen with the following priority maintaining the above rules:
+           X: A, B then C
+           Y: C then B
+        """
+        paths = {}
+
+        known_x = self._known_tracking.get(SinglePhaseKind.X)
+        if known_x is not None:
+            paths[SinglePhaseKind.X] = known_x
+
+        known_y = self._known_tracking.get(SinglePhaseKind.Y)
+        if (known_y is not None) and (known_x != known_y):
+            paths[SinglePhaseKind.Y] = known_y
+        else:
+            known_y = None
+
+        if (known_x is not None) and (known_y is not None):
+            return paths
+
+        candidate_phase_counts = {xy: Counter(candidates) for xy, candidates in self._candidate_tracking.items()}
+        if known_x is not None:
+            candidates = candidate_phase_counts.get(SinglePhaseKind.Y)
+            if candidates:
+                paths[SinglePhaseKind.Y] = self._find_candidate(candidates, priority=Y_PRIORITY, after=known_x)
+            else:
+                paths[SinglePhaseKind.Y] = SinglePhaseKind.NONE
+        elif known_y is not None:
+            candidates = candidate_phase_counts.get(SinglePhaseKind.X)
+            if candidates:
+                paths[SinglePhaseKind.X] = self._find_candidate(candidates, priority=X_PRIORITY, before=known_y)
+            else:
+                paths[SinglePhaseKind.X] = SinglePhaseKind.NONE
+        else:
+            x_candidate, y_candidate = self._process_candidates(candidate_phase_counts)
+            paths[SinglePhaseKind.X] = x_candidate
+            paths[SinglePhaseKind.Y] = y_candidate
+
+        return paths
+
+    def _process_candidates(self, candidate_phase_counts: Dict[SinglePhaseKind, CounterType[SinglePhaseKind]]) -> Tuple[SinglePhaseKind, SinglePhaseKind]:
+        candidate_x_counts = candidate_phase_counts.get(SinglePhaseKind.X, Counter())
+        candidate_y_counts = candidate_phase_counts.get(SinglePhaseKind.Y, Counter())
+
+        if not candidate_x_counts:
+            return SinglePhaseKind.NONE, self._find_candidate(candidate_y_counts, priority=Y_PRIORITY)
+        elif len(candidate_x_counts) == 1:
+            x_candidate = list(candidate_x_counts.keys())[0]
+            return x_candidate, self._find_candidate(candidate_y_counts, priority=Y_PRIORITY, after=x_candidate)
+        elif not candidate_y_counts:
+            return self._find_candidate(candidate_x_counts, priority=X_PRIORITY), SinglePhaseKind.NONE
+        elif len(candidate_y_counts) == 1:
+            y_candidate = list(candidate_y_counts.keys())[0]
+            return self._find_candidate(candidate_x_counts, priority=X_PRIORITY, before=y_candidate), y_candidate
+        else:
+            x_candidate = self._find_candidate(candidate_x_counts, priority=X_PRIORITY)
+            y_candidate = self._find_candidate(candidate_y_counts, priority=Y_PRIORITY)
+
+            if is_before(x_candidate, y_candidate):
+                return x_candidate, y_candidate
+            elif candidate_x_counts[x_candidate] > candidate_y_counts[y_candidate]:
+                return x_candidate, self._find_candidate(candidate_y_counts, priority=Y_PRIORITY, after=x_candidate)
+            elif candidate_y_counts[y_candidate] > candidate_x_counts[x_candidate]:
+                return self._find_candidate(candidate_x_counts, priority=X_PRIORITY, before=y_candidate), y_candidate
+            else:
+                x_candidate2 = self._find_candidate(candidate_x_counts, priority=X_PRIORITY, before=y_candidate)
+                y_candidate2 = self._find_candidate(candidate_y_counts, priority=Y_PRIORITY, after=x_candidate)
+
+                if x_candidate2 == SinglePhaseKind.NONE:
+                    return x_candidate, y_candidate2
+                elif y_candidate2 == SinglePhaseKind.NONE:
+                    return x_candidate2, y_candidate
+                elif candidate_x_counts[x_candidate2] > candidate_y_counts[y_candidate2]:
+                    return x_candidate2, y_candidate
+                elif candidate_y_counts[y_candidate2] > candidate_x_counts[x_candidate2]:
+                    return x_candidate, y_candidate2
+                else:
+                    return x_candidate, y_candidate2
+
+    @staticmethod
+    def _find_candidate(
+        candidate_counts: CounterType[SinglePhaseKind],
+        priority: List[SinglePhaseKind],
+        before: Optional[SinglePhaseKind] = None,
+        after: Optional[SinglePhaseKind] = None
+    ) -> SinglePhaseKind:
+        valid_candidates = [(phase, count) for (phase, count) in candidate_counts.most_common() if is_before(phase, before) and is_after(phase, after)]
+        if not valid_candidates:
+            return SinglePhaseKind.NONE
+        elif len(valid_candidates) == 1:
+            return valid_candidates[0][0]
+
+        candidates = list(takewhile(lambda cand: cand[1] == valid_candidates[0][1], valid_candidates))
+        if len(candidates) == 1:
+            return candidates[0][0]
+
+        for phase in priority:
+            for candidate, _ in candidates:
+                if candidate == phase:
+                    return candidate
+
+        raise ValueError("INTERNAL ERROR: If you get here it means you did not limit the candidates to only valid phases, go fix that!")
+
+
+def _validate_for_tracking(phase: SinglePhaseKind):
+    if phase not in PhaseCode.XY:
+        raise ValueError(f"Unable to track phase {phase}, expected X or Y.")
+
+
+def _is_valid_candidate(phase: SinglePhaseKind, xy_phase: SinglePhaseKind) -> bool:
+    if xy_phase == SinglePhaseKind.X:
+        return _is_valid_candidate_x(phase)
+    else:
+        return _is_valid_candidate_y(phase)
+
+
+def _is_valid_candidate_x(phase: SinglePhaseKind) -> bool:
+    if phase in PhaseCode.ABC:
+        return True
+    else:
+        raise ValueError(f"Unable to use phase {phase} as a candidate, expected A, B or C.")
+
+
+def _is_valid_candidate_y(phase: SinglePhaseKind) -> bool:
+    if phase in PhaseCode.BC:
+        return True
+    else:
+        raise ValueError(f"Unable to use phase {phase} as a candidate, expected B or C.")

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

@@ -0,0 +1,24 @@
+#  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__ = ["XyPhaseStep"]
+
+from zepben.ewb.dataclassy import dataclass
+
+from zepben.ewb import Terminal, PhaseCode
+
+
+@dataclass(slots=True)
+class XyPhaseStep(object):
+
+    terminal: Terminal
+    """
+    The incoming terminal
+    """
+
+    phase_code: PhaseCode
+    """
+    The phases used to get to this step (should only be, XY, X or Y)
+    """

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

@@ -0,0 +1,202 @@
+#  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__ = ["AssignToFeeders", "BaseFeedersInternal"]
+
+from collections.abc import Collection
+from logging import Logger
+from typing import Iterable, Union, List, Dict, Any, Set, Type, Generator, TYPE_CHECKING
+
+from zepben.ewb import Switch, ProtectedSwitch, PowerElectronicsConnection
+from zepben.ewb.model.cim.iec61970.base.core.feeder import Feeder
+from zepben.ewb.model.cim.iec61970.base.wires.power_transformer import PowerTransformer
+from zepben.ewb.services.network.network_service import NetworkService
+from zepben.ewb.services.network.tracing.networktrace.conditions.conditions import stop_at_open
+from zepben.ewb.services.network.tracing.networktrace.network_trace import NetworkTrace
+from zepben.ewb.services.network.tracing.networktrace.network_trace_action_type import NetworkTraceActionType
+from zepben.ewb.services.network.tracing.networktrace.network_trace_step import NetworkTraceStep
+from zepben.ewb.services.network.tracing.networktrace.operators.network_state_operators import NetworkStateOperators
+from zepben.ewb.services.network.tracing.networktrace.tracing import Tracing
+from zepben.ewb.services.network.tracing.traversal.step_context import StepContext
+
+if TYPE_CHECKING:
+    from zepben.ewb import AuxiliaryEquipment, Equipment, LvFeeder, ConductingEquipment, EquipmentContainer, Terminal
+
+
+class AssignToFeeders:
+    """
+    Convenience class that provides methods for assigning HV/MV feeders on a `NetworkService`.
+    Requires that a Feeder have a normalHeadTerminal with associated ConductingEquipment.
+    This class is backed by a `NetworkTrace`.
+    """
+
+    def __init__(self, debug_logger: Logger = None):
+        self._debug_logger = debug_logger
+
+    async def run(
+        self,
+        network: NetworkService,
+        network_state_operators: Type[NetworkStateOperators] = NetworkStateOperators.NORMAL,
+        start_terminal: Terminal = None
+    ):
+        """
+        Assign equipment to feeders in the specified network, given an optional start terminal.
+
+        :param network: The [NetworkService] to process.
+        :param network_state_operators: operator interfaces relating to the network state we are operating on
+        :param start_terminal: An optional [Terminal] to start from:
+        * When a start terminal is provided, the trace will assign all feeders associated with the terminals equipment to all connected equipment.
+        * If no start terminal is provided, all feeder head terminals in the network will be used instead, assigning their associated feeder.
+        """
+
+        await AssignToFeedersInternal(
+            network_state_operators,
+            self._debug_logger
+        ).run(network, start_terminal)
+
+
+class BaseFeedersInternal:
+    def __init__(self, network_state_operators: Type[NetworkStateOperators] = NetworkStateOperators.NORMAL, debug_logger: Logger = None):
+        self.network_state_operators = network_state_operators
+        self._debug_logger = debug_logger
+
+    def _feeders_from_terminal(self, terminal: Terminal) -> Generator[Feeder, None, None]:
+        return terminal.conducting_equipment.feeders(self.network_state_operators)
+
+    def _associate_equipment_with_containers(self, equipment_containers: Iterable[EquipmentContainer], equipment: Iterable[Equipment]):
+        for feeder in equipment_containers:
+            for it in equipment:
+                #todo remove this and fix the test that is using PatchedNetworkTraceStepPath (removing it). Error is that the feeder test doesn't have a head
+                # equipment, and the trace validation throws an error.
+                if it is not None:
+                    self.network_state_operators.associate_equipment_and_container(it, feeder)
+
+    def _associate_relay_systems_with_containers(self, equipment_containers: Iterable[EquipmentContainer], to_equipment: ProtectedSwitch):
+        self._associate_equipment_with_containers(
+            equipment_containers,
+            [scheme.system for relayFunction in to_equipment.relay_functions for scheme in relayFunction.schemes if scheme.system is not None]
+        )
+
+    def _associate_power_electronic_units(self, equipment_containers: Iterable[EquipmentContainer], to_equipment: PowerElectronicsConnection):
+        self._associate_equipment_with_containers(equipment_containers, to_equipment.units)
+
+    def _feeder_energizes(self, feeders: Iterable[Union[LvFeeder, Feeder]], lv_feeders: Iterable[LvFeeder]):
+        for feeder in feeders:
+            for lv_feeder in lv_feeders:
+                self.network_state_operators.associate_energizing_feeder(feeder, lv_feeder)
+
+    def _feeder_try_energize_lv_feeders(self, feeders: Iterable[Feeder], lv_feeder_start_points: Set[ConductingEquipment], to_equipment: PowerTransformer):
+
+        lv_feeders = []
+        if len(sites := list(to_equipment.sites)) > 0:
+            for s in sites:
+                lv_feeders.extend(lv_f for lv_f in s.find_lv_feeders(lv_feeder_start_points, self.network_state_operators))
+        else:
+            for eq in to_equipment:
+                lv_feeders.extend(eq.lv_feeders(self.network_state_operators))
+
+        self._feeder_energizes(feeders, lv_feeders)
+
+
+class AssignToFeedersInternal(BaseFeedersInternal):
+
+    async def run(
+        self,
+        network: NetworkService,
+        start_terminal: Terminal = None
+    ):
+        feeder_start_points = network.feeder_start_points
+        lv_feeder_start_points = network.lv_feeder_start_points
+        terminal_to_aux_equipment = network.aux_equipment_by_terminal
+
+        if start_terminal is None:
+            for it in list(it for it in network.objects(Feeder)):
+                await self.run_with_feeders(it.normal_head_terminal,
+                                            feeder_start_points,
+                                            lv_feeder_start_points,
+                                            terminal_to_aux_equipment,
+                                            [it])
+
+        else:
+            await self.run_with_feeders(start_terminal,
+                                        feeder_start_points,
+                                        lv_feeder_start_points,
+                                        terminal_to_aux_equipment,
+                                        list(self._feeders_from_terminal(start_terminal)))
+
+    async def run_with_feeders(self,
+                               terminal: Terminal,
+                               feeder_start_points: Set[ConductingEquipment],
+                               lv_feeder_start_points: Set[ConductingEquipment],
+                               terminal_to_aux_equipment: Dict[Terminal, List[AuxiliaryEquipment]],
+                               feeders_to_assign: List[Feeder]):
+
+        if terminal is None or len(feeders_to_assign) == 0:
+            return
+
+        if isinstance(start_ce := terminal.conducting_equipment, Switch) and self.network_state_operators.is_open(start_ce):
+            self._associate_equipment_with_containers(feeders_to_assign, [start_ce])
+        else:
+            traversal = await self._create_trace(terminal_to_aux_equipment, feeder_start_points, lv_feeder_start_points, feeders_to_assign)
+            await traversal.run(terminal, False, can_stop_on_start_item=False)
+
+    async def _create_trace(self,
+                            terminal_to_aux_equipment: Dict[Terminal, List[AuxiliaryEquipment]],
+                            feeder_start_points: Set[ConductingEquipment],
+                            lv_feeder_start_points: Set[ConductingEquipment],
+                            feeders_to_assign: List[Feeder]
+                            ) -> NetworkTrace[Any]:
+
+        def _reached_lv(ce: ConductingEquipment):
+            return True if ce.base_voltage and ce.base_voltage.nominal_voltage < 1000 else False
+
+        def _reached_substation_transformer(ce: ConductingEquipment):
+            return True if isinstance(ce, PowerTransformer) and len(list(ce.substations)) > 0 else False
+
+        async def step_action(nts: NetworkTraceStep, context: StepContext):
+            await self._process(nts.path, context, terminal_to_aux_equipment, lv_feeder_start_points, feeders_to_assign)
+
+        return (
+            Tracing.network_trace(
+                network_state_operators=self.network_state_operators,
+                action_step_type=NetworkTraceActionType.ALL_STEPS,
+                debug_logger=self._debug_logger,
+                name=f'AssignToFeeders({self.network_state_operators.description})'
+            )
+            .add_condition(stop_at_open())
+            .add_stop_condition(
+                lambda step, ctx: step.path.to_equipment in feeder_start_points
+            )
+            .add_queue_condition(
+                lambda step, ctx, x, y: not _reached_substation_transformer(step.path.to_equipment)
+            )
+            .add_queue_condition(
+                lambda step, ctx, x, y: not _reached_lv(step.path.to_equipment)
+            )
+            .add_step_action(step_action)
+        )
+
+    async def _process(self,
+                       step_path: NetworkTraceStep.Path,
+                       step_context: StepContext,
+                       terminal_to_aux_equipment: Dict[Terminal, Collection[AuxiliaryEquipment]],
+                       lv_feeder_start_points: Set[ConductingEquipment],
+                       feeders_to_assign: List[Feeder]):
+
+        if step_path.traced_internally and not step_context.is_start_item:
+            return
+
+        self._associate_equipment_with_containers(feeders_to_assign, terminal_to_aux_equipment.get(step_path.to_terminal, {}))
+        self._associate_equipment_with_containers(feeders_to_assign, [step_path.to_equipment])
+
+        to_equip = step_path.to_equipment
+        if isinstance(to_equip, PowerTransformer):
+            self._feeder_try_energize_lv_feeders(feeders_to_assign, lv_feeder_start_points, to_equip)
+        elif isinstance(to_equip, ProtectedSwitch):
+            self._associate_relay_systems_with_containers(feeders_to_assign, to_equip)
+        elif isinstance(to_equip, PowerElectronicsConnection):
+            self._associate_power_electronic_units(feeders_to_assign, to_equip)