zepben.ewb 1.0.0__py3-none-any.whl

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

@@ -0,0 +1,103 @@
+#  Copyright 2024 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+from __future__ import annotations
+
+__all__ = ["PowerTransformerInfo"]
+
+from typing import List, Optional, Generator, TYPE_CHECKING
+
+from zepben.ewb.model.cim.iec61968.assets.asset_info import AssetInfo
+from zepben.ewb.model.resistance_reactance import ResistanceReactance
+from zepben.ewb.util import nlen, ngen, get_by_mrid, safe_remove
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.iec61968.assetinfo.transformer_tank_info import TransformerTankInfo
+
+
+class PowerTransformerInfo(AssetInfo):
+    """Set of power transformer data, from an equipment library."""
+
+    _transformer_tank_infos: Optional[List[TransformerTankInfo]] = None
+    """Data for all the tanks described by this power transformer data."""
+
+    def __init__(self, transformer_tank_infos: List[TransformerTankInfo] = None, **kwargs):
+        super(PowerTransformerInfo, self).__init__(**kwargs)
+        if transformer_tank_infos:
+            for ti in transformer_tank_infos:
+                self.add_transformer_tank_info(ti)
+
+    def num_transformer_tank_infos(self):
+        """
+        Get the number of `TransformerTankInfo`s associated with this `PowerTransformerInfo`.
+        """
+        return nlen(self._transformer_tank_infos)
+
+    @property
+    def transformer_tank_infos(self) -> Generator[TransformerTankInfo, None, None]:
+        """
+        The `TransformerTankInfo`s of this `PowerTransformerInfo`.
+        """
+        return ngen(self._transformer_tank_infos)
+
+    def get_transformer_tank_info(self, mrid: str) -> TransformerTankInfo:
+        """
+        Get the `TransformerTankInfo` for this `PowerTransformerInfo` identified by `mrid`.
+
+        `mrid` the mRID of the required `TransformerTankInfo`
+        Returns The `TransformerTankInfo` with the specified `mrid`.
+        Raises `KeyError` if `mrid` wasn't present.
+        """
+        return get_by_mrid(self._transformer_tank_infos, mrid)
+
+    def add_transformer_tank_info(self, tti: TransformerTankInfo) -> PowerTransformerInfo:
+        """
+        `tti` The `TransformerTankInfo` to
+        associate with this `PowerTransformerInfo`.
+
+        Returns A reference to this `PowerTransformerInfo` to allow fluent use.
+
+        Raises `ValueError` if another `TransformerTankInfo` with the same `mrid` already
+        exists in this `PowerTransformerInfo`
+        """
+        if self._validate_reference(tti, self.get_transformer_tank_info, "A TransformerTankInfo"):
+            return self
+
+        self._transformer_tank_infos = list() if self._transformer_tank_infos is None else self._transformer_tank_infos
+        self._transformer_tank_infos.append(tti)
+        return self
+
+    def remove_transformer_tank_info(self, tti: TransformerTankInfo) -> PowerTransformerInfo:
+        """
+        Disassociate an `TransformerTankInfo` from this `PowerTransformerInfo`.
+
+        `tti` the `TransformerTankInfo` to
+        disassociate with this `PowerTransformerInfo`.
+        Raises `ValueError` if `tti` was not associated with this `PowerTransformerInfo`.
+        Returns A reference to this `Asset` to allow fluent use.
+        """
+        self._transformer_tank_infos = safe_remove(self._transformer_tank_infos, tti)
+        return self
+
+    def clear_transformer_tank_infos(self) -> PowerTransformerInfo:
+        """
+        Clears all `TransformerTankInfo`.
+        Returns self
+        """
+        self._transformer_tank_infos = None
+        return self
+
+    def resistance_reactance(self, end_number: int) -> Optional[ResistanceReactance]:
+        """
+        Get the `ResistanceReactance` for the specified `end_number` from the datasheet information.
+        `end_number` The number of the end to fetch the ResistanceReactance for.
+        Returns a `ResistanceReactance` for the specified end, or None if one couldn't be calculated.
+        """
+        for tti in self.transformer_tank_infos:
+            rr = tti.resistance_reactance(end_number)
+            if rr is not None:
+                return rr
+        else:
+            return None

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

@@ -0,0 +1,67 @@
+#  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__ = ["ShortCircuitTest"]
+
+from typing import Optional
+
+from zepben.ewb.model.cim.iec61968.assetinfo.transformer_test import TransformerTest
+
+
+class ShortCircuitTest(TransformerTest):
+    """
+    Short-circuit test results determine mesh impedance parameters. They include load losses and leakage impedances. For three-phase windings, the excitation
+    can be a positive sequence (the default) or a zero sequence. There shall be at least one grounded winding.
+    """
+
+    current: Optional[float] = None
+    """
+    Short circuit current in amps.
+    """
+
+    energised_end_step: Optional[int] = None
+    """
+    Tap step number for the energised end of the test pair.
+    """
+
+    grounded_end_step: Optional[int] = None
+    """
+    Tap step number for the grounded end of the test pair.
+    """
+
+    leakage_impedance: Optional[float] = None
+    """
+    Leakage impedance measured from a positive-sequence or single-phase short-circuit test in ohms.
+    """
+
+    leakage_impedance_zero: Optional[float] = None
+    """
+    Leakage impedance measured from a zero-sequence short-circuit test in ohms.
+    """
+
+    loss: Optional[int] = None
+    """
+    Load losses from a positive-sequence or single-phase short-circuit test in watts.
+    """
+
+    loss_zero: Optional[int] = None
+    """
+    Load losses from a zero-sequence short-circuit test in watts.
+    """
+
+    power: Optional[int] = None
+    """
+    Short circuit apparent power in VA.
+    """
+
+    voltage: Optional[float] = None
+    """
+    Short circuit voltage as a percentage.
+    """
+
+    voltage_ohmic_part: Optional[float] = None
+    """
+    Short Circuit Voltage – Ohmic Part as a percentage.
+    """

zepben/ewb/model/cim/iec61968/assetinfo/shunt_compensator_info.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__ = ["ShuntCompensatorInfo"]
+
+from typing import Optional
+
+from zepben.ewb.model.cim.iec61968.assets.asset_info import AssetInfo
+
+
+class ShuntCompensatorInfo(AssetInfo):
+    """Properties of shunt capacitor, shunt reactor or switchable bank of shunt capacitor or reactor assets."""
+
+    max_power_loss: Optional[int] = None
+    """Maximum allowed apparent power loss in watts."""
+
+    rated_current: Optional[int] = None
+    """Rated current in amperes."""
+
+    rated_reactive_power: Optional[int] = None
+    """Rated reactive power in volt-amperes reactive."""
+
+    rated_voltage: Optional[int] = None
+    """Rated voltage in volts."""

zepben/ewb/model/cim/iec61968/assetinfo/switch_info.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/.
+
+__all__ = ["SwitchInfo"]
+
+from typing import Optional
+
+from zepben.ewb.model.cim.iec61968.assets.asset_info import AssetInfo
+
+
+class SwitchInfo(AssetInfo):
+    """Switch datasheet information."""
+
+    rated_interrupting_time: Optional[float] = None
+    """Switch rated interrupting time in seconds."""

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

@@ -0,0 +1,137 @@
+#  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__ = ["TransformerEndInfo"]
+
+import math
+from typing import Optional, TYPE_CHECKING, Tuple
+
+from zepben.ewb.model.cim.iec61968.assets.asset_info import AssetInfo
+from zepben.ewb.model.cim.iec61970.base.wires.winding_connection import WindingConnection
+from zepben.ewb.model.resistance_reactance import ResistanceReactance
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.iec61968.assetinfo.no_load_test import NoLoadTest
+    from zepben.ewb.model.cim.iec61968.assetinfo.open_circuit_test import OpenCircuitTest
+    from zepben.ewb.model.cim.iec61968.assetinfo.short_circuit_test import ShortCircuitTest
+    from zepben.ewb.model.cim.iec61968.assetinfo.transformer_tank_info import TransformerTankInfo
+    from zepben.ewb.model.cim.iec61970.base.wires.transformer_star_impedance import TransformerStarImpedance
+
+
+class TransformerEndInfo(AssetInfo):
+    """Transformer end data."""
+
+    connection_kind: WindingConnection = WindingConnection.UNKNOWN
+    """Kind of connection."""
+
+    emergency_s: Optional[int] = None
+    """Apparent power that the winding can carry under emergency conditions (also called long-term emergency power). Unit: VA"""
+
+    end_number: int = 0
+    """Number for this transformer end, corresponding to the end's order in the PowerTransformer.vectorGroup attribute. Highest voltage winding
+         should be 1."""
+
+    insulation_u: Optional[int] = None
+    """Basic insulation level voltage rating. Unit: Volts"""
+
+    phase_angle_clock: Optional[int] = None
+    """Winding phase angle where 360 degrees are represented with clock hours, so the valid values are {0, ..., 11}. For example,
+         to express the second winding in code 'Dyn11', set attributes as follows: 'endNumber'=2, 'connectionKind' = Yn and 'phaseAngleClock' = 11."""
+
+    r: Optional[float] = None
+    """DC resistance. Unit: Ohms"""
+
+    rated_s: Optional[int] = None
+    """Normal apparent power rating. Unit: VA"""
+
+    rated_u: Optional[int] = None
+    """Rated voltage: phase-phase for three-phase windings, and either phase-phase or phase-neutral for single-phase windings. Unit: Volts"""
+
+    short_term_s: Optional[int] = None
+    """Apparent power that this winding can carry for a short period of time (in emergency). Unit: VA"""
+
+    transformer_tank_info: Optional['TransformerTankInfo'] = None
+    """Transformer tank data that this end description is part of."""
+
+    transformer_star_impedance: Optional['TransformerStarImpedance'] = None
+    """Transformer star impedance calculated from this transformer end datasheet."""
+
+    energised_end_no_load_tests: Optional['NoLoadTest'] = None
+    """
+    All no-load test measurements in which this transformer end was energised.
+    """
+
+    energised_end_short_circuit_tests: Optional['ShortCircuitTest'] = None
+    """
+    All short-circuit test measurements in which this transformer end was short-circuited.
+    """
+
+    grounded_end_short_circuit_tests: Optional['ShortCircuitTest'] = None
+    """
+    All short-circuit test measurements in which this transformer end was energised.
+    """
+
+    open_end_open_circuit_tests: Optional['OpenCircuitTest'] = None
+    """
+    All open-circuit test measurements in which this transformer end was not excited.
+    """
+
+    energised_end_open_circuit_tests: Optional['OpenCircuitTest'] = None
+    """
+    All open-circuit test measurements in which this transformer end was excited.
+    """
+
+    def resistance_reactance(self) -> Optional[ResistanceReactance]:
+        """
+        Get the `ResistanceReactance` for this `TransformerEndInfo` from either the pre-calculated `transformer_star_impedance` or
+        calculated from the associated test data.
+
+        Returns the `ResistanceReactance` for this `TransformerEndInfo` or None if it could not be calculated
+        """
+        if self.transformer_star_impedance is not None:
+            return self.transformer_star_impedance.resistance_reactance().merge_if_incomplete(lambda: self.calculate_resistance_reactance_from_tests())
+        else:
+            return self.calculate_resistance_reactance_from_tests()
+
+    def calculate_resistance_reactance_from_tests(self) -> Optional[ResistanceReactance]:
+        """
+        Get the `ResistanceReactance` for this `TransformerEndInfo` calculated from the associated test data.
+
+        Returns the `ResistanceReactance` for this `TransformerEndInfo` or None if it could not be calculated
+
+        Calculation  of r0 and x0 from Test data is not supported. r0 nad x0 must be populated directly in the
+        associated TransformerStarImpedance
+        """
+        if not self.rated_u or not self.rated_s:
+            return None
+
+        def calculate_x(voltage: float, r: float) -> Optional[float]:
+            if voltage is None or r is None:
+                return None
+
+            return round(math.sqrt((((voltage / 100) * (self.rated_u ** 2) / self.rated_s) ** 2) - (r ** 2)), 2)
+
+        def calculate_r_x_from_test(short_circuit_test: 'ShortCircuitTest') -> Optional[Tuple[float, float]]:
+            if short_circuit_test is None:
+                return None
+            elif short_circuit_test.voltage_ohmic_part is not None:
+                r = round((short_circuit_test.voltage_ohmic_part * (self.rated_u ** 2)) / (self.rated_s * 100), 2)
+            elif short_circuit_test.loss is not None:
+                r = round(short_circuit_test.loss * ((self.rated_u / self.rated_s) ** 2), 2)
+            else:
+                return None
+
+            return r, calculate_x(short_circuit_test.voltage, r)
+
+        rr = ResistanceReactance()
+        rx = calculate_r_x_from_test(self.energised_end_short_circuit_tests)
+        if rx is not None:
+            rr.r, rr.x = rx
+
+        r0x0 = calculate_r_x_from_test(self.grounded_end_short_circuit_tests)
+        if r0x0 is not None:
+            rr.r0, rr.x0 = r0x0
+
+        return rr if not rr.is_empty() else None

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

@@ -0,0 +1,108 @@
+#  Copyright 2024 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+from __future__ import annotations
+
+__all__ = ["TransformerTankInfo"]
+
+from typing import Optional, List, Generator, TYPE_CHECKING
+
+from zepben.ewb.model.cim.iec61968.assets.asset_info import AssetInfo
+from zepben.ewb.model.resistance_reactance import ResistanceReactance
+from zepben.ewb.util import nlen, ngen, safe_remove, get_by_mrid
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.iec61968.assetinfo.power_transformer_info import PowerTransformerInfo
+    from zepben.ewb.model.cim.iec61968.assetinfo.transformer_end_info import TransformerEndInfo
+
+
+class TransformerTankInfo(AssetInfo):
+    """Set of transformer tank data, from an equipment library."""
+
+    power_transformer_info: Optional[PowerTransformerInfo] = None
+    """Power transformer data that this tank description is part of."""
+
+    _transformer_end_infos: Optional[List[TransformerEndInfo]] = None
+    """Data for all the ends described by this transformer tank data."""
+
+    def __init__(self, transformer_end_infos: List[TransformerEndInfo] = None, **kwargs):
+        super(TransformerTankInfo, self).__init__(**kwargs)
+        if transformer_end_infos:
+            for tei in transformer_end_infos:
+                self.add_transformer_end_info(tei)
+
+    def num_transformer_end_infos(self):
+        """
+        Get the number of `TransformerEndInfo`s associated with this `TransformerTankInfo`.
+        """
+        return nlen(self._transformer_end_infos)
+
+    @property
+    def transformer_end_infos(self) -> Generator[TransformerEndInfo, None, None]:
+        """
+        The `TransformerEndInfo`s of this `TransformerTankInfo`.
+        """
+        return ngen(self._transformer_end_infos)
+
+    def get_transformer_end_info(self, mrid: str) -> TransformerEndInfo:
+        """
+        Get the `TransformerEndInfo` for this `TransformerTankInfo` identified by `mrid`.
+
+        `mrid` the mRID of the required `TransformerEndInfo`
+        Returns The `TransformerEndInfo` with the specified `mrid`.
+        Raises `KeyError` if `mrid` wasn't present.
+        """
+        return get_by_mrid(self._transformer_end_infos, mrid)
+
+    def add_transformer_end_info(self, tei: TransformerEndInfo) -> TransformerTankInfo:
+        """
+        `tei` The `TransformerEndInfo` to
+        associate with this `TransformerTankInfo`.
+
+        Returns A reference to this `TransformerTankInfo` to allow fluent use.
+
+        Raises `ValueError` if another `TransformerEndInfo` with the same `mrid` already
+        exists in this `TransformerTankInfo`
+        """
+        if self._validate_reference(tei, self.get_transformer_end_info, "A TransformerEndInfo"):
+            return self
+
+        self._transformer_end_infos = list() if self._transformer_end_infos is None else self._transformer_end_infos
+        self._transformer_end_infos.append(tei)
+        return self
+
+    def remove_transformer_end_info(self, tei: TransformerEndInfo) -> TransformerTankInfo:
+        """
+        Disassociate an `TransformerEndInfo` from this `TransformerTankInfo`.
+
+        `tei` the `TransformerEndInfo` to
+        disassociate with this `TransformerTankInfo`.
+        Raises `ValueError` if `tei` was not associated with this `TransformerTankInfo`.
+        Returns A reference to this `TransformerTankInfo` to allow fluent use.
+        """
+        self._transformer_end_infos = safe_remove(self._transformer_end_infos, tei)
+        return self
+
+    def clear_transformer_end_infos(self) -> TransformerTankInfo:
+        """
+        Clears all `TransformerEndInfo`.
+        Returns self
+        """
+        self._transformer_end_infos = None
+        return self
+
+    def resistance_reactance(self, end_number: int) -> Optional[ResistanceReactance]:
+        """
+        Get the `ResistanceReactance` for the specified `end_number` from the datasheet information.
+        `end_number` The number of the end to fetch the ResistanceReactance for.
+        Returns a `ResistanceReactance` for the specified end, or None if one couldn't be calculated.
+        """
+        for tei in self.transformer_end_infos:
+            if tei.end_number == end_number:
+                rr = tei.resistance_reactance()
+                if rr is not None:
+                    return rr
+        else:
+            return None

zepben/ewb/model/cim/iec61968/assetinfo/transformer_test.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__ = ["TransformerTest"]
+
+from typing import Optional
+
+from zepben.ewb.model.cim.iec61970.base.core.identified_object import IdentifiedObject
+
+
+class TransformerTest(IdentifiedObject):
+    """
+    Test result for transformer ends, such as short-circuit, open-circuit (excitation) or no-load test.
+    """
+
+    base_power: Optional[int] = None
+    """
+    Base power at which the tests are conducted, usually equal to the ratedS of one of the involved transformer ends in VA.
+    """
+
+    temperature: Optional[float] = None
+    """
+    Temperature at which the test is conducted in degrees Celsius.
+    """

zepben/ewb/model/cim/iec61968/assetinfo/wire_info.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__ = ["WireInfo"]
+
+from typing import Optional
+
+from zepben.ewb.model.cim.iec61968.assetinfo.wire_material_kind import WireMaterialKind
+from zepben.ewb.model.cim.iec61968.assets.asset_info import AssetInfo
+
+
+class WireInfo(AssetInfo):
+    """
+    Wire data that can be specified per line segment phase, or for the line segment as a whole in case its phases all
+    have the same wire characteristics
+
+    Attributes -
+        rated_current : Current carrying capacity of the wire under stated thermal conditions in amperes.
+        material : `zepben.protobuf.cim.iec61968.assetinfo.WireMaterialKind` - Conductor material.
+    """
+    rated_current: Optional[int] = None
+    material: WireMaterialKind = WireMaterialKind.UNKNOWN

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

@@ -0,0 +1,57 @@
+#  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__ = ["WireMaterialKind"]
+
+from enum import Enum
+
+from zepben.ewb import unique
+
+
+@unique
+class WireMaterialKind(Enum):
+    """
+    Kind of wire material.
+    """
+
+    UNKNOWN = 0
+    """UNKNOWN"""
+
+    aaac = 1
+    """Aluminum-alloy conductor steel reinforced."""
+
+    acsr = 2
+    """Aluminum conductor steel reinforced."""
+
+    acsrAz = 3
+    """Aluminum conductor steel reinforced, aluminumized steel core"""
+
+    aluminum = 4
+    """Aluminum wire."""
+
+    aluminumAlloy = 5
+    """Aluminum-alloy wire."""
+
+    aluminumAlloySteel = 6
+    """Aluminum-alloy-steel wire."""
+
+    aluminumSteel = 7
+    """Aluminum-steel wire."""
+
+    copper = 8
+    """Copper wire."""
+
+    copperCadmium = 9
+    """Copper cadmium wire."""
+
+    other = 10
+    """Other wire material."""
+
+    steel = 11
+    """Steel wire."""
+
+    @property
+    def short_name(self):
+        return str(self)[17:]

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