pyfect-dev 0.1.0__py3-none-any.whl

pyfect/graph/_cycles.py

@@ -0,0 +1,144 @@
+"""Cycles and two-colorings."""
+
+from __future__ import annotations
+
+from collections import deque
+
+from pyfect.graph._compact import Compact, view
+from pyfect.graph._errors import fail
+from pyfect.graph._query import far_end
+from pyfect.graph._records import CycleResult
+from pyfect.graph._store import Store
+
+_NEW, _OPEN, _DONE = 0, 1, 2
+
+
+def find_cycle(store: Store) -> CycleResult | None:
+    """The first cycle a depth-first search from each node in order finds;
+    an undirected search does not go back along the edge it came by."""
+    colors: dict[int, int] = {}
+    parent_node: dict[int, int] = {}
+    parent_edge: dict[int, int] = {}
+
+    def cycle(ancestor: int, current: int, closing: int) -> CycleResult:
+        path = [current]
+        edges: list[int] = []
+        cursor = current
+        while cursor != ancestor:
+            edges.append(parent_edge[cursor])
+            cursor = parent_node[cursor]
+            path.append(cursor)
+        return CycleResult((*reversed(path), ancestor), (*reversed(edges), closing))
+
+    for start in store.nodes:
+        if colors.get(start, _NEW) != _NEW:
+            continue
+        colors[start] = _OPEN
+        stack = [[start, 0]]
+        while stack:
+            frame = stack[-1]
+            node = frame[0]
+            adjacency = store.adjacency[node]
+            if frame[1] >= len(adjacency):
+                colors[node] = _DONE
+                stack.pop()
+                continue
+            index = adjacency[frame[1]]
+            frame[1] += 1
+            if store.kind == "undirected" and parent_edge.get(node) == index:
+                continue
+            neighbor = far_end(store, node, store.edges[index])
+            color = colors.get(neighbor, _NEW)
+            if color == _OPEN:
+                return cycle(neighbor, node, index)
+            if color == _NEW:
+                colors[neighbor] = _OPEN
+                parent_node[neighbor] = node
+                parent_edge[neighbor] = index
+                stack.append([neighbor, 0])
+    return None
+
+
+def _undirected_acyclic(compact: Compact) -> bool:
+    neighbors, edges = compact.outgoing, compact.edge_rows
+    visited = [False] * len(compact)
+    for start in range(len(compact)):
+        if visited[start]:
+            continue
+        visited[start] = True
+        stack = [(start, -1)]
+        while stack:
+            node, came_by = stack.pop()
+            for neighbor, edge in zip(neighbors[node], edges[node], strict=True):
+                if edge == came_by:
+                    continue
+                if visited[neighbor]:
+                    return False
+                visited[neighbor] = True
+                stack.append((neighbor, edge))
+    return True
+
+
+def _directed_acyclic(compact: Compact) -> bool:
+    outgoing = compact.outgoing
+    colors = [_NEW] * len(compact)
+    for start in range(len(compact)):
+        if colors[start] != _NEW:
+            continue
+        colors[start] = _OPEN
+        stack = [[start, 0]]
+        while stack:
+            frame = stack[-1]
+            node = frame[0]
+            if frame[1] < len(outgoing[node]):
+                neighbor = outgoing[node][frame[1]]
+                frame[1] += 1
+                if colors[neighbor] == _OPEN:
+                    return False
+                if colors[neighbor] == _NEW:
+                    colors[neighbor] = _OPEN
+                    stack.append([neighbor, 0])
+            else:
+                colors[node] = _DONE
+                stack.pop()
+    return True
+
+
+def is_acyclic(store: Store) -> bool:
+    """Remembered on the store until a change could make or break a cycle."""
+    if store.acyclic is None:
+        compact = view(store)
+        store.acyclic = (
+            _undirected_acyclic(compact)
+            if store.kind == "undirected"
+            else _directed_acyclic(compact)
+        )
+    return store.acyclic
+
+
+def two_coloring(store: Store, operation: str) -> tuple[Compact, list[int]] | None:
+    """Each node's side (0 or 1) by breadth-first search from each
+    uncolored node in order, or ``None`` when an edge joins one side."""
+    if store.kind == "directed":
+        fail(f"Cannot {operation} of directed graph")
+    compact = view(store)
+    outgoing = compact.outgoing
+    colors = [-1] * len(compact)
+    for start in range(len(compact)):
+        if colors[start] != -1:
+            continue
+        colors[start] = 0
+        queue = deque([start])
+        while queue:
+            node = queue.popleft()
+            for neighbor in outgoing[node]:
+                if colors[neighbor] == -1:
+                    colors[neighbor] = 1 - colors[node]
+                    queue.append(neighbor)
+                elif colors[neighbor] == colors[node]:
+                    return None
+    return compact, colors
+
+
+def is_bipartite(store: Store) -> bool:
+    return two_coloring(store, "determine bipartite status") is not None

pyfect/graph/_enumerate.py

@@ -0,0 +1,168 @@
+"""Lazy path enumerations: every simple path, and every shortest path.
+
+Endpoints and the limit are checked when the enumeration is made; each
+``iter`` starts over on the graph as it is then (checking the endpoints
+again), and an iterator already running keeps the graph it started on.
+"""
+
+from __future__ import annotations
+
+import heapq
+import math
+from collections.abc import Iterator
+from typing import Any
+
+from pyfect.graph._compact import Compact, view
+from pyfect.graph._errors import bound, fail, missing_node
+from pyfect.graph._records import PathResult
+from pyfect.graph._shortest import Cost, edge_weights, non_negative, require_endpoints
+from pyfect.graph._store import Store
+from pyfect.graph._walker import Fresh
+
+LIMIT = "Path enumeration limit must be a non-negative integer or Infinity"
+
+
+def _ends(compact: Compact, source: int, target: int) -> tuple[int, int]:
+    start = compact.index_of(source)
+    if start is None:
+        raise missing_node(source)
+    goal = compact.index_of(target)
+    if goal is None:
+        raise missing_node(target)
+    return start, goal
+
+
+def _simple(
+    rows: list[list[tuple[int, int]]], start: int, goal: int, most: float
+) -> Iterator[tuple[list[int], list[int]]]:
+    """Up to ``most`` paths from ``start`` to ``goal`` visiting no node
+    twice, depth-first along ``rows`` (each node's ``(neighbor, edge)``
+    pairs, in order), as compact nodes and edges."""
+    nodes = [start]
+    hops: list[int] = []
+    visited = [False] * len(rows)
+    visited[start] = True
+    stack = [[start, 0]]
+    emitted = 0
+
+    def backtrack() -> None:
+        node = stack.pop()[0]
+        if stack:
+            visited[node] = False
+            nodes.pop()
+            hops.pop()
+
+    while stack and emitted < most:
+        frame = stack[-1]
+        node = frame[0]
+        if node == goal:
+            emitted += 1
+            yield nodes, hops
+            backtrack()
+            continue
+        if frame[1] >= len(rows[node]):
+            backtrack()
+            continue
+        neighbor, edge = rows[node][frame[1]]
+        frame[1] += 1
+        if not visited[neighbor]:
+            visited[neighbor] = True
+            nodes.append(neighbor)
+            hops.append(edge)
+            stack.append([neighbor, 0])
+
+
+def simple_paths(
+    store: Store, source: int, target: int, limit: float | None
+) -> Fresh[PathResult[Any]]:
+    """Depth-first in edge order; a path's distance is its edge count."""
+    require_endpoints(store, source, target)
+    most = bound(limit, math.inf, LIMIT)
+
+    def walk() -> Iterator[PathResult[Any]]:
+        compact = view(store)
+        start, goal = _ends(compact, source, target)
+        if most == 0:
+            return
+        rows = [
+            list(zip(neighbors, edges, strict=True))
+            for neighbors, edges in zip(compact.outgoing, compact.edge_rows, strict=True)
+        ]
+        for nodes, hops in _simple(rows, start, goal, most):
+            yield PathResult(
+                tuple(compact.node_ids[n] for n in nodes),
+                tuple(compact.edge_ids[e] for e in hops),
+                len(hops),
+                tuple(compact.edges[e].data for e in hops),
+            )
+
+    return Fresh(walk)
+
+
+def _tied_predecessors(
+    compact: Compact, start: int, weights: list[float]
+) -> tuple[list[float], list[list[tuple[int, int]]]]:
+    """Dijkstra from ``start``, keeping every predecessor ``(node, edge)``
+    on a shortest path, in the order they were found."""
+    size = len(compact)
+    neighbors, edge_rows = compact.outgoing, compact.edge_rows
+    distances = [math.inf] * size
+    distances[start] = 0
+    previous: list[list[tuple[int, int]]] = [[] for _ in range(size)]
+    queue: list[tuple[float, int, int]] = [(0, 0, start)]
+    sequence = 1
+    while queue:
+        current_distance, _, current = heapq.heappop(queue)
+        if current_distance != distances[current]:
+            continue
+        for neighbor, edge in zip(neighbors[current], edge_rows[current], strict=True):
+            following = current_distance + weights[edge]
+            if weights[edge] != math.inf and not math.isfinite(following):
+                fail("All shortest paths distance calculation exceeded the finite number range")
+            if following < distances[neighbor]:
+                distances[neighbor] = following
+                previous[neighbor] = [(current, edge)]
+                heapq.heappush(queue, (following, sequence, neighbor))
+                sequence += 1
+            elif following == distances[neighbor] and following != math.inf:
+                previous[neighbor].append((current, edge))
+    return distances, previous
+
+
+def all_shortest_paths(
+    store: Store, source: int, target: int, cost: Cost, limit: float | None
+) -> Fresh[PathResult[Any]]:
+    """Every simple path of least total cost, found by walking back from
+    ``target`` through each node's tied predecessors in edge order. Costs
+    are read when iteration starts."""
+    require_endpoints(store, source, target)
+    most = bound(limit, math.inf, LIMIT)
+
+    def walk() -> Iterator[PathResult[Any]]:
+        compact = view(store)
+        start, goal = _ends(compact, source, target)
+        weights = edge_weights(
+            store,
+            compact,
+            cost,
+            non_negative,
+            "All shortest paths requires non-negative edge weights",
+        )
+        if most == 0:
+            return
+        distances, previous = _tied_predecessors(compact, start, weights)
+        distance = distances[goal]
+        if distance == math.inf:
+            return
+        if start == goal:
+            yield PathResult((source,), (), 0, ())
+            return
+        for nodes, hops in _simple(previous, goal, start, most):
+            yield PathResult(
+                tuple(compact.node_ids[n] for n in reversed(nodes)),
+                tuple(compact.edge_ids[e] for e in reversed(hops)),
+                distance,
+                tuple(compact.edges[e].data for e in reversed(hops)),
+            )
+
+    return Fresh(walk)

pyfect/graph/_errors.py

@@ -0,0 +1,51 @@
+"""``GraphError`` and the messages several modules raise it with."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Never
+
+from pyfect.errors import TaggedError
+
+MAX_SAFE_INDEX = 2**53 - 1
+"""Indexes stay JavaScript safe integers, so snapshots round-trip with Effect's."""
+
+
+@dataclass(eq=False)
+class GraphError(TaggedError):
+    """An invalid graph operation: a missing node, a kind mismatch, a
+    mutation of a finalized or busy graph, a bad weight."""
+
+    message: str
+
+    def __str__(self) -> str:
+        return self.message
+
+
+def fail(message: str) -> Never:
+    raise GraphError(message)
+
+
+def missing_node(node: int) -> GraphError:
+    return GraphError(f"Node {node} does not exist")
+
+
+def is_safe_index(value: object) -> bool:
+    """``Number.isSafeInteger(value) && value >= 0``."""
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        return False
+    return math.isfinite(value) and float(value).is_integer() and 0 <= value <= MAX_SAFE_INDEX
+
+
+def bound(value: float | None, default: float, message: str) -> float:
+    """A radius or limit: a non-negative whole number or ``math.inf``."""
+    chosen = default if value is None else value
+    if chosen != math.inf and not (
+        not isinstance(chosen, bool)
+        and math.isfinite(chosen)
+        and float(chosen).is_integer()
+        and chosen >= 0
+    ):
+        fail(message)
+    return chosen

pyfect/graph/_flow.py

@@ -0,0 +1,164 @@
+"""Maximum flow and minimum cut (Edmonds-Karp on a residual graph)."""
+
+from __future__ import annotations
+
+import math
+from collections import deque
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from pyfect.graph._compact import Compact, view
+from pyfect.graph._errors import fail, missing_node
+from pyfect.graph._records import MaximumFlowResult, MinimumCutResult
+from pyfect.graph._store import Store
+
+
+@dataclass(slots=True)
+class _Arc:
+    origin: int
+    to: int
+    capacity: float
+    flow: float = 0.0
+
+
+@dataclass(frozen=True, slots=True)
+class _Solution:
+    flow: MaximumFlowResult
+    source_side: list[bool]
+    node_ids: list[int]
+
+
+def _source_side(size: int, source: int, residual: _Residual) -> list[bool]:
+    """The nodes the source reaches on residual capacity."""
+    arcs, adjacency = residual.arcs, residual.adjacency
+    side = [False] * size
+    side[source] = True
+    queue = deque([source])
+    while queue:
+        for index in adjacency[queue.popleft()]:
+            arc = arcs[index]
+            if arc.capacity - arc.flow > 0 and not side[arc.to]:
+                side[arc.to] = True
+                queue.append(arc.to)
+    return side
+
+
+@dataclass(slots=True)
+class _Residual:
+    """Each edge as a forward arc (``forward[edge]``, -1 for a self-loop)
+    paired with a reverse arc at the next index."""
+
+    arcs: list[_Arc]
+    adjacency: list[list[int]]
+    forward: list[int]
+
+
+def _residual(store: Store, compact: Compact, capacity: Callable[[Any], float]) -> _Residual:
+    sources, targets = compact.endpoints
+    residual = _Residual([], [[] for _ in range(len(compact))], [-1] * len(sources))
+    arcs, adjacency = residual.arcs, residual.adjacency
+
+    def build() -> None:
+        for edge, data in enumerate(e.data for e in compact.edges):
+            amount = float(capacity(data))
+            if not math.isfinite(amount) or amount < 0:
+                fail(f"Edge {compact.edge_ids[edge]} capacity must be a finite non-negative number")
+            origin, to = sources[edge], targets[edge]
+            if origin == to:
+                continue
+            residual.forward[edge] = len(arcs)
+            adjacency[origin].append(len(arcs))
+            arcs.append(_Arc(origin, to, amount))
+            adjacency[to].append(len(arcs))
+            arcs.append(_Arc(to, origin, 0.0))
+
+    store.guarded(build)
+    return residual
+
+
+def _solve(
+    store: Store, source_id: int, target_id: int, capacity: Callable[[Any], float]
+) -> _Solution:
+    if store.kind == "undirected":
+        fail("Cannot compute flow of undirected graph")
+    compact = view(store)
+    source = compact.index_of(source_id)
+    if source is None:
+        raise missing_node(source_id)
+    target = compact.index_of(target_id)
+    if target is None:
+        raise missing_node(target_id)
+    if source == target:
+        fail("Flow source and target must be different nodes")
+    residual = _residual(store, compact, capacity)
+    arcs = residual.arcs
+    value = 0.0
+    while (parent := _augmenting(len(compact), source, target, residual)) is not None:
+        path: list[_Arc] = []
+        node = target
+        while node != source:
+            path.append(arcs[parent[node]])
+            node = arcs[parent[node]].origin
+        amount = min(arc.capacity - arc.flow for arc in path)
+        if not math.isfinite(value + amount):
+            fail("Maximum flow exceeds the finite number range")
+        node = target
+        while node != source:
+            arcs[parent[node]].flow += amount
+            arcs[parent[node] ^ 1].flow -= amount
+            node = arcs[parent[node]].origin
+        value += amount
+    edge_ids = compact.edge_ids
+    sources, targets = compact.endpoints
+    flows = {
+        edge_ids[edge]: 0.0 if arc == -1 else arcs[arc].flow
+        for edge, arc in enumerate(residual.forward)
+    }
+    side = _source_side(len(compact), source, residual)
+    cut = tuple(
+        edge_ids[edge]
+        for edge in range(len(edge_ids))
+        if sources[edge] != targets[edge] and side[sources[edge]] and not side[targets[edge]]
+    )
+    return _Solution(MaximumFlowResult(value, flows, cut), side, compact.node_ids)
+
+
+def _augmenting(size: int, source: int, target: int, residual: _Residual) -> list[int] | None:
+    """Parent arcs of a shortest augmenting path, the search stopping as
+    soon as it reaches ``target``."""
+    arcs, adjacency = residual.arcs, residual.adjacency
+    parent = [-1] * size
+    visited = [False] * size
+    visited[source] = True
+    queue = deque([source])
+    while queue and not visited[target]:
+        node = queue.popleft()
+        for index in adjacency[node]:
+            arc = arcs[index]
+            if arc.capacity - arc.flow > 0 and not visited[arc.to]:
+                visited[arc.to] = True
+                parent[arc.to] = index
+                queue.append(arc.to)
+                if arc.to == target:
+                    break
+    return parent if visited[target] else None
+
+
+def maximum_flow(
+    store: Store, source: int, target: int, capacity: Callable[[Any], float]
+) -> MaximumFlowResult:
+    return _solve(store, source, target, capacity).flow
+
+
+def minimum_cut(
+    store: Store, source: int, target: int, capacity: Callable[[Any], float]
+) -> MinimumCutResult:
+    solution = _solve(store, source, target, capacity)
+    ids = solution.node_ids
+    return MinimumCutResult(
+        solution.flow.value,
+        solution.flow.cut,
+        tuple(ids[n] for n, inside in enumerate(solution.source_side) if inside),
+        tuple(ids[n] for n, inside in enumerate(solution.source_side) if not inside),
+    )

pyfect/graph/_forest.py

@@ -0,0 +1,109 @@
+"""Minimum spanning forests and transitive reductions: subgraphs that keep
+every node and index."""
+
+from __future__ import annotations
+
+import math
+from collections import deque
+from collections.abc import Callable
+from typing import Any
+
+from pyfect.graph._cycles import is_acyclic
+from pyfect.graph._errors import fail
+from pyfect.graph._records import IndexedEdge, IndexedNode, Kind, Snapshot
+from pyfect.graph._snapshot import from_snapshot
+from pyfect.graph._store import Store
+
+
+def _keeping(store: Store, kind: Kind, kept: set[int]) -> Store:
+    return from_snapshot(
+        Snapshot(
+            kind,
+            [IndexedNode(index, data) for index, data in store.nodes.items()],
+            [
+                IndexedEdge(index, edge.source, edge.target, edge.data)
+                for index, edge in store.edges.items()
+                if index in kept
+            ],
+        )
+    )
+
+
+def minimum_spanning_forest(store: Store, cost: Callable[[Any], float]) -> Store:
+    """Kruskal: edges by weight, ties in edge order; an infinite weight is
+    no edge."""
+    if store.kind == "directed":
+        fail("Cannot find minimum spanning forest of directed graph")
+    position = {node: i for i, node in enumerate(store.nodes)}
+
+    def weigh() -> list[tuple[float, int]]:
+        weighted: list[tuple[float, int]] = []
+        for index, edge in store.edges.items():
+            weight = float(cost(edge.data))
+            if math.isnan(weight) or weight == -math.inf:
+                fail("Minimum spanning forest does not support NaN or -Infinity edge weights")
+            if weight != math.inf:
+                weighted.append((weight, index))
+        return weighted
+
+    weighted = sorted(store.guarded(weigh), key=lambda pair: pair[0])
+    parents = list(range(len(position)))
+    ranks = [0] * len(position)
+
+    def find(node: int) -> int:
+        root = node
+        while parents[root] != root:
+            root = parents[root]
+        while parents[node] != node:
+            parents[node], node = root, parents[node]
+        return root
+
+    selected: set[int] = set()
+    for _, index in weighted:
+        edge = store.edges[index]
+        a, b = find(position[edge.source]), find(position[edge.target])
+        if a == b:
+            continue
+        selected.add(index)
+        if ranks[a] < ranks[b]:
+            a, b = b, a
+        parents[b] = a
+        if ranks[a] == ranks[b]:
+            ranks[a] += 1
+    return _keeping(store, "undirected", selected)
+
+
+def transitive_reduction(store: Store) -> Store:
+    """Keeps the first edge from each source to each target that no other
+    path reaches."""
+    if store.kind == "undirected":
+        fail("Cannot transitively reduce undirected graph")
+    if not is_acyclic(store):
+        fail("Cannot transitively reduce cyclic graph")
+    first: dict[int, dict[int, int]] = {}
+    for index, edge in store.edges.items():
+        first.setdefault(edge.source, {}).setdefault(edge.target, index)
+    retained: set[int] = set()
+    for source, targets in first.items():
+        for target, index in targets.items():
+            if not _reaches_otherwise(store, source, target):
+                retained.add(index)
+    return _keeping(store, "directed", retained)
+
+
+def _reaches_otherwise(store: Store, source: int, target: int) -> bool:
+    """Whether ``target`` is reachable from ``source`` without a direct edge."""
+    visited = {source}
+    queue = deque([source])
+    while queue:
+        current = queue.popleft()
+        for index in store.adjacency[current]:
+            reached = store.edges[index].target
+            if current == source and reached == target:
+                continue
+            if reached == target:
+                return True
+            if reached not in visited:
+                visited.add(reached)
+                queue.append(reached)
+    return False