power-grid-model 1.10.99__py3-none-macosx_13_0_x86_64.whl → 1.12.104__py3-none-macosx_13_0_x86_64.whl

power_grid_model/__init__.py

@@ -13,6 +13,7 @@ from power_grid_model._core.power_grid_meta import (
 )
 from power_grid_model._core.power_grid_model import PowerGridModel
 from power_grid_model.enum import (
+    AngleMeasurementType,
     Branch3Side,
     BranchSide,
     CalculationMethod,
@@ -27,3 +28,27 @@ from power_grid_model.enum import (
     WindingType,
 )
 from power_grid_model.typing import ComponentAttributeMapping
+
+__all__ = [
+    "AngleMeasurementType",
+    "Branch3Side",
+    "BranchSide",
+    "CalculationMethod",
+    "CalculationType",
+    "ComponentAttributeFilterOptions",
+    "ComponentAttributeMapping",
+    "ComponentType",
+    "DatasetType",
+    "FaultPhase",
+    "FaultType",
+    "LoadGenType",
+    "MeasuredTerminalType",
+    "PowerGridModel",
+    "ShortCircuitVoltageScaling",
+    "TapChangingStrategy",
+    "WindingType",
+    "attribute_dtype",
+    "attribute_empty_value",
+    "initialize_array",
+    "power_grid_meta_data",
+]

power_grid_model/_core/buffer_handling.py

@@ -11,26 +11,26 @@ from typing import cast
 
 import numpy as np
 
+from power_grid_model._core.data_types import (
+    AttributeType,
+    ComponentData,
+    DenseBatchData,
+    IndexPointer,
+    SingleComponentData,
+    SparseBatchArray,
+    SparseBatchData,
+)
 from power_grid_model._core.error_handling import VALIDATOR_MSG
 from power_grid_model._core.index_integer import IdxC, IdxNp
 from power_grid_model._core.power_grid_core import IdxPtr, VoidPtr
 from power_grid_model._core.power_grid_meta import ComponentMetaData
-from power_grid_model._utils import (
+from power_grid_model._core.utils import (
     _extract_data_from_component_data,
     _extract_indptr,
     check_indptr_consistency,
     is_columnar,
     is_sparse,
 )
-from power_grid_model.data_types import (
-    AttributeType,
-    ComponentData,
-    DenseBatchData,
-    IndexPointer,
-    SingleComponentData,
-    SparseBatchArray,
-    SparseBatchData,
-)
 
 
 @dataclass
@@ -117,9 +117,15 @@ def _get_raw_attribute_data_view(data: np.ndarray, schema: ComponentMetaData, at
     Returns:
         a raw view on the data set.
     """
-    if schema.dtype[attribute].shape == (3,) and data.shape[-1] != 3:
-        raise ValueError("Given data has a different schema than supported.")
-    return _get_raw_data_view(data, dtype=schema.dtype[attribute].base)
+    dense_batch_ndim = 2
+
+    attr_schema = schema.dtype[attribute]
+    attr_shape_start = data.ndim - attr_schema.ndim
+    dataset_shape = data.shape[:attr_shape_start]
+    attr_shape = data.shape[attr_shape_start:]
+    if len(dataset_shape) <= dense_batch_ndim and attr_shape == attr_schema.shape:
+        return _get_raw_data_view(data, dtype=schema.dtype[attribute].base)
+    raise ValueError("Given data has a different schema than supported.")
 
 
 def _get_indptr_view(indptr: np.ndarray) -> IdxPtr:  # type: ignore[valid-type]
@@ -185,15 +191,24 @@ def _get_dense_buffer_properties(
     if actual_ndim not in (1, 2):
         raise ValueError(f"Array can only be 1D or 2D. {VALIDATOR_MSG}")
 
-    actual_is_batch = actual_ndim == 2
-    actual_batch_size = shape[0] if actual_is_batch else 1
+    single_dataset_ndim = 1
+    batch_dataset_ndim = 2
+
+    actual_is_batch = actual_ndim == batch_dataset_ndim
+    actual_batch_size = shape[0] if actual_is_batch else single_dataset_ndim
     n_elements_per_scenario = shape[-1]
     n_total_elements = actual_batch_size * n_elements_per_scenario
 
     if is_batch is not None and is_batch != actual_is_batch:
-        raise ValueError(f"Provided 'is batch' is incorrect for the provided data. {VALIDATOR_MSG}")
+        raise ValueError(
+            f"Incorrect/inconsistent data provided: {'batch' if actual_is_batch else 'single'} "
+            f"data provided but {'batch' if is_batch else 'single'} data expected. {VALIDATOR_MSG}"
+        )
     if batch_size is not None and batch_size != actual_batch_size:
-        raise ValueError(f"Provided 'batch size' is incorrect for the provided data. {VALIDATOR_MSG}")
+        raise ValueError(
+            f"Incorrect/inconsistent batch size provided: {actual_batch_size} scenarios provided "
+            f"but {batch_size} scenarios expected. {VALIDATOR_MSG}"
+        )
 
     return BufferProperties(
         is_sparse=is_sparse_property,

power_grid_model/_core/data_handling.py

@@ -6,16 +6,26 @@
 Data handling
 """
 
+from typing import Literal, overload
+
 import numpy as np
 
-from power_grid_model._core.dataset_definitions import ComponentType, DatasetType
+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._utils import process_data_filter
-from power_grid_model.data_types import Dataset, SingleDataset
-from power_grid_model.enum import CalculationType, ComponentAttributeFilterOptions
-from power_grid_model.errors import PowerGridUnreachableHitError
-from power_grid_model.typing import ComponentAttributeMapping
+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:
@@ -38,7 +48,7 @@ def get_output_type(*, calculation_type: CalculationType, symmetric: bool) -> Da
     if calculation_type == CalculationType.short_circuit:
         return DatasetType.sc_output
 
-    raise NotImplementedError()
+    raise NotImplementedError
 
 
 def prepare_input_view(input_data: SingleDataset) -> CConstDataset:
@@ -85,6 +95,54 @@ def prepare_output_view(output_data: Dataset, output_type: DatasetType) -> CMuta
     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,
@@ -96,7 +154,7 @@ def create_output_data(
     Create the output dataset based on component and batch size from the model; and output attributes requested by user.
 
     Args:
-        output_component_types:
+        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)
@@ -118,11 +176,7 @@ def create_output_data(
     result_dict: Dataset = {}
 
     for name, count in all_component_count.items():
-        # shape
-        if is_batch:
-            shape: tuple[int] | tuple[int, int] = (batch_size, count)
-        else:
-            shape = (count,)
+        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
@@ -134,8 +188,8 @@ def create_output_data(
             ComponentAttributeFilterOptions.everything,
             ComponentAttributeFilterOptions.relevant,
         ]:
-            result_dict[name] = {attr: np.empty(shape, dtype=dtype[attr]) for attr in dtype.names}
+            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, dtype=dtype[attr]) for attr in requested_component}
+            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

@@ -6,13 +6,12 @@
 
 # This file is automatically generated. DO NOT modify it manually!
 
+from collections.abc import Mapping
 from enum import Enum, EnumMeta
-from typing import Any, Mapping, TypeAlias, TypeVar
+from typing import Any, TypeAlias, TypeVar
 
 # fmt: off
 
-# pylint: disable=invalid-name
-
 class _MetaEnum(EnumMeta):
     def __contains__(cls, member):
         """
@@ -24,7 +23,7 @@ class _MetaEnum(EnumMeta):
         Returns:
             bool: True if the member is part of the Enum, False otherwise.
         """
-        return member in cls.__members__.keys()
+        return member in cls.__members__
 
 
 class DatasetType(str, Enum, metaclass=_MetaEnum):
@@ -56,6 +55,7 @@ class ComponentType(str, Enum, metaclass=_MetaEnum):
 
     node = "node"
     line = "line"
+    asym_line = "asym_line"
     link = "link"
     generic_branch = "generic_branch"
     transformer = "transformer"
@@ -76,8 +76,6 @@ class ComponentType(str, Enum, metaclass=_MetaEnum):
     fault = "fault"
 
 
-# pylint: enable=invalid-name
-
 DatasetTypeLike: TypeAlias = DatasetType | str
 DatasetTypeVar = TypeVar("DatasetTypeVar", bound=DatasetTypeLike)  # helper used for type deduction
 

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
+    """