pkstruct 0.1.0__py3-none-any.whl

pkstruct/graphs/graph.py

@@ -0,0 +1,262 @@
+"""
+pkstruct.graphs.graph
+=====================
+Core graph data structure using adjacency-list representation.
+
+Supports both directed and undirected modes, with optional edge weights.
+All public operations are thread-safe via ``StructureLock``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+from pkstruct.graphs.exceptions import VertexNotFoundError, EdgeNotFoundError
+from pkstruct.shared.threading import StructureLock
+
+
+class Graph:
+    """Adjacency-list based graph supporting directed/undirected and weighted modes.
+
+    Parameters
+    ----------
+    directed : bool, default=False
+        If *True*, edges are one-way; otherwise edges are bidirectional.
+
+    Example
+    -------
+    >>> g = Graph()
+    >>> g.add_vertex("A")
+    >>> g.add_edge("A", "B")
+    >>> g.add_edge("A", "C")
+    >>> len(g)
+    3
+    >>> list(g.get_neighbors("A"))
+    ['B', 'C']
+    """
+
+    __slots__ = ("_adj", "_directed", "_lock", "_edge_count")
+
+    def __init__(self, directed: bool = False) -> None:
+        self._adj: dict[Any, dict[Any, float]] = {}
+        self._directed: bool = directed
+        self._lock: StructureLock = StructureLock()
+        self._edge_count: int = 0
+
+    # ------------------------------------------------------------------
+    # Mutation
+    # ------------------------------------------------------------------
+
+    def add_vertex(self, v: Any) -> None:
+        """Add a vertex to the graph. No-op if already present."""
+        with self._lock:
+            if v not in self._adj:
+                self._adj[v] = {}
+
+    def add_edge(self, u: Any, v: Any, weight: float = 1.0) -> None:
+        """Add an edge between *u* and *v* with optional *weight*.
+
+        Vertices are created automatically if they do not exist.
+        If the edge already exists, its weight is updated.
+        """
+        with self._lock:
+            self.add_vertex(u)
+            self.add_vertex(v)
+            if v not in self._adj[u]:
+                self._edge_count += 1
+            self._adj[u][v] = weight
+            if not self._directed and u != v:
+                self._adj[v][u] = weight
+
+    def remove_vertex(self, v: Any) -> None:
+        """Remove *v* and all incident edges.
+
+        Raises
+        ------
+        VertexNotFoundError
+            If *v* is not in the graph.
+        """
+        with self._lock:
+            if v not in self._adj:
+                raise VertexNotFoundError(v)
+            for neighbor in list(self._adj[v]):
+                self._adj[neighbor].pop(v, None)
+            del self._adj[v]
+            self._edge_count = sum(len(nbrs) for nbrs in self._adj.values())
+            if not self._directed:
+                self._edge_count //= 2
+
+    def remove_edge(self, u: Any, v: Any) -> None:
+        """Remove the edge from *u* to *v*.
+
+        Raises
+        ------
+        VertexNotFoundError
+            If either vertex does not exist.
+        EdgeNotFoundError
+            If the edge does not exist.
+        """
+        with self._lock:
+            if u not in self._adj:
+                raise VertexNotFoundError(u)
+            if v not in self._adj:
+                raise VertexNotFoundError(v)
+            if v not in self._adj[u]:
+                raise EdgeNotFoundError(u, v)
+            del self._adj[u][v]
+            self._edge_count -= 1
+            if not self._directed and u != v:
+                self._adj[v].pop(u, None)
+
+    def clear(self) -> None:
+        """Remove all vertices and edges."""
+        with self._lock:
+            self._adj.clear()
+            self._edge_count = 0
+
+    # ------------------------------------------------------------------
+    # Access
+    # ------------------------------------------------------------------
+
+    def has_vertex(self, v: Any) -> bool:
+        """Return *True* if *v* is in the graph."""
+        with self._lock:
+            return v in self._adj
+
+    def has_edge(self, u: Any, v: Any) -> bool:
+        """Return *True* if the edge (u, v) exists."""
+        with self._lock:
+            return u in self._adj and v in self._adj[u]
+
+    def get_weight(self, u: Any, v: Any) -> float:
+        """Return the weight of edge (u, v).
+
+        Raises
+        ------
+        VertexNotFoundError
+            If either vertex does not exist.
+        EdgeNotFoundError
+            If the edge does not exist.
+        """
+        with self._lock:
+            if u not in self._adj:
+                raise VertexNotFoundError(u)
+            if v not in self._adj[u]:
+                raise EdgeNotFoundError(u, v)
+            return self._adj[u][v]
+
+    def set_weight(self, u: Any, v: Any, weight: float) -> None:
+        """Set the weight of edge (u, v).
+
+        Raises
+        ------
+        VertexNotFoundError
+            If either vertex does not exist.
+        EdgeNotFoundError
+            If the edge does not exist.
+        """
+        with self._lock:
+            if u not in self._adj:
+                raise VertexNotFoundError(u)
+            if v not in self._adj[u]:
+                raise EdgeNotFoundError(u, v)
+            self._adj[u][v] = weight
+            if not self._directed and u != v:
+                self._adj[v][u] = weight
+
+    def get_neighbors(self, v: Any) -> list[Any]:
+        """Return a list of neighbors of *v* (outgoing in directed mode).
+
+        Raises
+        ------
+        VertexNotFoundError
+            If *v* is not in the graph.
+        """
+        with self._lock:
+            if v not in self._adj:
+                raise VertexNotFoundError(v)
+            return list(self._adj[v].keys())
+
+    def get_vertices(self) -> list[Any]:
+        """Return a list of all vertices in the graph."""
+        with self._lock:
+            return list(self._adj.keys())
+
+    def get_edges(self) -> list[tuple[Any, Any, float]]:
+        """Return a list of all edges as (u, v, weight) tuples."""
+        with self._lock:
+            edges: list[tuple[Any, Any, float]] = []
+            seen: set[frozenset] = set()
+            for u in self._adj:
+                for v, w in self._adj[u].items():
+                    if not self._directed:
+                        key = frozenset((u, v))
+                        if key in seen:
+                            continue
+                        seen.add(key)
+                    edges.append((u, v, w))
+            return edges
+
+    def degree(self, v: Any) -> int:
+        """Return the degree of vertex *v*.
+
+        For directed graphs, returns the out-degree (number of outgoing edges).
+
+        Raises
+        ------
+        VertexNotFoundError
+            If *v* is not in the graph.
+        """
+        with self._lock:
+            if v not in self._adj:
+                raise VertexNotFoundError(v)
+            return len(self._adj[v])
+
+    def order(self) -> int:
+        """Return the number of vertices in the graph."""
+        with self._lock:
+            return len(self._adj)
+
+    def edge_count(self) -> int:
+        """Return the number of edges in the graph."""
+        with self._lock:
+            return self._edge_count
+
+    def is_directed(self) -> bool:
+        """Return *True* if this is a directed graph."""
+        return self._directed
+
+    def is_empty(self) -> bool:
+        """Return *True* if the graph has no vertices."""
+        with self._lock:
+            return len(self._adj) == 0
+
+    def copy(self) -> Graph:
+        """Return a deep copy of the graph."""
+        with self._lock:
+            new_graph = Graph(directed=self._directed)
+            for v in self._adj:
+                new_graph._adj[v] = dict(self._adj[v])
+            new_graph._edge_count = self._edge_count
+            return new_graph
+
+    # ------------------------------------------------------------------
+    # Dunders
+    # ------------------------------------------------------------------
+
+    def __len__(self) -> int:
+        return self.order()
+
+    def __contains__(self, v: Any) -> bool:
+        return self.has_vertex(v)
+
+    def __iter__(self) -> Iterator[Any]:
+        vertices = self.get_vertices()
+        return iter(vertices)
+
+    def __repr__(self) -> str:
+        with self._lock:
+            vertices = list(self._adj.keys())
+            edges = self.get_edges()
+            return f"Graph(directed={self._directed}, vertices={len(vertices)}, edges={len(edges)})"

pkstruct/graphs/mst.py

@@ -0,0 +1,118 @@
+"""
+pkstruct.graphs.mst
+===================
+Minimum spanning tree algorithms: Kruskal and Prim.
+"""
+
+from __future__ import annotations
+
+import heapq
+from typing import Any
+
+from pkstruct.graphs.graph import Graph
+from pkstruct.graphs.exceptions import InvalidGraphOperationError
+
+
+def kruskal(graph: Graph) -> list[tuple[Any, Any, float]]:
+    """Compute the Minimum Spanning Tree using Kruskal's algorithm.
+
+    Parameters
+    ----------
+    graph : Graph
+        An undirected weighted graph.
+
+    Returns
+    -------
+    list[tuple[Any, Any, float]]
+        Edges of the MST as ``(u, v, weight)`` tuples.
+
+    Raises
+    ------
+    InvalidGraphOperationError
+        If the graph is directed.
+    """
+    if graph.is_directed():
+        raise InvalidGraphOperationError("Kruskal's algorithm requires an undirected graph.")
+
+    edges = sorted(graph.get_edges(), key=lambda e: e[2])
+    parent: dict[Any, Any] = {}
+    rank: dict[Any, int] = {}
+
+    def find(x: Any) -> Any:
+        while parent[x] != x:
+            parent[x] = parent[parent[x]]
+            x = parent[x]
+        return x
+
+    def union(x: Any, y: Any) -> None:
+        rx, ry = find(x), find(y)
+        if rx == ry:
+            return
+        if rank[rx] < rank[ry]:
+            parent[rx] = ry
+        elif rank[rx] > rank[ry]:
+            parent[ry] = rx
+        else:
+            parent[ry] = rx
+            rank[rx] += 1
+
+    for v in graph:
+        parent[v] = v
+        rank[v] = 0
+
+    mst: list[tuple[Any, Any, float]] = []
+    for u, v, w in edges:
+        if find(u) != find(v):
+            union(u, v)
+            mst.append((u, v, w))
+
+    return mst
+
+
+def prim(graph: Graph) -> list[tuple[Any, Any, float]]:
+    """Compute the Minimum Spanning Tree using Prim's algorithm.
+
+    Parameters
+    ----------
+    graph : Graph
+        An undirected weighted graph.
+
+    Returns
+    -------
+    list[tuple[Any, Any, float]]
+        Edges of the MST as ``(u, v, weight)`` tuples.
+
+    Raises
+    ------
+    InvalidGraphOperationError
+        If the graph is directed or empty.
+    """
+    if graph.is_directed():
+        raise InvalidGraphOperationError("Prim's algorithm requires an undirected graph.")
+
+    vertices = list(graph)
+    if not vertices:
+        raise InvalidGraphOperationError("Graph is empty.")
+
+    start = vertices[0]
+    visited: set[Any] = {start}
+    pq: list[tuple[float, Any, Any]] = []
+
+    for neighbor in graph.get_neighbors(start):
+        weight = graph.get_weight(start, neighbor)
+        heapq.heappush(pq, (weight, start, neighbor))
+
+    mst: list[tuple[Any, Any, float]] = []
+
+    while pq and len(visited) < len(vertices):
+        w, u, v = heapq.heappop(pq)
+        if v in visited:
+            continue
+        visited.add(v)
+        mst.append((u, v, w))
+        for neighbor in graph.get_neighbors(v):
+            if neighbor not in visited:
+                weight = graph.get_weight(v, neighbor)
+                heapq.heappush(pq, (weight, v, neighbor))
+
+    return mst

pkstruct/graphs/scc.py

@@ -0,0 +1,138 @@
+"""
+pkstruct.graphs.scc
+===================
+Strongly connected components algorithms: Kosaraju and Tarjan.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pkstruct.graphs.graph import Graph
+from pkstruct.graphs.directed import DirectedGraph
+from pkstruct.graphs.exceptions import InvalidGraphOperationError
+
+
+def kosaraju(graph: Graph) -> list[list[Any]]:
+    """Find strongly connected components using Kosaraju's algorithm.
+
+    Parameters
+    ----------
+    graph : Graph
+        A directed graph.
+
+    Returns
+    -------
+    list[list[Any]]
+        List of SCCs, each being a list of vertices.
+
+    Raises
+    ------
+    InvalidGraphOperationError
+        If the graph is undirected.
+    """
+    if not graph.is_directed():
+        raise InvalidGraphOperationError("Kosaraju's algorithm requires a directed graph.")
+
+    visited: set[Any] = set()
+    finish_stack: list[Any] = []
+
+    def _dfs(v: Any) -> None:
+        visited.add(v)
+        for neighbor in graph.get_neighbors(v):
+            if neighbor not in visited:
+                _dfs(neighbor)
+        finish_stack.append(v)
+
+    for v in graph:
+        if v not in visited:
+            _dfs(v)
+
+    if isinstance(graph, DirectedGraph):
+        transposed = graph.reverse()
+    else:
+        transposed = DirectedGraph()
+        for v in graph:
+            transposed.add_vertex(v)
+        for u in graph:
+            for v, w in {n: graph.get_weight(u, n) for n in graph.get_neighbors(u)}.items():
+                transposed.add_edge(v, u, w)
+
+    visited.clear()
+    sccs: list[list[Any]] = []
+
+    def _dfs_reverse(v: Any, component: list[Any]) -> None:
+        visited.add(v)
+        component.append(v)
+        for neighbor in transposed.get_neighbors(v):
+            if neighbor not in visited:
+                _dfs_reverse(neighbor, component)
+
+    while finish_stack:
+        v = finish_stack.pop()
+        if v not in visited:
+            component: list[Any] = []
+            _dfs_reverse(v, component)
+            sccs.append(component)
+
+    return sccs
+
+
+def tarjan(graph: Graph) -> list[list[Any]]:
+    """Find strongly connected components using Tarjan's algorithm.
+
+    Parameters
+    ----------
+    graph : Graph
+        A directed graph.
+
+    Returns
+    -------
+    list[list[Any]]
+        List of SCCs, each being a list of vertices.
+
+    Raises
+    ------
+    InvalidGraphOperationError
+        If the graph is undirected.
+    """
+    if not graph.is_directed():
+        raise InvalidGraphOperationError("Tarjan's algorithm requires a directed graph.")
+
+    index_counter: int = 0
+    index: dict[Any, int] = {}
+    lowlink: dict[Any, int] = {}
+    stack: list[Any] = []
+    on_stack: set[Any] = set()
+    sccs: list[list[Any]] = []
+
+    def _strongconnect(v: Any) -> None:
+        nonlocal index_counter
+        index[v] = index_counter
+        lowlink[v] = index_counter
+        index_counter += 1
+        stack.append(v)
+        on_stack.add(v)
+
+        for neighbor in graph.get_neighbors(v):
+            if neighbor not in index:
+                _strongconnect(neighbor)
+                lowlink[v] = min(lowlink[v], lowlink[neighbor])
+            elif neighbor in on_stack:
+                lowlink[v] = min(lowlink[v], index[neighbor])
+
+        if lowlink[v] == index[v]:
+            component: list[Any] = []
+            while True:
+                w = stack.pop()
+                on_stack.discard(w)
+                component.append(w)
+                if w == v:
+                    break
+            sccs.append(component)
+
+    for v in graph:
+        if v not in index:
+            _strongconnect(v)
+
+    return sccs