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

power_grid_model_ds/_core/model/arrays/base/_build.py

@@ -0,0 +1,166 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""Contains the build_array function."""
+
+import logging
+from collections.abc import Sized
+from typing import Any, Iterable
+
+import numpy as np
+
+from power_grid_model_ds._core.model.constants import empty
+from power_grid_model_ds._core.utils.misc import is_sequence
+
+
+def build_array(*args: tuple[Any], dtype: np.dtype, defaults: dict[str, np.generic], **kwargs) -> np.ndarray:
+    """Constructs the array from the given args/kwargs."""
+    parsed_input, size = _parse_input(*args, dtype=dtype, **kwargs)
+
+    array: np.ndarray = np.zeros(size, dtype=dtype)
+    _fill_defaults(array, defaults)
+
+    if not size:
+        return array
+
+    if isinstance(parsed_input, np.ndarray) and parsed_input.dtype.names:
+        _check_missing_columns(array.dtype.names, defaults, set(parsed_input.dtype.names))
+        return _parse_structured_array(parsed_input, array)
+    if isinstance(parsed_input, np.ndarray):
+        # Note: defaults are not supported when working with unstructured arrays
+        return _parse_array(parsed_input, array.dtype)
+
+    _check_missing_columns(array.dtype.names, defaults, set(parsed_input.keys()))
+    _fill_with_kwargs(array, parsed_input)
+    return array
+
+
+def _parse_input(*args: Any, dtype: np.dtype, **kwargs):
+    """Combines the args and kwargs to a dict."""
+    columns: list[str] = list(dtype.names) if dtype.names else []
+    if args and kwargs:
+        raise TypeError("Cannot construct from both args and kwargs")
+
+    if args and isinstance(args[0], np.ndarray):
+        return args[0], len(args[0])
+    if args and isinstance(args[0], Iterable):
+        kwargs = _args2kwargs(args, columns)
+    elif args:
+        raise TypeError(f"Invalid args: {args}")
+
+    if kwargs:
+        return _parse_kwargs(kwargs, columns)
+    return {}, 0
+
+
+def _check_missing_columns(array_columns: tuple, defaults: dict[str, np.generic], provided_columns: set[str]):
+    required_columns = set(array_columns) - set(defaults.keys())
+    if missing_columns := required_columns - provided_columns:
+        raise ValueError(f"Missing required columns: {missing_columns}")
+
+
+def _fill_defaults(array: np.ndarray, defaults: dict[str, np.generic]):
+    """Fills the defaults into the array."""
+    for column, default in defaults.items():
+        if default is empty:
+            array[column] = empty(array.dtype[column])  # type: ignore[call-overload]
+        else:
+            array[column] = default  # type: ignore[call-overload]
+
+
+def _fill_with_kwargs(array: np.ndarray, kwargs: dict[str, np.ndarray]):
+    """Fills the kwargs into the array."""
+    for column, values in kwargs.items():
+        array[column] = values  # type: ignore[call-overload]
+
+
+def _parse_structured_array(from_array: np.ndarray, to_array: np.ndarray) -> np.ndarray:
+    shared_columns, ignored_columns = _determine_column_overlap(from_array, to_array)
+    if ignored_columns:
+        logging.debug(
+            "Ignored provided columns %s during build of array with columns %s", ignored_columns, to_array.dtype.names
+        )
+    to_array[shared_columns] = from_array[shared_columns]  # type: ignore[index]
+    return to_array
+
+
+def _determine_column_overlap(from_array: np.ndarray, to_array: np.ndarray) -> tuple[list[str], list[str]]:
+    """Returns two lists: columns present in both arrays and the columns that are only present in from_array"""
+    from_columns = set(from_array.dtype.names)
+    to_columns = set(to_array.dtype.names)
+
+    return list(from_columns & to_columns), list(from_columns - to_columns)
+
+
+def _parse_array(array: np.ndarray, dtype: np.dtype):
+    if len(array.shape) == 1 and array.dtype == dtype:
+        return array
+    if len(array.shape) == 1:
+        return np.array(array, dtype=dtype)
+    if len(array.shape) == 2:
+        return _parse_2d_array(array, dtype)
+    raise NotImplementedError(f"Unsupported array shape {array.shape}")
+
+
+def _parse_2d_array(array: np.ndarray, dtype: np.dtype):
+    """Parses the 2d array to a 1d array."""
+    columns: list[str] = list(dtype.names) if dtype.names else []
+    if len(columns) not in array.shape:
+        raise ValueError(f"Cannot convert array of shape {array.shape} into {len(columns)} columns.")
+    column_dim = 0 if len(columns) == array.shape[0] else 1
+    size_dim = 1 if column_dim == 0 else 0
+    new_array = np.ones(array.shape[size_dim], dtype=dtype)
+    for index, column in enumerate(columns):
+        if column_dim == 0:
+            new_array[column] = array[index, :]  # type: ignore[call-overload]
+        else:
+            new_array[column] = array[:, index]  # type: ignore[call-overload]
+    return new_array
+
+
+def _parse_kwargs(kwargs: dict[str, list | np.ndarray], columns: list[str]) -> tuple[dict[str, np.ndarray], int]:
+    """Parses the kwargs to a dict of np.ndarrays."""
+    parsed_kwargs = {}
+
+    size = 0
+    for column, values in kwargs.items():
+        parsed_kwargs[column] = np.array(values).flatten()
+
+        value_size = _get_size(values)
+        if size == 0:
+            size = value_size
+        elif size != len(values):
+            raise ValueError(f"Size of column '{column}' does not match other columns.")
+
+    if invalid_columns := set(parsed_kwargs.keys()) - set(columns):
+        raise ValueError(f"Invalid columns: {invalid_columns}")
+    return parsed_kwargs, size
+
+
+def _get_size(values: Sized):
+    """Returns the size of the values."""
+    if is_sequence(values):
+        return len(values)
+    return 1
+
+
+def _args2kwargs(args: tuple[Any, ...], columns: list[str]) -> dict[str, list]:
+    """Parses the args to kwargs."""
+    kwargs = {}
+    if len(args) == 1:
+        args = args[0]
+
+    args_as_array = np.array(args)
+    if len(args_as_array.shape) != 2:
+        raise ValueError(
+            "Cannot parse args: input is not 2D, probably due to an inconsistent number of values per row."
+        )
+
+    _, args_n_columns = args_as_array.shape
+    if args_n_columns != len(columns):
+        raise ValueError(f"Cannot parse args: requires {len(columns)} columns per row, got {args_n_columns}.")
+
+    for index, column in enumerate(columns):
+        kwargs[column] = [row[index] for row in args]
+    return kwargs

power_grid_model_ds/_core/model/arrays/base/_filters.py

@@ -0,0 +1,115 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+from typing import Any, Iterable, Literal
+
+import numpy as np
+from numpy.typing import NDArray
+
+from power_grid_model_ds._core.model.arrays.base.errors import MultipleRecordsReturned, RecordDoesNotExist
+from power_grid_model_ds._core.utils.misc import is_sequence
+
+
+def get_filter_mask(
+    *args: int | Iterable[int] | np.ndarray,
+    array: np.ndarray,
+    mode_: Literal["AND", "OR"],
+    **kwargs: Any | list[Any] | np.ndarray,
+) -> np.ndarray:
+    """Returns a mask that matches the input parameters."""
+    parsed_kwargs = _parse(args, kwargs)
+
+    if invalid_kwargs := set(parsed_kwargs.keys()) - set(array.dtype.names):
+        raise ValueError(f"Invalid kwargs: {invalid_kwargs}")
+
+    filter_mask = _initialize_filter_mask(mode_, array.size)
+    for field, values in parsed_kwargs.items():
+        field_mask = _build_filter_mask_for_field(array, field, values)
+        if mode_ == "AND":
+            filter_mask &= field_mask
+        elif mode_ == "OR":
+            filter_mask |= field_mask
+        else:
+            raise ValueError(f"Invalid mode: {mode_}, must be 'AND' or 'OR'")
+    return filter_mask
+
+
+def apply_filter(
+    *args: int | Iterable[int] | np.ndarray,
+    array: np.ndarray,
+    mode_: Literal["AND", "OR"],
+    **kwargs: Any | list[Any] | np.ndarray,
+) -> np.ndarray:
+    """Return an array with the records that match the input parameters.
+    Note: output could be an empty array."""
+    filter_mask = get_filter_mask(*args, array=array, mode_=mode_, **kwargs)
+    return array[filter_mask]
+
+
+def apply_exclude(
+    *args: int | Iterable[int] | np.ndarray,
+    array: np.ndarray,
+    mode_: Literal["AND", "OR"],
+    **kwargs: Any | list[Any] | np.ndarray,
+) -> np.ndarray:
+    """Return an array without records that match the input parameters.
+    Note: output could be an empty array."""
+    filter_mask = get_filter_mask(*args, array=array, mode_=mode_, **kwargs)
+    return array[~filter_mask]
+
+
+def apply_get(
+    *args: int | Iterable[int] | np.ndarray,
+    array: np.ndarray,
+    mode_: Literal["AND", "OR"],
+    **kwargs: Any | list[Any] | np.ndarray,
+) -> np.ndarray:
+    """Returns a record that matches the input parameters.
+    If no or multiple records match the input parameters, an error is raised.
+    """
+    filtered_array = apply_filter(*args, array=array, mode_=mode_, **kwargs)
+    if filtered_array.size == 1:
+        return filtered_array
+
+    args_str = f"\n\twith args: {args[0]}" if args else ""
+    kwargs_str = f"\n\twith kwargs: {kwargs}" if kwargs else ""
+    if filtered_array.size == 0:
+        raise RecordDoesNotExist(f"No record found! {args_str}{kwargs_str}")
+    raise MultipleRecordsReturned(f"Found more than one record! {args_str}{kwargs_str}")
+
+
+def _build_filter_mask_for_field(array: np.ndarray, field: str, values) -> np.ndarray:
+    if not is_sequence(values):
+        # Note: is_sequence() does not consider a string as a sequence.
+        values = [values]
+
+    if not len(values):  # pylint: disable=use-implicit-booleaness-not-len
+        return np.full(array.size, False)
+    if isinstance(values, set):
+        values = list(values)
+    if len(values) == 1:  # speed-up for single value
+        return array[field] == values[0]
+    return np.isin(array[field], values)
+
+
+def _parse(args: tuple[int | Iterable[int] | NDArray, ...] | NDArray[np.int64], kwargs):
+    if not args and not kwargs:
+        raise TypeError("No input provided.")
+    if len(args) > 1:
+        raise ValueError("Cannot parse more than 1 positional argument.")
+    if len(args) == 1 and "id" in kwargs:
+        raise ValueError("Cannot parse both positional argument and keyword argument 'id'.")
+    if len(args) == 1 and isinstance(args[0], int):
+        kwargs.update({"id": args})
+    elif len(args) == 1:
+        kwargs.update({"id": args[0]})
+    return kwargs
+
+
+def _initialize_filter_mask(mode_: Literal["AND", "OR"], size: int) -> np.ndarray:
+    if mode_ == "AND":
+        return np.full(size, True)
+    if mode_ == "OR":
+        return np.full(size, False)
+    raise ValueError(f"Invalid mode: {mode_}, must be 'AND' or 'OR'")

power_grid_model_ds/_core/model/arrays/base/_modify.py

@@ -0,0 +1,64 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""Helper functions for arrays"""
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+
+def re_order(array: np.ndarray, new_order: ArrayLike, column: str = "id") -> np.ndarray:
+    """Re-order an id-array by the id column so that it follows a new_order.
+    Expects the new_order input to contain the same values as self.id
+    """
+    if column not in array.dtype.names:
+        raise ValueError(f"Cannot re-order array: column {column} does not exist.")
+    if not np.array_equal(np.sort(array[column]), np.sort(new_order)):
+        raise ValueError(f"Cannot re-order array: mismatch between new_order and values in '{column}'-column.")
+
+    permutation_a = np.argsort(array[column])
+    permutation_b = np.argsort(new_order)
+    inverse = np.empty_like(new_order, dtype=int)
+    inverse[permutation_b] = np.arange(permutation_b.size)
+    new_order_indices = permutation_a[inverse]
+    return array[new_order_indices]
+
+
+def update_by_id(array: np.ndarray, ids: ArrayLike, allow_missing: bool, **kwargs) -> NDArray[np.bool_]:
+    """Update values in an array by id
+
+    Args:
+        array: the array to update
+        ids: the ids to update
+        allow_missing: whether to allow ids that do not exist in the array
+        **kwargs: the columns to update and their new values
+    Returns:
+        mask: the mask on the original array for the provided ids
+    """
+    mask = np.isin(array["id"], ids)
+    if not allow_missing:
+        nr_hits = np.sum(mask)
+        nr_ids = np.unique(ids).size  # ignore edge cases with duplicate ids
+        if nr_hits != nr_ids:
+            raise ValueError("One or more ids do not exist. Provide allow_missing=True if this is intended.")
+
+    for name, values in kwargs.items():
+        array[name][mask] = values
+    return mask
+
+
+def check_ids(array: np.ndarray, return_duplicates: bool = False) -> NDArray | None:
+    """Check for duplicate ids within the array"""
+    if "id" not in array.dtype.names:
+        raise AttributeError("Array has no 'id' column.")
+
+    unique, counts = np.unique(array["id"], return_counts=True)
+    duplicate_mask = counts > 1
+    duplicates = unique[duplicate_mask]
+
+    if return_duplicates:
+        return duplicates
+    if duplicates.size > 0:
+        raise ValueError(f"Found duplicate ids in array: {duplicates}")
+    return None

power_grid_model_ds/_core/model/arrays/base/_optional.py

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""Optional dependencies for the arrays module."""
+
+try:
+    # pylint: disable=unused-import
+    import pandas
+except ImportError:
+    pandas = None

power_grid_model_ds/_core/model/arrays/base/_string.py

@@ -0,0 +1,94 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""Module for array to string conversion."""
+
+from typing import TYPE_CHECKING, Optional
+
+import numpy as np
+
+from power_grid_model_ds._core import fancypy as fp
+
+if TYPE_CHECKING:
+    from power_grid_model_ds._core.model.arrays.base.array import FancyArray
+
+
+def convert_array_to_string(array: "FancyArray", rows: int = 10, column_width: int | str = "auto") -> str:
+    """Return a string representation of the array as a table.
+
+    Args:
+        column_width: the width of each column in the table. Will be determined by its contents if set to "auto".
+        rows: the number of rows to show. If the array is larger than this, the middle rows are hidden.
+    """
+    start_rows, end_rows = _get_start_and_end_rows(array, rows)
+    if end_rows is not None:
+        rows_to_print = fp.concatenate(start_rows, end_rows)
+    else:
+        rows_to_print = start_rows
+
+    match column_width:
+        case "auto":
+            column_widths = _determine_column_widths(rows_to_print)
+        case int():
+            column_widths = [(column, column_width) for column in array.dtype.names]
+        case _:
+            raise NotImplementedError(f"column_width={column_width} is not supported. Use 'auto' or int.")
+
+    header = "|".join(f"{_center_and_truncate(column, width)}" for column, width in column_widths) + "\n"
+    if end_rows is None:
+        body = _rows_to_strings(rows_to_print, column_widths)
+        return header + "\n".join(body)
+
+    start_rows = _rows_to_strings(start_rows, column_widths)
+    cutoff_line = f"(..{array.size - rows_to_print.size} hidden rows..)".center(len(header))
+    end_rows = _rows_to_strings(end_rows, column_widths)
+    return header + "\n".join(start_rows) + "\n" + cutoff_line + "\n" + "\n".join(end_rows)
+
+
+def _rows_to_strings(rows: "FancyArray", column_widths: list[tuple[str, int]]) -> list[str]:
+    rows_as_strings = []
+    for row in rows.data:
+        row_as_strings = []
+        for attr, (_, width) in zip(row.tolist(), column_widths):
+            row_as_strings.append(_center_and_truncate(str(attr), width))
+        rows_as_strings.append("|".join(row_as_strings))
+    return rows_as_strings
+
+
+def _determine_column_widths(array: "FancyArray") -> list[tuple[str, int]]:
+    """Get the maximum width of each column in the array."""
+    column_widths: list[tuple[str, int]] = []
+    if not array.dtype.names:
+        return column_widths
+
+    for column in array.dtype.names:
+        data = array.data[column]
+        if data.size:
+            # if float, round to 3 decimals
+            if data.dtype.kind == "f":
+                data = np.around(data, decimals=3)
+            # to string to get the length
+            data = data.astype(str)
+            longest_string = max(data, key=len)
+            if len(column) > len(longest_string):
+                longest_string = column
+        else:
+            longest_string = column
+        column_widths.append((column, len(longest_string) + 2))
+    return column_widths
+
+
+def _center_and_truncate(string: str, width: int) -> str:
+    if len(string) <= width:
+        return string.center(width)
+    return f"{string[:width - 2]}..".center(width)
+
+
+def _get_start_and_end_rows(array: "FancyArray", rows: int) -> tuple["FancyArray", Optional["FancyArray"]]:
+    if array.size <= rows:
+        return array, None
+    cutoff = rows // 2
+    start_rows = array[:cutoff]
+    end_rows = array[-cutoff:]
+    return start_rows, end_rows