zepben.ewb 1.0.0b1__py3-none-any.whl

zepben/ewb/model/cim/iec61970/base/generation/production/battery_unit.py

@@ -0,0 +1,108 @@
+#  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__ = ["BatteryUnit"]
+
+from typing import List, Optional, Generator, TYPE_CHECKING
+
+from zepben.ewb.model.cim.extensions.iec61970.base.wires.battery_control_mode import BatteryControlMode
+from zepben.ewb.model.cim.iec61970.base.generation.production.battery_state_kind import BatteryStateKind
+from zepben.ewb.model.cim.iec61970.base.generation.production.power_electronics_unit import PowerElectronicsUnit
+from zepben.ewb.util import nlen, ngen, get_by_mrid, safe_remove
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.extensions.iec61970.base.wires.battery_control import BatteryControl
+
+
+class BatteryUnit(PowerElectronicsUnit):
+    """An electrochemical energy storage device."""
+
+    def __init__(self, controls: List['BatteryControl'] = None, **kwargs):
+        super(BatteryUnit, self).__init__(**kwargs)
+        if controls:
+            for bc in controls:
+                self.add_control(bc)
+
+    battery_state: BatteryStateKind = BatteryStateKind.UNKNOWN
+    """The current state of the battery (charging, full, etc.)."""
+
+    rated_e: Optional[int] = None
+    """Full energy storage capacity of the battery in watt hours (Wh). The attribute shall be a positive value."""
+
+    stored_e: Optional[int] = None
+    """Amount of energy currently stored in watt hours (Wh). The attribute shall be a positive value or zero and lower than `rated_e`."""
+
+    _controls: Optional[List['BatteryControl']] = None
+
+    # NOTE: This is called `num_battery_controls` because `num_controls` is already used by `PowerSystemResource`.
+    def num_battery_controls(self):
+        """
+        Returns The number of `BatteryControl`s associated with this `BatteryUnit`
+        """
+        return nlen(self._controls)
+
+    @property
+    def controls(self) -> Generator['BatteryControl', None, None]:
+        """
+        [ZBEX] The `BatteryControl`s associated with this `BatteryUnit`
+        """
+        return ngen(self._controls)
+
+    def get_control(self, mrid: str) -> 'BatteryControl':
+        """
+        Get the `BatteryControl` for this `BatteryUnit` identified by `mrid`
+
+        `mrid` the mRID of the required `BatteryControl`
+        Returns The `BatteryControl` with the specified `mrid` if it exists
+        Raises `KeyError` if `mrid` wasn't present.
+        """
+        return get_by_mrid(self._controls, mrid)
+
+    def get_control_by_mode(self, control_mode: BatteryControlMode) -> 'BatteryControl':
+        """
+        Get the `BatteryControl` for this `BatteryUnit` identified by its `control_mode`
+
+        `control_mode` the `BatteryControlMode` of the desired `BatteryControl`
+        Returns The `BatteryControl` with the specified `control_mode` if it exists
+        Raises `KeyError` if a `BatteryControl` with `control_mode` wasn't present.
+        """
+        if self._controls:
+            for control in self._controls:
+                if control.control_mode == control_mode:
+                    return control
+        raise IndexError(f"No BatteryControl with a control_mode of {control_mode} was found in BatteryUnit {str(self)}")
+
+    def add_control(self, bc: 'BatteryControl') -> 'BatteryUnit':
+        """
+        Associate `bc` to this `BatteryUnit`.
+
+        `bc` the `BatteryControl` to associate with this `BatteryUnit`.
+        Returns A reference to this `BatteryUnit` to allow fluent use.
+        Raises `ValueError` if another `BatteryControl` with the same `mrid` already exists for this `BatteryUnit`.
+        """
+        if self._validate_reference(bc, self.get_control, "A BatteryControl"):
+            return self
+        self._controls = list() if self._controls is None else self._controls
+        self._controls.append(bc)
+        return self
+
+    def remove_control(self, bc: 'BatteryControl') -> 'BatteryUnit':
+        """
+        Disassociate `bc` from this `BatteryUnit`
+
+        `bc` the `BatteryControl` to disassociate from this `BatteryUnit`.
+        Returns A reference to this `BatteryUnit` to allow fluent use.
+        Raises `ValueError` if `up` was not associated with this `BatteryUnit`.
+        """
+        self._controls = safe_remove(self._controls, bc)
+        return self
+
+    def clear_controls(self) -> 'BatteryUnit':
+        """
+        Clear all battery_controls.
+        Returns A reference to this `BatteryUnit` to allow fluent use.
+        """
+        self._controls = None
+        return self

zepben/ewb/model/cim/iec61970/base/generation/production/photo_voltaic_unit.py

@@ -0,0 +1,13 @@
+#  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__ = ["PhotoVoltaicUnit"]
+
+from zepben.ewb.model.cim.iec61970.base.generation.production.power_electronics_unit import PowerElectronicsUnit
+
+
+class PhotoVoltaicUnit(PowerElectronicsUnit):
+    """A photovoltaic device or an aggregation of such devices."""
+    pass

zepben/ewb/model/cim/iec61970/base/generation/production/power_electronics_unit.py

@@ -0,0 +1,28 @@
+#  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__ = ["PowerElectronicsUnit"]
+
+from typing import Optional, TYPE_CHECKING
+
+from zepben.ewb.model.cim.iec61970.base.core.equipment import Equipment
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.iec61970.base.wires.power_electronics_connection import PowerElectronicsConnection
+
+
+class PowerElectronicsUnit(Equipment):
+    """
+    A generating unit or battery or aggregation that connects to the AC network using power electronics rather than rotating machines.
+    """
+
+    power_electronics_connection: Optional['PowerElectronicsConnection'] = None
+    """An AC network connection may have several power electronics units connecting through it."""
+
+    max_p: Optional[int] = None
+    """Maximum active power limit. This is the maximum (nameplate) limit for the unit."""
+
+    min_p: Optional[int] = None
+    """Minimum active power limit. This is the minimum (nameplate) limit for the unit."""

zepben/ewb/model/cim/iec61970/base/generation/production/power_electronics_wind_unit.py

@@ -0,0 +1,13 @@
+#  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__ = ["PowerElectronicsWindUnit"]
+
+from zepben.ewb.model.cim.iec61970.base.generation.production.power_electronics_unit import PowerElectronicsUnit
+
+
+class PowerElectronicsWindUnit(PowerElectronicsUnit):
+    """A wind generating unit that connects to the AC network with power electronics rather than rotating machines or an aggregation of such units."""
+    pass

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

@@ -0,0 +1,13 @@
+#  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__ = ["Accumulator"]
+
+from zepben.ewb.model.cim.iec61970.base.meas.measurement import Measurement
+
+
+class Accumulator(Measurement):
+    """Accumulator represents an accumulated (counted) Measurement, e.g. an energy value."""
+    pass

zepben/ewb/model/cim/iec61970/base/meas/accumulator_value.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__ = ["AccumulatorValue"]
+
+from typing import Optional
+
+from zepben.ewb.model.cim.iec61970.base.meas.measurement_value import MeasurementValue
+
+
+class AccumulatorValue(MeasurementValue):
+    """AccumulatorValue represents an accumulated (counted) MeasurementValue."""
+
+    value: int = 0
+    """The value to supervise"""
+
+    accumulator_mrid: Optional[str] = None
+    """The `zepben.ewb.model.cim.iec61970.base.meas.measurement.Accumulator` mRID of this `AccumulatorValue`"""

zepben/ewb/model/cim/iec61970/base/meas/analog.py

@@ -0,0 +1,16 @@
+#  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__ = ["Analog"]
+
+from zepben.ewb.model.cim.iec61970.base.meas.measurement import Measurement
+
+
+class Analog(Measurement):
+    """Analog represents an analog Measurement."""
+
+    positive_flow_in: bool = False
+    """If true then this measurement is an active power, reactive power or current with the convention that a positive value measured at the 
+    Terminal means power is flowing into the related PowerSystemResource."""

zepben/ewb/model/cim/iec61970/base/meas/analog_value.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__ = ["AnalogValue"]
+
+from typing import Optional
+
+from zepben.ewb.model.cim.iec61970.base.meas.measurement_value import MeasurementValue
+
+
+class AnalogValue(MeasurementValue):
+    """`AnalogValue` represents an analog `MeasurementValue`."""
+
+    value: float = 0.0
+    """The value to supervise"""
+
+    analog_mrid: Optional[str] = None
+    """The `zepben.ewb.model.cim.iec61970.base.meas.measurement.Analog` mRID of this `AnalogValue`"""

zepben/ewb/model/cim/iec61970/base/meas/control.py

@@ -0,0 +1,26 @@
+#  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__ = ["Control"]
+
+from typing import Optional, TYPE_CHECKING
+
+from zepben.ewb.model.cim.iec61970.base.meas.iopoint import IoPoint
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.iec61970.base.scada.remote_control import RemoteControl
+
+
+class Control(IoPoint):
+    """
+    Control is used for supervisory/device control. It represents control outputs that are used to change the state in a
+    process, e.g. close or open breaker, a set point value or a raise lower command.
+    """
+
+    power_system_resource_mrid: Optional[str] = None
+    """AnalogValue represents an analog MeasurementValue."""
+
+    remote_control: Optional['RemoteControl'] = None
+    """AnalogValue represents an analog MeasurementValue."""

zepben/ewb/model/cim/iec61970/base/meas/discrete.py

@@ -0,0 +1,13 @@
+#  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__ = ["Discrete"]
+
+from zepben.ewb.model.cim.iec61970.base.meas.measurement import Measurement
+
+
+class Discrete(Measurement):
+    """Discrete represents a discrete Measurement, i.e. a Measurement representing discrete values, e.g. a Breaker position."""
+    pass

zepben/ewb/model/cim/iec61970/base/meas/discrete_value.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__ = ["DiscreteValue"]
+
+from typing import Optional
+
+from zepben.ewb.model.cim.iec61970.base.meas.measurement_value import MeasurementValue
+
+
+class DiscreteValue(MeasurementValue):
+    """`DiscreteValue` represents a discrete `MeasurementValue`."""
+
+    value: int = 0
+    """The value to supervise"""
+
+    discrete_mrid: Optional[str] = None
+    """The `zepben.ewb.model.cim.iec61970.base.meas.measurement.Discrete` mRID of this `DiscreteValue`"""

zepben/ewb/model/cim/iec61970/base/meas/iopoint.py

@@ -0,0 +1,16 @@
+#  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__ = ["IoPoint"]
+
+from zepben.ewb.model.cim.iec61970.base.core.identified_object import IdentifiedObject
+
+
+class IoPoint(IdentifiedObject):
+    """
+    This class describes a measurement or control value.
+    The purpose is to enable having attributes and associations common for measurement and control.
+    """
+    pass

zepben/ewb/model/cim/iec61970/base/meas/measurement.py

@@ -0,0 +1,60 @@
+#  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__ = ["Measurement"]
+
+from typing import Optional, TYPE_CHECKING
+
+from zepben.ewb.model.cim.iec61970.base.core.identified_object import IdentifiedObject
+from zepben.ewb.model.cim.iec61970.base.core.phase_code import PhaseCode
+from zepben.ewb.model.cim.iec61970.base.domain.unit_symbol import UnitSymbol
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.iec61970.base.scada.remote_source import RemoteSource
+
+
+class Measurement(IdentifiedObject):
+    """
+    A Measurement represents any measured, calculated or non-measured non-calculated quantity. Any piece of equipment
+    may contain Measurements, e.g. a substation may have temperature measurements and door open indications,
+    a transformer may have oil temperature and tank pressure measurements, a bay may contain a number of power flow
+    measurements and a Breaker may contain a switch status measurement.
+
+    The PSR - Measurement association is intended to capture this use of Measurement and is included in the naming
+    hierarchy based on EquipmentContainer. The naming hierarchy typically has Measurements as leafs,
+    e.g. Substation-VoltageLevel-Bay-Switch-Measurement.
+
+    Some Measurements represent quantities related to a particular sensor location in the network, e.g. a voltage
+    transformer (PT) at a busbar or a current transformer (CT) at the bar between a breaker and an isolator. The
+    sensing position is not captured in the PSR - Measurement association. Instead it is captured by the Measurement
+    - Terminal association that is used to define the sensing location in the network topology. The location is
+    defined by the connection of the Terminal to ConductingEquipment.
+
+    If both a Terminal and PSR are associated, and the PSR is of type ConductingEquipment, the associated Terminal
+    should belong to that ConductingEquipment instance.
+
+    When the sensor location is needed both Measurement-PSR and Measurement-Terminal are used. The Measurement-Terminal
+    association is never used alone.
+    """
+
+    power_system_resource_mrid: Optional[str] = None
+    """The MRID of the power system resource that contains the measurement."""
+
+    remote_source: Optional['RemoteSource'] = None
+    """The `zepben.ewb.model.cim.iec61970.base.scada.remote_source.RemoteSource` taking the `Measurement`"""
+
+    terminal_mrid: Optional[str] = None
+    """A measurement may be associated with a terminal in the network."""
+
+    phases: PhaseCode = PhaseCode.ABC
+    """Indicates to which phases the measurement applies and avoids the need to use 'measurementType' to also encode phase information 
+    (which would explode the types). The phase information in Measurement, along with 'measurementType' and 'phases' uniquely defines a Measurement for a 
+    device, based on normal network phase. Their meaning will not change when the computed energizing phasing is changed due to jumpers or other reasons. 
+    If the attribute is missing three phases (ABC) shall be assumed."""
+
+    unit_symbol: UnitSymbol = UnitSymbol.NONE
+    """Specifies the type of measurement.  For example, this specifies if the measurement represents an indoor temperature, outdoor temperature, bus voltage, 
+    line flow, etc. When the measurementType is set to "Specialization", the type of Measurement is defined in more detail by the specialized class which 
+    inherits from Measurement."""

zepben/ewb/model/cim/iec61970/base/meas/measurement_value.py

@@ -0,0 +1,21 @@
+#  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__ = ["MeasurementValue"]
+
+from datetime import datetime
+from typing import Optional
+
+from zepben.ewb.dataclassy import dataclass
+
+
+@dataclass(slots=True)
+class MeasurementValue(object):
+    """
+    The current state for a measurement. A state value is an instance of a measurement from a specific source.
+    Measurements can be associated with many state values, each representing a different source for the measurement.
+    """
+    time_stamp: Optional[datetime] = None
+    """The time when the value was last updated."""

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

@@ -0,0 +1,23 @@
+#  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__ = ["CurrentRelay"]
+
+from typing import Optional
+
+from zepben.ewb.model.cim.extensions.iec61970.base.protection.protection_relay_function import ProtectionRelayFunction
+
+
+class CurrentRelay(ProtectionRelayFunction):
+    """A device that checks current flow values in any direction or designated direction."""
+
+    current_limit_1: Optional[float] = None
+    """Current limit number 1 for inverse time pickup in amperes."""
+
+    inverse_time_flag: Optional[bool] = None
+    """Set true if the current relay has inverse time characteristic."""
+
+    time_delay_1: Optional[float] = None
+    """Inverse time delay number 1 for current limit number 1 in seconds."""

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

@@ -0,0 +1,22 @@
+#  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__ = ["RemoteControl"]
+
+from typing import Optional, TYPE_CHECKING
+
+from zepben.ewb.model.cim.iec61970.base.scada.remote_point import RemotePoint
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.iec61970.base.meas.control import Control
+
+
+class RemoteControl(RemotePoint):
+    """
+    Remote controls are outputs that are sent by the remote unit to actuators in the process.
+    """
+
+    control: Optional['Control'] = None
+    """The `zepben.ewb.model.cim.iec61970.base.meas.control.Control` for the `RemoteControl` point."""

zepben/ewb/model/cim/iec61970/base/scada/remote_point.py

@@ -0,0 +1,16 @@
+#  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__ = ["RemotePoint"]
+
+from zepben.ewb.model.cim.iec61970.base.core.identified_object import IdentifiedObject
+
+
+class RemotePoint(IdentifiedObject):
+    """
+    For a RTU remote points correspond to telemetered values or control outputs. Other units (e.g. control centers)
+    usually also contain calculated values.
+    """
+    pass

zepben/ewb/model/cim/iec61970/base/scada/remote_source.py

@@ -0,0 +1,22 @@
+#  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__ = ["RemoteSource"]
+
+from typing import Optional, TYPE_CHECKING
+
+from zepben.ewb.model.cim.iec61970.base.scada.remote_point import RemotePoint
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.iec61970.base.meas.measurement import Measurement
+
+
+class RemoteSource(RemotePoint):
+    """
+    Remote sources are state variables that are telemetered or calculated within the remote unit.
+    """
+
+    measurement: Optional['Measurement'] = None
+    """The `meas.measurement.Measurement` for the `RemoteSource` point."""

zepben/ewb/model/cim/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/.