multiarrangement 0.1.0__py3-none-any.whl

coverlib/__init__.py

@@ -0,0 +1 @@
+from .api import generate_cover, CoverResult

coverlib/api.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+from .combinatorics import block_pairs, schonheim_lb
+from .fetchers import fetch_ljcr_cover
+from .cache import get_seed_blocks, save_blocks_file
+from .optimizer import CoverOptimizer
+
+@dataclass
+class CoverResult:
+    v: int
+    k: int
+    blocks: List[Tuple[int,...]]  # 0-based
+    b: int
+    lmax: int
+    hist: Dict[int,int]
+    sumsq: int
+
+def generate_cover(
+    v: int,
+    k: int,
+    *,
+    passes: int = 12,
+    greedy_trials: int = 2,
+    forbid_above: int = 2,
+    group_rounds: int = 12,
+    group_time: float = 10.0,
+    group_cands: int = 100,
+    cache_dir: Optional[str] = None,
+    offline_only: bool = False,
+    seed_file: Optional[str] = None,
+    seed: int = 12345,
+) -> CoverResult:
+    """High-level API: fetch/cache seed, then rebalance and return result (0-based blocks)."""
+    from .repair import coverage_from_blocks  # local import to avoid cycles
+
+    if seed_file:
+        path = Path(seed_file)
+        from .cache import read_blocks_file
+        blocks = read_blocks_file(path, v, k)
+    else:
+        if cache_dir:
+            cache = Path(cache_dir)
+        else:
+            try:
+                import multiarrangement
+                cache = Path(multiarrangement.__file__).parent / "ljcr_cache"
+            except Exception:
+                cache = Path("ljcr_cache")
+        blocks = get_seed_blocks(v, k, cache, offline_first=True, offline_only=offline_only, fetcher=fetch_ljcr_cover)
+
+    counts, _ = coverage_from_blocks(v, blocks)
+    if min(counts) < 1:
+        from .repair import repair_to_coverage
+        blocks = repair_to_coverage(v, k, blocks)
+
+    opt = CoverOptimizer(v, blocks, seed=seed)
+    forbid = None if forbid_above < 0 else forbid_above
+    opt.local_search(passes=passes, forbid_above=forbid, greedy_trials=greedy_trials)
+
+    improved = True
+    r = group_rounds
+    while r>0 and improved:
+        r -= 1
+        lnow = opt.lambda_max()
+        if lnow <= 2: break
+        improved = opt.reduce_lmax_group(target=lnow-1, time_limit=group_time,
+                                         max_pairs_considered=20, candidates_per_block=group_cands)
+
+    return CoverResult(v=v, k=k, blocks=opt.blocks, b=len(opt.blocks), lmax=opt.lambda_max(), hist=opt.histogram(), sumsq=opt.sumsq())

coverlib/cache.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+from pathlib import Path
+from typing import List, Tuple
+
+__all__ = ["cache_path", "read_blocks_file", "save_blocks_file", "get_seed_blocks"]
+
+def cache_path(cache_dir: Path, v: int, k: int) -> Path:
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    return cache_dir / f"v{v}_k{k}_t2.txt"
+
+def read_blocks_file(path: Path, v: int, k: int) -> List[Tuple[int,...]]:
+    blocks: List[Tuple[int,...]] = []
+    if not path.exists(): return blocks
+    with path.open("r", encoding="utf-8") as f:
+        for ln in f:
+            ln = ln.strip().replace(",", " ")
+            if not ln or ln.startswith("#"): continue
+            nums = [int(x) for x in ln.split()]
+            if len(nums) != k: continue
+            blocks.append(tuple(sorted(nums)))
+    if not blocks: return []
+    zero_based = any(0 in b for b in blocks)
+    if not zero_based:
+        blocks = [tuple(x-1 for x in b) for b in blocks]
+    for b in blocks:
+        if any(x < 0 or x >= v for x in b):
+            raise ValueError(f"{path}: item out of range for v={v}.")
+    return blocks
+
+def save_blocks_file(path: Path, blocks: List[Tuple[int,...]], indexing: str = "zero") -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as f:
+        for b in blocks:
+            if indexing == "one":
+                f.write(" ".join(str(x+1) for x in b) + "\n")
+            else:
+                f.write(" ".join(str(x) for x in b) + "\n")
+
+def get_seed_blocks(v: int, k: int, cache_dir: Path, offline_first: bool, offline_only: bool,
+                    fetcher) -> List[Tuple[int,...]]:
+    p = cache_path(cache_dir, v, k)
+    if offline_first or offline_only:
+        blocks = read_blocks_file(p, v, k)
+        if blocks:
+            print(f"Loaded seed from cache: {p} (blocks={len(blocks)})")
+            return blocks
+        if offline_only:
+            raise RuntimeError(f"Cache miss and offline-only enabled. Expected: {p}")
+    print(f"Cache miss for (v={v},k={k}). Fetching from LJCR…")
+    blocks = fetcher(v, k)
+    save_blocks_file(p, blocks, indexing="zero")
+    print(f"Saved LJCR seed to cache: {p}")
+    return blocks

coverlib/cli.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+import argparse
+from pathlib import Path
+from .api import generate_cover
+from .combinatorics import schonheim_lb
+
+def main():
+    ap = argparse.ArgumentParser(description="covergen: cache-first LJCR (v,k,2) rebalancer (fixed-b)")
+    ap.add_argument("--v", type=int, required=True)
+    ap.add_argument("--k", type=int, required=True)
+    ap.add_argument("--passes", type=int, default=12)
+    ap.add_argument("--greedy-trials", type=int, default=2)
+    ap.add_argument("--forbid-above", type=int, default=2)
+    ap.add_argument("--group-rounds", type=int, default=12)
+    ap.add_argument("--group-time", type=float, default=10.0)
+    ap.add_argument("--group-cands", type=int, default=100)
+    from pathlib import Path
+    # Prefer packaged cache under multiarrangement/ljcr_cache if available
+    try:
+        import multiarrangement
+        default_cache = str((Path(multiarrangement.__file__).parent / "ljcr_cache").resolve())
+    except Exception:
+        default_cache = str((Path(__file__).parent.parent / "ljcr_cache").resolve())
+    ap.add_argument("--cache-dir", type=str, default=default_cache)
+    ap.add_argument("--offline-only", action="store_true")
+    ap.add_argument("--seed-file", type=str, default=None)
+    ap.add_argument("--outfile", type=str, default=None)
+    args = ap.parse_args()
+
+    res = generate_cover(
+        args.v, args.k,
+        passes=args.passes, greedy_trials=args.greedy_trials,
+        forbid_above=args.forbid_above,
+        group_rounds=args.group_rounds, group_time=args.group_time, group_cands=args.group_cands,
+        cache_dir=args.cache_dir, offline_only=args.offline_only, seed_file=args.seed_file,
+    )
+
+    P = args.v*(args.v-1)//2
+    avg_lambda = res.b * (args.k*(args.k-1)//2) / P
+    print(f"Seed (after repair/prune): b={res.b}, Schönheim≥{schonheim_lb(args.v,args.k)}, avg λ={avg_lambda:.3f}")
+    print("Final    λ_max:", res.lmax, "hist:", res.hist, "sumsq:", res.sumsq)
+
+    out = Path(args.outfile or f"rebalance_v{args.v}_k{args.k}.txt")
+    with out.open("w", encoding="utf-8") as f:
+        for blk in res.blocks:
+            f.write(" ".join(str(x) for x in blk) + "\n")  # 0-based output by default
+    print("Saved improved cover to", out)
+
+if __name__ == "__main__":
+    main()

coverlib/combinatorics.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+import math
+from typing import Dict, List, Tuple
+
+__all__ = [
+    "pair_index", "invert_pair_index", "block_pairs", "schonheim_lb", "histogram"
+]
+
+def pair_index(i: int, j: int, v: int) -> int:
+    if i > j: i, j = j, i
+    prior = i * (v - 1) - (i * (i - 1)) // 2
+    return prior + (j - i - 1)
+
+def invert_pair_index(p: int, v: int) -> Tuple[int,int]:
+    acc = 0
+    for i in range(v - 1):
+        row = v - 1 - i
+        if p < acc + row:
+            j = i + 1 + (p - acc)
+            return i, j
+        acc += row
+    raise ValueError("pair index out of range")
+
+def block_pairs(block: Tuple[int,...], v: int) -> Tuple[int,...]:
+    k = len(block)
+    out: List[int] = []
+    for a in range(k):
+        ia = block[a]
+        for b in range(a+1, k):
+            ib = block[b]
+            out.append(pair_index(ia, ib, v))
+    return tuple(out)
+
+def schonheim_lb(v: int, k: int) -> int:
+    return math.ceil((v / k) * math.ceil((v - 1) / (k - 1)))
+
+def histogram(counts: List[int]) -> Dict[int,int]:
+    h: Dict[int,int] = {}
+    for c in counts: h[c] = h.get(c,0) + 1
+    return dict(sorted(h.items()))

coverlib/fetchers.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+import html, re, urllib.request
+from typing import List, Tuple
+
+LJCR_URL = "https://ljcr.dmgordon.org/cover/show_cover.php?v={v}&k={k}&t=2"
+_INT_RE = re.compile(r"-?\d+")
+
+__all__ = ["fetch_ljcr_cover"]
+
+def fetch_ljcr_cover(v: int, k: int) -> List[Tuple[int,...]]:
+    url = LJCR_URL.format(v=v, k=k)
+    try:
+        with urllib.request.urlopen(url, timeout=30) as resp:
+            data = resp.read().decode("utf-8", errors="replace")
+    except Exception as e:
+        raise RuntimeError(f"Failed to fetch LJCR page: {e} | URL: {url}")
+
+    text = html.unescape(data)
+    blocks: List[Tuple[int,...]] = []
+
+    # Strategy 1: parse <pre>/<code>
+    for tag in ("pre","code"):
+        for m in re.finditer(fr"(?is)<{tag}[^>]*>(.*?)</{tag}>", text):
+            for line in m.group(1).splitlines():
+                nums = [int(x) for x in _INT_RE.findall(line)]
+                if len(nums) == k:
+                    blk = tuple(sorted(x-1 for x in nums))
+                    if all(0 <= x < v for x in blk):
+                        blocks.append(blk)
+        if blocks: return blocks
+
+    # Strategy 2: per-line fallback
+    for line in text.splitlines():
+        nums = [int(x) for x in _INT_RE.findall(line)]
+        if len(nums) == k:
+            blk = tuple(sorted(x-1 for x in nums))
+            if all(0 <= x < v for x in blk):
+                blocks.append(blk)
+    if blocks: return blocks
+
+    # Strategy 3: collect long run after first block-ish line
+    allints: List[int] = []
+    seen_first = False
+    for line in text.splitlines():
+        nums = [int(x) for x in _INT_RE.findall(line)]
+        if not nums: continue
+        if not seen_first and len(nums) == k:
+            seen_first = True; allints.extend(nums)
+        elif seen_first:
+            allints.extend(nums)
+    if allints:
+        for i in range(0, len(allints), k):
+            chunk = allints[i:i+k]
+            if len(chunk) != k: continue
+            blk = tuple(sorted(x-1 for x in chunk))
+            if all(0 <= x < v for x in blk):
+                blocks.append(blk)
+    if not blocks:
+        raise RuntimeError(f"Could not parse any {k}-tuples from LJCR page for (v={v},k={k}). URL: {url}")
+
+    # sanity: uniform k
+    ks = {len(b) for b in blocks}
+    if len(ks) != 1 or list(ks)[0] != k:
+        raise RuntimeError(f"Parsed blocks have inconsistent k: {ks}")
+    return blocks

coverlib/optimizer.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+import random, time
+from typing import Dict, List, Optional, Set, Tuple
+from .combinatorics import block_pairs, invert_pair_index, pair_index, histogram
+
+__all__ = ["CoverOptimizer"]
+
+class CoverOptimizer:
+    """Fixed-b cover rebalancer (pure stdlib).
+    - Keeps coverage (pair_count >= 1 for all pairs).
+    - Improves lexicographically: lambda_max then sumsq.
+    - Has 1-opt (coverage-preserving) and a multi-block DFS swap to lower lambda_max.
+    """
+    def __init__(self, v: int, blocks: List[Tuple[int,...]], seed: int = 12345):
+        self.v=v; self.blocks=[tuple(sorted(b)) for b in blocks]; self.k=len(self.blocks[0])
+        random.seed(seed)
+        self.P = v*(v-1)//2
+        self.block_pairs = [block_pairs(b, v) for b in self.blocks]
+        self.pair_count = [0]*self.P
+        for pp in self.block_pairs:
+            for p in pp: self.pair_count[p]+=1
+        if min(self.pair_count) < 1:
+            raise ValueError("Seed cover does not cover all pairs.")
+
+    def lambda_max(self)->int: return max(self.pair_count)
+    def sumsq(self)->int: return sum(c*c for c in self.pair_count)
+    def histogram(self)->Dict[int,int]: return histogram(self.pair_count)
+
+    def try_replace_block(self, idx:int, *, forbid_above:Optional[int]=2, greedy_trials:int=1) -> bool:
+        v,k = self.v,self.k
+        old_block = self.blocks[idx]
+        old_pairs = set(self.block_pairs[idx])
+        critical = [p for p in old_pairs if self.pair_count[p]==1]
+        if not critical: return False
+        required: Set[int] = set()
+        for p in critical:
+            i,j = invert_pair_index(p, v); required.add(i); required.add(j)
+        if len(required)>k: return False
+
+        best_eval = (self.lambda_max(), self.sumsq())
+        best_cand: Optional[Tuple[int,...]] = None
+
+        def add_cost(x:int, cur:Tuple[int,...])->int:
+            cost=0
+            for y in cur:
+                if x==y: continue
+                c=self.pair_count[pair_index(x,y,v)]
+                cost += 1 + 2*c
+            return cost
+
+        trials=max(1,greedy_trials)
+        for _ in range(trials):
+            S=sorted(required)
+            while len(S)<k:
+                best_x=None; best_c=None
+                for x in range(v):
+                    if x in S: continue
+                    c=add_cost(x, tuple(S))
+                    if best_c is None or c<best_c or (c==best_c and random.random()<0.2):
+                        best_c=c; best_x=x
+                if best_x is None: break
+                S.append(best_x)
+            if len(S)!=k: continue
+            cand=tuple(sorted(S))
+            if cand==old_block: continue
+            cand_pairs=set(block_pairs(cand, v))
+            removed_only = old_pairs - cand_pairs
+            added_only   = cand_pairs - old_pairs
+            if any(self.pair_count[p]==1 for p in removed_only): continue
+            if forbid_above is not None and any(self.pair_count[p]+1 > forbid_above for p in added_only): continue
+
+            cur_lmax=self.lambda_max(); cur_sumsq=self.sumsq()
+            delta=0
+            for p in removed_only: delta += 1 - 2*self.pair_count[p]
+            for p in added_only:   delta += 1 + 2*self.pair_count[p]
+            new_sumsq = cur_sumsq + delta
+
+            maybe_inc = any(self.pair_count[p]+1 > cur_lmax for p in added_only)
+            maybe_dec = any(self.pair_count[p] == cur_lmax for p in removed_only)
+            if maybe_inc or maybe_dec:
+                changed={}
+                for p in removed_only: changed[p]=self.pair_count[p]-1
+                for p in added_only:   changed[p]=changed.get(p,self.pair_count[p])+1
+                new_lmax=0
+                for p in range(self.P):
+                    c = changed[p] if p in changed else self.pair_count[p]
+                    if c>new_lmax: new_lmax=c
+            else:
+                new_lmax=cur_lmax
+
+            if (new_lmax, new_sumsq) < best_eval:
+                best_eval=(new_lmax,new_sumsq); best_cand=cand
+
+        if best_cand is None: return False
+        cand_pairs = set(block_pairs(best_cand, v))
+        removed_only = set(self.block_pairs[idx]) - cand_pairs
+        added_only   = cand_pairs - set(self.block_pairs[idx])
+        for p in removed_only: self.pair_count[p]-=1
+        for p in added_only:   self.pair_count[p]+=1
+        self.blocks[idx]=best_cand
+        self.block_pairs[idx]=tuple(sorted(cand_pairs))
+        assert min(self.pair_count)>=1
+        return True
+
+    def local_search(self, passes:int=8, forbid_above:Optional[int]=2, greedy_trials:int=2)->None:
+        for _ in range(passes):
+            improved=False
+            lmax=self.lambda_max()
+            idxs=list(range(len(self.blocks)))
+            idxs.sort(key=lambda i: sum(1 for p in self.block_pairs[i] if self.pair_count[p]==lmax), reverse=True)
+            for i in idxs:
+                if self.try_replace_block(i, forbid_above=forbid_above, greedy_trials=greedy_trials):
+                    improved=True
+            if not improved: break
+
+    # group DFS (same approach you used)
+    def reduce_lmax_group(self, target:int, time_limit:float=15.0, max_pairs_considered:int=20,
+                          candidates_per_block:int=100, rng=random) -> bool:
+        start = time.time()
+        v,k = self.v,self.k
+        lmax = self.lambda_max()
+        if lmax <= target: return False
+        offenders = [p for p,c in enumerate(self.pair_count) if c==lmax]
+        rng.shuffle(offenders); offenders = offenders[:max_pairs_considered]
+        avoid_hi = {p for p,c in enumerate(self.pair_count) if c>=lmax-1}
+        from .combinatorics import block_pairs as bp
+
+        for p0 in offenders:
+            if time.time()-start > time_limit: break
+            idxs = [i for i,bp_ in enumerate(self.block_pairs) if p0 in bp_]
+            if not idxs: continue
+            count_out = self.pair_count[:]
+            for i in idxs:
+                for q in self.block_pairs[i]: count_out[q]-=1
+            if any(c > target for c in count_out):
+                continue
+            critical = {q for q in range(self.P) if count_out[q]==0}
+
+            cand_lists: List[List[Tuple[int,...]]] = []
+            cand_pairs: List[List[Set[int]]] = []
+            for i in idxs:
+                s: Set[Tuple[int,...]] = set(); tries = 0
+                while len(s) < candidates_per_block and tries < candidates_per_block*20:
+                    tries += 1; S: List[int] = []
+                    while len(S) < k:
+                        best_x=None; best_sc=None
+                        for x in range(v):
+                            if x in S: continue
+                            sc = 0.0
+                            for y in S:
+                                q = pair_index(x,y,v)
+                                if q in critical: sc += 5.0
+                                if q in avoid_hi: sc -= 2.0
+                            sc += rng.random()*0.1
+                            if best_sc is None or sc>best_sc:
+                                best_sc, best_x = sc, x
+                        if best_x is None: break
+                        S.append(best_x)
+                    if len(S)!=k: continue
+                    blk = tuple(sorted(S)); pp = set(bp(blk, v))
+                    if p0 in pp: continue
+                    s.add(blk)
+                lst = list(s)
+                if not lst:
+                    orig = set(self.blocks[i])
+                    while len(s) < min(20, candidates_per_block):
+                        S = set(orig)
+                        if len(S)>=2:
+                            S = set(random.sample(list(S), k-2))
+                        while len(S) < k:
+                            S.add(rng.randrange(v))
+                        blk = tuple(sorted(S)); pp = set(bp(blk,v))
+                        if p0 in pp: continue
+                        s.add(blk)
+                    lst = list(s)
+                cand_lists.append(lst)
+                cand_pairs.append([set(bp(blk,v)) for blk in lst])
+
+            temp = count_out[:]
+            critical_list = sorted(list(critical))
+            need = {q:1 for q in critical_list}
+            cover_pos = {q:set() for q in critical_list}
+            for pos in range(len(idxs)):
+                for m,pp in enumerate(cand_pairs[pos]):
+                    for q in critical_list:
+                        if q in pp: cover_pos[q].add(pos)
+            if any(len(cover_pos[q])==0 for q in critical_list):
+                continue
+
+            solution = [None]*len(idxs)
+            deadline = start + time_limit
+
+            def dfs(pos:int)->bool:
+                if time.time() > deadline: return False
+                if pos == len(idxs):
+                    return True
+                order = list(range(len(cand_lists[pos])))
+                order.sort(key=lambda m: (
+                    sum(temp[q] for q in cand_pairs[pos][m] if temp[q] >= target-1),
+                    -sum(1 for q in cand_pairs[pos][m] if q in need and need[q]>0)
+                ))
+                for m in order:
+                    pp = cand_pairs[pos][m]
+                    if any(temp[q]+1 > target for q in pp):
+                        continue
+                    ok=True
+                    for q in critical_list:
+                        if need[q]<=0: continue
+                        possible = any( (q in cand_pairs[p2][mm]) for p2 in range(pos, len(idxs)) for mm in range(len(cand_lists[p2])) )
+                        if not possible: ok=False; break
+                    if not ok: continue
+
+                    for q in pp: temp[q]+=1
+                    changed=[]
+                    for q in pp:
+                        if q in need and need[q]>0:
+                            need[q]-=1; changed.append(q)
+
+                    solution[pos]=m
+                    if dfs(pos+1): return True
+
+                    solution[pos]=None
+                    for q in pp: temp[q]-=1
+                    for q in changed: need[q]+=1
+                return False
+
+            if dfs(0):
+                for pos, i in enumerate(idxs):
+                    m = solution[pos]
+                    new_blk = cand_lists[pos][m]
+                    old_pp = self.block_pairs[i]
+                    for q in old_pp: self.pair_count[q]-=1
+                    self.blocks[i] = new_blk
+                    new_pp = tuple(sorted(block_pairs(new_blk, v)))
+                    self.block_pairs[i] = new_pp
+                    for q in new_pp: self.pair_count[q]+=1
+                assert min(self.pair_count) >= 1
+                return True
+        return False

coverlib/repair.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+import random
+from typing import List, Optional, Set, Tuple
+from .combinatorics import block_pairs, invert_pair_index, pair_index
+
+__all__ = ["repair_to_coverage", "greedy_sample_block"]
+
+def greedy_sample_block(v: int, k: int, uncovered_pairs: Set[int], trials: int = 512, rng=random) -> Tuple[int,...]:
+    if not uncovered_pairs:
+        return tuple(sorted(rng.sample(range(v), k)))
+    deg = [0]*v
+    for p in uncovered_pairs:
+        i,j = invert_pair_index(p, v); deg[i]+=1; deg[j]+=1
+    weights = [d+1 for d in deg]
+    best_blk, best_score = None, -1
+    for _ in range(trials):
+        cand = set(); w = weights[:]; total = sum(w)
+        while len(cand) < k and total>0:
+            r = rng.uniform(0,total); acc=0
+            for u,wu in enumerate(w):
+                acc += wu
+                if acc >= r:
+                    cand.add(u); total-=w[u]; w[u]=0; break
+        if len(cand) < k:
+            remain = [u for u in range(v) if u not in cand]
+            rng.shuffle(remain)
+            for u in remain[:k-len(cand)]: cand.add(u)
+        blk = tuple(sorted(cand))
+        c=0
+        for a in range(k):
+            ia = blk[a]
+            for b in range(a+1,k):
+                ib = blk[b]
+                if pair_index(ia,ib,v) in uncovered_pairs: c+=1
+        if c>best_score: best_score, best_blk = c, blk
+    return best_blk  # type: ignore
+
+def repair_to_coverage(v: int, k: int, blocks: List[Tuple[int,...]], rng=random) -> List[Tuple[int,...]]:
+    counts, bpairs = coverage_from_blocks(v, blocks)
+    P = v*(v-1)//2
+    uncovered = {p for p in range(P) if counts[p]==0}
+    if not uncovered: return blocks
+    while uncovered:
+        blk = greedy_sample_block(v,k,uncovered, trials=512, rng=rng)
+        blocks.append(blk)
+        pp = block_pairs(blk,v); bpairs.append(pp)
+        for p in pp:
+            if counts[p]==0: uncovered.discard(p)
+            counts[p]+=1
+    # prune (safe deletions)
+    order = list(range(len(blocks))); rng.shuffle(order)
+    for idx in order:
+        pp = bpairs[idx]
+        if any(counts[p]==1 for p in pp): continue
+        for p in pp: counts[p]-=1
+        blocks[idx] = None  # type: ignore
+    return [b for b in blocks if b is not None]
+
+# local helper to avoid circular import
+from .combinatorics import block_pairs as _bp
+
+def coverage_from_blocks(v: int, blocks: List[Tuple[int,...]]):
+    P = v*(v-1)//2
+    counts = [0]*P
+    bpairs = [_bp(b, v) for b in blocks]
+    for pp in bpairs:
+        for p in pp: counts[p]+=1
+    return counts, bpairs