fluidlayer 2.0.0__py3-none-any.whl

fluidlayer/model.py

@@ -0,0 +1,141 @@
+"""
+fluidlayer.model — FluidLayerLM and a param-matched transformer baseline.
+Both models share: embedding, learned absolute positions, RMSNorm pre-norm
+residual blocks, tied readout.  The only difference is the block body, so the
+A/B in `train.py` isolates exactly one thing: dense attention vs. the
+topological fluid.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from .autodiff import Tensor, concat, softmax_rows
+from .blocks import FluidLayerBlock, RMSNorm
+
+__all__ = ["FluidLayerLM", "TinyTransformer"]
+
+
+def _collect(module, prefix, out):
+    for name, val in vars(module).items():
+        if isinstance(val, Tensor):
+            out[f"{prefix}.{name}"] = val
+    return out
+
+
+class FluidLayerLM:
+    def __init__(self, vocab: int, d: int = 64, n_layers: int = 2, n_ctx: int = 128,
+                 seed: int = 0, **block_kw):
+        rng = np.random.default_rng(seed)
+        self.vocab, self.d, self.n_ctx = vocab, d, n_ctx
+        self.emb = Tensor(rng.normal(0, 0.02, (vocab, d)))
+        self.pos = Tensor(rng.normal(0, 0.01, (n_ctx, d)))
+        self.blocks = [FluidLayerBlock(d, seed=seed + 17 * (i + 1), **block_kw)
+                       for i in range(n_layers)]
+        self.norm = RMSNorm(d)
+
+    def forward(self, idx: np.ndarray) -> Tensor:
+        idx = np.asarray(idx, dtype=np.int64)
+        h = self.emb[idx] + self.pos[: idx.shape[0]]
+        for b in self.blocks:
+            h = b(h)
+        h = self.norm(h)
+        return h @ self.emb.T
+
+    def forward_batch(self, x):
+        """x: (B, T) token ids -> logits (B*T, V).  The block is sequence-local
+        (the diffusion mixes positions inside one sequence), so we loop."""
+        outs = [self.forward(x[b]) for b in range(x.shape[0])]
+        return concat(outs, axis=0)
+
+    def params(self) -> dict:
+        p = {}
+        _collect(self, "emb", p)
+        _collect(self, "pos", p)
+        for i, b in enumerate(self.blocks):
+            _collect(b, f"b{i}", p)
+            _collect(b.norm, f"b{i}.norm", p)
+        _collect(self.norm, "norm", p)
+        return p
+
+
+class TinyTransformer:
+    """Post-GPT transformer block (causal MHA + MLP), numpy/autodiff."""
+
+    def __init__(self, vocab: int, d: int = 64, n_layers: int = 2, n_ctx: int = 128,
+                 n_heads: int = 4, d_ff: int | None = None, seed: int = 0):
+        rng = np.random.default_rng(seed)
+        self.vocab, self.d, self.n_ctx = vocab, d, n_ctx
+        self.n_heads = n_heads
+        self.d_ff = d_ff or 4 * d
+        self.emb = Tensor(rng.normal(0, 0.02, (vocab, d)))
+        self.pos = Tensor(rng.normal(0, 0.01, (n_ctx, d)))
+        self.layers = []
+        for _ in range(n_layers):
+            s = d ** -0.5
+            self.layers.append({
+                "Wq": Tensor(rng.normal(0, s, (d, d))),
+                "Wk": Tensor(rng.normal(0, s, (d, d))),
+                "Wv": Tensor(rng.normal(0, s, (d, d))),
+                "Wo": Tensor(rng.normal(0, s, (d, d))),
+                "W1": Tensor(rng.normal(0, (d * self.d_ff) ** -0.5, (d, self.d_ff))),
+                "W2": Tensor(rng.normal(0, (d * self.d_ff) ** -0.5, (self.d_ff, d))),
+                "n1": RMSNorm(d), "n2": RMSNorm(d),
+            })
+        self.norm = RMSNorm(d)
+
+    def forward(self, idx: np.ndarray) -> Tensor:
+        idx = np.asarray(idx, dtype=np.int64)
+        n = idx.shape[0]
+        h = self.emb[idx] + self.pos[:n]
+        return self.forward_from_h(h)
+
+    def forward_from_h(self, h: Tensor, return_hidden: bool = False):
+        """Continue the forward pass from a (possibly MODIFIED) residual stream.
+
+        This is the hook a grafted memory layer needs: the branch rewrites `h`
+        and the frozen base model processes the rest.  Splitting `forward` into
+        "embed" + "forward_from_h" is what makes a *training-free* attachment
+        to an already-trained model possible at all.
+        """
+        n = h.data.shape[0]
+        causal = np.triu(np.ones((n, n), dtype=bool), k=1)
+        H, dh = self.n_heads, self.d // self.n_heads
+        for L in self.layers:
+            x = L["n1"](h)
+            q = x @ L["Wq"]
+            k = x @ L["Wk"]
+            v = x @ L["Wv"]
+            outs = []
+            for hh in range(H):
+                sl = slice(hh * dh, (hh + 1) * dh)
+                qh = q[:, sl]
+                kh = k[:, sl]
+                vh = v[:, sl]
+                sc = (qh @ kh.T) * (dh ** -0.5)
+                a = softmax_rows(sc, mask=causal)
+                outs.append(a @ vh)
+            o = np.concatenate([o.data for o in outs], axis=1)
+            oT = Tensor(o)
+            h = h + oT @ L["Wo"]
+            y = L["n2"](h)
+            h = h + (y @ L["W1"]).gelu() @ L["W2"]
+        h = self.norm(h)
+        logits = h @ self.emb.T
+        return (logits, h) if return_hidden else logits
+
+    def forward_batch(self, x):
+        outs = [self.forward(x[b]) for b in range(x.shape[0])]
+        return concat(outs, axis=0)
+
+    def params(self) -> dict:
+        p = {}
+        _collect(self, "emb", p)
+        _collect(self, "pos", p)
+        for i, L in enumerate(self.layers):
+            for k, v in L.items():
+                if isinstance(v, Tensor):
+                    p[f"L{i}.{k}"] = v
+            p[f"L{i}.n1.g"] = L["n1"].g
+            p[f"L{i}.n2.g"] = L["n2"].g
+        _collect(self.norm, "norm", p)
+        return p

fluidlayer/optim.py

@@ -0,0 +1,57 @@
+"""
+fluidlayer.optim — Adam, implemented locally (no torch in this environment).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+class Adam:
+    """Adam with decoupled weight decay and gradient clipping."""
+
+    def __init__(self, params: dict, lr: float = 1e-3, betas=(0.9, 0.999),
+                 eps: float = 1e-8, weight_decay: float = 0.0, clip: float = 1.0):
+        self.params = params
+        self.lr = lr
+        self.b1, self.b2 = betas
+        self.eps = eps
+        self.wd = weight_decay
+        self.clip = clip
+        self.t = 0
+        # params: name -> Tensor  (Tensor has .data and .grad)
+        self.m = {k: np.zeros_like(v.data) for k, v in params.items()}
+        self.v = {k: np.zeros_like(v.data) for k, v in params.items()}
+
+    def zero_grad(self):
+        for p in self.params.values():
+            p.grad = np.zeros_like(p.data)
+
+    def step(self, lr: float | None = None):
+        self.t += 1
+        lr = self.lr if lr is None else lr
+        b1c = 1 - self.b1 ** self.t
+        b2c = 1 - self.b2 ** self.t
+        total_sq = 0.0
+        for p in self.params.values():
+            g = p.grad
+            total_sq += float(np.sum(g * g))
+        norm = np.sqrt(total_sq)
+        scale = 1.0
+        if self.clip and norm > self.clip:
+            scale = self.clip / (norm + 1e-12)
+        for k, p in self.params.items():
+            g = p.grad * scale
+            if self.wd:
+                g = g + self.wd * p.data
+            self.m[k] = self.b1 * self.m[k] + (1 - self.b1) * g
+            self.v[k] = self.b2 * self.v[k] + (1 - self.b2) * (g * g)
+            mhat = self.m[k] / b1c
+            vhat = self.v[k] / b2c
+            p.data -= lr * mhat / (np.sqrt(vhat) + self.eps)
+
+    def lr_at(self, step: int, total: int, warmup: int = 200, floor: float = 0.1):
+        if step < warmup:
+            return self.lr * (step + 1) / warmup
+        p = (step - warmup) / max(1, total - warmup)
+        return self.lr * (floor + (1 - floor) * 0.5 * (1 + np.cos(np.pi * min(p, 1.0))))

fluidlayer/sheaf.py

@@ -0,0 +1,147 @@
+"""
+fluidlayer.sheaf — Cellular sheaf Laplacians on graphs.
+
+The mathematical object that makes "FluidLayer" real.
+
+A cellular sheaf F on a graph G assigns:
+  * a stalk (vector space) F(v) ~ R^d  to every vertex v
+  * a restriction map  F_{v<-e} : F(v) -> F(e)  to every incidence (v, e)
+
+Its coboundary  delta : C^0(G;F) -> C^1(G;F)  induces the **sheaf Laplacian**
+
+    L_F = delta* delta = delta^T delta      (PSD by construction)
+
+and the diffusion (the "fluid") is the heat flow on that operator:
+
+    dX/dt = -L_F X      =>      X(t) = exp(-t L_F) X(0)
+
+Two facts we rely on throughout (Hansen & Ghrist 2019; Bodnar et al. 2022):
+
+1.  lim_{t->inf} exp(-t L_F) = P_{ker(L_F)}      (the Hodge limit: the fluid
+    freezes onto the space of *global sections* -- consistent assignments).
+2.  On ker(L_F)^perp the flow contracts at rate exp(-lam_2 t).
+
+Implementation note: we use the **signed** sheaf Laplacian with absolute degree
+
+    L = D_abs - A ,   D_abs[i,i] = sum_j |A[i,j]| ,   A[i,j] = alpha_ij
+
+which is PSD for any sign pattern, reduces to the ordinary graph Laplacian
+when all signs are positive, and reproduces the G-balance phase transition:
+a *balanced* signed component freezes onto a NON-TRIVIAL sign pattern,
+an *unbalanced* one decays to zero (it "evaporates" instead of freezing).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = [
+    "build_laplacian", "sheaf_energy", "balance_residual", "is_balanced",
+    "laplacian_from_dense_A", "signed_laplacian_from_edges",
+]
+
+
+def build_laplacian(n: int, edges: np.ndarray, alpha: np.ndarray) -> np.ndarray:
+    """Signed sheaf Laplacian L = D_abs - A.
+
+    edges : (m, 2) int array of undirected edges (u, v), u != v
+    alpha : (m,) float array of signed edge weights (the restriction maps)
+    Returns L : (n, n) symmetric PSD.
+    """
+    L = np.zeros((n, n), dtype=np.float64)
+    if edges.shape[0] == 0:
+        return L
+    u = edges[:, 0].astype(np.int64)
+    v = edges[:, 1].astype(np.int64)
+    w = np.asarray(alpha, dtype=np.float64)
+
+    # A contribution (symmetric)
+    np.add.at(L, (u, v), w)
+    np.add.at(L, (v, u), w)
+    # D_abs: sum of |A[i,j]| over j
+    absA = np.zeros_like(L)
+    np.add.at(absA, (u, v), np.abs(w))
+    np.add.at(absA, (v, u), np.abs(w))
+    diag = absA.sum(axis=1)
+    L = np.diag(diag) - L          # L = D_abs - A   (PSD)
+    return L
+
+
+def laplacian_from_dense_A(A: np.ndarray) -> np.ndarray:
+    """L = D_abs - A for a dense symmetric A."""
+    A = np.asarray(A, dtype=np.float64)
+    A = 0.5 * (A + A.T)
+    D = np.diag(np.abs(A).sum(axis=1))
+    return D - A
+
+
+def signed_laplacian_from_edges(
+    n: int, edges: np.ndarray, alpha: np.ndarray
+) -> np.ndarray:
+    """Alias kept for readability at call sites."""
+    return build_laplacian(n, edges, alpha)
+
+
+def sheaf_energy(x: np.ndarray, edges: np.ndarray, alpha: np.ndarray) -> float:
+    """Total variation of the field across the sheaf edges.
+
+    E = sum_e  alpha_e^2 * (x_u - x_v)^2      (scalar stalk; x is (n,) or (n,d))
+
+    This is the quantity the "smoothness" regularizer anneals toward, and it
+    is exactly x^T L x / 2 for the signed Laplacian up to the sign convention.
+    """
+    if edges.shape[0] == 0:
+        return 0.0
+    u = edges[:, 0]
+    v = edges[:, 1]
+    w = np.asarray(alpha, dtype=np.float64)
+    diff = x[u] - x[v]
+    if diff.ndim == 1:
+        diff = diff[:, None]
+    return float(np.sum((w[:, None] ** 2) * (diff ** 2)))
+
+
+def balance_residual(L: np.ndarray) -> float:
+    """||L 1||_inf for the constant vector 1.
+
+    Zero  <=>  the sheaf is (G-)balanced: every node's incident restriction
+    maps sum to zero, so the constant field is a global section and the fluid
+    has a non-trivial frozen state.
+    """
+    n = L.shape[0]
+    if n == 0:
+        return 0.0
+    return float(np.max(np.abs(L @ np.ones(n))))
+
+
+def is_balanced(L: np.ndarray, tol: float = 1e-8) -> bool:
+    return balance_residual(L) < tol
+
+
+def component_balance(L: np.ndarray, adj: np.ndarray) -> np.ndarray:
+    """Per-component balance residual.
+
+    For each connected component (of the underlying unsigned graph) returns
+    ||L 1_C||_inf.  Zero means that component is balanced (freezes onto a
+    sign pattern); non-zero means it is unbalanced (decays to zero).
+    """
+    n = L.shape[0]
+    seen = np.zeros(n, dtype=bool)
+    out = []
+    for s in range(n):
+        if seen[s]:
+            continue
+        stack, comp = [s], []
+        seen[s] = True
+        while stack:
+            u = stack.pop()
+            comp.append(u)
+            nb = np.nonzero(adj[u])[0]
+            for w in nb:
+                if not seen[w]:
+                    seen[w] = True
+                    stack.append(w)
+        idx = np.array(comp)
+        res = L[np.ix_(idx, idx)].sum(axis=1)
+        out.append(float(np.max(np.abs(res))))
+    return np.array(out)

fluidlayer/topology.py

@@ -0,0 +1,294 @@
+"""
+fluidlayer.topology — building the data's geometry in one forward pass.
+
+This module implements the "instant geometry" of the proposal:
+
+  1. content routing      -> semantic edges (top-k over QK similarity)
+  2. temporal chain      -> order edges (position as 1-dimensional topology)
+  3. 0-D persistence     -> exact barcode via union-find (Kruskal filtration)
+  4. Betti numbers      -> beta_0 (components), beta_1 (cycle rank)
+
+(3) and (4) are *exact*, not approximated, and cost O(m log m) — which is why
+the geometry can be recomputed every forward pass instead of being cached
+offline.  This is the concrete answer to "jam the data's geometry in one pass".
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = [
+    "route_topk", "edges_from_topk", "chain_edges", "unique_edges",
+    "kruskal_barcode", "betti_numbers", "topo_descriptor",
+    "connected_components",
+    "hodge_relevance", "hodge_embedding", "hodge_edge_participation",
+    "local_density", "persistence_landmarks",
+]
+
+
+# ------------------------------------------------------- selection criteria
+def hodge_embedding(n: int, edges: np.ndarray, alpha: np.ndarray) -> np.ndarray:
+    """The Hodge embedding Psi = (L + (1/n) 11^T)^-1 of the sheaf Laplacian."""
+    from .sheaf import build_laplacian
+
+    laplacian = build_laplacian(n, edges, np.asarray(alpha, dtype=np.float64))
+    constant = np.ones((n, 1)) / np.sqrt(max(n, 1))
+    matrix = laplacian + constant @ constant.T
+    try:
+        return np.linalg.inv(matrix)
+    except np.linalg.LinAlgError:
+        return np.linalg.pinv(matrix)
+
+
+def hodge_edge_participation(
+    Psi: np.ndarray, a: np.ndarray, b: np.ndarray
+) -> np.ndarray:
+    """Return normalized Hodge participation for a set of node pairs."""
+    Psi = np.asarray(Psi, dtype=np.float64)
+    a = np.asarray(a, dtype=np.int64)
+    b = np.asarray(b, dtype=np.int64)
+    numerator = np.abs(Psi[a, b])
+    denominator = np.sqrt(
+        np.maximum(np.abs(Psi[a, a]), 1e-18)
+        * np.maximum(np.abs(Psi[b, b]), 1e-18)
+    )
+    return np.clip(numerator / denominator, 0.0, 1.0)
+
+
+def hodge_relevance(n: int, edges: np.ndarray, alpha: np.ndarray) -> np.ndarray:
+    """Return per-node harmonic participation scores for the sheaf Laplacian."""
+    embedding = hodge_embedding(n, edges, alpha)
+    participation = np.abs(embedding).sum(axis=1) - np.abs(np.diag(embedding))
+    return np.clip(participation, 0.0, None)
+
+
+def local_density(
+    protos: np.ndarray, radius: float | None = None, k: int = 8
+) -> np.ndarray:
+    """Return prototype neighborhood counts or effective top-k density."""
+    prototypes = np.asarray(protos, dtype=np.float64)
+    n = prototypes.shape[0]
+    if radius is not None:
+        squared_norms = (prototypes**2).sum(1)
+        distances = np.sqrt(
+            np.maximum(
+                squared_norms[:, None]
+                + squared_norms[None, :]
+                - 2.0 * (prototypes @ prototypes.T),
+                0.0,
+            )
+        )
+        return (distances <= radius).sum(axis=1).astype(np.float64)
+    normalized = prototypes / (
+        np.linalg.norm(prototypes, axis=1, keepdims=True) + 1e-12
+    )
+    similarities = normalized @ normalized.T
+    np.fill_diagonal(similarities, -np.inf)
+    k = int(min(k, n - 1)) if n > 1 else 1
+    nearest = np.partition(similarities, -k, axis=1)[:, -k:]
+    maximum = np.abs(nearest).max(axis=1, keepdims=True) + 1e-12
+    return (np.abs(nearest) / maximum).sum(axis=1)
+
+
+def persistence_landmarks(
+    n: int, edges: np.ndarray, weights: np.ndarray, k: int = 10
+) -> np.ndarray:
+    """Return node indices whose topological classes persist the longest."""
+    edges = np.asarray(edges, dtype=np.int64)
+    weights = np.asarray(weights, dtype=np.float64)
+    if edges.shape[0] == 0:
+        return np.arange(min(k, n), dtype=np.int64)
+    parent = list(range(n))
+    members = {i: [i] for i in range(n)}
+
+    def find(a):
+        while parent[a] != a:
+            parent[a] = parent[parent[a]]
+            a = parent[a]
+        return a
+
+    death = np.full(n, -np.inf, dtype=np.float64)
+    order = np.argsort(weights, kind="stable")
+    for edge_index in order:
+        u = int(edges[edge_index, 0])
+        v = int(edges[edge_index, 1])
+        weight = float(weights[edge_index])
+        root_u, root_v = find(u), find(v)
+        if root_u == root_v:
+            continue
+        merged_nodes = members[root_u] + members[root_v]
+        for node in merged_nodes:
+            death[node] = weight
+        if len(members[root_u]) < len(members[root_v]):
+            root_u, root_v = root_v, root_u
+        parent[root_v] = root_u
+        members[root_u] = members[root_u] + members[root_v]
+        del members[root_v]
+    for root in list(members):
+        for node in members[root]:
+            death[node] = np.inf
+    order_nodes = np.lexsort((np.arange(n), -death))
+    return order_nodes[:min(k, n)].astype(np.int64)
+
+
+def connected_components(n: int, edges: np.ndarray):
+    """Return connected-component labels and the number of components."""
+    parent = list(range(n))
+
+    def find(a):
+        while parent[a] != a:
+            parent[a] = parent[parent[a]]
+            a = parent[a]
+        return a
+
+    for edge in edges:
+        root_u, root_v = find(int(edge[0])), find(int(edge[1]))
+        if root_u != root_v:
+            parent[root_v] = root_u
+    roots = np.array([find(i) for i in range(n)])
+    _, labels = np.unique(roots, return_inverse=True)
+    return labels.astype(np.int64), int(labels.max()) + 1 if n else 0
+
+
+# ------------------------------------------------------------------ routing
+def route_topk(Q: np.ndarray, K: np.ndarray, k: int, causal: bool = True):
+    """Return each query's k most similar keys, masking future keys if causal."""
+    n = Q.shape[0]
+    scores = Q @ K.T / np.sqrt(Q.shape[1])
+    if causal:
+        mask = np.triu(np.ones((n, n), dtype=bool), k=1)
+        scores = np.where(mask, -np.inf, scores)
+    k = int(min(k, n))
+    idx = np.argpartition(-scores, kth=k - 1, axis=1)[:, :k]
+    row = np.arange(n)[:, None]
+    logits = scores[row, idx]
+    order = np.argsort(-logits, axis=1)
+    idx = np.take_along_axis(idx, order, axis=1)
+    logits = np.take_along_axis(logits, order, axis=1)
+    return idx, logits
+
+
+def edges_from_topk(idx: np.ndarray) -> np.ndarray:
+    """Return unique undirected edges from a (n, k) neighbor-index array."""
+    n, k = idx.shape
+    u = np.repeat(np.arange(n), k)
+    v = idx.reshape(-1)
+    mask = u < v
+    u, v = u[mask], v[mask]
+    if u.size == 0:
+        return np.zeros((0, 2), dtype=np.int64)
+    key = u.astype(np.int64) * n + v
+    _, idx2 = np.unique(key, return_index=True)
+    return np.stack([u[idx2], v[idx2]], axis=1)
+
+
+def chain_edges(n: int) -> np.ndarray:
+    """Return temporal-chain edges (i, i+1)."""
+    if n < 2:
+        return np.zeros((0, 2), dtype=np.int64)
+    return np.stack([np.arange(n - 1), np.arange(1, n)], axis=1)
+
+
+def unique_edges(*edge_sets):
+    """Return the union of edge lists with duplicates removed."""
+    nonempty = [edges for edges in edge_sets if edges.size]
+    if not nonempty:
+        return np.zeros((0, 2), dtype=np.int64)
+    all_edges = np.concatenate(nonempty, axis=0)
+    u = np.minimum(all_edges[:, 0], all_edges[:, 1])
+    v = np.maximum(all_edges[:, 0], all_edges[:, 1])
+    key = u.astype(np.int64) * (int(max(u.max(), v.max())) + 1) + v
+    _, keep = np.unique(key, return_index=True)
+    return np.stack([u[keep], v[keep]], axis=1)
+
+
+# ------------------------------------------------------------- persistence
+def kruskal_barcode(n: int, edges: np.ndarray, weights: np.ndarray):
+    """Return the exact 0-dimensional persistence barcode and beta_0."""
+    parent = list(range(n))
+
+    def find(a):
+        while parent[a] != a:
+            parent[a] = parent[parent[a]]
+            a = parent[a]
+        return a
+
+    m = edges.shape[0]
+    order = np.argsort(weights) if m else ()
+    birth = [0.0] * n
+    pairs = []
+    for edge_index in order:
+        u = int(edges[edge_index, 0])
+        v = int(edges[edge_index, 1])
+        weight = float(weights[edge_index])
+        root_u, root_v = find(u), find(v)
+        if root_u == root_v:
+            continue
+        birth_value = min(birth[root_u], birth[root_v])
+        pairs.append((birth_value, weight))
+        if birth[root_u] > birth[root_v]:
+            root_u, root_v = root_v, root_u
+        parent[root_v] = root_u
+        birth[root_u] = birth_value
+    roots = {find(i) for i in range(n)}
+    for root in roots:
+        pairs.append((birth[root], float("inf")))
+    return pairs, len(roots)
+
+
+def betti_numbers(n: int, edges: np.ndarray) -> dict:
+    """Return beta_0, beta_1, and graph size for a 1-dimensional complex."""
+    m = edges.shape[0]
+    parent = list(range(n))
+
+    def find(a):
+        while parent[a] != a:
+            parent[a] = parent[parent[a]]
+            a = parent[a]
+        return a
+
+    for edge in edges:
+        root_u, root_v = find(int(edge[0])), find(int(edge[1]))
+        if root_u != root_v:
+            parent[root_v] = root_u
+    components = len({find(i) for i in range(n)})
+    beta1 = m - n + components
+    return {
+        "beta0": components,
+        "beta1": int(max(beta1, 0)),
+        "m": int(m),
+        "n": int(n),
+    }
+
+
+def topo_descriptor(n: int, edges: np.ndarray, weights: np.ndarray) -> np.ndarray:
+    """Return a fixed-length topological signature of the routed complex."""
+    betti = betti_numbers(n, edges)
+    pairs, _ = kruskal_barcode(n, edges, weights)
+    finite = [(birth, death) for birth, death in pairs if np.isfinite(death)]
+    lifetimes = np.array(
+        [death - birth for birth, death in finite], dtype=np.float64
+    )
+    if lifetimes.size:
+        maximum = float(lifetimes.max())
+        total = float(lifetimes.sum())
+        mean = float(lifetimes.mean())
+        longer_quarter = int((lifetimes > 0.25 * maximum).sum())
+        longer_half = int((lifetimes > 0.50 * maximum).sum())
+    else:
+        maximum = total = mean = 0.0
+        longer_quarter = longer_half = 0
+    return np.array(
+        [
+            betti["beta0"],
+            betti["beta1"],
+            total,
+            maximum,
+            mean,
+            longer_quarter,
+            longer_half,
+            betti["m"] / max(n, 1),
+            np.log1p(betti["m"]),
+        ],
+        dtype=np.float64,
+    )