power-grid-model 1.12.69__py3-none-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl

power_grid_model/_core/data_handling.py

@@ -0,0 +1,195 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""
+Data handling
+"""
+
+from typing import Literal, overload
+
+import numpy as np
+
+from power_grid_model._core.data_types import (
+    BatchDataset,
+    Dataset,
+    DenseBatchArray,
+    SingleArray,
+    SingleColumnarData,
+    SingleDataset,
+)
+from power_grid_model._core.dataset_definitions import ComponentType, ComponentTypeVar, DatasetType
+from power_grid_model._core.enum import CalculationType, ComponentAttributeFilterOptions
+from power_grid_model._core.errors import PowerGridUnreachableHitError
+from power_grid_model._core.power_grid_dataset import CConstDataset, CMutableDataset
+from power_grid_model._core.power_grid_meta import initialize_array, power_grid_meta_data
+from power_grid_model._core.typing import ComponentAttributeMapping, ComponentAttributeMappingDict
+from power_grid_model._core.utils import process_data_filter
+from power_grid_model.data_types import DenseBatchColumnarData
+
+
+def get_output_type(*, calculation_type: CalculationType, symmetric: bool) -> DatasetType:
+    """
+    Get the output type based on the provided arguments.
+
+    Args:
+        calculation_type:
+            request the output type for a specific calculation type (power_flow, state_estimation, ...)
+        symmetric:
+            True: three-phase symmetric calculation, even for asymmetric loads/generations
+            False: three-phase asymmetric calculation
+
+    Returns:
+        the output type that fits the format requested by the output type
+    """
+    if calculation_type in (CalculationType.power_flow, CalculationType.state_estimation):
+        return DatasetType.sym_output if symmetric else DatasetType.asym_output
+
+    if calculation_type == CalculationType.short_circuit:
+        return DatasetType.sc_output
+
+    raise NotImplementedError
+
+
+def prepare_input_view(input_data: SingleDataset) -> CConstDataset:
+    """
+    Create a view of the input data in a format compatible with the PGM core libary.
+
+    Args:
+        input_data:
+            the input data to create the view from
+
+    Returns:
+        instance of CConstDataset ready to be fed into C API
+    """
+    return CConstDataset(input_data, dataset_type=DatasetType.input)
+
+
+def prepare_update_view(update_data: Dataset) -> CConstDataset:
+    """
+    Create a view of the update data, or an empty view if not provided, in a format compatible with the PGM core libary.
+
+    Args:
+        update_data:
+            the update data to create the view from. Defaults to None
+
+    Returns:
+        instance of CConstDataset ready to be fed into C API
+    """
+    return CConstDataset(update_data, dataset_type=DatasetType.update)
+
+
+def prepare_output_view(output_data: Dataset, output_type: DatasetType) -> CMutableDataset:
+    """
+    create a view of the output data in a format compatible with the PGM core libary.
+
+    Args:
+        output_data:
+            the output data to create the view from
+        output_type:
+            the output type of the output_data
+
+    Returns:
+        instance of CMutableDataset ready to be fed into C API
+    """
+    return CMutableDataset(output_data, dataset_type=output_type)
+
+
+@overload
+def create_output_data(
+    output_component_types: None | set[ComponentTypeVar] | list[ComponentTypeVar],
+    output_type: DatasetType,
+    all_component_count: dict[ComponentType, int],
+    is_batch: Literal[False],
+    batch_size: int,
+) -> dict[ComponentType, SingleArray]: ...
+@overload
+def create_output_data(
+    output_component_types: None | set[ComponentTypeVar] | list[ComponentTypeVar],
+    output_type: DatasetType,
+    all_component_count: dict[ComponentType, int],
+    is_batch: Literal[True],
+    batch_size: int,
+) -> dict[ComponentType, DenseBatchArray]: ...
+@overload
+def create_output_data(
+    output_component_types: ComponentAttributeFilterOptions,
+    output_type: DatasetType,
+    all_component_count: dict[ComponentType, int],
+    is_batch: Literal[False],
+    batch_size: int,
+) -> dict[ComponentType, SingleColumnarData]: ...
+@overload
+def create_output_data(
+    output_component_types: ComponentAttributeFilterOptions,
+    output_type: DatasetType,
+    all_component_count: dict[ComponentType, int],
+    is_batch: Literal[True],
+    batch_size: int,
+) -> dict[ComponentType, DenseBatchColumnarData]: ...
+@overload
+def create_output_data(
+    output_component_types: ComponentAttributeMappingDict,
+    output_type: DatasetType,
+    all_component_count: dict[ComponentType, int],
+    is_batch: Literal[False],
+    batch_size: int,
+) -> SingleDataset: ...
+@overload
+def create_output_data(
+    output_component_types: ComponentAttributeMappingDict,
+    output_type: DatasetType,
+    all_component_count: dict[ComponentType, int],
+    is_batch: Literal[True],
+    batch_size: int,
+) -> BatchDataset: ...
+def create_output_data(
+    output_component_types: ComponentAttributeMapping,
+    output_type: DatasetType,
+    all_component_count: dict[ComponentType, int],
+    is_batch: bool,
+    batch_size: int,
+) -> Dataset:
+    """
+    Create the output dataset based on component and batch size from the model; and output attributes requested by user.
+
+    Args:
+        output_component_types (ComponentAttributeMapping):
+            the output components the user seeks to extract
+        output_type:
+            the type of output that the user will see (as per the calculation options)
+        all_component_count:
+            the amount of components in the grid (as per the input data)
+        is_batch:
+            if the dataset is batch
+        batch_size:
+            the batch size
+
+    Returns:
+        Dataset: output dataset
+    """
+    processed_output_types = process_data_filter(output_type, output_component_types, list(all_component_count.keys()))
+
+    all_component_count = {k: v for k, v in all_component_count.items() if k in processed_output_types}
+
+    # create result dataset
+    result_dict: Dataset = {}
+
+    for name, count in all_component_count.items():
+        shape: tuple[int, int] | int = (batch_size, count) if is_batch else count
+
+        requested_component = processed_output_types[name]
+        dtype = power_grid_meta_data[output_type][name].dtype
+        if dtype.names is None:
+            raise PowerGridUnreachableHitError
+        if requested_component is None:
+            result_dict[name] = initialize_array(output_type, name, shape=shape, empty=True)
+        elif requested_component in [
+            ComponentAttributeFilterOptions.everything,
+            ComponentAttributeFilterOptions.relevant,
+        ]:
+            result_dict[name] = {attr: np.empty(shape=shape, dtype=dtype[attr]) for attr in dtype.names}
+        elif isinstance(requested_component, list | set):
+            result_dict[name] = {attr: np.empty(shape=shape, dtype=dtype[attr]) for attr in requested_component}
+
+    return result_dict

power_grid_model/_core/data_types.py

@@ -0,0 +1,143 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""
+Data types involving PGM datasets.
+
+Data types for library-internal use. In an attempt to clarify type hints, some types
+have been defined and explained in this file.
+"""
+
+from typing import TypeAlias, TypedDict, TypeVar
+
+import numpy as np
+
+from power_grid_model._core.dataset_definitions import ComponentType, ComponentTypeVar
+
+SingleArray: TypeAlias = np.ndarray
+
+AttributeType: TypeAlias = str
+
+SingleColumn: TypeAlias = np.ndarray
+
+DenseBatchArray: TypeAlias = np.ndarray
+
+SingleColumnarData = dict[AttributeType, SingleColumn]
+
+_SingleComponentData = TypeVar("_SingleComponentData", SingleArray, SingleColumnarData)  # deduction helper
+SingleComponentData = SingleArray | SingleColumnarData
+
+SingleRowBasedDataset = dict[ComponentTypeVar, SingleArray]
+SingleColumnarDataset = dict[ComponentTypeVar, SingleColumnarData]
+SingleDataset = dict[ComponentTypeVar, _SingleComponentData]
+
+BatchList = list[SingleDataset]
+
+BatchColumn: TypeAlias = np.ndarray
+
+DenseBatchColumnarData = dict[AttributeType, BatchColumn]
+
+IndexPointer: TypeAlias = np.ndarray
+
+
+class SparseBatchColumnarData(TypedDict):
+    """
+    Sparse batch columnar data is a dictionary containing the keys `indptr` and `data`.
+
+    - data: a :class:`SingleColumnarData`. The exact supported attribute columns depend on the component type.
+    - indptr: an :class:`IndexPointer` representing the start and end indices for each batch scenario.
+
+    - Examples:
+
+        - structure: {"indptr": :class:`IndexPointer`, "data": :class:`SingleColumnarData`}
+        - concrete example: {"indptr": [0, 2, 2, 3], "data": {"id": [0, 1, 0], "status": [1, 1, 0]}}
+
+            - the scenario 0 sets the status of components with ids 0 and 1 to 1
+              (and keeps defaults for other components)
+            - scenario 1 keeps the default values for all components
+            - scenario 2 sets the status of component with id 0 to 0 (and keeps defaults for other components)
+    """
+
+    indptr: IndexPointer
+    data: SingleColumnarData
+
+
+class SparseBatchArray(TypedDict):
+    """
+    A sparse batch array is a dictionary containing the keys `indptr` and `data`.
+
+    - data: a :class:`SingleArray`. The exact dtype depends on the type of component.
+    - indptr: an :class:`IndexPointer` representing the start and end indices for each batch scenario.
+
+    - Examples:
+
+        - structure: {"indptr": :class:`IndexPointer`, "data": :class:`SingleArray`}
+        - concrete example: {"indptr": [0, 2, 2, 3], "data": [(0, 1, 1), (1, 1, 1), (0, 0, 0)]}
+
+            - the scenario 0 sets the statuses of components with ids 0 and 1 to 1
+              (and keeps defaults for other components)
+            - scenario 1 keeps the default values for all components
+            - scenario 2 sets the statuses of component with id 0 to 0 (and keeps defaults for other components)
+    """
+
+    indptr: IndexPointer
+    data: SingleArray
+
+
+SparseBatchData = SparseBatchArray | SparseBatchColumnarData
+
+SparseDataComponentType: TypeAlias = str
+
+BatchColumnarData = DenseBatchColumnarData | SparseBatchColumnarData
+
+ColumnarData = SingleColumnarData | BatchColumnarData
+BatchArray = DenseBatchArray | SparseBatchArray
+
+
+BatchComponentData = BatchArray | BatchColumnarData
+
+_BatchComponentData = TypeVar("_BatchComponentData", BatchArray, BatchColumnarData)  # deduction helper
+
+
+BatchDataset = dict[ComponentTypeVar, _BatchComponentData]
+
+
+DataArray = SingleArray | BatchArray
+
+
+_ComponentData = TypeVar("_ComponentData", SingleComponentData, BatchComponentData)  # deduction helper
+ComponentData = DataArray | ColumnarData
+
+Dataset = dict[ComponentTypeVar, _ComponentData]
+
+
+DenseBatchData = DenseBatchArray | DenseBatchColumnarData
+
+# overloads that only match on latest PGM type
+SingleRowBasedOutputDataset = dict[ComponentType, SingleArray]
+SingleColumnarOutputDataset = dict[ComponentType, SingleColumnarData]
+SingleOutputDataset = dict[ComponentType, SingleComponentData]
+DenseBatchRowBasedOutputDataset = dict[ComponentType, DenseBatchArray]
+DenseBatchColumnarOutputDataset = dict[ComponentType, DenseBatchColumnarData]
+DenseBatchOutputDataset = dict[ComponentType, DenseBatchData]
+OutputDataset = dict[ComponentType, ComponentData]
+
+
+NominalValue = int
+
+RealValue = float
+
+AsymValue = tuple[RealValue, RealValue, RealValue]
+
+AttributeValue = RealValue | NominalValue | AsymValue
+
+Component = dict[AttributeType, AttributeValue | str]
+
+ComponentList = list[Component]
+
+SinglePythonDataset = dict[ComponentTypeVar, ComponentList]
+
+BatchPythonDataset = list[SinglePythonDataset]
+
+PythonDataset = SinglePythonDataset | BatchPythonDataset

power_grid_model/_core/dataset_definitions.py

@@ -0,0 +1,109 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""Data types for power grid model dataset and component types."""
+
+# This file is automatically generated. DO NOT modify it manually!
+
+from collections.abc import Mapping
+from enum import Enum, EnumMeta
+from typing import Any, TypeAlias, TypeVar
+
+# fmt: off
+
+class _MetaEnum(EnumMeta):
+    def __contains__(cls, member):
+        """
+        Check if member is part of the Enum.
+
+        Args:
+            member: Member to check.
+
+        Returns:
+            bool: True if the member is part of the Enum, False otherwise.
+        """
+        return member in cls.__members__
+
+
+class DatasetType(str, Enum, metaclass=_MetaEnum):
+    """
+    A DatasetType is the type of a :class:`Dataset` in power grid model.
+
+    - Examples:
+
+        - DatasetType.input = "input"
+        - DatasetType.update = "update"
+    """
+
+    input = "input"
+    sym_output = "sym_output"
+    asym_output = "asym_output"
+    update = "update"
+    sc_output = "sc_output"
+
+
+class ComponentType(str, Enum, metaclass=_MetaEnum):
+    """
+    A ComponentType is the type of a grid component.
+
+    - Examples:
+
+        - ComponentType.node = "node"
+        - ComponentType.line = "line"
+    """
+
+    node = "node"
+    line = "line"
+    asym_line = "asym_line"
+    link = "link"
+    generic_branch = "generic_branch"
+    transformer = "transformer"
+    transformer_tap_regulator = "transformer_tap_regulator"
+    three_winding_transformer = "three_winding_transformer"
+    sym_load = "sym_load"
+    sym_gen = "sym_gen"
+    asym_load = "asym_load"
+    asym_gen = "asym_gen"
+    shunt = "shunt"
+    source = "source"
+    sym_voltage_sensor = "sym_voltage_sensor"
+    asym_voltage_sensor = "asym_voltage_sensor"
+    sym_power_sensor = "sym_power_sensor"
+    asym_power_sensor = "asym_power_sensor"
+    sym_current_sensor = "sym_current_sensor"
+    asym_current_sensor = "asym_current_sensor"
+    fault = "fault"
+
+
+DatasetTypeLike: TypeAlias = DatasetType | str
+DatasetTypeVar = TypeVar("DatasetTypeVar", bound=DatasetTypeLike)  # helper used for type deduction
+
+ComponentTypeLike: TypeAlias = ComponentType | str
+ComponentTypeVar = TypeVar("ComponentTypeVar", bound=ComponentTypeLike)  # helper used for type deduction
+
+
+def _str_to_datatype(data_type: DatasetTypeLike) -> DatasetType:
+    """Helper function to transform data_type str to DatasetType."""
+    if isinstance(data_type, DatasetType):
+        return data_type
+    return DatasetType[data_type]
+
+
+def _map_to_datatypes(data: Mapping[DatasetTypeVar, Any]) -> dict[DatasetType, Any]:
+    """Helper function to map datatype str keys to DatasetType."""
+    return {_str_to_datatype(key): value for key, value in data.items()}
+
+
+def _str_to_component_type(component: ComponentTypeLike) -> ComponentType:
+    """Helper function to transform component str to ComponentType."""
+    if isinstance(component, ComponentType):
+        return component
+    return ComponentType[component]
+
+
+def _map_to_component_types(data: Mapping[ComponentTypeVar, Any]) -> dict[ComponentType, Any]:
+    """Helper function to map componenttype str keys to ComponentType."""
+    return {_str_to_component_type(key): value for key, value in data.items()}
+
+# fmt: on

power_grid_model/_core/enum.py

@@ -0,0 +1,226 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""
+Common enumerations for library-internal use.
+
+Note: these enumeration match the C++ arithmetic core, so don't change the values unless you change them in C++ as well
+
+"""
+
+from enum import IntEnum
+
+# Value names are defined in lower case instead of upper case
+
+
+class CalculationType(IntEnum):
+    """Calculation Types"""
+
+    power_flow = 0
+    state_estimation = 1
+    short_circuit = 2
+
+
+class CalculationMethod(IntEnum):
+    """Calculation Methods"""
+
+    linear = 0
+    newton_raphson = 1
+    iterative_linear = 2
+    iterative_current = 3
+    linear_current = 4
+    iec60909 = 5
+
+
+class TapChangingStrategy(IntEnum):
+    """Tap Changing Strategies"""
+
+    disabled = 0
+    """
+    Disable automatic tap adjustment
+    """
+    any_valid_tap = 1
+    """
+    Adjust tap position automatically; optimize for any value in the voltage band
+    """
+    min_voltage_tap = 2
+    """
+    Adjust tap position automatically; optimize for the lower end of the voltage band
+    """
+    max_voltage_tap = 3
+    """
+    Adjust tap position automatically; optimize for the higher end of the voltage band
+    """
+    fast_any_tap = 4
+    """
+    Adjust tap position automatically; optimize for any value in the voltage band; binary search
+    """
+
+
+class AngleMeasurementType(IntEnum):
+    """The type of the angle measurement for current sensors."""
+
+    local_angle = 0
+    """
+    The angle is relative to the local voltage angle
+    """
+    global_angle = 1
+    """
+    The angle is relative to the global voltage angle.
+    """
+
+
+class ShortCircuitVoltageScaling(IntEnum):
+    """Voltage scaling for short circuit calculations"""
+
+    minimum = 0
+    maximum = 1
+
+
+class _ExperimentalFeatures(IntEnum):
+    """Experimental features"""
+
+    disabled = 0
+    enabled = 1
+
+
+class ComponentAttributeFilterOptions(IntEnum):
+    """Filter option component or attribute"""
+
+    everything = 0
+    """Filter all components/attributes"""
+    relevant = 1
+    """Filter only non-empty components/attributes that contain non-NaN values"""
+
+
+class LoadGenType(IntEnum):
+    """Load and Generator Types"""
+
+    const_power = 0
+    const_impedance = 1
+    const_current = 2
+
+
+class WindingType(IntEnum):
+    """Transformer Winding Types"""
+
+    wye = 0
+    wye_n = 1
+    delta = 2
+    zigzag = 3
+    zigzag_n = 4
+
+
+class BranchSide(IntEnum):
+    """Branch Sides"""
+
+    from_side = 0
+    to_side = 1
+
+
+class Branch3Side(IntEnum):
+    """Branch3 Sides"""
+
+    side_1 = 0
+    side_2 = 1
+    side_3 = 2
+
+
+class MeasuredTerminalType(IntEnum):
+    """The type of asset measured by a (power) sensor"""
+
+    branch_from = 0
+    """
+    Measuring the from-terminal between a branch (except link) and a node
+    """
+    branch_to = 1
+    """
+    Measuring the to-terminal between a branch (except link) and a node
+    """
+    source = 2
+    """
+    Measuring the terminal between a source and a node
+    """
+    shunt = 3
+    """
+    Measuring the terminal between a shunt and a node
+    """
+    load = 4
+    """
+    Measuring the terminal between a load and a node
+    """
+    generator = 5
+    """
+    Measuring the terminal between a generator and a node
+    """
+    branch3_1 = 6
+    """
+    Measuring the terminal-1 between a branch3 and a node
+    """
+    branch3_2 = 7
+    """
+    Measuring the terminal-2 between a branch3 and a node
+    """
+    branch3_3 = 8
+    """
+    Measuring the terminal-3 between a branch3 and a node
+    """
+    node = 9
+    """
+    Measuring the total power injection into a node
+    """
+
+
+class FaultType(IntEnum):
+    """The type of fault represented by a fault component"""
+
+    three_phase = 0
+    single_phase_to_ground = 1
+    two_phase = 2
+    two_phase_to_ground = 3
+    nan = -128
+    """
+    Unspecified fault type. Needs to be overloaded at the latest in the update_data
+    """
+
+
+class FaultPhase(IntEnum):
+    """The faulty phase(s) affected by the provided fault type"""
+
+    abc = 0
+    """
+    All phases are faulty in a three-phase fault
+    """
+    a = 1
+    """
+    The first phase is faulty in a single-phase-to-ground fault
+    """
+    b = 2
+    """
+    The second phase is faulty in a single-phase-to-ground fault
+    """
+    c = 3
+    """
+    The third phase is faulty in a single-phase-to-ground fault
+    """
+    ab = 4
+    """
+    The first and second phase are faulty in a two-phase or two-phase-to-ground fault
+    """
+    ac = 5
+    """
+    The first and third phase are faulty in a two-phase or two-phase-to-ground fault
+    """
+    bc = 6
+    """
+    The second and third phase are faulty in a two-phase or two-phase-to-ground fault
+    """
+    default_value = -1
+    """
+    Use the default fault phase. Depends on the fault_type.
+    """
+    nan = -128
+    """
+    Unspecified fault phase. Needs to be overloaded at the latest in the update_data
+    """