zepben.ewb 1.0.0b1__py3-none-any.whl

zepben/ewb/model/cim/extensions/iec61970/base/protection/voltage_relay.py

@@ -0,0 +1,20 @@
+#  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__ = ["VoltageRelay"]
+
+from zepben.ewb.model.cim.extensions.iec61970.base.protection.protection_relay_function import ProtectionRelayFunction
+
+from zepben.ewb.model.cim.extensions.zbex import zbex
+
+
+@zbex
+class VoltageRelay(ProtectionRelayFunction):
+    """
+    [ZBEX]
+    A device that detects when the voltage in an AC circuit reaches a preset voltage. There are two basic types of voltage relay operation: overvoltage
+    relay for overvoltage detection and undervoltage relay for undervoltage detection.
+    """
+    pass

zepben/ewb/model/cim/extensions/iec61970/base/wires/__init__.py

@@ -0,0 +1,4 @@
+#  Copyright 2024 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.

zepben/ewb/model/cim/extensions/iec61970/base/wires/battery_control.py

@@ -0,0 +1,36 @@
+#  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__ = ["BatteryControl"]
+
+from typing import Optional
+
+from zepben.ewb.model.cim.extensions.iec61970.base.wires.battery_control_mode import BatteryControlMode
+from zepben.ewb.model.cim.extensions.zbex import zbex
+from zepben.ewb.model.cim.iec61970.base.wires.regulating_control import RegulatingControl
+
+
+@zbex
+class BatteryControl(RegulatingControl):
+    """
+    [ZBEX]
+    Describes behaviour specific to controlling batteries.
+    """
+
+    charging_rate: Optional[float] = None
+    """[ZBEX] Charging rate (input power) in percentage of maxP. (Unit: PerCent)"""
+
+    discharging_rate: Optional[float] = None
+    """[ZBEX] Discharge rate (output power) in percentage of maxP. (Unit: PerCent)"""
+
+    reserve_percent: Optional[float] = None
+    """
+    [ZBEX] 
+    Percentage of the rated storage capacity that should be reserved during normal operations. This reserve acts as a safeguard, preventing the energy level 
+    from dropping below this threshold under standard conditions. The field must be set to a non-negative value between 0 and 1. (Unit: PerCent)
+    """
+
+    control_mode: BatteryControlMode = BatteryControlMode.UNKNOWN
+    """[ZBEX] Mode of operation for the dispatch (charging/discharging) function of BatteryControl."""

zepben/ewb/model/cim/extensions/iec61970/base/wires/battery_control_mode.py

@@ -0,0 +1,82 @@
+#  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__ = ["BatteryControlMode"]
+
+from enum import Enum, unique
+
+from zepben.ewb.model.cim.extensions.zbex import zbex
+
+
+@zbex
+@unique
+class BatteryControlMode(Enum):
+    """
+    [ZBEX]
+    Mode of operation for the dispatch (charging/discharging) function of BatteryControl.
+    """
+
+    UNKNOWN = 0
+    """[ZBEX] Unknown control mode."""
+
+    peakShaveDischarge = 1
+    """
+    [ZBEX]
+    This mode directs the BatteryUnit to discharge as needed to maintain the power level of the monitored element within a defined range
+    (specified by target_deadband) or to keep it at or below the value specified by max_allowed_target_value. This mode helps prevent power spikes by 
+    discharging the BatteryUnit to manage peak demand effectively.
+    """
+
+    currentPeakShaveDischarge = 2
+    """
+    [ZBEX]
+    This mode directs the BatteryUnit to discharge as needed to maintain the current (in amps) at a monitored element below a specified target. Similar
+    to peakShaveDischarge, this mode aims to reduce demand peaks, focusing specifically on current levels to manage capacity and enhance system stability where
+    current control is essential.
+    """
+
+    following = 3
+    """[ZBEX] The control is triggered by time and resets the targetValue property to the present monitored element power."""
+
+    support = 4
+    """[ZBEX] 
+    This is essentially the opposite of peakShave modes. The fleet is dispatched to keep the power in the monitored terminal at or above target_value.
+    """
+
+    schedule = 5
+    """
+    [ZBEX]
+    In Schedule mode, a trapezoidal-shaped discharge schedule is specified through Tup (up ramp duration), TFlat (at duration),
+    and Tdn (down ramp duration) properties.
+    """
+
+    peakShaveCharge = 6
+    """
+    [ZBEX]
+    This mode directs the BatteryUnit to initiate charging when the power level at a monitored element falls below a specified threshold 
+    (min_allowed_target_value). This mode supports demand leveling by charging the BatteryUnit during low-demand periods, optimizing overall power management.
+    """
+
+    currentPeakShaveCharge = 7
+    """
+    [ZBEX]
+    This mode initiates charging when the current (in Amps) at a monitored element falls below a specified threshold (min_allowed_target_value).
+    Similar to peakShaveCharge, this mode aims to manage demand effectively, but it operates based on current levels rather than power, providing finer
+    control in systems where current management is prioritized.
+    """
+
+    time = 8
+    """
+    [ZBEX] 
+    In Time mode all storage elements are set to discharge when in the course of simulation the time of day passes the specified hour of day by the
+    TimeDisChargeTrigger property (hour is a decimal value, e.g., 10.5 = 1030)
+    """
+
+    profile = 9
+    """[ZBEX] In this mode both discharging and charging precisely follow a per-unit curve."""
+
+    @property
+    def short_name(self):
+        return str(self)[19:]

zepben/ewb/model/cim/extensions/iec61970/base/wires/transformer_cooling_type.py

@@ -0,0 +1,56 @@
+#  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__ = ["TransformerCoolingType"]
+
+from enum import Enum, unique
+
+from zepben.ewb.model.cim.extensions.zbex import zbex
+
+
+@zbex
+@unique
+class TransformerCoolingType(Enum):
+    """
+    [ZBEX]
+    Transformer cooling types.
+    """
+
+    UNKNOWN = 0
+    """[ZBEX] Default"""
+
+    ONAN = 1
+    """[ZBEX] Oil natural, air natural"""
+
+    ONAF = 2
+    """[ZBEX] Oil natural, air forced"""
+
+    OFAF = 3
+    """[ZBEX] Oil forced, air forced"""
+
+    OFWF = 4
+    """[ZBEX] Oil forced, water forced"""
+
+    ODAF = 5
+    """[ZBEX] Oil directed, air forced"""
+
+    KNAN = 6
+    """[ZBEX] Non-mineral oil natural, air natural"""
+
+    KNAF = 7
+    """[ZBEX] Non-mineral oil natural, air forced"""
+
+    KFAF = 8
+    """[ZBEX] Non-mineral oil forced, air forced"""
+
+    KFWF = 9
+    """[ZBEX] Non-mineral oil forced, water forced"""
+
+    KDAF = 10
+    """[ZBEX] Non-mineral oil directed, air forced"""
+
+    @property
+    def short_name(self):
+        return str(self)[23:]

zepben/ewb/model/cim/extensions/iec61970/base/wires/transformer_end_rated_s.py

@@ -0,0 +1,26 @@
+#  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__ = ["TransformerEndRatedS"]
+
+from dataclasses import dataclass
+
+from zepben.ewb.model.cim.extensions.iec61970.base.wires.transformer_cooling_type import TransformerCoolingType
+from zepben.ewb.model.cim.extensions.zbex import zbex
+
+
+@zbex
+@dataclass(frozen=True)
+class TransformerEndRatedS:
+    """
+    [ZBEX]
+    Normal apparent power rating for a PowerTransformerEnd based on their cooling types.
+    """
+
+    cooling_type: TransformerCoolingType
+    """[ZBEX] The cooling type for this rating."""
+
+    rated_s: int
+    """[ZBEX] The normal apparent power rating for this cooling type."""

zepben/ewb/model/cim/extensions/iec61970/base/wires/vector_group.py

@@ -0,0 +1,292 @@
+#  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__ = ["VectorGroup"]
+
+from enum import Enum, unique
+
+from zepben.ewb.model.cim.extensions.zbex import zbex
+
+
+@zbex
+@unique
+class VectorGroup(Enum):
+    """
+    [ZBEX]
+    Vector group of the transformer for protective relaying, e.g., Dyn1. For unbalanced transformers, this may not be
+    simply determined from the constituent winding connections and phase angle displacements.
+
+    The vectorGroup string consists of the following components in the order listed: high voltage winding connection,
+    mid voltage winding connection (for three winding transformers), phase displacement clock number from 0 to 11, low
+    voltage winding connection phase displacement clock number from 0 to 11.
+
+    The winding connections are D (delta), Y (wye), YN (wye with neutral), Z (zigzag), ZN (zigzag with neutral),
+    A (auto transformer). Upper case means the high voltage, lower case mid or low. The high voltage winding always has
+    clock position 0 and is not included in the vector group string.
+
+    Some examples:
+                   YNy0 (two winding wye to wye with no phase displacement),
+                   YNd11 (two winding wye to delta with 330 degrees phase displacement),
+                   YNyn0d5 (three winding transformer wye with neutral high voltage, wye with neutral mid
+                            voltage and no phase displacement, delta low voltage with 150 degrees displacement).
+
+    Phase displacement is defined as the angular difference between the phasors representing the voltages between the
+    neutral point (real or imaginary) and the corresponding terminals of two windings, a positive sequence voltage system
+    being applied to the high-voltage terminals, following each other in alphabetical sequence if they are lettered, or
+    in numerical sequence if they are numbered: the phasors are assumed to rotate in a counter-clockwise sense.
+    """
+
+    UNKNOWN = 0
+    """"[ZBEX] UNKNOWN."""
+
+    DD0 = 1
+    """[ZBEX] Dd0."""
+
+    DZ0 = 2
+    """[ZBEX] Dz0."""
+
+    DZN0 = 3
+    """[ZBEX] Dzn0."""
+
+    YNY0 = 4
+    """[ZBEX] YNy0."""
+
+    YNYN0 = 5
+    """[ZBEX] YNyn0."""
+
+    YY0 = 6
+    """[ZBEX] Yy0."""
+
+    YYN0 = 7
+    """[ZBEX] Yyn0."""
+
+    ZD0 = 8
+    """[ZBEX] Zd0."""
+
+    ZND0 = 9
+    """[ZBEX] ZNd0."""
+
+    DYN1 = 10
+    """[ZBEX] Dyn1."""
+
+    DZ1 = 11
+    """[ZBEX] Dz1."""
+
+    DZN1 = 12
+    """[ZBEX] Dzn1."""
+
+    YD1 = 13
+    """[ZBEX] Yd1."""
+
+    YND1 = 14
+    """[ZBEX] YNd1."""
+
+    YNZN1 = 15
+    """[ZBEX] YNzn1."""
+
+    YZ1 = 16
+    """[ZBEX] Yz1."""
+
+    YZN1 = 17
+    """[ZBEX] Yzn1."""
+
+    ZD1 = 18
+    """[ZBEX] Zd1."""
+
+    ZND1 = 19
+    """[ZBEX] ZNd1."""
+
+    ZNYN1 = 20
+    """[ZBEX] ZNyn1."""
+
+    ZY1 = 21
+    """[ZBEX] Zy1."""
+
+    ZYN1 = 22
+    """[ZBEX] Zyn1."""
+
+    DY5 = 23
+    """[ZBEX] Dy5."""
+
+    DYN5 = 24
+    """[ZBEX] Dyn5."""
+
+    YD5 = 25
+    """[ZBEX] Yd5."""
+
+    YND5 = 26
+    """[ZBEX] YNd5."""
+
+    YNZ5 = 27
+    """[ZBEX] YNz5."""
+
+    YNZN5 = 28
+    """[ZBEX] YNzn5."""
+
+    YZ5 = 29
+    """[ZBEX] Yz5."""
+
+    YZN5 = 30
+    """[ZBEX] Yzn5."""
+
+    ZNY5 = 31
+    """[ZBEX] ZNy5."""
+
+    ZNYN5 = 32
+    """[ZBEX] ZNyn5."""
+
+    ZY5 = 33
+    """[ZBEX] Zy5."""
+
+    ZYN5 = 34
+    """[ZBEX] Zyn5."""
+
+    DD6 = 35
+    """[ZBEX] Dd6."""
+
+    DZ6 = 36
+    """[ZBEX] Dz6."""
+
+    DZN6 = 37
+    """[ZBEX] Dzn6."""
+
+    YNY6 = 38
+    """[ZBEX] YNy6."""
+
+    YNYN6 = 39
+    """[ZBEX] YNyn6."""
+
+    YY6 = 40
+    """[ZBEX] Yy6."""
+
+    YYN6 = 41
+    """[ZBEX] Yyn6."""
+
+    ZD6 = 42
+    """[ZBEX] Zd6."""
+
+    ZND6 = 43
+    """[ZBEX] ZNd6."""
+
+    DY7 = 44
+    """[ZBEX] Dy7."""
+
+    DYN7 = 45
+    """[ZBEX] Dyn7."""
+
+    DZ7 = 46
+    """[ZBEX] Dz7."""
+
+    DZN7 = 47
+    """[ZBEX] Dzn7."""
+
+    YD7 = 48
+    """[ZBEX] Yd7."""
+
+    YND7 = 49
+    """[ZBEX] YNd7."""
+
+    YNZN7 = 50
+    """[ZBEX] YNzn7."""
+
+    YZ7 = 51
+    """[ZBEX] Yz7."""
+
+    YZN7 = 52
+    """[ZBEX] Yzn7."""
+
+    ZD7 = 53
+    """[ZBEX] Zd7."""
+
+    ZND7 = 54
+    """[ZBEX] ZNd7."""
+
+    ZNYN7 = 55
+    """[ZBEX] ZNyn7."""
+
+    ZY7 = 56
+    """[ZBEX] Zy7."""
+
+    ZYN7 = 57
+    """[ZBEX] Zyn7."""
+
+    DY11 = 58
+    """[ZBEX] Dy11."""
+
+    DYN11 = 59
+    """[ZBEX] Dyn11."""
+
+    YD11 = 60
+    """[ZBEX] Yd11."""
+
+    YND11 = 61
+    """[ZBEX] YNd11."""
+
+    YNZ11 = 62
+    """[ZBEX] YNz11."""
+
+    YNZN11 = 63
+    """[ZBEX] YNzn11."""
+
+    YZ11 = 64
+    """[ZBEX] Yz11."""
+
+    YZN11 = 65
+    """[ZBEX] Yzn11."""
+
+    ZNY11 = 66
+    """[ZBEX] ZNy11."""
+
+    ZNYN11 = 67
+    """[ZBEX] ZNyn11."""
+
+    ZY11 = 68
+    """[ZBEX] Zy11."""
+
+    ZYN11 = 69
+    """[ZBEX] Zyn11."""
+
+    DY1 = 70
+    """[ZBEX] Dy1."""
+
+    Y0 = 71
+    """[ZBEX] Y0."""
+
+    YN0 = 72
+    """[ZBEX] YN0."""
+
+    D0 = 73
+    """[ZBEX] D0."""
+
+    ZNY1 = 74
+    """[ZBEX] ZNy1."""
+
+    ZNY7 = 75
+    """[ZBEX] ZNy7."""
+
+    DDN0 = 76
+    """[ZBEX] Ddn0."""
+
+    DND0 = 77
+    """[ZBEX] DNd0."""
+
+    DNYN1 = 78
+    """[ZBEX] DNyn1."""
+
+    DNYN11 = 79
+    """[ZBEX] DNyn11."""
+
+    YNDN1 = 80
+    """[ZBEX] YNdn1."""
+
+    YNDN11 = 81
+    """[ZBEX] YNdn11."""
+
+    TTN11 = 82
+    """[ZBEX] Scott-T Transformer."""
+
+    @property
+    def short_name(self):
+        return str(self)[12:]

zepben/ewb/model/cim/extensions/zbex.py

@@ -0,0 +1,17 @@
+#  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/.
+
+def zbex(thing):
+    """
+    Indicates that a member or class is a Zepben extension added to the CIM standard.
+
+    All Zepben extensions should be annotated with @zbex, and have [ZBEX] linked into their docstring. Once this has been linked
+    everywhere, you will be able to use "find usages" to see all of our extension attributes/classes.
+
+    NOTE: Python doesn't let you decorate a member, so you will need to search for [ZBEX] to find those.
+    """
+
+    # We don't actually do anything with this decorator, it is just to mark that this is an extension.
+    return thing

zepben/ewb/model/cim/iec61968/__init__.py

@@ -0,0 +1,4 @@
+#  Copyright 2024 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.

zepben/ewb/model/cim/iec61968/assetinfo/__init__.py

@@ -0,0 +1,4 @@
+#  Copyright 2024 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.

zepben/ewb/model/cim/iec61968/assetinfo/cable_info.py

@@ -0,0 +1,15 @@
+#  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__ = ["CableInfo"]
+
+from zepben.ewb.model.cim.iec61968.assetinfo.wire_info import WireInfo
+
+
+class CableInfo(WireInfo):
+    """
+    Cable data. A cable is an underground conductor.
+    """
+    pass

zepben/ewb/model/cim/iec61968/assetinfo/no_load_test.py

@@ -0,0 +1,42 @@
+#  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__ = ["NoLoadTest"]
+
+from typing import Optional
+
+from zepben.ewb.model.cim.iec61968.assetinfo.transformer_test import TransformerTest
+
+
+class NoLoadTest(TransformerTest):
+    """
+    No-load test results determine core admittance parameters. They include exciting current and core loss measurements from applying voltage to one
+    winding. The excitation may be positive sequence or zero sequence. The test may be repeated at different voltages to measure saturation.
+    """
+
+    energised_end_voltage: Optional[int] = None
+    """
+    Voltage applied to the winding (end) during test in volts.
+    """
+
+    exciting_current: Optional[float] = None
+    """
+    Exciting current measured from a positive-sequence or single-phase excitation test as a percentage.
+    """
+
+    exciting_current_zero: Optional[float] = None
+    """
+    Exciting current measured from a zero-sequence open-circuit excitation test as a percentage.
+    """
+
+    loss: Optional[int] = None
+    """
+    Losses measured from a positive-sequence or single-phase excitation test in watts.
+    """
+
+    loss_zero: Optional[int] = None
+    """
+    Losses measured from a zero-sequence excitation test in watts.
+    """

zepben/ewb/model/cim/iec61968/assetinfo/open_circuit_test.py

@@ -0,0 +1,42 @@
+#  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__ = ["OpenCircuitTest"]
+
+from typing import Optional
+
+from zepben.ewb.model.cim.iec61968.assetinfo.transformer_test import TransformerTest
+
+
+class OpenCircuitTest(TransformerTest):
+    """
+    Open-circuit test results verify winding turn ratios and phase shifts. They include induced voltage and phase shift measurements on open-circuit windings,
+    with voltage applied to the energised end. For three-phase windings, the excitation can be a positive sequence (the default) or a zero sequence.
+    """
+
+    energised_end_step: Optional[int] = None
+    """
+    Tap step number for the energised end of the test pair.
+    """
+
+    energised_end_voltage: Optional[int] = None
+    """
+    Voltage applied to the winding (end) during test in volts.
+    """
+
+    open_end_step: Optional[int] = None
+    """
+    Tap step number for the open end of the test pair.
+    """
+
+    open_end_voltage: Optional[int] = None
+    """
+    Voltage measured at the open-circuited end, with the energised end set to rated voltage and all other ends open in volts.
+    """
+
+    phase_shift: Optional[float] = None
+    """
+    Phase shift measured at the open end with the energised end set to rated voltage and all other ends open in angle degrees.
+    """

zepben/ewb/model/cim/iec61968/assetinfo/overhead_wire_info.py

@@ -0,0 +1,15 @@
+#  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__ = ["OverheadWireInfo"]
+
+from zepben.ewb.model.cim.iec61968.assetinfo.wire_info import WireInfo
+
+
+class OverheadWireInfo(WireInfo):
+    """
+    Overhead wire data. A "wire" is an above ground conductor.
+    """
+    pass