pkstruct 0.1.0__py3-none-any.whl

pkstruct/graphs/shortest_path.py

@@ -0,0 +1,250 @@
+"""
+pkstruct.graphs.shortest_path
+==============================
+Shortest-path algorithms: Dijkstra, Bellman-Ford, Floyd-Warshall.
+"""
+
+from __future__ import annotations
+
+import heapq
+import math
+from typing import Any
+
+from pkstruct.graphs.graph import Graph
+from pkstruct.graphs.exceptions import (
+    NegativeCycleError,
+    NoPathError,
+    VertexNotFoundError,
+)
+
+
+def dijkstra(
+    graph: Graph, source: Any, target: Any | None = None
+) -> tuple[dict[Any, float], dict[Any, Any | None]]:
+    """Compute shortest paths from *source* using Dijkstra's algorithm.
+
+    Parameters
+    ----------
+    graph : Graph
+        Weighted graph (edge weights must be non-negative).
+    source : Any
+        Starting vertex.
+    target : Any, optional
+        If provided, early-exit when *target* is reached.
+
+    Returns
+    -------
+    tuple[dict[Any, float], dict[Any, Any | None]]
+        ``(distances, predecessors)`` where *distances* maps each vertex
+        to its shortest distance from *source*, and *predecessors* maps
+        each vertex to its predecessor on the shortest path.
+
+    Raises
+    ------
+    VertexNotFoundError
+        If *source* is not in the graph.
+    """
+    if not graph.has_vertex(source):
+        raise VertexNotFoundError(source)
+
+    distances: dict[Any, float] = {v: math.inf for v in graph}
+    predecessors: dict[Any, Any | None] = {v: None for v in graph}
+    distances[source] = 0.0
+
+    pq: list[tuple[float, Any]] = [(0.0, source)]
+    visited: set[Any] = set()
+
+    while pq:
+        d, v = heapq.heappop(pq)
+        if v in visited:
+            continue
+        visited.add(v)
+        if target is not None and v == target:
+            break
+        for neighbor in graph.get_neighbors(v):
+            if neighbor in visited:
+                continue
+            weight = graph.get_weight(v, neighbor)
+            new_dist = d + weight
+            if new_dist < distances[neighbor]:
+                distances[neighbor] = new_dist
+                predecessors[neighbor] = v
+                heapq.heappush(pq, (new_dist, neighbor))
+
+    return distances, predecessors
+
+
+def bellman_ford(graph: Graph, source: Any) -> tuple[dict[Any, float], dict[Any, Any | None]]:
+    """Compute shortest paths from *source* using Bellman-Ford.
+
+    Supports negative edge weights. Raises an error if a negative cycle
+    is reachable from *source*.
+
+    Parameters
+    ----------
+    graph : Graph
+        Weighted graph (may contain negative edge weights).
+    source : Any
+        Starting vertex.
+
+    Returns
+    -------
+    tuple[dict[Any, float], dict[Any, Any | None]]
+        ``(distances, predecessors)``.
+
+    Raises
+    ------
+    VertexNotFoundError
+        If *source* is not in the graph.
+    NegativeCycleError
+        If a negative-weight cycle is reachable from *source*.
+    """
+    if not graph.has_vertex(source):
+        raise VertexNotFoundError(source)
+
+    distances: dict[Any, float] = {v: math.inf for v in graph}
+    predecessors: dict[Any, Any | None] = {v: None for v in graph}
+    distances[source] = 0.0
+
+    vertices = list(graph)
+    n = len(vertices)
+    edges: list[tuple[Any, Any, float]] = []
+    for u in vertices:
+        for v in graph.get_neighbors(u):
+            w = graph.get_weight(u, v)
+            edges.append((u, v, w))
+
+    for _ in range(n - 1):
+        updated = False
+        for u, v, w in edges:
+            if distances[u] != math.inf and distances[u] + w < distances[v]:
+                distances[v] = distances[u] + w
+                predecessors[v] = u
+                updated = True
+        if not updated:
+            break
+
+    for u, v, w in edges:
+        if distances[u] != math.inf and distances[u] + w < distances[v]:
+            raise NegativeCycleError()
+
+    return distances, predecessors
+
+
+def floyd_warshall(
+    graph: Graph,
+) -> tuple[dict[Any, dict[Any, float]], dict[Any, dict[Any, Any | None]]]:
+    """Compute all-pairs shortest paths using Floyd-Warshall.
+
+    Parameters
+    ----------
+    graph : Graph
+        Weighted graph.
+
+    Returns
+    -------
+    tuple[dict[Any, dict[Any, float]], dict[Any, dict[Any, Any | None]]]
+        ``(distances, next_nodes)`` where *distances[u][v]* is the
+        shortest distance from *u* to *v*, and *next_nodes[u][v]* is
+        the next vertex on the shortest path from *u* to *v* (for path
+        reconstruction).
+
+    Raises
+    ------
+    NegativeCycleError
+        If the graph contains a negative-weight cycle.
+    """
+    vertices = list(graph)
+    dist: dict[Any, dict[Any, float]] = {u: {v: math.inf for v in vertices} for u in vertices}
+    nxt: dict[Any, dict[Any, Any | None]] = {u: {v: None for v in vertices} for u in vertices}
+
+    for v in vertices:
+        dist[v][v] = 0.0
+
+    for u in vertices:
+        for v in graph.get_neighbors(u):
+            w = graph.get_weight(u, v)
+            if w < dist[u][v]:
+                dist[u][v] = w
+                nxt[u][v] = v
+
+    for k in vertices:
+        for i in vertices:
+            for j in vertices:
+                if dist[i][k] != math.inf and dist[k][j] != math.inf:
+                    new_dist = dist[i][k] + dist[k][j]
+                    if new_dist < dist[i][j]:
+                        dist[i][j] = new_dist
+                        nxt[i][j] = nxt[i][k]
+
+    for v in vertices:
+        if dist[v][v] < 0:
+            raise NegativeCycleError()
+
+    return dist, nxt
+
+
+def reconstruct_path(predecessors: dict[Any, Any | None], source: Any, target: Any) -> list[Any]:
+    """Reconstruct a shortest path from a predecessors dictionary.
+
+    Parameters
+    ----------
+    predecessors : dict[Any, Any | None]
+        Predecessor map from Dijkstra or Bellman-Ford.
+    source : Any
+        Starting vertex.
+    target : Any
+        Target vertex.
+
+    Returns
+    -------
+    list[Any]
+        The path from *source* to *target* as a list of vertices.
+
+    Raises
+    ------
+    NoPathError
+        If no path exists.
+    """
+    path: list[Any] = []
+    v = target
+    while v is not None:
+        path.append(v)
+        v = predecessors[v]
+    path.reverse()
+    if path[0] != source:
+        raise NoPathError(source, target)
+    return path
+
+
+def reconstruct_path_fw(
+    next_nodes: dict[Any, dict[Any, Any | None]], source: Any, target: Any
+) -> list[Any]:
+    """Reconstruct a shortest path from Floyd-Warshall's next_nodes table.
+
+    Parameters
+    ----------
+    next_nodes : dict[Any, dict[Any, Any | None]]
+        Next-node map from :func:`floyd_warshall`.
+    source : Any
+        Starting vertex.
+    target : Any
+        Target vertex.
+
+    Returns
+    -------
+    list[Any]
+        The path from *source* to *target*.
+
+    Raises
+    ------
+    NoPathError
+        If no path exists.
+    """
+    if next_nodes[source][target] is None and source != target:
+        raise NoPathError(source, target)
+    path: list[Any] = [source]
+    while source != target:
+        source = next_nodes[source][target]
+        path.append(source)
+    return path

pkstruct/graphs/topo_sort.py

@@ -0,0 +1,108 @@
+"""
+pkstruct.graphs.topo_sort
+=========================
+Topological sort algorithms: Kahn's algorithm and DFS-based sort.
+"""
+
+from __future__ import annotations
+
+from collections import deque, defaultdict
+from typing import Any
+
+from pkstruct.graphs.graph import Graph
+from pkstruct.graphs.exceptions import InvalidGraphOperationError
+
+
+def topological_sort_kahn(graph: Graph) -> list[Any]:
+    """Topological sort using Kahn's algorithm (BFS-based).
+
+    Parameters
+    ----------
+    graph : Graph
+        A directed graph.
+
+    Returns
+    -------
+    list[Any]
+        Vertices in topological order.
+
+    Raises
+    ------
+    InvalidGraphOperationError
+        If the graph is undirected or contains a cycle.
+    """
+    if not graph.is_directed():
+        raise InvalidGraphOperationError("Topological sort requires a directed graph.")
+
+    in_degree: dict[Any, int] = {v: 0 for v in graph}
+    for u in graph:
+        for v in graph.get_neighbors(u):
+            in_degree[v] += 1
+
+    queue: deque[Any] = deque([v for v in graph if in_degree[v] == 0])
+    result: list[Any] = []
+
+    while queue:
+        v = queue.popleft()
+        result.append(v)
+        for neighbor in graph.get_neighbors(v):
+            in_degree[neighbor] -= 1
+            if in_degree[neighbor] == 0:
+                queue.append(neighbor)
+
+    if len(result) != len(list(graph)):
+        raise InvalidGraphOperationError("Graph contains a cycle; topological sort not possible.")
+
+    return result
+
+
+def topological_sort_dfs(graph: Graph) -> list[Any]:
+    """Topological sort using DFS-based algorithm.
+
+    Parameters
+    ----------
+    graph : Graph
+        A directed graph.
+
+    Returns
+    -------
+    list[Any]
+        Vertices in topological order.
+
+    Raises
+    ------
+    InvalidGraphOperationError
+        If the graph is undirected or contains a cycle.
+    """
+    if not graph.is_directed():
+        raise InvalidGraphOperationError("Topological sort requires a directed graph.")
+
+    WHITE, GRAY, BLACK = 0, 1, 2
+    color: dict[Any, int] = {v: WHITE for v in graph}
+    result: list[Any] = []
+    has_cycle: bool = False
+
+    def _dfs(v: Any) -> None:
+        nonlocal has_cycle
+        if has_cycle:
+            return
+        color[v] = GRAY
+        for neighbor in graph.get_neighbors(v):
+            if color[neighbor] == GRAY:
+                has_cycle = True
+                return
+            if color[neighbor] == WHITE:
+                _dfs(neighbor)
+        color[v] = BLACK
+        result.append(v)
+
+    for v in graph:
+        if color[v] == WHITE:
+            _dfs(v)
+            if has_cycle:
+                raise InvalidGraphOperationError(
+                    "Graph contains a cycle; topological sort not possible."
+                )
+
+    result.reverse()
+    return result

pkstruct/graphs/traversal.py

@@ -0,0 +1,175 @@
+"""
+pkstruct.graphs.traversal
+=========================
+Graph traversal algorithms: BFS and DFS.
+
+All functions operate on any ``Graph``-like object that provides
+``get_neighbors(v)`` and ``has_vertex(v)``.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Iterator
+from typing import Any
+
+from pkstruct.graphs.graph import Graph
+
+
+def bfs(graph: Graph, start: Any) -> list[Any]:
+    """Breadth-first search returning vertices in visitation order.
+
+    Parameters
+    ----------
+    graph : Graph
+        The graph to traverse.
+    start : Any
+        The starting vertex.
+
+    Returns
+    -------
+    list[Any]
+        Vertices in BFS order.
+
+    Raises
+    ------
+    VertexNotFoundError
+        If *start* is not in the graph.
+    """
+    if not graph.has_vertex(start):
+        from pkstruct.graphs.exceptions import VertexNotFoundError
+
+        raise VertexNotFoundError(start)
+
+    visited: set[Any] = set()
+    result: list[Any] = []
+    queue: deque[Any] = deque([start])
+    visited.add(start)
+
+    while queue:
+        v = queue.popleft()
+        result.append(v)
+        for neighbor in graph.get_neighbors(v):
+            if neighbor not in visited:
+                visited.add(neighbor)
+                queue.append(neighbor)
+
+    return result
+
+
+def dfs(graph: Graph, start: Any) -> list[Any]:
+    """Depth-first search returning vertices in visitation order.
+
+    Parameters
+    ----------
+    graph : Graph
+        The graph to traverse.
+    start : Any
+        The starting vertex.
+
+    Returns
+    -------
+    list[Any]
+        Vertices in DFS order.
+
+    Raises
+    ------
+    VertexNotFoundError
+        If *start* is not in the graph.
+    """
+    if not graph.has_vertex(start):
+        from pkstruct.graphs.exceptions import VertexNotFoundError
+
+        raise VertexNotFoundError(start)
+
+    visited: set[Any] = set()
+    result: list[Any] = []
+    _dfs_recursive(graph, start, visited, result)
+    return result
+
+
+def _dfs_recursive(graph: Graph, v: Any, visited: set[Any], result: list[Any]) -> None:
+    visited.add(v)
+    result.append(v)
+    for neighbor in graph.get_neighbors(v):
+        if neighbor not in visited:
+            _dfs_recursive(graph, neighbor, visited, result)
+
+
+def bfs_paths(graph: Graph, start: Any, goal: Any) -> list[list[Any]]:
+    """Return all shortest paths from *start* to *goal* using BFS.
+
+    Parameters
+    ----------
+    graph : Graph
+        The graph to search.
+    start : Any
+        Starting vertex.
+    goal : Any
+        Target vertex.
+
+    Returns
+    -------
+    list[list[Any]]
+        All shortest paths from start to goal (may be multiple if
+        there are multiple shortest paths).
+    """
+    queue: deque[list[Any]] = deque([[start]])
+    result: list[list[Any]] = []
+    shortest: int | None = None
+
+    while queue:
+        path = queue.popleft()
+        v = path[-1]
+        if v == goal:
+            if shortest is None:
+                shortest = len(path)
+            if len(path) == shortest:
+                result.append(path)
+            continue
+        if shortest is not None and len(path) >= shortest:
+            continue
+        for neighbor in graph.get_neighbors(v):
+            if neighbor not in path:
+                queue.append(path + [neighbor])
+
+    return result
+
+
+def dfs_paths(graph: Graph, start: Any, goal: Any) -> list[list[Any]]:
+    """Return all paths from *start* to *goal* using DFS.
+
+    Parameters
+    ----------
+    graph : Graph
+        The graph to search.
+    start : Any
+        Starting vertex.
+    goal : Any
+        Target vertex.
+
+    Returns
+    -------
+    list[list[Any]]
+        All paths from start to goal.
+    """
+    result: list[list[Any]] = []
+    _dfs_paths_recursive(graph, start, goal, [start], result)
+    return result
+
+
+def _dfs_paths_recursive(
+    graph: Graph,
+    v: Any,
+    goal: Any,
+    path: list[Any],
+    result: list[list[Any]],
+) -> None:
+    if v == goal:
+        result.append(list(path))
+        return
+    for neighbor in graph.get_neighbors(v):
+        if neighbor not in path:
+            path.append(neighbor)
+            _dfs_paths_recursive(graph, neighbor, goal, path, result)
+            path.pop()

pkstruct/graphs/visualization.py

@@ -0,0 +1,90 @@
+"""
+pkstruct.graphs.visualization
+=============================
+ASCII visualization utilities for graphs.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pkstruct.graphs.graph import Graph
+from pkstruct.graphs.exceptions import VertexNotFoundError
+
+
+def visualize(graph: Graph, show_weights: bool = True) -> str:
+    """Return an ASCII representation of the graph.
+
+    Parameters
+    ----------
+    graph : Graph
+        The graph to visualize.
+    show_weights : bool, default=True
+        If *True*, display edge weights.
+
+    Returns
+    -------
+    str
+        Multi-line ASCII art of the graph.
+    """
+    lines: list[str] = []
+    lines.append(
+        f"Graph (directed={graph.is_directed()}, vertices={graph.order()}, edges={graph.edge_count()})"
+    )
+    lines.append("")
+
+    if graph.is_empty():
+        lines.append("(empty)")
+        return "\n".join(lines)
+
+    for v in graph:
+        neighbors = graph.get_neighbors(v)
+        if not neighbors:
+            lines.append(f"  {v!r} -> (isolated)")
+        else:
+            parts: list[str] = []
+            for n in neighbors:
+                w = graph.get_weight(v, n)
+                if show_weights:
+                    parts.append(f"{n!r} [{w}]")
+                else:
+                    parts.append(f"{n!r}")
+            arrow = " <-> " if not graph.is_directed() else " -> "
+            lines.append(f"  {v!r} -> {arrow.join(parts)}")
+
+    return "\n".join(lines)
+
+
+def adjacency_matrix(graph: Graph) -> str:
+    """Return the adjacency matrix as a formatted string.
+
+    Parameters
+    ----------
+    graph : Graph
+        The graph to render.
+
+    Returns
+    -------
+    str
+        String representation of the adjacency matrix.
+    """
+    vertices = list(graph)
+    n = len(vertices)
+    if n == 0:
+        return "(empty)"
+
+    idx = {v: i for i, v in enumerate(vertices)}
+    matrix: list[list[str]] = [["."] * n for _ in range(n)]
+
+    for u in vertices:
+        for v in graph.get_neighbors(u):
+            w = graph.get_weight(u, v)
+            matrix[idx[u]][idx[v]] = str(w)
+
+    header = "    " + "  ".join(f"{v!r:>4}" for v in vertices)
+    rows: list[str] = [header]
+    for i, v in enumerate(vertices):
+        row = f"{v!r:>3} " + "  ".join(f"{matrix[i][j]:>4}" for j in range(n))
+        rows.append(row)
+
+    return "\n".join(rows)

pkstruct/graphs/weighted.py

@@ -0,0 +1,37 @@
+"""
+pkstruct.graphs.weighted
+========================
+Weighted graph convenience class and weighted-graph utility functions.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pkstruct.graphs.graph import Graph
+
+
+class WeightedGraph(Graph):
+    """A weighted undirected graph (convenience subclass of ``Graph``).
+
+    Every edge carries a numeric weight (default ``1.0``).
+    Useful as a shorthand when all edges are expected to have meaningful
+    weights (e.g., for shortest-path or MST algorithms).
+
+    Example
+    -------
+    >>> g = WeightedGraph()
+    >>> g.add_edge("A", "B", 4.2)
+    >>> g.add_edge("B", "C", 2.7)
+    >>> g.get_weight("A", "B")
+    4.2
+    """
+
+    def add_edge(self, u: Any, v: Any, weight: float = 1.0) -> None:
+        super().add_edge(u, v, weight)
+
+    def __repr__(self) -> str:
+        with self._lock:
+            vertices = list(self._adj.keys())
+            edges = self.get_edges()
+            return f"WeightedGraph(vertices={len(vertices)}, edges={len(edges)})"