zepben.ewb 1.0.0b1__py3-none-any.whl

zepben/ewb/model/cim/iec61968/customers/customer.py

@@ -0,0 +1,93 @@
+#  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__ = ["Customer"]
+
+from typing import Optional, Generator, List, TYPE_CHECKING
+
+from zepben.ewb.model.cim.iec61968.common.organisation_role import OrganisationRole
+from zepben.ewb.model.cim.iec61968.customers.customer_kind import CustomerKind
+from zepben.ewb.util import nlen, get_by_mrid, ngen, safe_remove
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.iec61968.customers.customer_agreement import CustomerAgreement
+
+
+class Customer(OrganisationRole):
+    """
+    Organisation receiving services from service supplier.
+    """
+
+    kind: CustomerKind = CustomerKind.UNKNOWN
+    """Kind of customer"""
+
+    special_need: Optional[str] = None
+    """A special service need such as life support, hospitals, etc."""
+
+    _customer_agreements: Optional[List[CustomerAgreement]] = None
+
+    def __init__(self, customer_agreements: List[CustomerAgreement] = None, **kwargs):
+        super(Customer, self).__init__(**kwargs)
+        if customer_agreements:
+            for agreement in customer_agreements:
+                self.add_agreement(agreement)
+
+    def num_agreements(self) -> int:
+        """
+        Get the number of `CustomerAgreement`s associated with this `Customer`.
+        """
+        return nlen(self._customer_agreements)
+
+    @property
+    def agreements(self) -> Generator[CustomerAgreement, None, None]:
+        """
+        The `CustomerAgreement`s for this `Customer`.
+        """
+        return ngen(self._customer_agreements)
+
+    def get_agreement(self, mrid: str) -> CustomerAgreement:
+        """
+        Get the `CustomerAgreement` for this `Customer` identified by `mrid`.
+
+        `mrid` the mRID of the required `customer_agreement.CustomerAgreement`
+        Returns the `CustomerAgreement` with the specified `mrid`.
+        Raises `KeyError` if `mrid` wasn't present.
+        """
+        return get_by_mrid(self._customer_agreements, mrid)
+
+    def add_agreement(self, customer_agreement: CustomerAgreement) -> Customer:
+        """
+        Associate a `CustomerAgreement` with this `Customer`.
+        `customer_agreement` The `customer_agreement.CustomerAgreement` to associate with this `Customer`.
+        Returns A reference to this `Customer` to allow fluent use.
+        Raises `ValueError` if another `CustomerAgreement` with the same `mrid` already exists for this `Customer`
+        """
+        if self._validate_reference(customer_agreement, self.get_agreement, "A CustomerAgreement"):
+            return self
+
+        self._customer_agreements = list() if self._customer_agreements is None else self._customer_agreements
+        self._customer_agreements.append(customer_agreement)
+        return self
+
+    def remove_agreement(self, customer_agreement: CustomerAgreement) -> Customer:
+        """
+        Disassociate `customer_agreement` from this `Customer`.
+
+        `customer_agreement` the `customer_agreement.CustomerAgreement` to disassociate with this `Customer`.
+        Returns A reference to this `Customer` to allow fluent use.
+        Raises `ValueError` if `customer_agreement` was not associated with this `Customer`.
+        """
+        self._customer_agreements = safe_remove(self._customer_agreements, customer_agreement)
+        return self
+
+    def clear_agreements(self) -> Customer:
+        """
+        Clear all customer agreements.
+        Returns self
+        """
+        self._customer_agreements = None
+        return self

zepben/ewb/model/cim/iec61968/customers/customer_agreement.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/.
+
+from __future__ import annotations
+
+__all__ = ["CustomerAgreement"]
+
+from typing import Optional, Generator, List, TYPE_CHECKING
+
+from zepben.ewb.model.cim.iec61968.common.agreement import Agreement
+from zepben.ewb.util import nlen, get_by_mrid, ngen, safe_remove
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.iec61968.customers.customer import Customer
+    from zepben.ewb.model.cim.iec61968.customers.pricing_structure import PricingStructure
+
+
+class CustomerAgreement(Agreement):
+    """
+    Agreement between the customer and the service supplier to pay for service at a specific service location. It
+    records certain billing information about the type of service provided at the service location and is used
+    during charge creation to determine the type of service.
+    """
+
+    _customer: Optional[Customer] = None
+    """The `zepben.ewb.model.cim.iec61968.customers.customer.Customer` that has this `CustomerAgreement`."""
+
+    _pricing_structures: Optional[List[PricingStructure]] = None
+
+    def __init__(self, customer: Customer = None, pricing_structures: List[PricingStructure] = None, **kwargs):
+        super(CustomerAgreement, self).__init__(**kwargs)
+        if customer:
+            self.customer = customer
+        if pricing_structures:
+            for ps in pricing_structures:
+                self.add_pricing_structure(ps)
+
+    @property
+    def customer(self):
+        """The `Customer` that has this `CustomerAgreement`."""
+        return self._customer
+
+    @customer.setter
+    def customer(self, cust):
+        if self._customer is None or self._customer is cust:
+            self._customer = cust
+        else:
+            raise ValueError(f"customer for {str(self)} has already been set to {self._customer}, cannot reset this field to {cust}")
+
+    def num_pricing_structures(self):
+        """
+        The number of `PricingStructure`s associated with this `CustomerAgreement`
+        """
+        return nlen(self._pricing_structures)
+
+    @property
+    def pricing_structures(self) -> Generator[PricingStructure, None, None]:
+        """
+        The `PricingStructure`s of this `CustomerAgreement`.
+        """
+        return ngen(self._pricing_structures)
+
+    def get_pricing_structure(self, mrid: str) -> PricingStructure:
+        """
+        Get the `PricingStructure` for this `CustomerAgreement` identified by `mrid`
+
+        `mrid` the mRID of the required `PricingStructure`
+        Returns the `PricingStructure` with the specified `mrid` if it exists
+        Raises `KeyError` if `mrid` wasn't present.
+        """
+        return get_by_mrid(self._pricing_structures, mrid)
+
+    def add_pricing_structure(self, ps: PricingStructure) -> CustomerAgreement:
+        """
+        Associate `ps` with this `CustomerAgreement`
+
+        `ps` the `PricingStructure` to associate with this `CustomerAgreement`.
+        Returns A reference to this `CustomerAgreement` to allow fluent use.
+        Raises `ValueError` if another `PricingStructure` with the same `mrid` already exists for this `CustomerAgreement`
+        """
+        if self._validate_reference(ps, self.get_pricing_structure, "A PricingStructure"):
+            return self
+
+        self._pricing_structures = list() if self._pricing_structures is None else self._pricing_structures
+        self._pricing_structures.append(ps)
+        return self
+
+    def remove_pricing_structure(self, ps: PricingStructure) -> CustomerAgreement:
+        """
+        Disassociate `ps` from this `CustomerAgreement`
+
+        `ps` the `PricingStructure` to disassociate from this `CustomerAgreement`.
+        Returns A reference to this `CustomerAgreement` to allow fluent use.
+        Raises `ValueError` if `ps` was not associated with this `CustomerAgreement`.
+        """
+        self._pricing_structures = safe_remove(self._pricing_structures, ps)
+        return self
+
+    def clear_pricing_structures(self) -> CustomerAgreement:
+        """
+        Clear all pricing structures.
+        Returns a reference to this `CustomerAgreement` to allow fluent use.
+        """
+        self._pricing_structures = None
+        return self

zepben/ewb/model/cim/iec61968/customers/customer_kind.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__ = ["CustomerKind"]
+
+from enum import Enum, unique
+
+
+@unique
+class CustomerKind(Enum):
+    """
+    Kind of customer.
+    """
+
+    UNKNOWN = 0
+    """ Default """
+
+    commercialIndustrial = 1
+    """ Commercial industrial customer. """
+
+    energyServiceScheduler = 2
+    """ Customer as energy service scheduler. """
+
+    energyServiceSupplier = 3
+    """ Customer as energy service supplier. """
+
+    enterprise = 4
+    """ --- Missing form CIM --- """
+
+    internalUse = 5
+    """ Internal use customer. """
+
+    other = 6
+    """ Other kind of customer. """
+
+    pumpingLoad = 7
+    """ Pumping load customer. """
+
+    regionalOperator = 8
+    """ --- Missing form CIM --- """
+
+    residential = 9
+    """ Residential customer. """
+
+    residentialAndCommercial = 10
+    """ Residential and commercial customer. """
+
+    residentialAndStreetlight = 11
+    """ Residential and streetlight customer. """
+
+    residentialFarmService = 12
+    """ Residential farm service customer. """
+
+    residentialStreetlightOthers = 13
+    """ Residential streetlight or other related customer. """
+
+    subsidiary = 14
+    """ --- Missing form CIM --- """
+
+    windMachine = 15
+    """ Wind machine customer. """
+
+    @property
+    def short_name(self):
+        return str(self)[13:]

zepben/ewb/model/cim/iec61968/customers/pricing_structure.py

@@ -0,0 +1,88 @@
+#  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__ = ["PricingStructure"]
+
+from typing import Optional, Generator, List, TYPE_CHECKING
+
+from zepben.ewb.model.cim.iec61968.common.document import Document
+from zepben.ewb.util import get_by_mrid, nlen, ngen, safe_remove
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.iec61968.customers.tariff import Tariff
+
+
+class PricingStructure(Document):
+    """
+    Grouping of pricing components and prices used in the creation of customer charges and the eligibility
+    criteria under which these terms may be offered to a customer. The reasons for grouping include state,
+    customer classification, site characteristics, classification (i.e. fee price structure, deposit price
+    structure, electric service price structure, etc.) and accounting requirements.
+    """
+    _tariffs: Optional[List[Tariff]] = None
+
+    def __init__(self, tariffs: List[Tariff] = None, **kwargs):
+        super(PricingStructure, self).__init__(**kwargs)
+        if tariffs:
+            for tariff in tariffs:
+                self.add_tariff(tariff)
+
+    def num_tariffs(self):
+        """
+        Returns The number of `Tariff`s associated with this `PricingStructure`
+        """
+        return nlen(self._tariffs)
+
+    @property
+    def tariffs(self) -> Generator[Tariff, None, None]:
+        """
+        The `Tariff`s of this `PricingStructure`.
+        """
+        return ngen(self._tariffs)
+
+    def get_tariff(self, mrid: str) -> Tariff:
+        """
+        Get the `Tariff` for this `PricingStructure` identified by `mrid`
+
+        `mrid` the mRID of the required `Tariff`
+        Returns The `Tariff` with the specified `mrid` if it exists
+        Raises `KeyError` if `mrid` wasn't present.
+        """
+        return get_by_mrid(self._tariffs, mrid)
+
+    def add_tariff(self, tariff: Tariff) -> PricingStructure:
+        """
+        Associate a `Tariff` with this `PricingStructure`.
+
+        `tariff` the `Tariff` to associate with this `PricingStructure`.
+        Returns A reference to this `PricingStructure` to allow fluent use.
+        Raises `ValueError` if another `Tariff` with the same `mrid` already exists for this `PricingStructure`.
+        """
+        if self._validate_reference(tariff, self.get_tariff, "A Tariff"):
+            return self
+        self._tariffs = list() if self._tariffs is None else self._tariffs
+        self._tariffs.append(tariff)
+        return self
+
+    def remove_tariff(self, tariff: Tariff) -> PricingStructure:
+        """
+        Disassociate `tariff` from this `PricingStructure`.
+
+        `tariff` the `Tariff` to disassociate from this `PricingStructure`.
+        Returns A reference to this `PricingStructure` to allow fluent use.
+        Raises `ValueError` if `tariff` was not associated with this `PricingStructure`.
+        """
+        self._tariffs = safe_remove(self._tariffs, tariff)
+        return self
+
+    def clear_tariffs(self) -> PricingStructure:
+        """
+        Clear all tariffs.
+        Returns A reference to this `PricingStructure` to allow fluent use.
+        """
+        self._tariffs = None
+        return self

zepben/ewb/model/cim/iec61968/customers/tariff.py

@@ -0,0 +1,18 @@
+#  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__ = ["Tariff"]
+
+from zepben.ewb.model.cim.iec61968.common.document import Document
+
+
+class Tariff(Document):
+    """
+    Document, approved by the responsible regulatory agency, listing the terms and conditions,
+    including a schedule of prices, under which utility services will be provided. It has a
+    unique number within the state or province. For rate schedules it is frequently allocated
+    by the affiliated Public utilities commission (PUC).
+    """
+    pass

zepben/ewb/model/cim/iec61968/infiec61968/__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/infiec61968/infassetinfo/__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/infiec61968/infassetinfo/current_transformer_info.py

@@ -0,0 +1,51 @@
+#  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__ = ["CurrentTransformerInfo"]
+
+from typing import Optional
+
+from zepben.ewb.model.cim.iec61968.assets.asset_info import AssetInfo
+from zepben.ewb.model.cim.iec61968.infiec61968.infcommon.ratio import Ratio
+
+
+class CurrentTransformerInfo(AssetInfo):
+    """Properties of current transformer asset."""
+
+    accuracy_class: Optional[str] = None
+    """CT accuracy classification."""
+
+    accuracy_limit: Optional[float] = None
+    """Accuracy limit."""
+
+    core_count: Optional[int] = None
+    """Number of cores."""
+
+    ct_class: Optional[str] = None
+    """CT classification; i.e. class 10P."""
+
+    knee_point_voltage: Optional[int] = None
+    """Maximum voltage in volts across the secondary terminals where the CT still displays linear characteristics."""
+
+    max_ratio: Optional[Ratio] = None
+    """Maximum ratio between the primary and secondary current."""
+
+    nominal_ratio: Optional[Ratio] = None
+    """Nominal ratio between the primary and secondary current; i.e. 100:5"""
+
+    primary_ratio: Optional[float] = None
+    """Ratio for the primary winding tap changer (numerator)."""
+
+    rated_current: Optional[int] = None
+    """Rated current on the primary side in amperes."""
+
+    secondary_fls_rating: Optional[int] = None
+    """Full load secondary (FLS) rating for secondary winding in amperes."""
+
+    secondary_ratio: Optional[float] = None
+    """Ratio for the secondary winding tap changer (denominator)."""
+
+    usage: Optional[str] = None
+    """Intended usage of the CT; i.e. metering, protection."""

zepben/ewb/model/cim/iec61968/infiec61968/infassetinfo/potential_transformer_info.py

@@ -0,0 +1,33 @@
+#  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__ = ["PotentialTransformerInfo"]
+
+from typing import Optional
+
+from zepben.ewb.model.cim.iec61968.assets.asset_info import AssetInfo
+from zepben.ewb.model.cim.iec61968.infiec61968.infcommon.ratio import Ratio
+
+
+class PotentialTransformerInfo(AssetInfo):
+    """Properties of potential transformer asset."""
+
+    accuracy_class: Optional[str] = None
+    """PT accuracy classification."""
+
+    nominal_ratio: Optional[Ratio] = None
+    """Nominal ratio between the primary and secondary voltage."""
+
+    primary_ratio: Optional[float] = None
+    """Ratio for the primary winding tap changer (numerator)."""
+
+    pt_class: Optional[str] = None
+    """Potential transformer (PT) classification covering burden."""
+
+    rated_voltage: Optional[int] = None
+    """Rated voltage on the primary side in Volts."""
+
+    secondary_ratio: Optional[float] = None
+    """Ratio for the secondary winding tap changer (denominator)."""

zepben/ewb/model/cim/iec61968/infiec61968/infassetinfo/transformer_construction_kind.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__ = ["TransformerConstructionKind"]
+
+from enum import Enum, unique
+
+
+@unique
+class TransformerConstructionKind(Enum):
+    """
+    Kind of transformer construction.
+    """
+
+    unknown = 0
+    """"""
+
+    onePhase = 1
+    """"""
+
+    threePhase = 2
+    """"""
+
+    aerial = 3
+    """"""
+
+    overhead = 4
+    """"""
+
+    dryType = 5
+    """"""
+
+    network = 6
+    """"""
+
+    padmountDeadFront = 7
+    """"""
+
+    padmountFeedThrough = 8
+    """"""
+
+    padmountLiveFront = 9
+    """"""
+
+    padmountLoopThrough = 10
+    """"""
+
+    padmounted = 11
+    """"""
+
+    subway = 12
+    """"""
+
+    underground = 13
+    """"""
+
+    vault = 14
+    """"""
+
+    vaultThreePhase = 15
+    """"""
+
+    @property
+    def short_name(self):
+        return str(self)[28:]

zepben/ewb/model/cim/iec61968/infiec61968/infassetinfo/transformer_function_kind.py

@@ -0,0 +1,43 @@
+#  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__ = ["TransformerFunctionKind"]
+
+from enum import Enum, unique
+
+
+@unique
+class TransformerFunctionKind(Enum):
+    """
+    Function of a transformer.
+    """
+
+    UNKNOWN = 0
+    """Unknown type of transformer."""
+
+    voltageRegulator = 1
+    """ A transformer that changes the voltage magnitude at a certain point in the power system. """
+
+    distributionTransformer = 2
+    """ A transformer that provides the final voltage transformation in the electric power distribution system. """
+
+    isolationTransformer = 3
+    """ A transformer whose primary purpose is to isolate circuits. """
+
+    autotransformer = 4
+    """ A transformer with a special winding divided into several sections enabling the voltage to be varied at will. (IEC ref 811-26-04). """
+
+    powerTransformer = 5
+    """"""
+
+    secondaryTransformer = 6
+    """"""
+
+    other = 7
+    """ Another type of transformer. """
+
+    @property
+    def short_name(self):
+        return str(self)[24:]

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

@@ -0,0 +1,4 @@
+#  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/.

zepben/ewb/model/cim/iec61968/infiec61968/infassets/pole.py

@@ -0,0 +1,87 @@
+#  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/.
+
+from __future__ import annotations
+
+__all__ = ["Pole"]
+
+from typing import List, Optional, Generator, TYPE_CHECKING
+
+from zepben.ewb.model.cim.iec61968.assets.structure import Structure
+from zepben.ewb.util import get_by_mrid, ngen, nlen, safe_remove
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.iec61968.assets.streetlight import Streetlight
+
+
+class Pole(Structure):
+    """A Pole Asset"""
+
+    classification: str = ""
+    """Pole class: 1, 2, 3, 4, 5, 6, 7, H1, H2, Other, Unknown."""
+
+    _streetlights: Optional[List[Streetlight]] = None
+
+    def __init__(self, streetlights: List[Streetlight] = None, **kwargs):
+        super(Pole, self).__init__(**kwargs)
+        if streetlights:
+            for light in streetlights:
+                self.add_streetlight(light)
+
+    def num_streetlights(self) -> int:
+        """
+        Get the number of `Streetlight`s associated with this `Pole`.
+        """
+        return nlen(self._streetlights)
+
+    @property
+    def streetlights(self) -> Generator[Streetlight, None, None]:
+        """
+        The `Streetlight`s of this `Pole`.
+        """
+        return ngen(self._streetlights)
+
+    def get_streetlight(self, mrid: str) -> Streetlight:
+        """
+        Get the `Streetlight` for this asset identified by `mrid`.
+
+        `mrid` the mRID of the required `Streetlight`
+        Returns The `Streetlight` with the specified `mrid`.
+        Raises `KeyError` if `mrid` wasn't present.
+        """
+        return get_by_mrid(self._streetlights, mrid)
+
+    def add_streetlight(self, streetlight: Streetlight) -> Pole:
+        """
+        Associate a `Streetlight` with this `Pole`
+
+        `streetlight` the `Streetlight` to associate with this `Pole`.
+        Returns A reference to this `Pole` to allow fluent use.
+        Raises `ValueError` if another `Streetlight` with the same `mrid` already exists in this `Pole`
+        """
+        if self._validate_reference(streetlight, self.get_streetlight, "A Streetlight"):
+            return self
+
+        self._streetlights = list() if self._streetlights is None else self._streetlights
+        self._streetlights.append(streetlight)
+        return self
+
+    def remove_streetlight(self, streetlight: Streetlight) -> Pole:
+        """
+        Disassociate `streetlight` from this `Pole`
+        `streetlight` the `Streetlight` to disassociate from this `Pole`.
+        Raises `ValueError` if `streetlight` was not associated with this `Pole`.
+        Returns A reference to this `Pole` to allow fluent use.
+        """
+        self._streetlights = safe_remove(self._streetlights, streetlight)
+        return self
+
+    def clear_streetlights(self) -> Pole:
+        """
+        Clear all Streetlights.
+        Returns self
+        """
+        self._streetlights = None
+        return self