pypebbling 0.1.0__tar.gz

pypebbling-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eric Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pypebbling-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: pypebbling
+Version: 0.1.0
+Summary: Exact pebbling reachability and solvability on graphs, with replayable move certificates and an independent checker
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ortools>=9.15
+Provides-Extra: test
+Requires-Dist: pytest>=8.4; extra == "test"
+Dynamic: license-file
+
+# pypebbling
+
+Exact tools for graph pebbling: reachability, solvability and minimality of pebble distributions, with
+move sequences anyone can replay.
+
+A pebbling move removes two pebbles from a vertex and puts one pebble on a neighbouring vertex. A
+distribution is solvable if every vertex can receive a pebble by some sequence of moves. The optimal pebbling
+number of a graph is the smallest number of pebbles in a solvable distribution.
+
+## Install
+
+```bash
+pip install pypebbling
+```
+
+The package is imported as `pebbling`. It needs Python 3.12 or later and installs OR-Tools.
+
+## Example
+
+```python
+from pebbling.graphs import grid_graph
+from pebbling.solver import solvability
+from pebbling.certify import replay
+
+G = grid_graph(5, 5)
+P = [0] * 25
+for r, c in [(1, 1), (1, 3), (3, 1), (3, 3)]:
+    P[r * 5 + c] = 4
+
+solvable, certs, _ = solvability(G, tuple(P))
+print("solvable:", solvable)
+
+moves = certs[0]  # vertex (0, 0); vertex v is (v // 5, v % 5)
+print("moves to (0, 0):", [(divmod(u, 5), divmod(w, 5)) for u, w in moves])
+print("replay ok:", replay(G.adj, P, moves, 0))
+```
+
+## What is inside
+
+- `pebbling.solver`: exact backward search over demands, with exact integer potentials for pruning.
+- `pebbling.ipsolver`: a second exact engine, an integer flow model solved with CP-SAT.
+- `pebbling.certify`: replays move sequences.
+- `naivecheck`: an independent naive checker, written separately from the solver.
+
+Source code, proofs of correctness, the validation suite and a counterexample to a conjecture of Petr,
+Portier and Stolarczyk are in the repository linked on this page.
+
+## License
+
+MIT

pypebbling-0.1.0/README.md

@@ -0,0 +1,50 @@
+# pypebbling
+
+Exact tools for graph pebbling: reachability, solvability and minimality of pebble distributions, with
+move sequences anyone can replay.
+
+A pebbling move removes two pebbles from a vertex and puts one pebble on a neighbouring vertex. A
+distribution is solvable if every vertex can receive a pebble by some sequence of moves. The optimal pebbling
+number of a graph is the smallest number of pebbles in a solvable distribution.
+
+## Install
+
+```bash
+pip install pypebbling
+```
+
+The package is imported as `pebbling`. It needs Python 3.12 or later and installs OR-Tools.
+
+## Example
+
+```python
+from pebbling.graphs import grid_graph
+from pebbling.solver import solvability
+from pebbling.certify import replay
+
+G = grid_graph(5, 5)
+P = [0] * 25
+for r, c in [(1, 1), (1, 3), (3, 1), (3, 3)]:
+    P[r * 5 + c] = 4
+
+solvable, certs, _ = solvability(G, tuple(P))
+print("solvable:", solvable)
+
+moves = certs[0]  # vertex (0, 0); vertex v is (v // 5, v % 5)
+print("moves to (0, 0):", [(divmod(u, 5), divmod(w, 5)) for u, w in moves])
+print("replay ok:", replay(G.adj, P, moves, 0))
+```
+
+## What is inside
+
+- `pebbling.solver`: exact backward search over demands, with exact integer potentials for pruning.
+- `pebbling.ipsolver`: a second exact engine, an integer flow model solved with CP-SAT.
+- `pebbling.certify`: replays move sequences.
+- `naivecheck`: an independent naive checker, written separately from the solver.
+
+Source code, proofs of correctness, the validation suite and a counterexample to a conjecture of Petr,
+Portier and Stolarczyk are in the repository linked on this page.
+
+## License
+
+MIT

pypebbling-0.1.0/naivecheck/__init__.py

@@ -0,0 +1 @@
+"""Independent naive checker."""

pypebbling-0.1.0/naivecheck/flowmodel.py

@@ -0,0 +1,26 @@
+"""Independent flow-model check of unreachability, for instances too large for naive search."""
+from ortools.sat.python import cp_model
+
+
+def target_feasible(adj, P, X, time_limit=None):
+    n = len(adj)
+    total = sum(P)
+    model = cp_model.CpModel()
+    F = {}
+    for u in range(n):
+        for w in adj[u]:
+            F[(u, w)] = model.NewIntVar(0, total, f"F{u}_{w}")
+    for v in range(n):
+        incoming = [F[(u, v)] for u in adj[v]]
+        outgoing = [F[(v, w)] for w in adj[v]]
+        model.Add(P[v] + sum(incoming) - 2 * sum(outgoing) >= (1 if v == X else 0))
+    solver = cp_model.CpSolver()
+    solver.parameters.num_workers = 1
+    if time_limit is not None:
+        solver.parameters.max_time_in_seconds = time_limit
+    status = solver.Solve(model)
+    if status == cp_model.INFEASIBLE:
+        return False
+    if status in (cp_model.OPTIMAL, cp_model.FEASIBLE):
+        return True
+    return None

pypebbling-0.1.0/naivecheck/naive.py

@@ -0,0 +1,200 @@
+"""Deliberately naive pebbling checker, written independently of the `pebbling` package."""
+from fractions import Fraction
+
+
+def build_adjacency(spec):
+    kind, _, rest = spec.partition(":")
+    if kind == "grid":
+        rows, cols = (int(t) for t in rest.split("x"))
+        adj = [[] for _ in range(rows * cols)]
+        for r in range(rows):
+            for c in range(cols):
+                for dr, dc in ((1, 0), (-1, 0), (0, 1), (0, -1)):
+                    r2, c2 = r + dr, c + dc
+                    if 0 <= r2 < rows and 0 <= c2 < cols:
+                        adj[r * cols + c].append(r2 * cols + c2)
+        return adj
+    if kind == "path":
+        n = int(rest)
+        return [[x for x in (i - 1, i + 1) if 0 <= x < n] for i in range(n)]
+    if kind == "cycle":
+        n = int(rest)
+        return [sorted({(i - 1) % n, (i + 1) % n}) for i in range(n)]
+    if kind == "complete":
+        n = int(rest)
+        return [[j for j in range(n) if j != i] for i in range(n)]
+    if kind == "petersen":
+        adj = [[] for _ in range(10)]
+        pairs = []
+        for i in range(5):
+            pairs.append((i, (i + 1) % 5))
+            pairs.append((i, i + 5))
+            pairs.append((5 + i, 5 + (i + 2) % 5))
+        for a, b in pairs:
+            adj[a].append(b)
+            adj[b].append(a)
+        return adj
+    if kind == "edges":
+        n_str, _, e_str = rest.partition(":")
+        adj = [[] for _ in range(int(n_str))]
+        for e in e_str.split(";"):
+            if e:
+                a, b = (int(t) for t in e.split("-"))
+                adj[a].append(b)
+                adj[b].append(a)
+        return adj
+    raise ValueError(spec)
+
+
+def distances_from(adj, source):
+    dist = {source: 0}
+    frontier = [source]
+    while frontier:
+        nxt = []
+        for x in frontier:
+            for y in adj[x]:
+                if y not in dist:
+                    dist[y] = dist[x] + 1
+                    nxt.append(y)
+        frontier = nxt
+    return [dist[v] for v in range(len(adj))]
+
+
+def value(adj, P, X):
+    d = distances_from(adj, X)
+    total = Fraction(0)
+    for y in range(len(adj)):
+        total += Fraction(P[y], 2 ** d[y])
+    return total
+
+
+def replay_moves(adj, P, moves, X):
+    state = list(P)
+    for u, w in moves:
+        if w not in adj[u]:
+            return False
+        if state[u] < 2:
+            return False
+        state[u] -= 2
+        state[w] += 1
+    return state[X] >= 1
+
+
+class StateLimit(Exception):
+    pass
+
+
+def is_reachable(adj, P, X, prune_by_value=False, max_states=None, greedy_only=False):
+    """Forward depth-first search over pebbling states."""
+    start = tuple(P)
+    if start[X] > 0:
+        return True
+    d = distances_from(adj, X)
+    half_powers = [Fraction(1, 2 ** k) for k in range(max(d) + 2)]
+    start_val = sum((Fraction(P[y], 2 ** d[y]) for y in range(len(adj))), Fraction(0))
+    if prune_by_value and start_val < 1:
+        return False
+    seen = {start}
+    stack = [(start, start_val)]
+    n = len(adj)
+    while stack:
+        state, val = stack.pop()
+        candidates = []
+        for u in range(n):
+            if state[u] >= 2:
+                for w in adj[u]:
+                    if greedy_only and d[w] >= d[u]:
+                        continue
+                    candidates.append((u, w))
+        candidates.sort(key=lambda m: d[m[1]] - d[m[0]], reverse=True)
+        for u, w in candidates:
+            nxt = list(state)
+            nxt[u] -= 2
+            nxt[w] += 1
+            if w == X:
+                return True
+            nxt = tuple(nxt)
+            if nxt in seen:
+                continue
+            nval = val - 2 * half_powers[d[u]] + half_powers[d[w]]
+            if prune_by_value and nval < 1:
+                continue
+            seen.add(nxt)
+            if max_states is not None and len(seen) > max_states:
+                raise StateLimit(len(seen))
+            stack.append((nxt, nval))
+    return False
+
+
+def reachable_vertices(adj, P, max_states=None):
+    """Vertices that hold a pebble in some state reachable from P."""
+    start = tuple(P)
+    n = len(adj)
+    covered = {v for v in range(n) if start[v] > 0}
+    seen = {start}
+    stack = [start]
+    while stack:
+        state = stack.pop()
+        for u in range(n):
+            if state[u] >= 2:
+                for w in adj[u]:
+                    nxt = list(state)
+                    nxt[u] -= 2
+                    nxt[w] += 1
+                    nxt = tuple(nxt)
+                    covered.add(w)
+                    if nxt not in seen:
+                        seen.add(nxt)
+                        if max_states is not None and len(seen) > max_states:
+                            raise StateLimit(len(seen))
+                        stack.append(nxt)
+    return covered
+
+
+def is_solvable(adj, P, max_states=None):
+    return len(reachable_vertices(adj, P, max_states)) == len(adj)
+
+
+def check_minimal_distribution(adj, P, witness_hints=None, prune_by_value=False,
+                               max_states=None, certificates=None, hint_only=False):
+    """Naive minimality verification of a claimed minimal distribution."""
+    n = len(adj)
+    report = {"reach_method": {}, "deletions": {}, "ok": True}
+    for X in range(n):
+        try:
+            ok = is_reachable(adj, P, X, prune_by_value=prune_by_value, max_states=max_states)
+            report["reach_method"][X] = "search"
+        except StateLimit:
+            cert = (certificates or {}).get(X)
+            if cert is None:
+                report["reach_method"][X] = "undecided"
+                report["ok"] = False
+                continue
+            ok = replay_moves(adj, P, cert, X)
+            report["reach_method"][X] = "certificate_replay"
+        if not ok:
+            report["ok"] = False
+            report["unreachable_in_P"] = X
+            return report
+    for v in range(n):
+        if P[v] == 0:
+            continue
+        Q = list(P)
+        Q[v] -= 1
+        order = list(range(n))
+        if witness_hints and v in witness_hints:
+            h = witness_hints[v]
+            order = [h] if hint_only else [h] + [x for x in order if x != h]
+        found = None
+        undecided = []
+        for X in order:
+            try:
+                if not is_reachable(adj, Q, X, prune_by_value=prune_by_value, max_states=max_states):
+                    found = X
+                    break
+            except StateLimit:
+                undecided.append(X)
+        report["deletions"][v] = {"unreachable_target": found, "undecided_targets": undecided}
+        if found is None:
+            report["ok"] = False
+    return report

pypebbling-0.1.0/pebbling/__init__.py

@@ -0,0 +1 @@
+"""Pebbling toolkit: exact reachability, solvability, minimality and potentials."""

pypebbling-0.1.0/pebbling/certify.py

@@ -0,0 +1,12 @@
+"""Replay a pebbling move sequence."""
+
+
+def replay(adj, P, moves, target):
+    """True iff every move is legal from P in order and the result has a pebble on target."""
+    Q = list(P)
+    for u, w in moves:
+        if w not in adj[u] or Q[u] < 2:
+            return False
+        Q[u] -= 2
+        Q[w] += 1
+    return Q[target] >= 1

pypebbling-0.1.0/pebbling/graphs.py

@@ -0,0 +1,164 @@
+"""Graphs for pebbling: constructors, all-pairs distances, grid symmetries."""
+from collections import deque
+import random
+
+
+class Graph:
+    def __init__(self, name, num_vertices, edges, kind="other", coords=None, grid_shape=None):
+        n = num_vertices
+        nbrs = [set() for _ in range(n)]
+        for a, b in edges:
+            if not (0 <= a < n and 0 <= b < n) or a == b:
+                raise ValueError(f"bad edge {(a, b)} for {name}")
+            nbrs[a].add(b)
+            nbrs[b].add(a)
+        self.name = name
+        self.kind = kind
+        self.n = n
+        self.adj = tuple(tuple(sorted(s)) for s in nbrs)
+        self.edges = tuple(sorted({(min(a, b), max(a, b)) for a, b in edges}))
+        self.coords = coords
+        self.grid_shape = grid_shape
+        self.dist = tuple(tuple(self._bfs(s)) for s in range(n))
+        for row in self.dist:
+            if min(row) < 0:
+                raise ValueError(f"{name} is disconnected")
+        self.diam = max(max(row) for row in self.dist)
+        # potentials are exact integers: v_P(X) = sum_y P[y] * weight[X][y] / scale
+        self.scale = 1 << self.diam
+        self.weight = tuple(tuple(1 << (self.diam - d) for d in row) for row in self.dist)
+        self.weight2 = tuple(tuple(2 * w for w in row) for row in self.weight)
+
+    def _bfs(self, s):
+        dist = [-1] * self.n
+        dist[s] = 0
+        q = deque([s])
+        while q:
+            x = q.popleft()
+            for y in self.adj[x]:
+                if dist[y] < 0:
+                    dist[y] = dist[x] + 1
+                    q.append(y)
+        return dist
+
+    def spec(self):
+        """String from which make_graph() rebuilds this graph (for worker processes)."""
+        if self.kind == "grid":
+            return f"grid:{self.grid_shape[0]}x{self.grid_shape[1]}"
+        if self.kind in ("path", "cycle", "complete"):
+            return f"{self.kind}:{self.n}"
+        if self.kind == "petersen":
+            return "petersen"
+        return "edges:" + str(self.n) + ":" + ";".join(f"{a}-{b}" for a, b in self.edges)
+
+    def __repr__(self):
+        return f"Graph({self.name}, n={self.n}, |E|={len(self.edges)})"
+
+
+def complete_graph(n):
+    return Graph(f"K{n}", n, [(a, b) for a in range(n) for b in range(a + 1, n)], kind="complete")
+
+
+def path_graph(n):
+    return Graph(f"P{n}", n, [(i, i + 1) for i in range(n - 1)], kind="path")
+
+
+def cycle_graph(n):
+    if n < 3:
+        raise ValueError("cycle needs n >= 3")
+    return Graph(f"C{n}", n, [(i, (i + 1) % n) for i in range(n)], kind="cycle")
+
+
+def grid_graph(m, n):
+    edges = []
+    for i in range(m):
+        for j in range(n):
+            v = i * n + j
+            if i + 1 < m:
+                edges.append((v, v + n))
+            if j + 1 < n:
+                edges.append((v, v + 1))
+    coords = tuple((i, j) for i in range(m) for j in range(n))
+    return Graph(f"grid{m}x{n}", m * n, edges, kind="grid", coords=coords, grid_shape=(m, n))
+
+
+def petersen_graph():
+    outer = [(i, (i + 1) % 5) for i in range(5)]
+    spokes = [(i, i + 5) for i in range(5)]
+    inner = [(5 + i, 5 + (i + 2) % 5) for i in range(5)]
+    return Graph("Petersen", 10, outer + spokes + inner, kind="petersen")
+
+
+def random_connected_graph(n, p, rng):
+    """G(n, p) conditioned on connectivity (rejection sampling), for solver cross-checks."""
+    while True:
+        edges = [(a, b) for a in range(n) for b in range(a + 1, n) if rng.random() < p]
+        try:
+            g = Graph(f"rand{n}", n, edges, kind="other")
+        except ValueError:
+            continue
+        return g
+
+
+def make_graph(spec):
+    kind, _, rest = spec.partition(":")
+    if kind == "grid":
+        m, n = rest.split("x")
+        return grid_graph(int(m), int(n))
+    if kind == "path":
+        return path_graph(int(rest))
+    if kind == "cycle":
+        return cycle_graph(int(rest))
+    if kind == "complete":
+        return complete_graph(int(rest))
+    if kind == "petersen":
+        return petersen_graph()
+    if kind == "edges":
+        n_str, _, e_str = rest.partition(":")
+        edges = [tuple(int(x) for x in e.split("-")) for e in e_str.split(";") if e]
+        return Graph(f"rand{n_str}", int(n_str), edges, kind="other")
+    raise ValueError(spec)
+
+
+def grid_symmetries(m, n):
+    """The 8 dihedral maps of an m-by-n grid."""
+    maps = [
+        ("id", (m, n), lambda i, j: (i, j)),
+        ("flip_rows", (m, n), lambda i, j: (m - 1 - i, j)),
+        ("flip_cols", (m, n), lambda i, j: (i, n - 1 - j)),
+        ("rot180", (m, n), lambda i, j: (m - 1 - i, n - 1 - j)),
+        ("transpose", (n, m), lambda i, j: (j, i)),
+        ("anti_transpose", (n, m), lambda i, j: (n - 1 - j, m - 1 - i)),
+        ("rot90", (n, m), lambda i, j: (j, m - 1 - i)),
+        ("rot270", (n, m), lambda i, j: (n - 1 - j, i)),
+    ]
+    out = []
+    for name, (m2, n2), f in maps:
+        perm = []
+        for i in range(m):
+            for j in range(n):
+                i2, j2 = f(i, j)
+                if not (0 <= i2 < m2 and 0 <= j2 < n2):
+                    raise AssertionError(f"symmetry {name} leaves the grid")
+                perm.append(i2 * n2 + j2)
+        out.append((name, (m2, n2), tuple(perm)))
+    return out
+
+
+def apply_perm(P, perm):
+    """Image of distribution P under a vertex map perm (perm must be a bijection)."""
+    Q = [0] * len(P)
+    for v, c in enumerate(P):
+        Q[perm[v]] = c
+    return tuple(Q)
+
+
+def boundary_distance(G, v):
+    """Distance from v to the nearest boundary vertex."""
+    if G.kind == "grid":
+        m, n = G.grid_shape
+        i, j = G.coords[v]
+        return min(i, j, m - 1 - i, n - 1 - j)
+    if G.kind == "path":
+        return min(v, G.n - 1 - v)
+    raise ValueError(f"boundary distance undefined for kind {G.kind}")

pypebbling-0.1.0/pebbling/ipsolver.py

@@ -0,0 +1,165 @@
+"""Second exact reachability engine: integer feasibility solved with OR-Tools CP-SAT."""
+from ortools.sat.python import cp_model
+
+from .certify import replay
+
+
+class IPUndecided(Exception):
+    pass
+
+
+def firing_bounds(G, P):
+    W = G.weight
+    scale = G.scale
+    n = G.n
+    support = [y for y in range(n) if P[y]]
+    out = []
+    for u in range(n):
+        phi = sum(P[y] * W[u][y] for y in support)
+        num = 2 * phi - scale
+        out.append(num // (3 * scale) if num >= 3 * scale else 0)
+    return out
+
+
+def ip_cover(G, P, D, restrict=True, time_limit=None, cuts=(), params=None):
+    """Move sequence covering demand D (dict), None if not coverable."""
+    n = G.n
+    if all(P[v] >= d for v, d in D.items()):
+        return ()
+    total = sum(P)
+    if restrict:
+        bound = firing_bounds(G, P)
+    else:
+        bound = [total // 2] * n
+    model = cp_model.CpModel()
+    f = {}
+    for u in range(n):
+        if bound[u] == 0:
+            continue
+        for w in G.adj[u]:
+            if restrict and D.get(w, 0) == 0 and bound[w] == 0:
+                continue
+            f[(u, w)] = model.NewIntVar(0, bound[u], f"f_{u}_{w}")
+    inflow = [[] for _ in range(n)]
+    outflow = [[] for _ in range(n)]
+    for (u, w), var in f.items():
+        outflow[u].append(var)
+        inflow[w].append(var)
+    for v in range(n):
+        need = D.get(v, 0)
+        if not inflow[v] and not outflow[v]:
+            if P[v] < need:
+                return None
+            continue
+        model.Add(P[v] + sum(inflow[v]) - 2 * sum(outflow[v]) >= need)
+    if f and "moves" in cuts:
+        model.Add(sum(f.values()) <= total - sum(D.values()))
+    if f and "potential" in cuts and len(D) == 1:
+        ((X, need),) = D.items()
+        wX = G.weight[X]
+        phiX = sum(P[y] * wX[y] for y in range(n) if P[y])
+        model.Add(sum(var * (2 * wX[u] - wX[w]) for (u, w), var in f.items()) <= phiX - need * wX[X])
+    if "two_cycle" in cuts:
+        for (u, w), var in f.items():
+            if u < w and (w, u) in f:
+                b = model.NewBoolVar(f"dir_{u}_{w}")
+                model.Add(var == 0).OnlyEnforceIf(b)
+                model.Add(f[(w, u)] == 0).OnlyEnforceIf(b.Not())
+    solver = cp_model.CpSolver()
+    solver.parameters.num_workers = 1
+    if time_limit is not None:
+        solver.parameters.max_time_in_seconds = time_limit
+    if params:
+        for name, val in params.items():
+            setattr(solver.parameters, name, val)
+    status = solver.Solve(model)
+    if status == cp_model.INFEASIBLE:
+        return None
+    if status not in (cp_model.OPTIMAL, cp_model.FEASIBLE):
+        raise IPUndecided(solver.StatusName(status))
+    F = {a: solver.Value(var) for a, var in f.items() if solver.Value(var) > 0}
+    moves = flow_to_moves(n, F)
+    Q = list(P)
+    for u, w in moves:
+        if Q[u] < 2 or w not in G.adj[u]:
+            raise AssertionError("IP certificate failed to replay")
+        Q[u] -= 2
+        Q[w] += 1
+    if any(Q[v] < d for v, d in D.items()):
+        raise AssertionError("IP certificate does not cover the demand")
+    return tuple(moves)
+
+
+def ip_reach(G, P, X, restrict=True, time_limit=None, cuts=(), params=None):
+    moves = ip_cover(G, P, {X: 1}, restrict=restrict, time_limit=time_limit, cuts=cuts, params=params)
+    if moves is not None and not replay(G.adj, P, moves, X):
+        raise AssertionError("IP certificate failed to replay")
+    return moves
+
+
+def flow_to_moves(n, F):
+    """Cancel directed cycles in a balanced multiset, then list moves in topological order."""
+    F = dict(F)
+    while True:
+        cycle = _find_cycle(n, F)
+        if cycle is None:
+            break
+        c = min(F[a] for a in cycle)
+        for a in cycle:
+            F[a] -= c
+            if F[a] == 0:
+                del F[a]
+    indeg = [0] * n
+    succ = [[] for _ in range(n)]
+    for (u, w) in F:
+        succ[u].append(w)
+        indeg[w] += 1
+    order = [v for v in range(n) if indeg[v] == 0]
+    i = 0
+    while i < len(order):
+        v = order[i]
+        i += 1
+        for w in succ[v]:
+            indeg[w] -= 1
+            if indeg[w] == 0:
+                order.append(w)
+    if len(order) != n:
+        raise AssertionError("cycle cancellation left a cycle")
+    moves = []
+    for v in order:
+        for w in sorted(succ[v]):
+            moves.extend([(v, w)] * F[(v, w)])
+    return moves
+
+
+def _find_cycle(n, F):
+    succ = [[] for _ in range(n)]
+    for (u, w) in F:
+        succ[u].append(w)
+    color = [0] * n  # 0 new, 1 on stack, 2 done
+    parent = [-1] * n
+    for s in range(n):
+        if color[s]:
+            continue
+        stack = [(s, 0)]
+        color[s] = 1
+        while stack:
+            v, i = stack[-1]
+            if i < len(succ[v]):
+                stack[-1] = (v, i + 1)
+                w = succ[v][i]
+                if color[w] == 0:
+                    color[w] = 1
+                    parent[w] = v
+                    stack.append((w, 0))
+                elif color[w] == 1:
+                    cyc = [(v, w)]
+                    x = v
+                    while x != w:
+                        cyc.append((parent[x], x))
+                        x = parent[x]
+                    return cyc
+            else:
+                color[v] = 2
+                stack.pop()
+    return None

pypebbling-0.1.0/pebbling/numbers.py

@@ -0,0 +1,63 @@
+"""pi(G) and pi_opt(G) by exhaustive enumeration of distributions."""
+from itertools import combinations
+from math import comb
+
+
+def distributions(n, k):
+    """All distributions of k pebbles on n vertices (stars and bars), each exactly once."""
+    if n == 1:
+        yield (k,)
+        return
+    last = k + n - 2
+    for bars in combinations(range(k + n - 1), n - 1):
+        out = []
+        prev = -1
+        for b in bars:
+            out.append(b - prev - 1)
+            prev = b
+        out.append(last - prev)
+        yield tuple(out)
+
+
+def count_distributions(n, k):
+    return comb(k + n - 1, n - 1)
+
+
+def pebbling_number(n, is_solvable, k_max=10**9):
+    """Pebbling number by scanning k upward; returns a dict with the value and witnesses."""
+    witness_below = tuple([0] * n)  # the empty distribution is unsolvable
+    per_k = []
+    for k in range(1, k_max + 1):
+        checked = 0
+        found = None
+        for P in distributions(n, k):
+            checked += 1
+            if not is_solvable(P):
+                found = P
+                break
+        per_k.append({"k": k, "checked": checked, "unsolvable_example": found})
+        if found is None:
+            return {"value": k, "witness_below": witness_below, "checked_at_value": checked,
+                    "total_at_value": count_distributions(n, k), "per_k": per_k}
+        witness_below = found
+    return {"value": None, "per_k": per_k}
+
+
+def optimal_pebbling_number(n, is_solvable, k_max=10**9):
+    """Optimal pebbling number by scanning k upward; returns a dict with the value and witnesses."""
+    per_k = []
+    for k in range(1, k_max + 1):
+        checked = 0
+        found = None
+        for P in distributions(n, k):
+            checked += 1
+            if is_solvable(P):
+                found = P
+                break
+        per_k.append({"k": k, "checked": checked, "solvable_example": found})
+        if found is not None:
+            below = per_k[-2]["checked"] if len(per_k) > 1 else 0
+            return {"value": k, "witness": found, "checked_all_unsolvable_at_k_minus_1": below,
+                    "total_at_k_minus_1": count_distributions(n, k - 1) if k > 1 else 1,
+                    "per_k": per_k}
+    return {"value": None, "per_k": per_k}

pypebbling-0.1.0/pebbling/path.py

@@ -0,0 +1,55 @@
+"""Path-specific reachability by carries."""
+from fractions import Fraction
+
+
+def left_arrivals(P):
+    n = len(P)
+    A = [0] * n
+    carry = 0
+    for i in range(1, n):
+        carry = (P[i - 1] + carry) // 2
+        A[i] = carry
+    return A
+
+
+def right_arrivals(P):
+    n = len(P)
+    B = [0] * n
+    carry = 0
+    for i in range(n - 2, -1, -1):
+        carry = (P[i + 1] + carry) // 2
+        B[i] = carry
+    return B
+
+
+def reachable(P):
+    A = left_arrivals(P)
+    B = right_arrivals(P)
+    return [P[i] + A[i] + B[i] >= 1 for i in range(len(P))]
+
+
+def solvable(P):
+    return all(reachable(P))
+
+
+def minimality_status(P):
+    """'unsolvable', 'not_minimal' or 'minimal'; for 'minimal' also v -> an unreachable vertex of P - e_v."""
+    if not solvable(P):
+        return "unsolvable", None
+    witnesses = {}
+    Q = list(P)
+    for v, c in enumerate(P):
+        if c == 0:
+            continue
+        Q[v] -= 1
+        r = reachable(Q)
+        Q[v] += 1
+        bad = [i for i, ok in enumerate(r) if not ok]
+        if not bad:
+            return "not_minimal", v
+        witnesses[v] = bad[0]
+    return "minimal", witnesses
+
+
+def value(P, X):
+    return sum((Fraction(c, 2 ** abs(X - y)) for y, c in enumerate(P) if c), Fraction(0))

pypebbling-0.1.0/pebbling/portfolio.py

@@ -0,0 +1,79 @@
+"""Decision procedure for large instances: backward search under a node budget, then CP-SAT."""
+from .certify import replay
+from .ipsolver import ip_reach
+from .solver import Solver, Undecided
+
+
+class Oracle:
+    def __init__(self, G, P, node_limit=20000, inherited_fail=(), ip_time_limit=None):
+        self.G = G
+        self.P = tuple(P)
+        self.bs = Solver(G, self.P, inherited_fail=inherited_fail, node_limit=node_limit)
+        self.phiP = self.bs.phiP
+        self.ip_time_limit = ip_time_limit
+        self.engine_counts = {"bs": 0, "ip": 0}
+
+    def reach(self, X):
+        """(moves or None, engine)."""
+        try:
+            moves = self.bs.reach(X)
+            engine = "bs"
+        except Undecided:
+            moves = ip_reach(self.G, self.P, X, time_limit=self.ip_time_limit)
+            engine = "ip"
+        self.engine_counts[engine] += 1
+        if moves is not None and not replay(self.G.adj, self.P, moves, X):
+            raise AssertionError(f"certificate replay failed ({engine})")
+        return moves, engine
+
+
+def solvability(G, P, parent_certs=None, inherited_fail=(), node_limit=20000, priority=None,
+                collect=None, ip_time_limit=None):
+    """(True, certs, oracle) or (False, (X, engine), oracle)."""
+    o = Oracle(G, P, node_limit=node_limit, inherited_fail=inherited_fail, ip_time_limit=ip_time_limit)
+    certs = {}
+    pending = []
+    for X in range(G.n):
+        c = parent_certs.get(X) if parent_certs else None
+        if c is not None and replay(G.adj, o.P, c, X):
+            certs[X] = c
+        else:
+            pending.append(X)
+    if collect is not None:
+        collect.update(certs)
+    if priority is None:
+        pending.sort(key=lambda X: o.phiP[X])
+    else:
+        pending.sort(key=lambda X: (priority(X), o.phiP[X]))
+    for X in pending:
+        moves, engine = o.reach(X)
+        if moves is None:
+            return False, (X, engine), o
+        certs[X] = moves
+        if collect is not None:
+            collect[X] = moves
+    return True, certs, o
+
+
+def minimality(G, P, node_limit=20000, certs=None, fail_layers=(), ip_time_limit=None):
+    """Same contract as solver.minimality; witnesses map v -> (unreachable X, engine)."""
+    ok, info, o = solvability(G, P, parent_certs=certs, inherited_fail=fail_layers,
+                              node_limit=node_limit, ip_time_limit=ip_time_limit)
+    if not ok:
+        return {"status": "unsolvable", "unreachable": info[0], "engine": info[1]}
+    certs = info
+    layers = (o.bs.fail,) + tuple(fail_layers)
+    witnesses = {}
+    for v in range(G.n):
+        if P[v] == 0:
+            continue
+        P2 = list(P)
+        P2[v] -= 1
+        dv = G.dist[v]
+        ok2, info2, _ = solvability(G, P2, parent_certs=certs, inherited_fail=layers,
+                                    node_limit=node_limit, priority=lambda X: dv[X],
+                                    ip_time_limit=ip_time_limit)
+        if ok2:
+            return {"status": "not_minimal", "removable": v, "certs": certs}
+        witnesses[v] = info2
+    return {"status": "minimal", "certs": certs, "witnesses": witnesses}

pypebbling-0.1.0/pebbling/solver.py

@@ -0,0 +1,269 @@
+"""Exact pebbling reachability, solvability and minimality; proofs in docs/solver_notes.md."""
+import sys
+from array import array
+from fractions import Fraction
+from operator import gt
+
+from .certify import replay
+
+sys.setrecursionlimit(max(sys.getrecursionlimit(), 50000))
+
+FAIL_CACHE_CAP = 600_000   # clearing a memo only costs time; it never changes an answer
+SUCC_CACHE_CAP = 100_000
+
+
+class Undecided(Exception):
+    """The node budget ran out; the answer is unknown."""
+
+
+def value(G, P, X):
+    """v_P(X) as an exact Fraction, summed term by term from the definition."""
+    total = Fraction(0)
+    dX = G.dist[X]
+    for y, c in enumerate(P):
+        if c:
+            total += Fraction(c, 1 << dX[y])
+    return total
+
+
+def potential_scaled(G, P, X):
+    """v_P(X) * 2**diam as an exact integer."""
+    w = G.weight[X]
+    return sum(c * w[y] for y, c in enumerate(P) if c)
+
+
+def _packed_tables(G, F):
+    cache = G.__dict__.setdefault("_packed_cache", {})
+    t = cache.get(F)
+    if t is None:
+        n = G.n
+        W = G.weight
+        packW = tuple(sum(W[v][y] << (F * y) for y in range(n)) for v in range(n))
+        packW2 = tuple(2 * p for p in packW)
+        H = sum(1 << (F * y + F - 1) for y in range(n))
+        t = (packW, packW2, H, (1 << F) - 1)
+        cache[F] = t
+    return t
+
+
+class Solver:
+    """Reachability oracle for one fixed distribution P (memo shared across targets)."""
+
+    def __init__(self, G, P, potential_prune=True, inherited_fail=(), node_limit=None,
+                 potential_impl="packed"):
+        P = tuple(P)
+        if len(P) != G.n:
+            raise ValueError("distribution length does not match graph")
+        for c in P:
+            if not isinstance(c, int) or c < 0:
+                raise ValueError(f"bad pebble count {c!r}")
+        if potential_impl not in ("packed", "list"):
+            raise ValueError(potential_impl)
+        self.G = G
+        self.P = P
+        self.total = sum(P)
+        self.potential_prune = potential_prune
+        self.inherited_fail = tuple(inherited_fail)
+        self.node_limit = node_limit
+        self.fail = set()
+        self.succ = {}
+        self.nodes = 0
+        self.total_nodes = 0
+        self._adj = G.adj
+        self._W = G.weight
+        self._W2 = G.weight2
+        W = G.weight
+        support = [y for y, c in enumerate(P) if c]
+        self.phiP = [sum(P[y] * W[x][y] for y in support) for x in range(G.n)]
+        self._packed = potential_prune and potential_impl == "packed"
+        if self._packed:
+            F = ((self.total + 2) * G.scale).bit_length() + 2
+            packW, packW2, H, mask = _packed_tables(G, F)
+            self._F = F
+            self._mask = mask
+            self._pW = packW
+            self._pW2 = packW2
+            self._H = H
+            self._PH = sum(P[y] * packW[y] for y in support) + H
+
+    def reach(self, X):
+        """A move sequence ((from, to), ...) that puts a pebble on X, or None if X is unreachable."""
+        self.nodes = 0
+        if self.P[X] >= 1:
+            return ()
+        if self._packed:
+            phiD = self._pW[X]
+            if (self._PH - phiD) & self._H != self._H:
+                return None
+        elif self.potential_prune:
+            phiD = list(self._W[X])
+            if any(map(gt, phiD, self.phiP)):
+                return None
+        else:
+            phiD = None
+        try:
+            return self._cover({X: 1}, 1, phiD, array("I", (X, 1)).tobytes())
+        finally:
+            self.total_nodes += self.nodes
+
+    def _add_fail(self, key):
+        if len(self.fail) >= FAIL_CACHE_CAP:
+            self.fail.clear()
+        self.fail.add(key)
+
+    def _cover(self, D, size, phiD, key):
+        P = self.P
+        deficits = []
+        deficit_total = 0
+        for v, d in D.items():
+            e = d - P[v]
+            if e > 0:
+                deficits.append(v)
+                deficit_total += e
+        if not deficits:
+            return ()
+        if size + deficit_total > self.total:
+            return None
+        cached = self.succ.get(key)
+        if cached is not None:
+            return cached
+        if key in self.fail:
+            return None
+        for layer in self.inherited_fail:
+            if key in layer:
+                return None
+        self.nodes += 1
+        if self.node_limit is not None and self.nodes > self.node_limit:
+            raise Undecided(f"node limit {self.node_limit} exceeded")
+
+        total = self.total
+        adj = self._adj
+        prune = self.potential_prune
+        packed = self._packed
+        phiP = self.phiP
+        if packed:
+            PH = self._PH
+            H = self._H
+            pW = self._pW
+            pW2 = self._pW2
+        else:
+            W = self._W
+            W2 = self._W2
+
+        best_v = -1
+        best_kids = None
+        for v in deficits:
+            kids = []
+            if packed:
+                pWv = pW[v]
+            elif prune:
+                Wv = W[v]
+            for u in adj[v]:
+                du = D.get(u, 0)
+                pu = P[u]
+                grow = (du + 2 - pu if du + 2 > pu else 0) - (du - pu if du > pu else 0)
+                # child has size+1 and deficit (deficit_total - 1 + grow)
+                if size + deficit_total + grow > total:
+                    continue
+                if packed:
+                    phi2 = phiD + pW2[u] - pWv
+                    if (PH - phi2) & H != H:
+                        continue
+                elif prune:
+                    phi2 = [a + b - c for a, b, c in zip(phiD, W2[u], Wv)]
+                    if any(map(gt, phi2, phiP)):
+                        continue
+                else:
+                    phi2 = None
+                kids.append((u, phi2))
+            if not kids:
+                self._add_fail(key)
+                return None
+            if best_kids is None or len(kids) < len(best_kids):
+                best_v, best_kids = v, kids
+
+        v = best_v
+        kids = best_kids
+        if len(kids) > 1:
+            if packed:
+                F = self._F
+                mask = self._mask
+                kids.sort(key=lambda t: (D.get(t[0], 0) - P[t[0]], ((t[1] >> (F * t[0])) & mask) - phiP[t[0]]))
+            elif prune:
+                kids.sort(key=lambda t: (D.get(t[0], 0) - P[t[0]], t[1][t[0]] - phiP[t[0]]))
+            else:
+                kids.sort(key=lambda t: (D.get(t[0], 0) - P[t[0]], -phiP[t[0]]))
+        dv = D[v]
+        for u, phi2 in kids:
+            D2 = dict(D)
+            if dv == 1:
+                del D2[v]
+            else:
+                D2[v] = dv - 1
+            D2[u] = D2.get(u, 0) + 2
+            key2 = array("I", [x for item in sorted(D2.items()) for x in item]).tobytes()
+            res = self._cover(D2, size + 1, phi2, key2)
+            if res is not None:
+                res = res + ((u, v),)
+                if len(self.succ) >= SUCC_CACHE_CAP:
+                    self.succ.clear()
+                self.succ[key] = res
+                return res
+        self._add_fail(key)
+        return None
+
+
+def solvability(G, P, parent_certs=None, inherited_fail=(), potential_prune=True, node_limit=None,
+                potential_impl="packed"):
+    """Decide whether every vertex is reachable from P."""
+    s = Solver(G, P, potential_prune=potential_prune, inherited_fail=inherited_fail,
+               node_limit=node_limit, potential_impl=potential_impl)
+    certs = {}
+    pending = []
+    for X in range(G.n):
+        c = parent_certs.get(X) if parent_certs else None
+        if c is not None and replay(G.adj, s.P, c, X):
+            certs[X] = c
+        else:
+            pending.append(X)
+    pending.sort(key=lambda X: s.phiP[X])
+    for X in pending:
+        c = s.reach(X)
+        if c is None:
+            return False, X, s
+        certs[X] = c
+    return True, certs, s
+
+
+def is_solvable(G, P, **kw):
+    return solvability(G, P, **kw)[0]
+
+
+def reachable_set(G, P, **kw):
+    s = Solver(G, P, **kw)
+    return frozenset(X for X in range(G.n) if s.reach(X) is not None)
+
+
+def minimality(G, P, potential_prune=True, node_limit=None, certs=None, fail_layers=(),
+               potential_impl="packed"):
+    """Classify P as 'unsolvable', 'not_minimal' or 'minimal'."""
+    ok, info, s = solvability(G, P, parent_certs=certs, inherited_fail=fail_layers,
+                              potential_prune=potential_prune, node_limit=node_limit,
+                              potential_impl=potential_impl)
+    if not ok:
+        return {"status": "unsolvable", "unreachable": info}
+    certs = info
+    layers = (s.fail,) + tuple(fail_layers)
+    witnesses = {}
+    for v in range(G.n):
+        if P[v] == 0:
+            continue
+        P2 = list(P)
+        P2[v] -= 1
+        ok2, info2, _ = solvability(G, P2, parent_certs=certs, inherited_fail=layers,
+                                    potential_prune=potential_prune, node_limit=node_limit,
+                                    potential_impl=potential_impl)
+        if ok2:
+            return {"status": "not_minimal", "removable": v, "certs": certs}
+        witnesses[v] = info2
+    return {"status": "minimal", "certs": certs, "witnesses": witnesses}

pypebbling-0.1.0/pypebbling.egg-info/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: pypebbling
+Version: 0.1.0
+Summary: Exact pebbling reachability and solvability on graphs, with replayable move certificates and an independent checker
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ortools>=9.15
+Provides-Extra: test
+Requires-Dist: pytest>=8.4; extra == "test"
+Dynamic: license-file
+
+# pypebbling
+
+Exact tools for graph pebbling: reachability, solvability and minimality of pebble distributions, with
+move sequences anyone can replay.
+
+A pebbling move removes two pebbles from a vertex and puts one pebble on a neighbouring vertex. A
+distribution is solvable if every vertex can receive a pebble by some sequence of moves. The optimal pebbling
+number of a graph is the smallest number of pebbles in a solvable distribution.
+
+## Install
+
+```bash
+pip install pypebbling
+```
+
+The package is imported as `pebbling`. It needs Python 3.12 or later and installs OR-Tools.
+
+## Example
+
+```python
+from pebbling.graphs import grid_graph
+from pebbling.solver import solvability
+from pebbling.certify import replay
+
+G = grid_graph(5, 5)
+P = [0] * 25
+for r, c in [(1, 1), (1, 3), (3, 1), (3, 3)]:
+    P[r * 5 + c] = 4
+
+solvable, certs, _ = solvability(G, tuple(P))
+print("solvable:", solvable)
+
+moves = certs[0]  # vertex (0, 0); vertex v is (v // 5, v % 5)
+print("moves to (0, 0):", [(divmod(u, 5), divmod(w, 5)) for u, w in moves])
+print("replay ok:", replay(G.adj, P, moves, 0))
+```
+
+## What is inside
+
+- `pebbling.solver`: exact backward search over demands, with exact integer potentials for pruning.
+- `pebbling.ipsolver`: a second exact engine, an integer flow model solved with CP-SAT.
+- `pebbling.certify`: replays move sequences.
+- `naivecheck`: an independent naive checker, written separately from the solver.
+
+Source code, proofs of correctness, the validation suite and a counterexample to a conjecture of Petr,
+Portier and Stolarczyk are in the repository linked on this page.
+
+## License
+
+MIT

pypebbling-0.1.0/pypebbling.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+naivecheck/__init__.py
+naivecheck/flowmodel.py
+naivecheck/naive.py
+pebbling/__init__.py
+pebbling/certify.py
+pebbling/graphs.py
+pebbling/ipsolver.py
+pebbling/numbers.py
+pebbling/path.py
+pebbling/portfolio.py
+pebbling/solver.py
+pypebbling.egg-info/PKG-INFO
+pypebbling.egg-info/SOURCES.txt
+pypebbling.egg-info/dependency_links.txt
+pypebbling.egg-info/requires.txt
+pypebbling.egg-info/top_level.txt

pypebbling-0.1.0/pypebbling.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pypebbling-0.1.0/pypebbling.egg-info/requires.txt

@@ -0,0 +1,4 @@
+ortools>=9.15
+
+[test]
+pytest>=8.4

pypebbling-0.1.0/pypebbling.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+naivecheck
+pebbling

pypebbling-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pypebbling"
+version = "0.1.0"
+description = "Exact pebbling reachability and solvability on graphs, with replayable move certificates and an independent checker"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["ortools>=9.15"]
+license = "MIT"
+
+[project.optional-dependencies]
+test = ["pytest>=8.4"]
+
+[tool.setuptools]
+packages = ["pebbling", "naivecheck"]

pypebbling-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+