power-grid-model 1.12.20__py3-none-musllinux_1_2_x86_64.whl → 1.12.112__py3-none-musllinux_1_2_x86_64.whl

power_grid_model/_core/buffer_handling.py

@@ -7,15 +7,19 @@ Power grid model buffer handler
 """
 
 from dataclasses import dataclass
-from typing import cast
+from typing import cast, overload
 
 import numpy as np
 
 from power_grid_model._core.data_types import (
     AttributeType,
     ComponentData,
+    DenseBatchArray,
+    DenseBatchColumnarData,
     DenseBatchData,
     IndexPointer,
+    SingleArray,
+    SingleColumnarData,
     SingleComponentData,
     SparseBatchArray,
     SparseBatchData,
@@ -88,6 +92,10 @@ def _get_raw_data_view(data: np.ndarray, dtype: np.dtype) -> VoidPtr:
     return np.ascontiguousarray(data, dtype=dtype).ctypes.data_as(VoidPtr)
 
 
+@overload
+def _get_raw_component_data_view(data: np.ndarray, schema: ComponentMetaData) -> VoidPtr: ...
+@overload
+def _get_raw_component_data_view(data: dict[AttributeType, np.ndarray], schema: ComponentMetaData) -> None: ...
 def _get_raw_component_data_view(
     data: np.ndarray | dict[AttributeType, np.ndarray], schema: ComponentMetaData
 ) -> VoidPtr | None:
@@ -200,9 +208,15 @@ def _get_dense_buffer_properties(
     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,
@@ -480,7 +494,13 @@ def _create_sparse_buffer(properties: BufferProperties, schema: ComponentMetaDat
     return cast(SparseBatchData, {"data": data, "indptr": indptr})
 
 
-def _create_contents_buffer(shape, dtype, columns: list[AttributeType] | None) -> SingleComponentData | DenseBatchData:
+@overload
+def _create_contents_buffer(shape, dtype, columns: None) -> SingleArray | DenseBatchArray: ...
+@overload
+def _create_contents_buffer(
+    shape, dtype, columns: list[AttributeType]
+) -> SingleColumnarData | DenseBatchColumnarData: ...
+def _create_contents_buffer(shape, dtype, columns):
     if columns is None:
         return np.empty(shape=shape, dtype=dtype)
 

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.data_types import Dataset, SingleDataset
-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._core.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:
@@ -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

@@ -9,35 +9,35 @@ Data types for library-internal use. In an attempt to clarify type hints, some t
 have been defined and explained in this file.
 """
 
-from typing import TypeAlias, TypedDict, TypeVar
+from typing import TypedDict, TypeVar
 
 import numpy as np
 
-from power_grid_model._core.dataset_definitions import ComponentTypeVar
+from power_grid_model._core.dataset_definitions import ComponentType, ComponentTypeVar
 
-SingleArray: TypeAlias = np.ndarray
+type SingleArray = np.ndarray
 
-AttributeType: TypeAlias = str
+type AttributeType = str
 
-SingleColumn: TypeAlias = np.ndarray
-
-DenseBatchArray: TypeAlias = np.ndarray
+type SingleColumn = np.ndarray
+type DenseBatchArray = 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
+type BatchColumn = np.ndarray
 
 DenseBatchColumnarData = dict[AttributeType, BatchColumn]
 
-IndexPointer: TypeAlias = np.ndarray
+type IndexPointer = np.ndarray
 
 
 class SparseBatchColumnarData(TypedDict):
@@ -86,7 +86,7 @@ class SparseBatchArray(TypedDict):
 
 SparseBatchData = SparseBatchArray | SparseBatchColumnarData
 
-SparseDataComponentType: TypeAlias = str
+type SparseDataComponentType = str
 
 BatchColumnarData = DenseBatchColumnarData | SparseBatchColumnarData
 
@@ -113,6 +113,16 @@ 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

power_grid_model/_core/dataset_definitions.py

@@ -8,7 +8,7 @@
 
 from collections.abc import Mapping
 from enum import Enum, EnumMeta
-from typing import Any, TypeAlias, TypeVar
+from typing import TypeVar
 
 # fmt: off
 
@@ -76,10 +76,10 @@ class ComponentType(str, Enum, metaclass=_MetaEnum):
     fault = "fault"
 
 
-DatasetTypeLike: TypeAlias = DatasetType | str
+type DatasetTypeLike = DatasetType | str
 DatasetTypeVar = TypeVar("DatasetTypeVar", bound=DatasetTypeLike)  # helper used for type deduction
 
-ComponentTypeLike: TypeAlias = ComponentType | str
+type ComponentTypeLike = ComponentType | str
 ComponentTypeVar = TypeVar("ComponentTypeVar", bound=ComponentTypeLike)  # helper used for type deduction
 
 
@@ -90,7 +90,7 @@ def _str_to_datatype(data_type: DatasetTypeLike) -> DatasetType:
     return DatasetType[data_type]
 
 
-def _map_to_datatypes(data: Mapping[DatasetTypeVar, Any]) -> dict[DatasetType, Any]:
+def _map_to_datatypes[K: DatasetTypeLike, V](data: Mapping[K, V]) -> dict[DatasetType, V]:
     """Helper function to map datatype str keys to DatasetType."""
     return {_str_to_datatype(key): value for key, value in data.items()}
 
@@ -102,7 +102,7 @@ def _str_to_component_type(component: ComponentTypeLike) -> ComponentType:
     return ComponentType[component]
 
 
-def _map_to_component_types(data: Mapping[ComponentTypeVar, Any]) -> dict[ComponentType, Any]:
+def _map_to_component_types[K: ComponentTypeLike, V](data: Mapping[K, V]) -> dict[ComponentType, V]:
     """Helper function to map componenttype str keys to ComponentType."""
     return {_str_to_component_type(key): value for key, value in data.items()}
 

power_grid_model/_core/error_handling.py

@@ -7,6 +7,7 @@ Error handling
 """
 
 import re
+from enum import IntEnum
 
 import numpy as np
 
@@ -33,6 +34,7 @@ from power_grid_model._core.errors import (
     PowerGridBatchError,
     PowerGridDatasetError,
     PowerGridError,
+    PowerGridIllegalOperationError,
     PowerGridNotImplementedError,
     PowerGridSerializationError,
     PowerGridUnreachableHitError,
@@ -40,14 +42,17 @@ from power_grid_model._core.errors import (
     TapSearchStrategyIncompatibleError,
 )
 from power_grid_model._core.index_integer import IdxNp
-from power_grid_model._core.power_grid_core import power_grid_core as pgc
+from power_grid_model._core.power_grid_core import get_power_grid_core as get_pgc
 
 VALIDATOR_MSG = "\nTry validate_input_data() or validate_batch_data() to validate your data.\n"
-# error codes
-PGM_NO_ERROR = 0
-PGM_REGULAR_ERROR = 1
-PGM_BATCH_ERROR = 2
-PGM_SERIALIZATION_ERROR = 3
+
+
+class _PgmCErrorCode(IntEnum):
+    NO_ERROR = 0
+    REGULAR_ERROR = 1
+    BATCH_ERROR = 2
+    SERIALIZATION_ERROR = 3
+
 
 _MISSING_CASE_FOR_ENUM_RE = re.compile(r" is not implemented for (.+) #(-?\d+)!\n")
 _INVALID_ARGUMENTS_RE = re.compile(r" is not implemented for ")  # multiple different flavors
@@ -82,6 +87,7 @@ _INVALID_CALCULATION_METHOD_RE = re.compile(r"The calculation method is invalid
 _INVALID_SHORT_CIRCUIT_PHASE_OR_TYPE_RE = re.compile(r"short circuit type")  # multiple different flavors
 _TAP_STRATEGY_SEARCH_OPT_INCMPT_RE = re.compile(r"Search method is incompatible with optimization strategy: ")
 _POWER_GRID_DATASET_ERROR_RE = re.compile(r"Dataset error: ")  # multiple different flavors
+_POWER_GRID_ILLEGAL_OPERATION_ERROR_RE = re.compile(r"Illegal operation: ")  # multiple different flavors
 _POWER_GRID_UNREACHABLE_HIT_RE = re.compile(r"Unreachable code hit when executing ")  # multiple different flavors
 _POWER_GRID_NOT_IMPLEMENTED_ERROR_RE = re.compile(r"The functionality is either not supported or not yet implemented!")
 
@@ -108,6 +114,7 @@ _ERROR_MESSAGE_PATTERNS = {
     _INVALID_SHORT_CIRCUIT_PHASE_OR_TYPE_RE: InvalidShortCircuitPhaseOrType,
     _TAP_STRATEGY_SEARCH_OPT_INCMPT_RE: TapSearchStrategyIncompatibleError,
     _POWER_GRID_DATASET_ERROR_RE: PowerGridDatasetError,
+    _POWER_GRID_ILLEGAL_OPERATION_ERROR_RE: PowerGridIllegalOperationError,
     _POWER_GRID_UNREACHABLE_HIT_RE: PowerGridUnreachableHitError,
     _POWER_GRID_NOT_IMPLEMENTED_ERROR_RE: PowerGridNotImplementedError,
 }
@@ -133,30 +140,32 @@ def find_error(batch_size: int = 1, decode_error: bool = True) -> RuntimeError |
     Returns: error object, can be none
 
     """
-    error_code: int = pgc.error_code()
-    if error_code == PGM_NO_ERROR:
-        return None
-    if error_code == PGM_REGULAR_ERROR:
-        error_message = pgc.error_message()
-        error_message += VALIDATOR_MSG
-        return _interpret_error(error_message, decode_error=decode_error)
-    if error_code == PGM_BATCH_ERROR:
-        error_message = "There are errors in the batch calculation." + VALIDATOR_MSG
-        error = PowerGridBatchError(error_message)
-        n_fails = pgc.n_failed_scenarios()
-        failed_idxptr = pgc.failed_scenarios()
-        failed_msgptr = pgc.batch_errors()
-        error.failed_scenarios = np.ctypeslib.as_array(failed_idxptr, shape=(n_fails,)).copy()
-        error.error_messages = [failed_msgptr[i].decode() for i in range(n_fails)]  # type: ignore
-        error.errors = [_interpret_error(message, decode_error=decode_error) for message in error.error_messages]
-        all_scenarios = np.arange(batch_size, dtype=IdxNp)
-        mask = np.ones(batch_size, dtype=np.bool_)
-        mask[error.failed_scenarios] = False
-        error.succeeded_scenarios = all_scenarios[mask]
-        return error
-    if error_code == PGM_SERIALIZATION_ERROR:
-        return PowerGridSerializationError(pgc.error_message())
-    return RuntimeError("Unknown error!")
+    error_code: int = get_pgc().error_code()
+    match error_code:
+        case _PgmCErrorCode.NO_ERROR:
+            return None
+        case _PgmCErrorCode.REGULAR_ERROR:
+            error_message = get_pgc().error_message()
+            error_message += VALIDATOR_MSG
+            return _interpret_error(error_message, decode_error=decode_error)
+        case _PgmCErrorCode.BATCH_ERROR:
+            error_message = "There are errors in the batch calculation." + VALIDATOR_MSG
+            error = PowerGridBatchError(error_message)
+            n_fails = get_pgc().n_failed_scenarios()
+            failed_idxptr = get_pgc().failed_scenarios()
+            failed_msgptr = get_pgc().batch_errors()
+            error.failed_scenarios = np.ctypeslib.as_array(failed_idxptr, shape=(n_fails,)).copy()
+            error.error_messages = [failed_msgptr[i].decode() for i in range(n_fails)]  # type: ignore
+            error.errors = [_interpret_error(message, decode_error=decode_error) for message in error.error_messages]
+            all_scenarios = np.arange(batch_size, dtype=IdxNp)
+            mask = np.ones(batch_size, dtype=np.bool_)
+            mask[error.failed_scenarios] = False
+            error.succeeded_scenarios = all_scenarios[mask]
+            return error
+        case _PgmCErrorCode.SERIALIZATION_ERROR:
+            return PowerGridSerializationError(get_pgc().error_message())
+        case _:
+            return RuntimeError("Unknown error!")
 
 
 def assert_no_error(batch_size: int = 1, decode_error: bool = True):

power_grid_model/_core/errors.py

@@ -124,6 +124,10 @@ class PowerGridNotImplementedError(PowerGridError):
     """The functionality is either not supported or not yet implemented."""
 
 
+class PowerGridIllegalOperationError(PowerGridError):
+    """An illegal operation was attempted to the C API, such as accessing a null pointer."""
+
+
 class PowerGridUnreachableHitError(PowerGridError):
     """Supposedly unreachable code was hit.
 

power_grid_model/_core/options.py

@@ -9,7 +9,7 @@ Option class
 from collections.abc import Callable
 from typing import Any
 
-from power_grid_model._core.power_grid_core import OptionsPtr, power_grid_core as pgc
+from power_grid_model._core.power_grid_core import OptionsPtr, get_power_grid_core as get_pgc
 
 
 class OptionSetter:
@@ -36,15 +36,15 @@ class Options:
 
     _opt: OptionsPtr
     # option setter
-    calculation_type = OptionSetter(pgc.set_calculation_type)
-    calculation_method = OptionSetter(pgc.set_calculation_method)
-    symmetric = OptionSetter(pgc.set_symmetric)
-    error_tolerance = OptionSetter(pgc.set_err_tol)
-    max_iterations = OptionSetter(pgc.set_max_iter)
-    threading = OptionSetter(pgc.set_threading)
-    tap_changing_strategy = OptionSetter(pgc.set_tap_changing_strategy)
-    short_circuit_voltage_scaling = OptionSetter(pgc.set_short_circuit_voltage_scaling)
-    experimental_features = OptionSetter(pgc.set_experimental_features)
+    calculation_type = OptionSetter(get_pgc().set_calculation_type)
+    calculation_method = OptionSetter(get_pgc().set_calculation_method)
+    symmetric = OptionSetter(get_pgc().set_symmetric)
+    error_tolerance = OptionSetter(get_pgc().set_err_tol)
+    max_iterations = OptionSetter(get_pgc().set_max_iter)
+    threading = OptionSetter(get_pgc().set_threading)
+    tap_changing_strategy = OptionSetter(get_pgc().set_tap_changing_strategy)
+    short_circuit_voltage_scaling = OptionSetter(get_pgc().set_short_circuit_voltage_scaling)
+    experimental_features = OptionSetter(get_pgc().set_experimental_features)
 
     @property
     def opt(self) -> OptionsPtr:
@@ -57,11 +57,11 @@ class Options:
 
     def __new__(cls, *args, **kwargs):
         instance = super().__new__(cls, *args, **kwargs)
-        instance._opt = pgc.create_options()
+        instance._opt = get_pgc().create_options()
         return instance
 
     def __del__(self):
-        pgc.destroy_options(self._opt)
+        get_pgc().destroy_options(self._opt)
 
     # not copyable
     def __copy__(self):

power_grid_model/_core/power_grid_core.py

@@ -6,6 +6,7 @@
 Loader for the dynamic library
 """
 
+import threading
 from collections.abc import Callable
 from ctypes import CDLL, POINTER, c_char, c_char_p, c_double, c_size_t, c_void_p
 from inspect import signature
@@ -14,6 +15,10 @@ from itertools import chain
 from power_grid_model._core.index_integer import IdC, IdxC
 from power_grid_model._core.power_grid_model_c.get_pgm_dll_path import get_pgm_dll_path
 
+# threading local
+_thread_local_data = threading.local()
+
+
 # integer index
 IdxPtr = POINTER(IdxC)
 """Pointer to index."""
@@ -195,14 +200,12 @@ class PowerGridCore:
     """
 
     _handle: HandlePtr
-    _instance: "PowerGridCore | None" = None
 
     # singleton of power grid core
     def __new__(cls, *args, **kwargs):
-        if cls._instance is None:
-            cls._instance = super().__new__(cls, *args, **kwargs)
-            cls._instance._handle = _CDLL.PGM_create_handle()
-        return cls._instance
+        instance = super().__new__(cls, *args, **kwargs)
+        instance._handle = _CDLL.PGM_create_handle()
+        return instance
 
     def __del__(self):
         _CDLL.PGM_destroy_handle(self._handle)
@@ -481,6 +484,12 @@ class PowerGridCore:
     def dataset_const_get_info(self, dataset: ConstDatasetPtr) -> DatasetInfoPtr:  # type: ignore[empty-body]
         pass  # pragma: no cover
 
+    @make_c_binding
+    def dataset_const_set_next_cartesian_product_dimension(
+        self, dataset: ConstDatasetPtr, next_dataset: ConstDatasetPtr
+    ) -> None:  # type: ignore[empty-body]
+        pass  # pragma: no cover
+
     @make_c_binding
     def dataset_writable_get_info(self, dataset: WritableDatasetPtr) -> DatasetInfoPtr:  # type: ignore[empty-body]
         pass  # pragma: no cover
@@ -560,4 +569,9 @@ class PowerGridCore:
 
 
 # make one instance
-power_grid_core = PowerGridCore()
+def get_power_grid_core() -> PowerGridCore:
+    try:
+        return _thread_local_data.power_grid_core
+    except AttributeError:
+        _thread_local_data.power_grid_core = PowerGridCore()
+        return _thread_local_data.power_grid_core