DEV-2963 Update Python SDK

changelog.md

@@ -9,9 +9,23 @@
   and reapply directions where appropriate using `SetDirection`.
 * `Cut` supports adding a maximum of 2 terminals.
 * `NetworkTraceTracker` now uses a `set` to track visited objects, if you were using unhashable objects this will need to be addressed.
+* Added a new `debug_logging` and `name` parameters to the constructor of the following traces. The helper functions in `Tracing` also have these parameters,
+  which defaults to `None` and `network_trace`, meaning anyone using these wrappers will be unaffected by the change:
+  * `AssignToFeeders`
+  * `AssignToLvFeeders`
+  * `ClearDirection`
+  * `FindSwerEquipment`
+  * `PhaseInferrer`
+  * `RemovePhases`
+  * `SetDirection`
+  * `SetPhases`
+* `NetworkStateOperators` has a new abstract `description`. If you are creating custom operators you will need to add it.
+* `StepAction` will now raise an exception if `apply` is overridden. override `_apply` instead, or pass the function to `__init__`
 
 ### New Features
 * Added `ClearDirection` that clears feeder directions.
+* You can now pass a logger to all `Tracing` methods and `TestNetworkBuilder.build` to enable debug logging for the traces it runs. The debug logging will
+  include the results of all queue and stop condition checks, and each item that is stepped on.
 
 ### Enhancements
 * Tracing models with `Cut` and `Clamp` are now supported via the new tracing API.
@@ -24,6 +38,9 @@
   * The prefix for generated mRIDs for "other" equipment can be specified with the `default_mrid_prefix` argument in `from_other` and `to_other`.
 * When processing feeder assignments, all LV feeders belonging to a dist substation site will now be considered energized when the site is energized by a
   feeder.
+* `NetworkTrace` now supports starting from a known `NetworkTraceStep.Path`. This allows you to force a trace to start in a particular direction, or to continue
+  a follow-up trace from a detected stop point.
+* `Traversal.is_stopping`/`Traversal.is_not_stopping` now accept `StepAction` and any child classes, including those subclassing `StepActionWithContextValue`
 
 ### Fixes
 * When finding `LvFeeders` in the `Site` we will now exclude `LvFeeders` that start with an open `Switch`
@@ -38,6 +55,8 @@
 * `NetworkTrace`/`Traversal` now correctly respects `can_stop_on_start_item` when providing multiple start items.
 * `AssignToFeeders`/`AssignToLvFeeders` now finds back-fed equipment correctly
 * `AssignToFeeders` and `AssignToLvFeeders` will now associate `PowerElectronicUnits` with their `powerElectronicsConnection` `Feeder`/`LvFeeder`.
+* Phases are now correctly assigned to the LV side of an LV2 transformer that is in parallel with a previously energised LV1 transformer.
+
 
 ### Notes
 * None.

src/zepben/evolve/__init__.py

@@ -156,6 +156,7 @@
 from zepben.evolve.services.network.translator.network_cim2proto import *
 from zepben.evolve.services.network.network_service import *
 
+from zepben.evolve.services.network.tracing.networktrace.network_trace_step import *
 from zepben.evolve.services.network.tracing.connectivity.connectivity_result import *
 from zepben.evolve.services.network.tracing.connectivity.nominal_phase_path import *
 from zepben.evolve.services.network.tracing.connectivity.phase_paths import *
@@ -204,6 +205,8 @@
 from zepben.evolve.services.network.tracing.traversal.traversal_condition import *
 from zepben.evolve.services.network.tracing.traversal.weighted_priority_queue import *
 
+from zepben.evolve.services.network.tracing.traversal.debug_logging import DebugLoggingWrapper
+
 from zepben.evolve.services.network.tracing.find_swer_equipment import *
 
 from zepben.evolve.services.common.meta.data_source import *
@@ -450,8 +453,6 @@
 from zepben.evolve.database.sqlite.network.network_database_reader import *
 from zepben.evolve.database.sqlite.network.network_service_reader import *
 
-from zepben.evolve.services.network.tracing.phases.set_phases import *
-
 from zepben.evolve.testing.test_network_builder import *
 
 # @formatter:on

src/zepben/evolve/model/busbranch/bus_branch.py

@@ -2,13 +2,15 @@
 #  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
+
 import abc
 from collections import Counter
 from dataclasses import dataclass, field
 from functools import reduce
-from typing import Set, Tuple, FrozenSet, Dict, Callable, Union, TypeVar, Any, List, Generic, Optional, Iterable
+from typing import Set, Tuple, FrozenSet, Dict, Callable, Union, TypeVar, Any, List, Generic, Optional, Iterable, TYPE_CHECKING
 
-from zepben.evolve import Junction, BusbarSection, EquivalentBranch, Traversal, StepContext
+from zepben.evolve import Junction, BusbarSection, EquivalentBranch, Traversal
 from zepben.evolve.model.cim.iec61970.base.core.conducting_equipment import ConductingEquipment
 from zepben.evolve.model.cim.iec61970.base.core.terminal import Terminal
 from zepben.evolve.model.cim.iec61970.base.wires.aclinesegment import AcLineSegment
@@ -20,6 +22,9 @@
 from zepben.evolve.services.network.network_service import NetworkService
 from zepben.evolve.services.network.tracing.busbranch_trace import BusBranchTrace, BusBranchTraceStep
 
+if TYPE_CHECKING:
+    from zepben.evolve import StepContext
+
 __all__ = [
     "BusBranchNetworkCreationValidator",
     "BusBranchNetworkCreator",
@@ -28,7 +33,6 @@
     "TerminalGrouping"
 ]
 
-
 BBN = TypeVar('BBN')  # Bus-Branch Network
 TN = TypeVar('TN')  # Topological Node
 TB = TypeVar('TB')  # Topological Branch
@@ -911,9 +915,11 @@ async def _group_negligible_impedance_terminals(
     await trace.run()
     return tg
 
+
 def _create_traversal_step_object(next_item: Union[Terminal, AcLineSegment]) -> BusBranchTraceStep:
     return BusBranchTraceStep(next_item)
 
+
 def _process_terminal(
     tg: TerminalGrouping[ConductingEquipment],
     has_negligible_impedance: Callable[[ConductingEquipment], bool]
@@ -1015,9 +1021,9 @@ def _next_common_acls(
 
     def can_process_ac_line(o: Terminal) -> bool:
         return o not in acls_terminals \
-               and isinstance(o.conducting_equipment, AcLineSegment) \
-               and has_common_impedance(o.conducting_equipment) \
-               and o.conducting_equipment not in common_acls.conducting_equipment_group
+            and isinstance(o.conducting_equipment, AcLineSegment) \
+            and has_common_impedance(o.conducting_equipment) \
+            and o.conducting_equipment not in common_acls.conducting_equipment_group
 
     def is_non_forking_ac_line(t: Terminal) -> bool:
         return t.connectivity_node is not None and len(list(t.connectivity_node.terminals)) == 2

src/zepben/evolve/services/network/tracing/connectivity/transformer_phase_paths.py

@@ -6,7 +6,7 @@
 
 from zepben.evolve import SinglePhaseKind as Phase, NominalPhasePath, PhaseCode
 
-__all__ = ["transformer_phase_paths"]
+__all__ = ["transformer_phase_paths", "add_neutral"]
 
 
 def _path(from_phase: Phase, to_phase: Phase) -> NominalPhasePath:
@@ -15,7 +15,7 @@ def _path(from_phase: Phase, to_phase: Phase) -> NominalPhasePath:
 
 
 # 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)
+add_neutral = _path(Phase.NONE, Phase.N)
 
 transformer_phase_paths: Dict[PhaseCode, Dict[PhaseCode, List[NominalPhasePath]]] = {
     PhaseCode.ABCN: {
@@ -61,7 +61,7 @@ def _path(from_phase: Phase, to_phase: Phase) -> NominalPhasePath:
         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.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: {
@@ -103,44 +103,44 @@ def _path(from_phase: Phase, to_phase: Phase) -> NominalPhasePath:
         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.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.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.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.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)],
@@ -151,40 +151,40 @@ def _path(from_phase: Phase, to_phase: Phase) -> NominalPhasePath:
         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.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.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.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.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.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.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.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)],
@@ -193,9 +193,9 @@ def _path(from_phase: Phase, to_phase: Phase) -> NominalPhasePath:
         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],
+        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],
     },
 }