power-grid-model-ds 0.0.1a11709467271__py3-none-any.whl

power_grid_model_ds/_core/model/containers/base.py

@@ -0,0 +1,244 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""Stores the FancyArrayContainer class"""
+
+import dataclasses
+import inspect
+import logging
+from dataclasses import dataclass
+from typing import Type, TypeVar
+
+import numpy as np
+
+from power_grid_model_ds._core import fancypy as fp
+from power_grid_model_ds._core.model.arrays.base.array import FancyArray
+from power_grid_model_ds._core.model.arrays.base.errors import RecordDoesNotExist
+from power_grid_model_ds._core.model.constants import EMPTY_ID
+
+Self = TypeVar("Self", bound="FancyArrayContainer")
+
+
+@dataclass
+class FancyArrayContainer:
+    """
+    Base class for ArrayContainers.
+    Contains general functionality that is nonspecific to the type of array being stored.
+    """
+
+    _id_counter: int
+
+    @property
+    def id_counter(self):
+        """Returns the private _id_counter field (as read-only)"""
+        return self._id_counter
+
+    @classmethod
+    def empty(cls: Type[Self]) -> Self:
+        """Create an empty grid"""
+        empty_fields = cls._get_empty_fields()
+        return cls(**empty_fields)
+
+    def all_arrays(self):
+        """Returns all arrays in the container."""
+
+        for field in dataclasses.fields(self):
+            attribute = getattr(self, field.name)
+            if isinstance(attribute, FancyArray):
+                yield attribute
+
+    @classmethod
+    def find_array_field(cls, array_type: Type[FancyArray]) -> dataclasses.Field:
+        """Find the Field that holds an array of type array_type.
+
+        Args:
+            array_type(type[FancyArray]): FancyArray subclass.
+
+        Raises:
+            TypeError: if no field with the given `array_type` is found or if multiple fields are found.
+
+        Returns:
+            a Field instance.
+        """
+        fields = [
+            field
+            for field in dataclasses.fields(cls)
+            if inspect.isclass(field.type) and issubclass(field.type, array_type)
+        ]
+        if (nr_fields := len(fields)) != 1:
+            raise TypeError(
+                f"Expected to find 1 array with type '{array_type.__name__}' in {cls.__name__} ({nr_fields} found)"
+            )
+        return fields[0]
+
+    @property
+    def max_id(self) -> int:
+        """Returns the max id across all arrays within the container."""
+        max_per_array = [np.max(array.id) if array.size > 0 else 0 for array in self.all_arrays()]
+        return int(max(max_per_array))
+
+    def check_ids(self, check_between_arrays: bool = True, check_within_arrays: bool = True) -> None:
+        """Checks for duplicate id values across all arrays in the container.
+
+        Args:
+            check_between_arrays(bool): whether to check for duplicate ids across arrays
+            check_within_arrays(bool): whether to check for duplicate ids within each array
+
+        Raises:
+            ValueError: if duplicates are found.
+        """
+
+        id_arrays = [array for array in self.all_arrays() if hasattr(array, "id")]
+        if not id_arrays:
+            return  # no arrays to check
+
+        duplicates_between_arrays = self._get_duplicates_between_arrays(
+            id_arrays, check=check_between_arrays
+        )  # if check_between_arrays else []
+        arrays_with_duplicates = self._get_arrays_with_duplicates(id_arrays, check=check_within_arrays)
+
+        if not any(duplicates_between_arrays) and not any(arrays_with_duplicates):
+            return
+
+        if any(duplicates_between_arrays):
+            logging.warning(f"The following ids occur in multiple arrays: {duplicates_between_arrays}!")
+        for array_class in arrays_with_duplicates:
+            logging.warning(f"{array_class.__name__} contains duplicates!")
+
+        raise ValueError(f"Duplicates found within {self.__class__.__name__}!")
+
+    def append(self, array: FancyArray, check_max_id: bool = True) -> None:
+        """Append the given asset_array to the corresponding field of ArrayContainer and generate ids.
+
+        Args:
+            array(FancyArray): the asset_array to be appended (e.g. a NodeArray instance).
+            check_max_id(bool): whether to check max(array.id) with the id counter
+
+        Returns:
+            None
+        """
+        self._append(array=array, check_max_id=check_max_id)
+
+    def attach_ids(self, array: FancyArray) -> FancyArray:
+        """Generate and attach ids to the given FancyArray. Also updates _id_counter.
+
+        Args:
+            array(FancyArray): the array of which the id column is set.
+
+        Returns:
+            FancyArray: initial array with updated `id` column.
+        """
+        if not array.size:
+            return array
+
+        if (id_set := set(array.id)) != {array.get_empty_value("id")}:
+            raise ValueError(f"Cannot attach ids to array that contains non-empty ids: {id_set}")
+
+        start = self._id_counter + 1
+        end = start + len(array)
+        array.id = np.arange(start, end)
+        self._id_counter = max(self._id_counter, end - 1)
+
+        return array
+
+    def search_for_id(self, record_id: int) -> list[FancyArray]:
+        """Attempts to find a record across all id-arrays within the container.
+
+        This method is only intended for debugging purposes since it is very inefficient.
+        In normal circumstances you should use ``get`` or ``filter`` to find records within a specific array.
+
+        Args:
+            record_id(int): the id of the record to be found.
+
+        Returns:
+         list[FancyArray]:a list of arrays that contain the given record_id.
+         Each array within the list contains all records with the given array.
+        """
+
+        logging.warning("Using search_for_id(). Make sure to use only while debugging!")
+
+        arrays_with_record = []
+
+        id_arrays = [array for array in self.all_arrays() if "id" in array.dtype.names]
+        for id_array in id_arrays:
+            matching_records = id_array.filter(id=record_id)
+            if matching_records.size:
+                arrays_with_record.append(matching_records)
+
+        if arrays_with_record:
+            return arrays_with_record
+        raise RecordDoesNotExist(f"record id '{record_id}' not found in {self.__class__.__name__}")
+
+    def _append(self, array: FancyArray, check_max_id: bool = True) -> None:
+        """
+        Append the given asset_array to the corresponding field of Grid and generate ids.
+        Args:
+            array: the asset_array to be appended (e.g. a KabelArray instance).
+            check_max_id: whether to check max(array.id) with the id counter
+        Returns: None.
+        """
+        if array.size == 0:
+            return
+
+        array_field = self.find_array_field(array.__class__)
+
+        if hasattr(array, "id"):
+            self._update_id_counter(array, check_max_id)
+
+        # Add the given asset_array to the corresponding array in the Grid.
+        array_attr = getattr(self, array_field.name)
+        appended = fp.concatenate(array_attr, array)
+        setattr(self, array_field.name, appended)
+
+    @classmethod
+    def _get_empty_fields(cls) -> dict:
+        empty_fields = {}
+
+        empty_fields.update(cls._get_empty_arrays())
+        empty_fields.update({"_id_counter": 0})
+        return empty_fields
+
+    @classmethod
+    def _get_empty_arrays(cls) -> dict:
+        return {
+            field.name: field.type()
+            for field in dataclasses.fields(cls)
+            if inspect.isclass(field.type) and issubclass(field.type, FancyArray)
+        }
+
+    def _update_id_counter(self, array, check_max_id: bool = True):
+        if np.all(array.id == EMPTY_ID):
+            array = self.attach_ids(array)
+        elif np.any(array.id == EMPTY_ID):
+            raise ValueError(f"Cannot append: array contains empty [{EMPTY_ID}] and non-empty ids.")
+
+        new_max_id = np.max(array.id)
+        if check_max_id and new_max_id < self._id_counter:
+            raise ValueError(f"Cannot append: id {new_max_id} is lower than the id counter")
+
+        # Update _id_counter
+        self._id_counter = max(self._id_counter, new_max_id)
+
+    @staticmethod
+    def _get_duplicates_between_arrays(id_arrays: list[FancyArray], check: bool) -> np.ndarray:
+        if not check:
+            return np.array([])
+        unique_ids_per_array = [np.unique(array.id) for array in id_arrays]
+
+        all_ids = np.concatenate(unique_ids_per_array)
+
+        unique_ids, counts = np.unique(all_ids, return_counts=True)
+        duplicate_mask = counts > 1
+        return unique_ids[duplicate_mask]
+
+    @staticmethod
+    def _get_arrays_with_duplicates(id_arrays: list[FancyArray], check: bool) -> list:
+        arrays_with_duplicates: list[Type] = []
+        if not check:
+            return arrays_with_duplicates
+        for id_array in id_arrays:
+            duplicates: np.ndarray = id_array.check_ids(return_duplicates=True)
+            if duplicates.size > 0:
+                arrays_with_duplicates.append(id_arrays.__class__)
+        return arrays_with_duplicates

power_grid_model_ds/_core/model/containers/grid_protocol.py

@@ -0,0 +1,22 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+"""This file contains the Grid protocol defining the minimal arrays contained in a grid"""
+
+from typing import Protocol
+
+from power_grid_model_ds._core.model.arrays import (
+    BranchArray,
+    NodeArray,
+    ThreeWindingTransformerArray,
+)
+
+
+class MinimalGridArrays(Protocol):
+    """Protocol for the minimal arrays contained in a grid,
+    they may be implemented using properties or added as attributes"""
+
+    node: NodeArray
+    three_winding_transformer: ThreeWindingTransformerArray
+    branches: BranchArray
+    branch_arrays: list[BranchArray]

power_grid_model_ds/_core/model/dtypes/appliances.py

@@ -0,0 +1,39 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""Appliance data types"""
+
+import numpy as np
+from numpy.typing import NDArray
+
+from power_grid_model_ds._core.model.dtypes.id import Id
+
+
+class Appliance(Id):
+    """Appliance data type"""
+
+    node: NDArray[np.int32]  # id of the coupled node
+    status: NDArray[np.int8]  # connection status to the node
+
+
+class Source(Appliance):
+    """Source data type"""
+
+    u_ref: NDArray[np.float64]  # reference voltage
+
+
+class SymLoad(Appliance):
+    """SymLoad data type"""
+
+    type: NDArray[np.int8]  # load type
+    p_specified: NDArray[np.float64]  # specified active power
+    q_specified: NDArray[np.float64]  # specified reactive power
+
+
+class SymGen(Appliance):
+    """SymGen data type"""
+
+    type: NDArray[np.int_]  # load type
+    p_specified: NDArray[np.float64]  # specified active power
+    q_specified: NDArray[np.float64]  # specified reactive power

power_grid_model_ds/_core/model/dtypes/branches.py

@@ -0,0 +1,117 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""Branch data types"""
+
+import numpy as np
+from numpy.typing import NDArray
+
+from power_grid_model_ds._core.model.constants import empty
+from power_grid_model_ds._core.model.dtypes.id import Id
+
+
+class Branch(Id):
+    """Branch data type"""
+
+    from_node: NDArray[np.int32]  # node id (from-side)
+    to_node: NDArray[np.int32]  # node id (to-side)
+    from_status: NDArray[np.int8]  # 1 = closed, 0 = open
+    to_status: NDArray[np.int8]  # 1 = closed, 0 = open
+    feeder_branch_id: NDArray[np.int32]  # branch id of the feeding branch
+    feeder_node_id: NDArray[np.int32]  # node id of the feeding node
+    is_feeder: NDArray[np.bool_]  # whether or not this branch is from the substation
+
+    _defaults = {
+        "feeder_branch_id": empty,
+        "feeder_node_id": empty,
+        "is_feeder": False,
+    }
+
+
+class Link(Branch):
+    """Link data type"""
+
+
+class Line(Branch):
+    """Line data type"""
+
+    r1: NDArray[np.float64]  # serial resistance
+    x1: NDArray[np.float64]  # serial reactance
+    c1: NDArray[np.float64]  # shunt capacitance
+    tan1: NDArray[np.float64]  # shunt loss factor
+    i_n: NDArray[np.float64]  # rated current
+
+
+class Transformer(Branch):
+    """Transformer data type"""
+
+    u1: NDArray[np.float64]  # rated voltage (from-side)
+    u2: NDArray[np.float64]  # rated voltage (to-side)
+    sn: NDArray[np.float64]  # rated power
+    tap_size: NDArray[np.float64]  # size of each tap of the tap changer
+    uk: NDArray[np.float64]  # relative short circuit voltage
+    pk: NDArray[np.float64]  # short circuit loss
+    i0: NDArray[np.float64]  # relative no-load current
+    p0: NDArray[np.float64]  # no-load loss
+    winding_from: NDArray[np.int8]  # winding type (from-side)
+    winding_to: NDArray[np.int8]  # winding type (to-side)
+    clock: NDArray[np.int8]  # clock number of phase shift
+    tap_side: NDArray[np.int8]  # side of tap changer
+    tap_pos: NDArray[np.int8]  # current position of tap changer
+    tap_min: NDArray[np.int8]  # position of tap changer at minimum voltage
+    tap_max: NDArray[np.int8]  # position of tap changer at maximum voltage
+    tap_nom: NDArray[np.int8]  # nominal position of tap changer
+
+
+class Branch3(Id):
+    """Branch3 data type"""
+
+    node_1: NDArray[np.int32]
+    node_2: NDArray[np.int32]
+    node_3: NDArray[np.int32]
+    status_1: NDArray[np.int8]
+    status_2: NDArray[np.int8]
+    status_3: NDArray[np.int8]
+
+
+class ThreeWindingTransformer(Branch3):
+    """ThreeWindingTransformer data type"""
+
+    u1: NDArray[np.float64]
+    u2: NDArray[np.float64]
+    u3: NDArray[np.float64]
+    sn_1: NDArray[np.float64]
+    sn_2: NDArray[np.float64]
+    sn_3: NDArray[np.float64]
+    uk_12: NDArray[np.float64]
+    uk_13: NDArray[np.float64]
+    uk_23: NDArray[np.float64]
+    pk_12: NDArray[np.float64]
+    pk_13: NDArray[np.float64]
+    pk_23: NDArray[np.float64]
+    i0: NDArray[np.float64]
+    p0: NDArray[np.float64]
+    winding_1: NDArray[np.int8]
+    winding_2: NDArray[np.int8]
+    winding_3: NDArray[np.int8]
+    clock_12: NDArray[np.int8]
+    clock_13: NDArray[np.int8]
+    tap_side: NDArray[np.int8]
+    tap_pos: NDArray[np.int8]
+    tap_min: NDArray[np.int8]
+    tap_max: NDArray[np.int8]
+    tap_nom: NDArray[np.int8]
+    tap_size: NDArray[np.float64]
+    uk_12_min: NDArray[np.float64]
+    uk_13_min: NDArray[np.float64]
+    uk_23_min: NDArray[np.float64]
+    pk_12_min: NDArray[np.float64]
+    pk_13_min: NDArray[np.float64]
+    pk_23_min: NDArray[np.float64]
+    uk_12_max: NDArray[np.float64]
+    uk_13_max: NDArray[np.float64]
+    uk_23_max: NDArray[np.float64]
+    pk_12_max: NDArray[np.float64]
+    pk_13_max: NDArray[np.float64]
+    pk_23_max: NDArray[np.float64]

power_grid_model_ds/_core/model/dtypes/id.py

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""Base data types"""
+
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from power_grid_model_ds._core.model.constants import empty
+
+
+class Id:
+    """Base dtype for id arrays"""
+
+    _defaults: dict[str, Any] = {"id": empty}
+    id: NDArray[np.int32]

power_grid_model_ds/_core/model/dtypes/nodes.py

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""Node data types"""
+
+import numpy as np
+from numpy.typing import NDArray
+
+from power_grid_model_ds._core.model.constants import empty
+from power_grid_model_ds._core.model.dtypes.id import Id
+from power_grid_model_ds._core.model.enums.nodes import NodeType
+
+
+class Node(Id):
+    """Node data type"""
+
+    u_rated: NDArray[np.float64]  # rated line-line voltage
+    node_type: NDArray[np.int8]
+    feeder_branch_id: NDArray[np.int32]  # branch id of the feeder
+    feeder_node_id: NDArray[np.int32]  # node id of the first substation node
+
+    _defaults = {
+        "node_type": NodeType.UNSPECIFIED.value,
+        "feeder_branch_id": empty,
+        "feeder_node_id": empty,
+    }

power_grid_model_ds/_core/model/dtypes/regulators.py

@@ -0,0 +1,30 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+import numpy as np
+from numpy.typing import NDArray
+
+from power_grid_model_ds._core.model.dtypes.id import Id
+
+
+class Regulator(Id):
+    "Regulator data type"
+
+    regulated_object: NDArray[np.int32]  # a valid regulated object ID
+    status: NDArray[np.int8]  # connection status of regulated object
+
+
+class TransformerTapRegulator(Regulator):
+    """Transformer tap regulator data type"""
+
+    control_side: NDArray[np.int8]  # the controlled side of the transformer (see BranchSide/Branch3Side of PGM)
+    u_set: NDArray[np.float64]  # the voltage setpoint
+    u_band: NDArray[np.float64]  # the width of the voltage band
+    line_drop_compensation_r: NDArray[np.float64]  # compensation for voltage drop due to resistance during transport
+    line_drop_compensation_x: NDArray[np.float64]  # compensation for voltage drop due to reactance during transport
+
+    _defaults = {
+        "line_drop_compensation_r": 0,
+        "line_drop_compensation_x": 0,
+    }

power_grid_model_ds/_core/model/dtypes/sensors.py

@@ -0,0 +1,63 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""
+Sensor data types
+Based on the sensors defined in power grid model:
+https://power-grid-model.readthedocs.io/en/v1.9.13/user_manual/components.html#sensor
+"""
+
+from typing import Annotated, Literal, TypeVar
+
+import numpy as np
+from numpy.typing import NDArray
+
+from power_grid_model_ds._core.model.dtypes.id import Id
+
+# define structural arrays with 3 values for 3-phase variables
+# based on https://stackoverflow.com/a/72585748
+_DT = TypeVar("_DT", bound=np.generic)
+NDArray3 = Annotated[NDArray[_DT], Literal[3]]
+
+
+class Sensor(Id):
+    """Base class for sensor data type"""
+
+    measured_object: NDArray[np.int32]
+
+
+class GenericPowerSensor(Sensor):
+    """Base class for power sensor data type"""
+
+    measured_terminal_type: NDArray[np.int32]
+    power_sigma: NDArray[np.float64]  # std of total power
+
+
+class SymPowerSensor(GenericPowerSensor):
+    """SymPowerSensor data type"""
+
+    p_measured: NDArray[np.float64]  # measured active power
+    q_measured: NDArray[np.float64]  # measured reactive power
+    p_sigma: NDArray[np.float64]  # std of active power
+    q_sigma: NDArray[np.float64]  # std of reactive power
+
+
+class GenericVoltageSensor(Sensor):
+    """Base class for voltage sensor data type"""
+
+
+class SymVoltageSensor(GenericVoltageSensor):
+    """SymVoltageSensor data type"""
+
+    u_sigma: NDArray[np.float64]  # std of voltage
+    u_measured: NDArray[np.float64]  # measured voltage
+    u_angle_measured: NDArray[np.float64]  # measured phase
+
+
+class AsymVoltageSensor(GenericVoltageSensor):
+    """AsymVoltageSensor data type"""
+
+    u_sigma: NDArray3[np.float64]  # std of 3 voltages
+    u_measured: NDArray3[np.float64]  # measured 3 voltages
+    u_angle_measured: NDArray3[np.float64]  # measured 3 phases

power_grid_model_ds/_core/model/enums/nodes.py

@@ -0,0 +1,16 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""Enums for Nodes"""
+
+from enum import IntEnum
+
+
+class NodeType(IntEnum):
+    """Node Types
+    Nodes located within a substation, are marked as Substation nodes.
+    """
+
+    UNSPECIFIED = 0
+    SUBSTATION_NODE = 1