zepben.ewb 1.0.0__py3-none-any.whl

zepben/ewb/model/cim/iec61970/base/wires/regulating_control.py

@@ -0,0 +1,173 @@
+#  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__ = ["RegulatingControl"]
+
+from typing import Optional, List, Generator, Iterable, TYPE_CHECKING
+
+from zepben.ewb.model.cim.iec61970.base.core.phase_code import PhaseCode
+from zepben.ewb.model.cim.iec61970.base.core.power_system_resource import PowerSystemResource
+from zepben.ewb.model.cim.iec61970.base.wires.regulating_control_mode_kind import RegulatingControlModeKind
+from zepben.ewb.util import nlen, get_by_mrid, safe_remove, ngen
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.iec61970.base.core.terminal import Terminal
+    from zepben.ewb.model.cim.iec61970.base.wires.regulating_cond_eq import RegulatingCondEq
+
+
+class RegulatingControl(PowerSystemResource):
+    """
+    Specifies a set of equipment that works together to control a power system quantity such as voltage or flow. Remote bus voltage control is possible by
+    specifying the controlled terminal located at some place remote from the controlling equipment. The specified terminal shall be associated with the
+    connectivity node of the controlled point. The most specific subtype of RegulatingControl shall be used in case such equipment participate in the
+    control, e.g. TapChangerControl for tap changers.
+
+    For flow control, load sign convention is used, i.e. positive sign means flow out from a TopologicalNode (bus) into the conducting equipment.
+
+    The attribute minAllowedTargetValue and maxAllowedTargetValue are required in the following cases: For a power generating module operated in power factor
+    control mode to specify maximum and minimum power factor values; Whenever it is necessary to have an off center target voltage for the tap changer
+    regulator. For instance, due to long cables to off shore wind farms and the  need to have a simpler setup at the off shore transformer platform,
+    the voltage is controlled from the land at the connection point for the off shore wind farm.
+
+    Since there usually is a voltage rise along the cable, there is typically an overvoltage of up 3-4 kV compared to the on shore station. Thus in normal
+    operation the tap changer on the on shore station is operated with a target set point, which is in the lower parts of the dead band.
+
+    The attributes minAllowedTargetValue and maxAllowedTargetValue are not related to the attribute targetDeadband and thus they are not treated as an
+    alternative of the targetDeadband. They are needed due to limitations in the local substation controller.
+
+    The attribute targetDeadband is used to prevent the power flow from move the tap position in circles (hunting) that is to be used regardless of the
+    attributes minAllowedTargetValue and maxAllowedTargetValue.
+    """
+
+    discrete: Optional[bool] = None
+    """The regulation is performed in a discrete mode. This applies to equipment with discrete controls, e.g. tap changers and shunt compensators."""
+
+    mode: [RegulatingControlModeKind] = RegulatingControlModeKind.UNKNOWN
+    """
+    The regulating control mode presently available. This specification allows for determining the kind of regulation without need for obtaining the 
+    units from a schedule.
+    """
+
+    monitored_phase: [PhaseCode] = PhaseCode.NONE
+    """Phase voltage controlling this regulator, measured at regulator location."""
+
+    target_deadband: Optional[float] = None
+    """
+    This is a deadband used with discrete control to avoid excessive update of controls like tap changers and shunt compensator banks while regulating. 
+    The units are the base units appropriate for the mode. The attribute shall be a positive value or zero. If RegulatingControl.discrete is set to "false",
+    the RegulatingControl.target_deadband is to be ignored. Note that for instance, if the targetValue is 100 kV and the targetDeadband is 2 kV the range is 
+    from 99 to 101 kV.
+    """
+
+    target_value: Optional[float] = None
+    """
+    The target value specified for case input. This value can be used for the target value without the use of schedules. The value has the units appropriate 
+    to the mode attribute.
+    """
+
+    enabled: Optional[bool] = None
+    """The flag tells if regulation is enabled."""
+
+    max_allowed_target_value: Optional[float] = None
+    """Maximum allowed target value (RegulatingControl.targetValue)."""
+
+    min_allowed_target_value: Optional[float] = None
+    """Minimum allowed target value (RegulatingControl.targetValue)."""
+
+    rated_current: Optional[float] = None
+    """The rated current of associated CT in amps for this RegulatingControl. Forms the base used to convert Line Drop Compensation settings from ohms to 
+    voltage."""
+
+    terminal: Optional[Terminal] = None
+    """
+    The terminal associated with this regulating control. The terminal is associated instead of a node, since the terminal could connect into either a 
+    topological node or a connectivity node. Sometimes it is useful to model regulation at a terminal of a bus bar object.
+    """
+
+    ct_primary: Optional[float] = None
+    """
+    [ZBEX]
+    Current rating of the CT, expressed in terms of the current (in Amperes) that flows in the Primary where the 'Primary' is the conductor
+    being monitored. It ensures proper operation of the regulating equipment by providing the necessary current references for control actions. An important side
+    effect of this current value is that it also defines the current value at which the full LDC R and X voltages are applied by the controller, where enabled.
+    """
+
+    min_target_deadband: Optional[float] = None
+    """
+    [ZBEX]
+    This is the minimum allowable range for discrete control in regulating devices, used to prevent frequent control actions and
+    promote operational stability. This attribute sets a baseline range within which no adjustments are made, applicable across various devices like voltage
+    regulators, shunt compensators, or battery units.
+    """
+
+    _regulating_cond_eq: Optional[List[RegulatingCondEq]] = None
+    """The [RegulatingCondEq] that are controlled by this regulating control scheme."""
+
+    def __init__(self, regulating_conducting_equipment: Optional[Iterable[RegulatingCondEq]] = None, **kwargs):
+        super(RegulatingControl, self).__init__(**kwargs)
+        if regulating_conducting_equipment is not None:
+            for eq in regulating_conducting_equipment:
+                self.add_regulating_cond_eq(eq)
+
+    @property
+    def regulating_conducting_equipment(self) -> Generator[RegulatingCondEq, None, None]:
+        """
+        Yields all the :class:`RegulatingCondEq` that are controlled by this :class:`RegulatingControl`.
+
+        :return: A generator that iterates over all RegulatingCondEq controlled by this RegulatingControl.
+        """
+        return ngen(self._regulating_cond_eq)
+
+    def num_regulating_cond_eq(self) -> int:
+        """
+        Get the number of :class:`RegulatingCondEq` that are controlled by this :class:`RegulatingControl`.
+
+        :return: The number of RegulatingCondEq that are controlled by this RegulatingControl.
+        """
+        return nlen(self._regulating_cond_eq)
+
+    def get_regulating_cond_eq(self, mrid: str) -> RegulatingCondEq:
+        """
+        Get a :class:`RegulatingCondEq` controlled by this :class:`RegulatingControl`.
+
+        :param mrid: The mRID of the desired RegulatingCondEq
+        :return: The RegulatingCondEq with the specified mRID if it exists, otherwise None.
+        :raises KeyError: If `mrid` wasn't present.
+        """
+        return get_by_mrid(self._regulating_cond_eq, mrid)
+
+    def add_regulating_cond_eq(self, regulating_cond_eq: RegulatingCondEq) -> RegulatingControl:
+        """
+        Associate this :class:`RegulatingControl` with a :class:`RegulatingCondEq` it is controlling.
+
+        :param regulating_cond_eq: The RegulatingCondEq to associate with this RegulatingControl.
+        :return: A reference to this RegulatingControl for fluent use.
+        """
+        if self._validate_reference(regulating_cond_eq, self.get_regulating_cond_eq, "A RegulatingCondEq"):
+            return self
+
+        self._regulating_cond_eq = list() if self._regulating_cond_eq is None else self._regulating_cond_eq
+        self._regulating_cond_eq.append(regulating_cond_eq)
+        return self
+
+    def remove_regulating_cond_eq(self, regulating_cond_eq: Optional[RegulatingCondEq]) -> RegulatingControl:
+        """
+        Disassociate this :class:`RegulatingControl` from a :class:`RegulatingCondEq`.
+
+        :param regulating_cond_eq: The RegulatingCondEq to disassociate from this RegulatingControl.
+        :return: A reference to this RegulatingControl for fluent use.
+        """
+        self._regulating_cond_eq = safe_remove(self._regulating_cond_eq, regulating_cond_eq)
+        return self
+
+    def clear_regulating_cond_eq(self) -> RegulatingControl:
+        """
+        Disassociate all :class:`RegulatingCondEq` from this :class:`RegulatingControl`.
+        :return: A reference to this RegulatingControl for fluent use.
+        """
+        self._regulating_cond_eq = None
+        return self

zepben/ewb/model/cim/iec61970/base/wires/regulating_control_mode_kind.py

@@ -0,0 +1,48 @@
+#  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__ = ["RegulatingControlModeKind"]
+
+from enum import Enum
+
+from zepben.ewb import unique
+
+
+@unique
+class RegulatingControlModeKind(Enum):
+    """
+    The kind of regulation model. For example regulating voltage, reactive power, active power, etc.
+    """
+
+    UNKNOWN = 0
+    """Default, unknown."""
+
+    voltage = 1
+    """Voltage is specified."""
+
+    activePower = 2
+    """Active power is specified."""
+
+    reactivePower = 3
+    """Reactive power is specified."""
+
+    currentFlow = 4
+    """Current flow is specified."""
+
+    admittance = 5
+    """Admittance is specified."""
+
+    timeScheduled = 6
+    """Control switches on/off by time of day. The times may change on the weekend, or in different seasons."""
+
+    temperature = 7
+    """Control switches on/off based on the local temperature (i.e., a thermostat)."""
+
+    powerFactor = 8
+    """Power factor is specified."""
+
+    @property
+    def short_name(self):
+        return str(self)[26:]

zepben/ewb/model/cim/iec61970/base/wires/rotating_machine.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__ = ["RotatingMachine"]
+
+from typing import Optional
+
+from zepben.ewb.model.cim.iec61970.base.wires.regulating_cond_eq import RegulatingCondEq
+
+
+class RotatingMachine(RegulatingCondEq):
+    """
+    A rotating machine which may be used as a generator or motor.
+    """
+
+    rated_power_factor: Optional[float] = None
+    """Power factor (nameplate data). It is primarily used for short circuit data exchange according to IEC 60909. The attribute cannot be a negative value."""
+
+    rated_s: Optional[float] = None
+    """Nameplate apparent power rating for the unit in volt-amperes (VA). The attribute shall have a positive value."""
+
+    rated_u: Optional[int] = None
+    """
+    Rated voltage in volts (nameplate data, Ur in IEC 60909-0). It is primarily used for short circuit data exchange according to IEC 60909.
+    The attribute shall be a positive value.
+    """
+
+    p: Optional[float] = None
+    """
+    Active power injection in watts. Load sign convention is used, i.e. positive sign means flow out from a node. Starting value for a steady state solution.
+    """
+
+    q: Optional[float] = None
+    """Reactive power injection. Load sign convention is used, i.e. positive sign means flow out from a node. Starting value for a steady state solution."""

zepben/ewb/model/cim/iec61970/base/wires/series_compensator.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__ = ["SeriesCompensator"]
+
+from typing import Optional
+
+from zepben.ewb.model.cim.iec61970.base.core.conducting_equipment import ConductingEquipment
+
+
+class SeriesCompensator(ConductingEquipment):
+    """
+    A Series Compensator is a series capacitor or reactor or an AC transmission line without charging susceptance. It is a two terminal device.
+    """
+    r: Optional[float] = None
+    """Positive sequence resistance in ohms."""
+
+    r0: Optional[float] = None
+    """Zero sequence resistance in ohms."""
+
+    x: Optional[float] = None
+    """Positive sequence reactance in ohms."""
+
+    x0: Optional[float] = None
+    """Zero sequence reactance in ohms."""
+
+    varistor_rated_current: Optional[int] = None
+    """
+    The maximum current in amps the varistor is designed to handle at specified duration. It is used for short circuit calculations. The attribute shall 
+    be a positive value. If null and varistorVoltageThreshold is null, a varistor is not present.
+    """
+
+    varistor_voltage_threshold: Optional[int] = None
+    """
+    The dc voltage in volts at which the varistor starts conducting. It is used for short circuit calculations. If null and varistorRatedCurrent is null, 
+    a varistor is not present.
+    """
+
+    def varistor_present(self) -> bool:
+        return self.varistor_rated_current is not None or self.varistor_voltage_threshold is not None

zepben/ewb/model/cim/iec61970/base/wires/shunt_compensator.py

@@ -0,0 +1,59 @@
+#  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__ = ["ShuntCompensator"]
+
+from typing import Optional, TYPE_CHECKING
+
+from zepben.ewb.model.cim.iec61970.base.wires.phase_shunt_connection_kind import PhaseShuntConnectionKind
+from zepben.ewb.model.cim.iec61970.base.wires.regulating_cond_eq import RegulatingCondEq
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.iec61968.assetinfo.shunt_compensator_info import ShuntCompensatorInfo
+
+
+class ShuntCompensator(RegulatingCondEq):
+    """
+    A shunt capacitor or reactor or switchable bank of shunt capacitors or reactors. A section of a shunt compensator
+    is an individual capacitor or reactor.  A negative value for reactivePerSection indicates that the compensator is
+    a reactor. ShuntCompensator is a single terminal device.  Ground is implied.
+    """
+    grounded: Optional[bool] = None
+    """Used for Yn and Zn connections. True if the neutral is solidly grounded. nom_u : The voltage at which the nominal reactive power may be calculated. 
+    This should normally be within 10% of the voltage at which the capacitor is connected to the network."""
+
+    nom_u: Optional[int] = None
+    """The voltage at which the nominal reactive power may be calculated. This should normally be within 10% of the voltage at which the capacitor is connected 
+    to the network."""
+
+    phase_connection: PhaseShuntConnectionKind = PhaseShuntConnectionKind.UNKNOWN
+    """The type of phase connection, such as wye or delta."""
+
+    sections: Optional[float] = None
+    """
+    Shunt compensator sections in use. Starting value for steady state solution. Non integer values are allowed to support continuous variables. The 
+    reasons for continuous value are to support study cases where no discrete shunt compensator's has yet been designed, a solutions where a narrow voltage 
+    band force the sections to oscillate or accommodate for a continuous solution as input. 
+    
+    For `LinearShuntCompensator` the value shall be between zero and `ShuntCompensator.maximumSections`. At value zero the shunt compensator conductance and 
+    admittance is zero. Linear interpolation of conductance and admittance between the previous and next integer section is applied in case of non-integer 
+    values. 
+    
+    For `NonlinearShuntCompensator`s shall only be set to one of the NonlinearShuntCompensatorPoint.sectionNumber. There is no interpolation between 
+    NonlinearShuntCompensatorPoint-s.
+    """
+
+    @property
+    def shunt_compensator_info(self) -> Optional['ShuntCompensatorInfo']:
+        """The `ShuntCompensatorInfo` for this `ShuntCompensator`"""
+        return self.asset_info
+
+    @shunt_compensator_info.setter
+    def shunt_compensator_info(self, sci: Optional['ShuntCompensatorInfo']):
+        """
+        Set the `ShuntCompensatorInfo` for this `ShuntCompensator`
+        `sci` The `ShuntCompensatorInfo` for this `ShuntCompensator`
+        """
+        self.asset_info = sci

zepben/ewb/model/cim/iec61970/base/wires/single_phase_kind.py

@@ -0,0 +1,107 @@
+#  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__ = ["SinglePhaseKind", "single_phase_kind_by_id", "SINGLE_PHASE_KIND_VALUES"]
+
+from enum import Enum
+from typing import Union
+
+from zepben.ewb import unique
+
+
+#
+# NOTE: The following import is actually at the bottom of this file to avoid cyclic imports.
+#
+# from zepben.ewb.model.cim.iec61970.base.core.phase_code import phase_code_from_single_phases, PhaseCode
+#
+
+def single_phase_kind_by_id(value):
+    """
+    Get a SinglePhaseKind by its value
+
+    `value` ID of the SinglePhaseKind from 0 as per the order of definition
+    Returns The SinglePhaseKind
+    """
+    return SINGLE_PHASE_KIND_VALUES[value]
+
+
+@unique
+class SinglePhaseKind(Enum):
+    """
+    Enumeration of single phase identifiers. Allows designation of single phases for both transmission and distribution equipment, circuits and loads.
+    """
+
+    NONE = (0, -1)
+    """No phase specified"""
+
+    A = (1, 0)
+    """Phase A"""
+
+    B = (2, 1)
+    """Phase B"""
+
+    C = (3, 2)
+    """Phase C"""
+
+    N = (4, 3)
+    """Neutral"""
+
+    X = (5, 0)
+    """An unknown primary phase."""
+
+    Y = (6, 1)
+    """An unknown primary phase."""
+
+    s1 = (7, 0)
+    """Secondary phase 1."""
+
+    s2 = (8, 1)
+    """Secondary phase 2."""
+
+    INVALID = (9, -1)
+    """Invalid phase. Caused by trying to energise with multiple phases simultaneously."""
+
+    @property
+    def bit_mask(self):
+        return 1 << self.mask_index if self.mask_index >= 0 else 0
+
+    @property
+    def id(self):
+        return self.value[0]
+
+    @property
+    def mask_index(self):
+        return self.value[1]
+
+    @property
+    def short_name(self):
+        return str(self)[16:]
+
+    def __lt__(self, other):
+        return self.id < other.id
+
+    def __add__(self, other: Union['SinglePhaseKind', 'PhaseCode']) -> 'PhaseCode':
+        if isinstance(other, SinglePhaseKind):
+            return phase_code_from_single_phases({self, other})
+        elif isinstance(other, PhaseCode):
+            return phase_code_from_single_phases(set(other.single_phases + [self]))
+        else:
+            return PhaseCode.NONE
+
+    def __sub__(self, other: Union['SinglePhaseKind', 'PhaseCode']) -> 'PhaseCode':
+        if isinstance(other, SinglePhaseKind):
+            return phase_code_from_single_phases({} if (self == other) else {self})
+        elif isinstance(other, PhaseCode):
+            return phase_code_from_single_phases({} if (self in other) else {self})
+        else:
+            return PhaseCode.NONE
+
+
+SINGLE_PHASE_KIND_VALUES = list(SinglePhaseKind.__members__.values())
+
+#
+# NOTE: The following import is deliberately at the bottom of this file to avoid cyclic imports.
+#
+from zepben.ewb.model.cim.iec61970.base.core.phase_code import phase_code_from_single_phases, PhaseCode  # noqa: E402

zepben/ewb/model/cim/iec61970/base/wires/static_var_compensator.py

@@ -0,0 +1,40 @@
+#  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__ = ["StaticVarCompensator"]
+
+from typing import Optional
+
+from zepben.ewb.model.cim.iec61970.base.wires.regulating_cond_eq import RegulatingCondEq
+from zepben.ewb.model.cim.iec61970.base.wires.svc_control_mode import SVCControlMode
+
+
+class StaticVarCompensator(RegulatingCondEq):
+    """
+    A facility for providing variable and controllable shunt reactive power.The SVC typically consists of a step-down transformer, filter, thyristor-controlled reactor,
+    and thyristor-switched capacitor arms. The SVC may operate in fixed MVar output mode or in voltage control mode. When in voltage control mode, the output of
+    the SVC will be proportional to the deviation of voltage at the controlled bus from the voltage set-point. The SVC characteristic slope defines the proportion.
+    If the voltage at the controlled bus is equal to the voltage set-point, the SVC MVar output is zero.
+    """
+    capacitive_rating: Optional[float] = None
+    """Capacitive reactance in Ohms at maximum capacitive reactive power. Shall always be positive."""
+
+    inductive_rating: Optional[float] = None
+    """Inductive reactance in Ohms at maximum inductive reactive power. Shall always be negative."""
+
+    q: Optional[float] = None
+    """
+    Reactive power injection in VAr. Load sign convention is used, i.e. positive sign means flow out from a node. 
+    Starting value for a steady state solution.
+    """
+
+    svc_control_mode: SVCControlMode = SVCControlMode.UNKNOWN
+    """SVC control mode."""
+
+    voltage_set_point: Optional[int] = None
+    """
+    The reactive power output of the SVC is proportional to the difference between the voltage at the regulated bus and the voltage set-point.
+    When the regulated bus voltage is equal to the voltage set-point, the reactive power output is zero. Must be in volts.
+    """

zepben/ewb/model/cim/iec61970/base/wires/svc_control_mode.py

@@ -0,0 +1,30 @@
+#  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__ = ["SVCControlMode"]
+
+from enum import Enum
+
+from zepben.ewb import unique
+
+
+@unique
+class SVCControlMode(Enum):
+    """
+    Static VAr Compensator control mode.
+    """
+
+    UNKNOWN = 0
+    """[ZBEX] Unknown control."""
+
+    reactivePower = 1
+    """Reactive power control."""
+
+    voltage = 2
+    """Voltage control."""
+
+    @property
+    def short_name(self):
+        return str(self)[15:]

zepben/ewb/model/cim/iec61970/base/wires/switch.py

@@ -0,0 +1,119 @@
+#  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__ = ["Switch"]
+
+from typing import Optional, TYPE_CHECKING
+
+from zepben.ewb.model.cim.iec61970.base.core.conducting_equipment import ConductingEquipment
+from zepben.ewb.model.cim.iec61970.base.wires.single_phase_kind import SinglePhaseKind
+from zepben.ewb.util import require
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.iec61968.assetinfo.switch_info import SwitchInfo
+
+
+def _calculate_open_state(current_state: int, is_open: bool, phase: SinglePhaseKind = None) -> int:
+    require(phase != SinglePhaseKind.NONE and phase != SinglePhaseKind.INVALID,
+            lambda: f"Invalid phase {phase} specified")
+    if phase is None:
+        return 0b1111 if is_open else 0
+    else:
+        return current_state | phase.bit_mask if is_open else current_state & ~phase.bit_mask
+
+
+def _check_open(current_state: int, phase: SinglePhaseKind = None) -> bool:
+    require(phase != SinglePhaseKind.NONE and phase != SinglePhaseKind.INVALID,
+            lambda: f"Invalid phase {phase} specified")
+    if phase is None:
+        return current_state != 0
+    else:
+        return (current_state & phase.bit_mask) != 0
+
+
+class Switch(ConductingEquipment):
+    """
+    A generic device designed to close, or open, or both, one or more electric circuits.
+    All switches are two terminal devices including grounding switches.
+
+    NOTE: The normal and currently open properties are implemented as an integer rather than a boolean to allow for the caching of
+      measurement values if the switch is operating un-ganged. These values will cache the latest values from the measurement
+      value for each phase of the switch.
+    """
+
+    rated_current: Optional[float] = None
+    """The maximum continuous current carrying capacity in amps governed by the device material and construction. The attribute shall be a positive value."""
+
+    _open: int = 0
+    """Tells if the switch is considered open when used as input to topology processing."""
+
+    _normally_open: int = 0
+    """The attribute is used in cases when no Measurement for the status value is present. If the Switch has a status measurement the Discrete.normalValue 
+    is expected to match with the Switch.normalOpen."""
+
+    @property
+    def switch_info(self) -> Optional[SwitchInfo]:
+        """Datasheet information for this Switch."""
+        return self.asset_info
+
+    @switch_info.setter
+    def switch_info(self, si: Optional[SwitchInfo]):
+        """
+        Set the :class:`SwitchInfo` for this :class:`Switch`
+        :param si: The SwitchInfo for this Switch
+        """
+        self.asset_info = si
+
+    def is_normally_open(self, phase: SinglePhaseKind = None) -> bool:
+        """
+        Check if the switch is normally open on `phase`.
+
+        `phase` The `single_phase_kind.SinglePhaseKind` to check the normal status. A `phase` of `None` (default) checks if any phase is open.
+        Returns True if `phase` is open in its normal state, False if it is closed
+        """
+        return _check_open(self._normally_open, phase)
+
+    def get_normal_state(self) -> int:
+        """
+        Get the underlying normal open states. Stored as 4 bits, 1 per phase.
+        """
+        return self._normally_open
+
+    def is_open(self, phase: SinglePhaseKind = None) -> bool:
+        """
+        Check if the switch is currently open on `phase`.
+
+        `phase` The `SinglePhaseKind` to check the current status. A `phase` of `None` (default) checks
+        if any phase is open.
+        Returns True if `phase` is open in its current state, False if it is closed
+        """
+        return _check_open(self._open, phase)
+
+    def get_state(self) -> int:
+        """
+        The attribute tells if the switch is considered open when used as input to topology processing.
+        Get the underlying open states. Stored as 4 bits, 1 per phase.
+        """
+        return self._open
+
+    def set_normally_open(self, is_normally_open: bool, phase: SinglePhaseKind = None) -> Switch:
+        """
+        `is_normally_open` indicates if the phase(s) should be opened.
+        `phase` the phase to set the normal status. If set to None will default to all phases.
+        Returns This `Switch` to be used fluently.
+        """
+        self._normally_open = _calculate_open_state(self._normally_open, is_normally_open, phase)
+        return self
+
+    def set_open(self, is_open: bool, phase: SinglePhaseKind = None) -> Switch:
+        """
+        `is_open` indicates if the phase(s) should be opened.
+        `phase` the phase to set the current status. If set to None will default to all phases.
+        Returns This `Switch` to be used fluently.
+        """
+        self._open = _calculate_open_state(self._open, is_open, phase)
+        return self