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

power_grid_model_ds/_core/model/grids/helpers.py

@@ -0,0 +1,122 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from power_grid_model_ds._core.model.arrays.pgm_arrays import BranchArray
+from power_grid_model_ds._core.model.enums.nodes import NodeType
+
+if TYPE_CHECKING:
+    from .base import Grid
+
+
+def set_feeder_ids(grid: "Grid"):
+    """Determines all feeder groups in the network and gives them a feeder identifier
+
+    feeder_branch_id := All assets being connected through the same feeding branch(es) on the substation
+    feeder_node_id := All assets connected to the same feeder node (substation)
+
+    Example:
+    Nodes Topology
+    (SUBSTATION) 101 --- 102 --- 103 -|- 104 --- 105 --- 101 (SUBSTATION)
+                         {-}
+                         106
+
+    Branches Topology:
+    (SUBSTATION) *** 201 *** 202 *** 203 *** 601 *** 204 *** (SUBSTATION)
+                         301
+                         ***
+
+         Substation ID | Feeder ID
+    101 | -1           | -1
+    102 | 101          | 201
+    103 | 101          | 201
+    104 | 101          | 204
+    105 | 101          | 204
+    106 | 101          | 201
+    201 | 101          | 201
+    202 | 101          | 201
+    203 | 101          | -1
+    204 | 101          | 204
+    301 | 101          | 201
+    601 | 101          | 204
+    """
+    _reset_feeder_ids(grid)
+    feeder_node_ids = grid.node.filter(node_type=NodeType.SUBSTATION_NODE).id
+    components = grid.graphs.active_graph.get_components(feeder_node_ids)
+    for component_node_ids in components:
+        component_branches = _get_active_component_branches(grid, component_node_ids)
+
+        feeder_branch = _get_feeder_branch(component_branches)
+
+        if feeder_branch.size == 0:
+            continue  # early exit
+
+        feeder_node_id = _get_feeder_node_id(feeder_branch, feeder_node_ids)
+
+        for array in grid.branch_arrays:
+            array.update_by_id(
+                component_branches.id,
+                feeder_branch_id=feeder_branch.id.item(),
+                feeder_node_id=feeder_node_id,
+                allow_missing=True,
+            )
+
+        grid.node.update_by_id(
+            component_node_ids,
+            feeder_branch_id=feeder_branch.id.item(),
+            feeder_node_id=feeder_node_id,
+            allow_missing=True,
+        )
+
+
+def set_is_feeder(grid: "Grid") -> None:
+    "Set the is_feeder property for all branches in the network."
+    feeder_node_ids = grid.node.filter(node_type=NodeType.SUBSTATION_NODE).id
+    array: BranchArray
+    for array in [grid.link, grid.line, grid.transformer]:
+        array.is_feeder = np.logical_xor(
+            np.isin(array.from_node, feeder_node_ids), np.isin(array.to_node, feeder_node_ids)
+        )
+
+
+def _reset_feeder_ids(grid: "Grid"):
+    # Resets all feeder ids to EMPTY_ID
+    for array in grid.branch_arrays:
+        array.set_empty("feeder_branch_id")
+        array.set_empty("feeder_node_id")
+
+    grid.node.set_empty("feeder_branch_id")
+    grid.node.set_empty("feeder_node_id")
+
+
+def _get_active_component_branches(grid: "Grid", component_node_ids: list[int]) -> BranchArray:
+    # a component is a set of actively connected nodes (ids)
+    # returns all active branches in the component
+
+    branches = grid.branches
+    branches_in_component = branches.filter(from_node=component_node_ids, to_node=component_node_ids, mode_="OR")
+    active_branches = branches_in_component.filter(from_status=1, to_status=1)
+    return active_branches
+
+
+def _get_feeder_branch(component_branches: BranchArray) -> BranchArray:
+    feeder_branches = component_branches.filter(is_feeder=True)
+
+    if feeder_branches.size == 1:
+        return feeder_branches
+
+    if feeder_branches.size > 1:
+        # Cannot point to multiple branches, so just pick the first one
+        return feeder_branches[0]
+
+    return BranchArray()
+
+
+def _get_feeder_node_id(feeder_branch: BranchArray, feeder_node_ids: np.ndarray) -> int:
+    # intersect to retrieve the feeder node id
+    feeder_node_id = np.intersect1d(feeder_branch.node_ids, feeder_node_ids)
+    return feeder_node_id.item()

power_grid_model_ds/_core/utils/misc.py

@@ -0,0 +1,41 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""Misc utils"""
+
+from collections.abc import Sequence
+from typing import Type, get_type_hints
+
+import numpy as np
+
+
+def is_sequence(seq):
+    """
+    Returns True for lists, tuples, sets, arrays
+    Return False for strings, dicts
+    """
+    if isinstance(seq, str):
+        return False
+
+    if isinstance(seq, (np.ndarray, set)):
+        return True
+    return isinstance(seq, Sequence)
+
+
+def get_inherited_attrs(cls: Type, *private_attributes):
+    """
+    Get the attribute from the object and all its parents
+    """
+
+    # The extras are needed for annotated types like NDArray3
+    retrieved_attributes = get_type_hints(cls, include_extras=True)
+    retrieved_attributes = {attr: type for attr, type in retrieved_attributes.items() if not attr.startswith("_")}
+
+    for private_attr in private_attributes:
+        for parent in reversed(list(cls.__mro__)):
+            attr_dict = retrieved_attributes.get(private_attr, {})
+            attr_dict.update(getattr(parent, private_attr, {}))
+            retrieved_attributes[private_attr] = attr_dict
+
+    return retrieved_attributes

power_grid_model_ds/_core/utils/pickle.py

@@ -0,0 +1,47 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""helper functions for pickling python objects and loading pickle objects"""
+
+import pickle
+from pathlib import Path
+
+from power_grid_model_ds._core.utils.zip import gzip2file
+
+
+def save_to_pickle(path: Path, python_object: object):
+    """Save a python object to pickle"""
+    path.parent.mkdir(exist_ok=True, parents=True)
+    with open(str(path), "wb") as file:
+        pickle.dump(python_object, file)
+
+
+def load_from_pickle(path: Path) -> object:
+    """Load a python object from a pickle file"""
+    with open(str(path), "rb") as file:
+        return pickle.load(file)
+
+
+def get_pickle_path(path: Path) -> Path:
+    """
+    Returns the path to the pickle file.
+    If ony a .gz-file is available, the .gz-file is unpacked.
+    """
+    pickle_suffix = ".pickle"
+    gz_suffix = ".gz"
+
+    if path.suffix == pickle_suffix and path.is_file():
+        return path
+
+    if path.with_suffix(pickle_suffix).is_file():
+        return path.with_suffix(pickle_suffix)
+
+    if path.suffix == gz_suffix and path.is_file():
+        return gzip2file(path)
+
+    pickle_gz_suffix = pickle_suffix + gz_suffix
+    if path.with_suffix(pickle_gz_suffix).is_file():
+        return gzip2file(path.with_suffix(pickle_gz_suffix))
+
+    raise FileNotFoundError(f"Expected either {path.name}.pickle or {path.name}.pickle.gz")

power_grid_model_ds/_core/utils/zip.py

@@ -0,0 +1,72 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""Helper functions for (un)zipping files"""
+
+import gzip
+import logging
+import os
+import shutil
+from pathlib import Path
+from typing import List
+from zipfile import ZipFile
+
+_logger = logging.getLogger(__name__)
+
+
+def zip_folder(folder_to_zip: Path) -> Path:
+    """Zip folder contents"""
+    zip_file_path = folder_to_zip.with_suffix(".zip").resolve()
+    folder_to_zip = folder_to_zip.resolve()
+
+    # move into folder to zip to avoid nested folders in .zip file
+    current_working_directory = os.getcwd()
+    os.chdir(folder_to_zip)
+    files_to_zip = [path.relative_to(folder_to_zip) for path in folder_to_zip.rglob("*")]
+    zip_files(zip_file_path, files_to_zip)
+
+    # move out of folder again
+    os.chdir(current_working_directory)
+
+    return zip_file_path
+
+
+def zip_files(zip_file_path: Path, files_to_zip: List[Path]) -> Path:
+    """Zip files"""
+    with ZipFile(str(zip_file_path.with_suffix(".zip")), "w") as zip_object:
+        for file in files_to_zip:
+            zip_object.write(str(file))
+        zip_object.close()
+    return zip_file_path.resolve()
+
+
+def unzip_files(zip_file_path: Path) -> Path:
+    """Unzip .zip file to folder"""
+    extraction_dir = zip_file_path.with_suffix("")
+    extraction_dir.mkdir(parents=True, exist_ok=True)
+    with ZipFile(str(zip_file_path.resolve()), "r") as zip_ref:
+        zip_ref.extractall(extraction_dir)
+    return extraction_dir
+
+
+def gzip2file(gzip_path: Path) -> Path:
+    """unzip a gzip (.gz) file"""
+    _logger.info(f"Unzipping {gzip_path.name}")
+
+    file_path = gzip_path.with_suffix("")
+    with gzip.open(gzip_path, "rb") as f_in:
+        with open(file_path, "wb") as f_out:
+            shutil.copyfileobj(f_in, f_out)
+    return file_path
+
+
+def file2gzip(file_path: Path) -> Path:
+    """zip a gzip (.gz) file"""
+    _logger.info(f"Zipping {file_path.name}")
+
+    gzip_path = file_path.with_suffix(f"{file_path.suffix}.gz")
+    with open(file_path, "rb") as f_in:
+        with gzip.open(gzip_path, "wb") as f_out:
+            shutil.copyfileobj(f_in, f_out)
+    return gzip_path

power_grid_model_ds/arrays.py

@@ -0,0 +1,39 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+from power_grid_model_ds._core.model.arrays import (
+    AsymVoltageSensorArray,
+    Branch3Array,
+    BranchArray,
+    IdArray,
+    LineArray,
+    LinkArray,
+    NodeArray,
+    SourceArray,
+    SymGenArray,
+    SymLoadArray,
+    SymPowerSensorArray,
+    SymVoltageSensorArray,
+    ThreeWindingTransformerArray,
+    TransformerArray,
+    TransformerTapRegulatorArray,
+)
+
+__all__ = [
+    "IdArray",
+    "NodeArray",
+    "BranchArray",
+    "LinkArray",
+    "LineArray",
+    "TransformerArray",
+    "Branch3Array",
+    "ThreeWindingTransformerArray",
+    "SourceArray",
+    "SymGenArray",
+    "SymLoadArray",
+    "TransformerTapRegulatorArray",
+    "AsymVoltageSensorArray",
+    "SymPowerSensorArray",
+    "SymVoltageSensorArray",
+]

power_grid_model_ds/constants.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+from power_grid_model_ds._core.model.constants import EMPTY_ID, empty
+
+__all__ = ["EMPTY_ID", "empty"]

power_grid_model_ds/enums.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+from power_grid_model_ds._core.model.enums.nodes import NodeType
+
+__all__ = ["NodeType"]

power_grid_model_ds/errors.py

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+from power_grid_model_ds._core.load_flow import PGMCoreException
+from power_grid_model_ds._core.model.arrays.base.errors import (
+    ArrayDefinitionError,
+    MultipleRecordsReturned,
+    RecordDoesNotExist,
+)
+from power_grid_model_ds._core.model.graphs.errors import (
+    GraphError,
+    MissingBranchError,
+    MissingNodeError,
+    NoPathBetweenNodes,
+)
+
+__all__ = [
+    "PGMCoreException",
+    "GraphError",
+    "ArrayDefinitionError",
+    "RecordDoesNotExist",
+    "MultipleRecordsReturned",
+    "MissingNodeError",
+    "MissingBranchError",
+    "NoPathBetweenNodes",
+]

power_grid_model_ds/fancypy.py

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+from power_grid_model_ds._core.fancypy import array_equal, concatenate, sort, unique
+from power_grid_model_ds._core.model.arrays.base.array import FancyArray
+from power_grid_model_ds._core.model.containers.base import FancyArrayContainer
+
+__all__ = ["FancyArray", "FancyArrayContainer", "concatenate", "unique", "sort", "array_equal"]

power_grid_model_ds/generators.py

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+from power_grid_model_ds._core.data_source.generator.arrays.line import LineGenerator
+from power_grid_model_ds._core.data_source.generator.arrays.node import NodeGenerator
+from power_grid_model_ds._core.data_source.generator.arrays.source import SourceGenerator
+from power_grid_model_ds._core.data_source.generator.arrays.transformer import TransformerGenerator
+from power_grid_model_ds._core.data_source.generator.grid_generators import RadialGridGenerator
+
+__all__ = ["RadialGridGenerator", "NodeGenerator", "LineGenerator", "TransformerGenerator", "SourceGenerator"]

power_grid_model_ds/graph_models.py

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+from power_grid_model_ds._core.model.graphs.models import RustworkxGraphModel
+from power_grid_model_ds._core.model.graphs.models.base import BaseGraphModel
+
+__all__ = ["BaseGraphModel", "RustworkxGraphModel"]