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

power_grid_model_ds/_core/model/graphs/container.py

@@ -0,0 +1,158 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""Stores the GraphContainer class"""
+
+import dataclasses
+from dataclasses import dataclass
+from pathlib import PosixPath
+from typing import Generator
+
+import numpy as np
+
+from power_grid_model_ds._core.model.arrays import Branch3Array, BranchArray, NodeArray
+from power_grid_model_ds._core.model.arrays.base.array import FancyArray
+from power_grid_model_ds._core.model.arrays.base.errors import RecordDoesNotExist
+from power_grid_model_ds._core.model.containers.grid_protocol import MinimalGridArrays
+from power_grid_model_ds._core.model.graphs.models import RustworkxGraphModel
+from power_grid_model_ds._core.model.graphs.models.base import BaseGraphModel
+
+
+@dataclass
+class GraphContainer:
+    """Contains graphs"""
+
+    active_graph: BaseGraphModel
+    """The graph containing only active branches."""
+
+    complete_graph: BaseGraphModel
+    """The graph containing all branches."""
+
+    @property
+    def graph_attributes(self) -> Generator:
+        """Get all graph attributes of the container.
+
+        Yield:
+            BaseGraphModel: The next graph attribute.
+        """
+        return (field for field in dataclasses.fields(self) if isinstance(getattr(self, field.name), BaseGraphModel))
+
+    @classmethod
+    def empty(cls, graph_model: type[BaseGraphModel] = RustworkxGraphModel) -> "GraphContainer":
+        """Get empty instance of GraphContainer.
+
+        Args:
+            graph_model (type[BaseGraphModel]): The graph model to use. Defaults to RustworkxGraphModel.
+              An alternative graph model can be passed as an argument.
+
+        Returns:
+            GraphContainer: The empty graph container.
+        """
+
+        return cls(
+            active_graph=graph_model(active_only=True),
+            complete_graph=graph_model(active_only=False),
+        )
+
+    def add_branch(self, branch: BranchArray) -> None:
+        """Add a branch to all graphs"""
+        for field in self.graph_attributes:
+            graph = getattr(self, field.name)
+            graph.add_branch_array(branch_array=branch)
+            setattr(self, field.name, graph)
+
+    def add_branch3(self, branch: Branch3Array) -> None:
+        """Add a branch to all graphs"""
+        for field in self.graph_attributes:
+            graph = getattr(self, field.name)
+            graph.add_branch3_array(branch3_array=branch)
+            setattr(self, field.name, graph)
+
+    def delete_branch(self, branch: BranchArray) -> None:
+        """Remove a branch from all graphs"""
+        for field in self.graph_attributes:
+            graph = getattr(self, field.name)
+            graph.delete_branch_array(branch_array=branch)
+            setattr(self, field.name, graph)
+
+    def delete_branch3(self, branch: Branch3Array) -> None:
+        """Remove a branch from all graphs"""
+        for field in self.graph_attributes:
+            graph = getattr(self, field.name)
+            graph.delete_branch3_array(branch3_array=branch)
+            setattr(self, field.name, graph)
+
+    def add_node(self, node: NodeArray) -> None:
+        """Add a node to all graphs"""
+        for field in dataclasses.fields(self):
+            graph = getattr(self, field.name)
+            graph.add_node_array(node_array=node, raise_on_fail=False)
+            setattr(self, field.name, graph)
+
+    def delete_node(self, node: NodeArray) -> None:
+        """Remove a node from all graphs"""
+        for field in dataclasses.fields(self):
+            graph = getattr(self, field.name)
+            graph.delete_node_array(node_array=node)
+            setattr(self, field.name, graph)
+
+    def make_active(self, branch: BranchArray) -> None:
+        """Add branch to all active_only graphs"""
+
+        from_node = branch.from_node.item()
+        to_node = branch.to_node.item()
+        for field in dataclasses.fields(self):
+            graph = getattr(self, field.name)
+            if graph.active_only:
+                graph.add_branch(from_ext_node_id=from_node, to_ext_node_id=to_node)
+            setattr(self, field.name, graph)
+
+    def make_inactive(self, branch: BranchArray) -> None:
+        """Remove a branch from all active_only graphs"""
+
+        from_node = branch.from_node.item()
+        to_node = branch.to_node.item()
+        for field in dataclasses.fields(self):
+            graph = getattr(self, field.name)
+            if graph.active_only:
+                graph.delete_branch(from_ext_node_id=from_node, to_ext_node_id=to_node)
+            setattr(self, field.name, graph)
+
+    def cache(self, cache_dir: PosixPath, compress: bool) -> PosixPath:
+        """Cache the container into a folder with .pkl and graph files"""
+        cache_dir.mkdir(parents=True, exist_ok=True)
+
+        for field in self.graph_attributes:
+            graph = getattr(self, field.name)
+            graph.cache(cache_dir=cache_dir, graph_name=field.name, compress=compress)
+        return cache_dir
+
+    @classmethod
+    def from_arrays(cls, arrays: MinimalGridArrays) -> "GraphContainer":
+        """Build from arrays"""
+        cls._validate_branches(arrays=arrays)
+
+        new_container = cls.empty()
+        for graph_field in new_container.graph_attributes:
+            graph = getattr(new_container, graph_field.name)
+            new_graph = graph.from_arrays(arrays, active_only=graph.active_only)
+            setattr(new_container, graph_field.name, new_graph)
+
+        return new_container
+
+    @staticmethod
+    def _validate_branches(arrays: MinimalGridArrays):
+        for array in arrays.branch_arrays:
+            if any(~np.isin(array.from_node, arrays.node.id)):
+                raise RecordDoesNotExist(f"Found invalid .from_node values in {array.__class__.__name__}")
+            if any(~np.isin(array.to_node, arrays.node.id)):
+                raise RecordDoesNotExist(f"Found invalid .to_node values in {array.__class__.__name__}")
+
+    def _append(self, array: FancyArray) -> None:
+        if isinstance(array, BranchArray):
+            self.add_branch(array)
+        if isinstance(array, Branch3Array):
+            self.add_branch3(array)
+        if isinstance(array, NodeArray):
+            self.add_node(array)

power_grid_model_ds/_core/model/graphs/errors.py

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+
+class GraphError(Exception):
+    """Raised when there is an error in the graph"""
+
+
+class MissingNodeError(GraphError):
+    """Raised when a node is missing"""
+
+
+class MissingBranchError(GraphError):
+    """Raised when a branch is missing"""
+
+
+class NoPathBetweenNodes(GraphError):
+    """Raised when there is no path between two nodes"""

power_grid_model_ds/_core/model/graphs/models/__init__.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.graphs.models.rustworkx import RustworkxGraphModel
+
+__all__ = ["RustworkxGraphModel"]

power_grid_model_ds/_core/model/graphs/models/_rustworkx_search.py

@@ -0,0 +1,63 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+from collections import Counter
+
+import rustworkx as rx
+
+
+def find_fundamental_cycles_rustworkx(graph):
+    """Detect fundamental cycles in the graph and returns the node cycle paths.
+
+    The nodes in cycles are found by:
+    1. Creating a minimum spanning forest (MSF) of the (possibly disconnected) graph, which is a set of minimum
+    spanning trees (MST's). Here, a MST is a subset of the original graph that connects all nodes with the minimum
+    possible amount of edges. (Also, see https://mathworld.wolfram.com/SpanningTree.html).
+
+    For a connected graph, all nodes are connected by edges, leading to a single MST. In that case,
+    the MSF consists of a single MST. (See https://mathworld.wolfram.com/ConnectedGraph.html for more information).
+
+    For a disconnected graph, there are multiple separated subgraphs; in other words, not all nodes are connected.
+    (ALso, see https://mathworld.wolfram.com/DisconnectedGraph.html). Each of the subgraphs will then form a MST.
+    The MSF is then the collection of these MST's.
+
+    NOTE: If there are cycles in the graph, the MSF is not unique. One of the options will be chosen.
+    Regardless of the chosen MSF, the algorithm works.
+
+    2. Determining which edges in the original graph are not part of the MSF. A propery of MST's is that adding
+    a single edge between nodes will always form a cycle.
+
+    3. Looping through the unused edges and determining the path of nodes of the cycle it would form.
+    This is done by determining the shortest path between the nodes on both sides of an unused edge within the MSF.
+    A combination of this shortest path and the unused edge forms the cycle path. A list of these paths is returned.
+
+    Returns:
+        node_cycle_paths(list[list[[int]]): a list of node paths, which are each a list of node_ids in a path.
+    """
+    mst = rx.minimum_spanning_tree(graph)
+    unused_edges = _find_unused_edges_rustworkx(graph, mst)
+    node_cycle_paths = _get_cycle_paths_rustworkx(unused_edges, mst)
+
+    return node_cycle_paths
+
+
+def _find_unused_edges_rustworkx(full_graph, subset_graph):
+    """Determine unused edges by comparing all edges with a subset of edges in the MST."""
+    full_edges = Counter(full_graph.edge_list())
+    subset_edges = Counter(subset_graph.edge_list())
+    unused_edges = full_edges - subset_edges
+    return unused_edges
+
+
+def _get_cycle_paths_rustworkx(unused_edges, spanning_forest_graph):
+    """Find nodes that are part of a cycle in the graph using the MST."""
+    node_cycle_paths = []
+    for source, target in unused_edges:
+        path_mapping = rx.dijkstra_shortest_paths(spanning_forest_graph, source, target, weight_fn=lambda x: 1)
+
+        path_nodes = list(path_mapping[target])
+        path_nodes.append(source)
+
+        node_cycle_paths.append(path_nodes)
+    return node_cycle_paths

power_grid_model_ds/_core/model/graphs/models/base.py

@@ -0,0 +1,326 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+from abc import ABC, abstractmethod
+
+import numpy as np
+from numpy._typing import NDArray
+
+from power_grid_model_ds._core.model.arrays.pgm_arrays import Branch3Array, BranchArray, NodeArray
+from power_grid_model_ds._core.model.containers.grid_protocol import MinimalGridArrays
+from power_grid_model_ds._core.model.graphs.errors import (
+    GraphError,
+    MissingBranchError,
+    MissingNodeError,
+    NoPathBetweenNodes,
+)
+
+
+# pylint: disable=too-many-public-methods
+class BaseGraphModel(ABC):
+    """Base class for graph models"""
+
+    def __init__(self, active_only=False) -> None:
+        self.active_only = active_only
+
+    @property
+    @abstractmethod
+    def nr_nodes(self):
+        """Returns the number of nodes in the graph"""
+
+    @property
+    @abstractmethod
+    def nr_branches(self):
+        """Returns the number of branches in the graph"""
+
+    @abstractmethod
+    def external_to_internal(self, ext_node_id: int) -> int:
+        """Convert external node id to internal node id (internal)
+
+        Raises:
+            MissingNodeError: if the external node id does not exist in the graph
+        """
+
+    @abstractmethod
+    def internal_to_external(self, int_node_id: int) -> int:
+        """Convert internal id (internal) to external node id"""
+
+    @property
+    @abstractmethod
+    def external_ids(self) -> list[int]:
+        """Return all external node ids
+
+        Warning: Depending on graph engine, performance could be slow for large graphs
+        """
+
+    def has_node(self, node_id: int) -> bool:
+        """Check if a node exists."""
+        try:
+            internal_node_id = self.external_to_internal(ext_node_id=node_id)
+        except MissingNodeError:
+            return False
+
+        return self._has_node(node_id=internal_node_id)
+
+    def add_node(self, ext_node_id: int, raise_on_fail: bool = True) -> None:
+        """Add a node to the graph."""
+        if self.has_node(ext_node_id):
+            if raise_on_fail:
+                raise GraphError(f"External node id '{ext_node_id}' already exists!")
+            return
+
+        self._add_node(ext_node_id)
+
+    def delete_node(self, ext_node_id: int, raise_on_fail: bool = True) -> None:
+        """Remove a node from the graph.
+
+        Args:
+            ext_node_id(int): id of the node to remove
+            raise_on_fail(bool): whether to raise an error if the node does not exist. Defaults to True
+
+        Raises:
+            MissingNodeError: if the node does not exist in the graph and ``raise_on_fail=True``
+        """
+        try:
+            internal_node_id = self.external_to_internal(ext_node_id)
+        except MissingNodeError as error:
+            if raise_on_fail:
+                raise error
+            return
+
+        self._delete_node(node_id=internal_node_id)
+
+    def add_node_array(self, node_array: NodeArray, raise_on_fail: bool = True) -> None:
+        """Add all nodes in the node array to the graph."""
+        for node in node_array:
+            self.add_node(ext_node_id=node.id.item(), raise_on_fail=raise_on_fail)
+
+    def delete_node_array(self, node_array: NodeArray, raise_on_fail: bool = True) -> None:
+        """Delete all nodes in node_array from the graph"""
+        for node in node_array:
+            self.delete_node(node.id.item(), raise_on_fail=raise_on_fail)
+
+    def has_branch(self, from_ext_node_id: int, to_ext_node_id: int) -> bool:
+        """Check if a branch exists between two nodes."""
+        try:
+            int_from_node_id = self.external_to_internal(from_ext_node_id)
+            int_to_node_id = self.external_to_internal(to_ext_node_id)
+        except MissingNodeError:
+            return False
+
+        return self._has_branch(from_node_id=int_from_node_id, to_node_id=int_to_node_id)
+
+    def add_branch(self, from_ext_node_id: int, to_ext_node_id: int) -> None:
+        """Add a new branch to the graph."""
+        self._add_branch(
+            from_node_id=self.external_to_internal(from_ext_node_id),
+            to_node_id=self.external_to_internal(to_ext_node_id),
+        )
+
+    def delete_branch(self, from_ext_node_id: int, to_ext_node_id: int, raise_on_fail: bool = True) -> None:
+        """Remove an existing branch from the graph.
+
+        Args:
+            from_ext_node_id: id of the from node
+            to_ext_node_id: id of the to node
+            raise_on_fail: whether to raise an error if the branch does not exist
+
+        Raises:
+            MissingBranchError: if branch does not exist in the graph and ``raise_on_fail=True``
+        """
+        try:
+            self._delete_branch(
+                from_node_id=self.external_to_internal(from_ext_node_id),
+                to_node_id=self.external_to_internal(to_ext_node_id),
+            )
+        except (MissingNodeError, MissingBranchError) as error:
+            if raise_on_fail:
+                raise MissingBranchError(
+                    f"Branch between nodes {from_ext_node_id} and {to_ext_node_id} does NOT exist!"
+                ) from error
+
+    def add_branch_array(self, branch_array: BranchArray) -> None:
+        """Add all branches in the branch array to the graph."""
+        for branch in branch_array:
+            if self._branch_is_relevant(branch):
+                self.add_branch(branch.from_node.item(), branch.to_node.item())
+
+    def add_branch3_array(self, branch3_array: Branch3Array) -> None:
+        """Add all branch3s in the branch3 array to the graph."""
+        for branch3 in branch3_array:
+            branches = _get_branch3_branches(branch3)
+            self.add_branch_array(branches)
+
+    def delete_branch_array(self, branch_array: BranchArray, raise_on_fail: bool = True) -> None:
+        """Delete all branches in branch_array from the graph."""
+        for branch in branch_array:
+            if self._branch_is_relevant(branch):
+                self.delete_branch(branch.from_node.item(), branch.to_node.item(), raise_on_fail=raise_on_fail)
+
+    def delete_branch3_array(self, branch_array: Branch3Array, raise_on_fail: bool = True) -> None:
+        """Delete all branch3s in the branch3 array from the graph."""
+        for branch3 in branch_array:
+            branches = _get_branch3_branches(branch3)
+            self.delete_branch_array(branches, raise_on_fail=raise_on_fail)
+
+    def get_shortest_path(self, ext_start_node_id: int, ext_end_node_id: int) -> tuple[list[int], int]:
+        """Calculate the shortest path between two nodes
+
+        Example:
+            given this graph: [1] - [2] - [3] - [4]
+
+            >>> graph.get_shortest_path(1, 4) == [1, 2, 3, 4], 3
+            >>> graph.get_shortest_path(1, 1) == [1], 0
+
+        Returns:
+            tuple[list[int], int]: a tuple where the first element is a list of external nodes from start to end.
+            The second element is the distance of the path in number of edges.
+
+        Raises:
+            NoPathBetweenNodes: if no path exists between the given nodes
+        """
+        if ext_start_node_id == ext_end_node_id:
+            return [ext_start_node_id], 0
+
+        try:
+            internal_path, distance = self._get_shortest_path(
+                source=self.external_to_internal(ext_start_node_id), target=self.external_to_internal(ext_end_node_id)
+            )
+            return self._internals_to_externals(internal_path), distance
+        except NoPathBetweenNodes as e:
+            raise NoPathBetweenNodes(f"No path between nodes {ext_start_node_id} and {ext_end_node_id}") from e
+
+    def get_all_paths(self, ext_start_node_id: int, ext_end_node_id: int) -> list[list[int]]:
+        """Retrieves all paths between two (external) nodes.
+        Returns a list of paths, each path containing a list of external nodes.
+        """
+        if ext_start_node_id == ext_end_node_id:
+            return []
+
+        internal_paths = self._get_all_paths(
+            source=self.external_to_internal(ext_start_node_id),
+            target=self.external_to_internal(ext_end_node_id),
+        )
+
+        if internal_paths == []:
+            raise NoPathBetweenNodes(f"No path between nodes {ext_start_node_id} and {ext_end_node_id}")
+
+        return [self._internals_to_externals(path) for path in internal_paths]
+
+    def get_components(self, substation_nodes: NDArray[np.int32]) -> list[list[int]]:
+        """Returns all separate components when the substation_nodes are removed of the graph as lists"""
+        internal_components = self._get_components(substation_nodes=self._externals_to_internals(substation_nodes))
+        return [self._internals_to_externals(component) for component in internal_components]
+
+    def get_connected(
+        self, node_id: int, nodes_to_ignore: list[int] | None = None, inclusive: bool = False
+    ) -> list[int]:
+        """Find all nodes connected to the node_id
+
+        Args:
+            node_id: node id to start the search from
+            inclusive: whether to include the given node id in the result
+            nodes_to_ignore: list of node ids to ignore while traversing the graph.
+                              Any nodes connected to `node_id` (solely) through these nodes will
+                              not be included in the result
+        Returns:
+            nodes: list of node ids sorted by distance, connected to the node id
+        """
+        if nodes_to_ignore is None:
+            nodes_to_ignore = []
+
+        nodes = self._get_connected(
+            node_id=self.external_to_internal(node_id),
+            nodes_to_ignore=self._externals_to_internals(nodes_to_ignore),
+            inclusive=inclusive,
+        )
+        return self._internals_to_externals(nodes)
+
+    def find_fundamental_cycles(self) -> list[list[int]]:
+        """Find all fundamental cycles in the graph.
+        Returns:
+            list[list[int]]: list of cycles, each cycle is a list of (external) node ids
+        """
+        internal_cycles = self._find_fundamental_cycles()
+        return [self._internals_to_externals(nodes) for nodes in internal_cycles]
+
+    @classmethod
+    def from_arrays(cls, arrays: MinimalGridArrays, active_only=False) -> "BaseGraphModel":
+        """Build from arrays"""
+        new_graph = cls(active_only=active_only)
+
+        new_graph.add_node_array(node_array=arrays.node)
+        new_graph.add_branch_array(arrays.branches)
+        new_graph.add_branch3_array(arrays.three_winding_transformer)
+
+        return new_graph
+
+    def _internals_to_externals(self, internal_nodes: list[int]) -> list[int]:
+        """Convert a list of internal nodes to external nodes"""
+        return [self.internal_to_external(node_id) for node_id in internal_nodes]
+
+    def _externals_to_internals(self, external_nodes: list[int] | NDArray) -> list[int]:
+        """Convert a list of external nodes to internal nodes"""
+        return [self.external_to_internal(node_id) for node_id in external_nodes]
+
+    def _branch_is_relevant(self, branch: BranchArray) -> bool:
+        """Check if a branch is relevant"""
+        if self.active_only:
+            return branch.is_active.item()
+        return True
+
+    @abstractmethod
+    def _get_connected(self, node_id: int, nodes_to_ignore: list[int], inclusive: bool = False) -> list[int]: ...
+
+    @abstractmethod
+    def _has_branch(self, from_node_id, to_node_id) -> bool: ...
+
+    @abstractmethod
+    def _has_node(self, node_id) -> bool: ...
+
+    @abstractmethod
+    def _add_node(self, ext_node_id: int) -> None: ...
+
+    @abstractmethod
+    def _delete_node(self, node_id: int): ...
+
+    @abstractmethod
+    def _add_branch(self, from_node_id, to_node_id) -> None: ...
+
+    @abstractmethod
+    def _delete_branch(self, from_node_id, to_node_id) -> None:
+        """
+        Raises:
+            MissingBranchError: if the branch does not exist
+        """
+
+    @abstractmethod
+    def _get_shortest_path(self, source, target): ...
+
+    @abstractmethod
+    def _get_all_paths(self, source, target) -> list[list[int]]: ...
+
+    @abstractmethod
+    def _get_components(self, substation_nodes: list[int]) -> list[list[int]]: ...
+
+    @abstractmethod
+    def _find_fundamental_cycles(self) -> list[list[int]]: ...
+
+
+def _get_branch3_branches(branch3: Branch3Array) -> BranchArray:
+    node_1 = branch3.node_1.item()
+    node_2 = branch3.node_2.item()
+    node_3 = branch3.node_3.item()
+
+    status_1 = branch3.status_1.item()
+    status_2 = branch3.status_2.item()
+    status_3 = branch3.status_3.item()
+
+    branches = BranchArray.zeros(3)
+    branches.from_node = [node_1, node_1, node_2]
+    branches.to_node = [node_2, node_3, node_3]
+    branches.from_status = [status_1, status_1, status_2]
+    branches.to_status = [status_2, status_3, status_3]
+
+    return branches