tgraphx 0.4.0__tar.gz → 0.4.2__tar.gz

{tgraphx-0.4.0 → tgraphx-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tgraphx
-Version: 0.4.0
+Version: 0.4.2
 Summary: Tensor-aware graph neural networks preserving spatial node feature layouts
 Author-email: Arash Sajjadi <arash.sajjadi@usask.ca>
 Maintainer-email: Arash Sajjadi <arash.sajjadi@usask.ca>

{tgraphx-0.4.0 → tgraphx-0.4.2}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "tgraphx"
 # Keep this in sync with tgraphx/__init__.py::__version__
-version = "0.4.0"
+version = "0.4.2"
 description = "Tensor-aware graph neural networks preserving spatial node feature layouts"
 readme = "README.md"
 requires-python = ">=3.10"

tgraphx-0.4.2/tests/test_mining_centrality.py

@@ -0,0 +1,215 @@
+"""Tests for tgraphx.mining.centrality — centrality algorithms."""
+import math
+import pytest
+import torch
+from tgraphx.mining import (
+    degree_centrality, pagerank, personalized_pagerank, hits,
+    katz_centrality, closeness_centrality, harmonic_centrality,
+    betweenness_centrality, eigenvector_centrality, k_core_numbers,
+    in_degree_centrality, out_degree_centrality,
+)
+
+
+def _chain(N=4):
+    src = list(range(N-1)) + list(range(1, N))
+    dst = list(range(1, N)) + list(range(N-1))
+    return torch.tensor([src, dst], dtype=torch.long), N
+
+
+def _star(N=5):
+    src = [0]*(N-1) + list(range(1, N))
+    dst = list(range(1, N)) + [0]*(N-1)
+    return torch.tensor([src, dst], dtype=torch.long), N
+
+
+def _triangle():
+    ei = torch.tensor([[0,1,2,1,2,0],[1,2,0,0,1,2]], dtype=torch.long)
+    return ei, 3
+
+
+class TestDegreeCentrality:
+    def test_star_hub_highest(self):
+        ei, N = _star()
+        dc = degree_centrality(ei, N, directed=False)
+        assert float(dc[0]) == float(dc.max())
+
+    def test_range_zero_one(self):
+        ei, N = _chain()
+        dc = degree_centrality(ei, N)
+        assert (dc >= 0).all() and (dc <= 1).all()
+
+    def test_isolated_zero(self):
+        ei = torch.zeros((2, 0), dtype=torch.long)
+        dc = degree_centrality(ei, 5)
+        assert dc.sum() == 0.0
+
+    def test_complete_all_one(self):
+        from tgraphx.mining import complete_graph
+        ei, N = complete_graph(4)
+        dc = degree_centrality(ei, N, directed=False)
+        assert all(abs(float(v) - 1.0) < 1e-5 for v in dc.tolist())
+
+
+class TestPageRank:
+    def test_sums_to_one(self):
+        ei, N = _chain()
+        pr = pagerank(ei, N)
+        assert abs(float(pr.sum()) - 1.0) < 1e-4
+
+    def test_non_negative(self):
+        ei, N = _chain()
+        pr = pagerank(ei, N)
+        assert (pr >= 0).all()
+
+    def test_uniform_on_symmetric_complete(self):
+        from tgraphx.mining import complete_graph
+        ei, N = complete_graph(4)
+        pr = pagerank(ei, N)
+        assert pr.std().item() < 0.01  # all equal for symmetric complete graph
+
+    def test_empty_graph(self):
+        ei = torch.zeros((2, 0), dtype=torch.long)
+        pr = pagerank(ei, 4)
+        # All equal: 1/N
+        assert pr.shape == (4,)
+        assert (pr >= 0).all()
+
+    def test_deterministic(self):
+        ei, N = _chain()
+        pr1 = pagerank(ei, N)
+        pr2 = pagerank(ei, N)
+        assert torch.equal(pr1, pr2)
+
+
+class TestPersonalisedPageRank:
+    def test_teleport_to_seed(self):
+        """PPR from node 0 should assign higher weight to node 0's side."""
+        ei, N = _chain(6)
+        pers = torch.zeros(6)
+        pers[0] = 1.0
+        ppr = personalized_pagerank(ei, N, pers)
+        assert float(ppr[0]) >= float(ppr[N-1])
+
+    def test_sums_to_one(self):
+        ei, N = _chain()
+        pers = torch.ones(N)
+        ppr = personalized_pagerank(ei, N, pers)
+        assert abs(float(ppr.sum()) - 1.0) < 1e-4
+
+
+class TestHITS:
+    def test_shapes(self):
+        ei, N = _chain()
+        h, a = hits(ei, N)
+        assert h.shape == (N,) and a.shape == (N,)
+
+    def test_non_negative(self):
+        ei, N = _chain()
+        h, a = hits(ei, N)
+        assert (h >= 0).all() and (a >= 0).all()
+
+    def test_empty_graph(self):
+        ei = torch.zeros((2, 0), dtype=torch.long)
+        h, a = hits(ei, 3)
+        assert h.shape == (3,) and a.shape == (3,)
+
+
+class TestKatzCentrality:
+    def test_non_negative(self):
+        ei, N = _chain()
+        k = katz_centrality(ei, N)
+        assert (k >= 0).all()
+
+    def test_higher_degree_higher_katz(self):
+        # In a chain, middle nodes should have >= katz as leaves.
+        ei, N = _chain(5)
+        k = katz_centrality(ei, N)
+        assert float(k[0]) <= float(k[2])  # leaf <= middle
+
+
+class TestClosenessCentrality:
+    def test_hand_computed_triangle(self):
+        """All K3 nodes have closeness = 1 (distance to each other node = 1)."""
+        ei, N = _triangle()
+        cc = closeness_centrality(ei, N)
+        for v in cc.tolist():
+            assert abs(v - 1.0) < 1e-5
+
+    def test_path_center_highest(self):
+        ei, N = _chain(5)  # 0-1-2-3-4
+        cc = closeness_centrality(ei, N)
+        # Node 2 (center) has highest closeness.
+        assert int(cc.argmax().item()) == 2
+
+    def test_size_guard(self):
+        ei = torch.zeros((2, 0), dtype=torch.long)
+        with pytest.raises(ValueError, match="max_nodes_exact"):
+            closeness_centrality(ei, 2001, max_nodes_exact=2000)
+
+
+class TestHarmonicCentrality:
+    def test_non_negative(self):
+        ei, N = _chain()
+        hc = harmonic_centrality(ei, N)
+        assert (hc >= 0).all()
+
+    def test_star_hub_highest(self):
+        ei, N = _star()
+        hc = harmonic_centrality(ei, N)
+        assert int(hc.argmax().item()) == 0
+
+
+class TestBetweennessCentrality:
+    def test_star_hub_highest(self):
+        """Hub node 0 lies on all shortest paths between leaves."""
+        ei, N = _star()
+        bc = betweenness_centrality(ei, N)
+        assert int(bc.argmax().item()) == 0
+
+    def test_path_middle_highest(self):
+        ei, N = _chain(5)
+        bc = betweenness_centrality(ei, N)
+        # Middle node 2 has highest betweenness in a 5-node path.
+        assert int(bc.argmax().item()) == 2
+
+    def test_triangle_all_zero(self):
+        """In K3, no node lies strictly between two others (only direct edges)."""
+        ei, N = _triangle()
+        bc = betweenness_centrality(ei, N)
+        assert bc.max().item() < 1e-6
+
+    def test_size_guard(self):
+        ei = torch.zeros((2, 0), dtype=torch.long)
+        with pytest.raises(ValueError, match="max_nodes_exact"):
+            betweenness_centrality(ei, 501, max_nodes_exact=500)
+
+
+class TestEigenvectorCentrality:
+    def test_non_negative(self):
+        ei, N = _chain()
+        ec = eigenvector_centrality(ei, N)
+        assert (ec >= 0).all()
+
+    def test_star_hub_highest(self):
+        ei, N = _star()
+        ec = eigenvector_centrality(ei, N)
+        assert int(ec.argmax().item()) == 0
+
+
+class TestKCoreNumbers:
+    def test_path_core_one(self):
+        """In a path graph all nodes have k-core = 1 (or 0 for isolated)."""
+        ei, N = _chain()
+        kc = k_core_numbers(ei, N)
+        assert kc.max().item() == 1
+
+    def test_triangle_core_two(self):
+        """In K3 all nodes have k-core = 2."""
+        ei, N = _triangle()
+        kc = k_core_numbers(ei, N)
+        assert kc.min().item() == 2 and kc.max().item() == 2
+
+    def test_isolated_core_zero(self):
+        ei = torch.zeros((2, 0), dtype=torch.long)
+        kc = k_core_numbers(ei, 5)
+        assert kc.max().item() == 0

tgraphx-0.4.2/tests/test_mining_generators_spectral.py

@@ -0,0 +1,259 @@
+"""Tests for graph generators, spectral analysis, label propagation, and embeddings."""
+import pytest
+import torch
+from tgraphx.mining import (
+    erdos_renyi_graph, barabasi_albert_graph, stochastic_block_model_graph,
+    watts_strogatz_graph, complete_graph, cycle_graph, path_graph, star_graph,
+    karate_club_graph, synthetic_anomaly_graph, motif_injected_graph,
+    graph_laplacian, normalized_laplacian, laplacian_eigenvalues,
+    fiedler_vector, algebraic_connectivity, laplacian_eigvec_positional_encoding,
+    spectral_clustering, spectral_distance, dirichlet_energy,
+    label_propagation, LabelPropagationClassifier,
+    extract_node_embeddings, extract_graph_embeddings,
+    embedding_similarity_matrix, embedding_pairwise_distances,
+    embedding_nearest_neighbors,
+    analyze_graph,
+)
+
+
+class TestGenerators:
+    def test_erdos_renyi_deterministic(self):
+        ei1, N1 = erdos_renyi_graph(20, 0.3, seed=0)
+        ei2, N2 = erdos_renyi_graph(20, 0.3, seed=0)
+        assert torch.equal(ei1, ei2) and N1 == N2 == 20
+
+    def test_erdos_renyi_density(self):
+        """Dense ER graph should have more edges than sparse one."""
+        ei_dense, _ = erdos_renyi_graph(20, 0.8, seed=42)
+        ei_sparse, _ = erdos_renyi_graph(20, 0.1, seed=42)
+        assert ei_dense.size(1) > ei_sparse.size(1)
+
+    def test_barabasi_albert_connects(self):
+        ei, N = barabasi_albert_graph(20, m=2, seed=0)
+        assert N == 20
+        assert ei.size(1) > 0
+
+    def test_sbm_communities_larger_p_in(self):
+        """SBM with higher p_in should have more intra-community edges."""
+        ei, N, labels = stochastic_block_model_graph([5, 5], p_in=0.8, p_out=0.05, seed=0)
+        intra = sum(int(labels[ei[0,k]]) == int(labels[ei[1,k]]) for k in range(ei.size(1)))
+        inter = ei.size(1) - intra
+        assert intra > inter
+
+    def test_watts_strogatz_shape(self):
+        ei, N = watts_strogatz_graph(10, k=4, p=0.1, seed=0)
+        assert N == 10
+
+    def test_complete_graph_edges(self):
+        ei, N = complete_graph(4)
+        assert ei.size(1) == 4 * 3  # 12 directed edges in K4
+
+    def test_cycle_graph_edges(self):
+        ei, N = cycle_graph(5)
+        assert ei.size(1) == 10  # 5 undirected * 2 directions
+
+    def test_path_graph_edges(self):
+        ei, N = path_graph(5)
+        assert ei.size(1) == 8  # 4 undirected edges
+
+    def test_star_graph_hub_degree(self):
+        ei, N = star_graph(5)
+        deg = torch.zeros(N, dtype=torch.long)
+        ones = torch.ones(ei.size(1), dtype=torch.long)
+        deg.scatter_add_(0, ei[0], ones)
+        assert int(deg[0]) == 4  # hub has degree 4
+
+    def test_karate_club(self):
+        ei, N = karate_club_graph()
+        assert N == 34
+
+    def test_anomaly_graph_mask_matches(self):
+        ei, N, mask = synthetic_anomaly_graph(20, num_anomalous=3, seed=0)
+        assert int(mask.sum()) == 3
+
+    def test_motif_injected(self):
+        ei, N, tri_nodes = motif_injected_graph(20, num_triangles=2, seed=0)
+        assert tri_nodes.numel() == 6
+
+
+class TestSpectral:
+    def test_laplacian_positive_semidefinite(self):
+        """Laplacian eigenvalues should be >= 0."""
+        ei, N = path_graph(5)
+        L = graph_laplacian(ei, N)
+        evals = torch.linalg.eigvalsh(L)
+        assert (evals >= -1e-6).all()
+
+    def test_laplacian_row_sums_zero(self):
+        """L * 1 = 0 (row sums are zero)."""
+        ei, N = complete_graph(4)
+        L = graph_laplacian(ei, N)
+        row_sums = L.sum(dim=1)
+        assert (row_sums.abs() < 1e-5).all()
+
+    def test_normalized_laplacian_spectrum_range(self):
+        """Normalised Laplacian eigenvalues should be in [0, 2]."""
+        ei, N = cycle_graph(6)
+        L_norm = normalized_laplacian(ei, N)
+        evals = torch.linalg.eigvalsh(L_norm)
+        assert float(evals.min()) >= -1e-6
+        assert float(evals.max()) <= 2.0 + 1e-6
+
+    def test_fiedler_vector_orthogonal_to_ones(self):
+        """Fiedler vector should be approximately orthogonal to the all-ones vector."""
+        ei, N = path_graph(6)
+        fv, lam2 = fiedler_vector(ei, N)
+        dot = float(fv.sum().abs().item())
+        assert dot < 0.1
+
+    def test_algebraic_connectivity_zero_disconnected(self):
+        ei = torch.tensor([[0,1],[1,0]], dtype=torch.long)  # 2 isolated components
+        N = 4  # nodes 2,3 are isolated
+        lam2 = algebraic_connectivity(ei, N)
+        assert lam2 < 1e-6  # disconnected → λ₂ = 0
+
+    def test_algebraic_connectivity_positive_connected(self):
+        ei, N = complete_graph(4)
+        lam2 = algebraic_connectivity(ei, N)
+        assert lam2 > 0
+
+    def test_laplacian_pe_shape(self):
+        ei, N = path_graph(8)
+        enc = laplacian_eigvec_positional_encoding(ei, N, k=4)
+        assert enc.shape == (N, 4)
+        assert enc.dtype == torch.float32
+
+    def test_spectral_clustering_shape(self):
+        ei, N, labels = stochastic_block_model_graph([4, 4], p_in=0.8, p_out=0.05, seed=0)
+        cluster_labels = spectral_clustering(ei, N, num_clusters=2, seed=0)
+        assert cluster_labels.shape == (N,)
+        assert set(cluster_labels.tolist()) <= {0, 1}
+
+    def test_spectral_distance_zero_same_graph(self):
+        ei, N = path_graph(5)
+        d = spectral_distance(ei, N, ei, N)
+        assert d < 1e-5
+
+    def test_spectral_distance_positive_different(self):
+        ei1, N1 = path_graph(5)
+        ei2, N2 = complete_graph(5)
+        d = spectral_distance(ei1, N1, ei2, N2)
+        assert d > 0
+
+    def test_dirichlet_energy_smooth(self):
+        """Constant node features should have zero Dirichlet energy."""
+        ei, N = path_graph(5)
+        x = torch.ones(N, 4)
+        e = dirichlet_energy(x, ei, N)
+        assert abs(e) < 1e-5
+
+    def test_spectral_size_guard(self):
+        ei = torch.zeros((2, 0), dtype=torch.long)
+        with pytest.raises(ValueError, match="max_nodes"):
+            graph_laplacian(ei, 2001, max_nodes=2000)
+
+
+class TestLabelPropagation:
+    def _two_clique_data(self):
+        """Two connected cliques + labels only on clique centers."""
+        # Clique 1: 0,1,2  Clique 2: 3,4,5
+        src = [0,0,1,3,3,4,0,1,2,3,4,5]
+        dst = [1,2,2,4,5,5,0,1,2,3,4,5]
+        ei = torch.tensor([src+dst, dst+src], dtype=torch.long)
+        ei = torch.unique(ei, dim=1)
+        N = 6
+        y = torch.tensor([0, 0, 0, 1, 1, 1], dtype=torch.long)
+        # Only reveal label for node 0 and node 3.
+        mask = torch.tensor([True, False, False, True, False, False])
+        return ei, N, y, mask
+
+    def test_propagates_correct_labels(self):
+        ei, N, y, mask = self._two_clique_data()
+        Z = label_propagation(ei, N, y, mask, num_classes=2)
+        preds = Z.argmax(dim=1)
+        # Nodes 1,2 should get class 0; nodes 4,5 should get class 1.
+        assert int(preds[1]) == 0 and int(preds[2]) == 0
+        assert int(preds[4]) == 1 and int(preds[5]) == 1
+
+    def test_output_shape(self):
+        ei, N, y, mask = self._two_clique_data()
+        Z = label_propagation(ei, N, y, mask, num_classes=2)
+        assert Z.shape == (N, 2)
+
+    def test_labeled_nodes_stay_close_to_seed(self):
+        """Labeled nodes should keep high probability for their own class."""
+        ei, N, y, mask = self._two_clique_data()
+        Z = label_propagation(ei, N, y, mask, num_classes=2, alpha=0.5)
+        # Node 0 labeled class 0 — still high probability class 0.
+        assert float(Z[0, 0]) >= float(Z[0, 1])
+
+    def test_classifier_api(self):
+        ei, N, y, mask = self._two_clique_data()
+        clf = LabelPropagationClassifier(alpha=0.9)
+        Z = clf.fit_predict(ei, N, y, mask, num_classes=2)
+        preds = clf.predict()
+        assert preds.shape == (N,)
+        assert Z.shape == (N, 2)
+
+    def test_deterministic(self):
+        ei, N, y, mask = self._two_clique_data()
+        Z1 = label_propagation(ei, N, y, mask, num_classes=2)
+        Z2 = label_propagation(ei, N, y, mask, num_classes=2)
+        assert torch.equal(Z1, Z2)
+
+
+class TestEmbeddings:
+    def test_extract_node_embeddings_shape(self):
+        import torch.nn as nn
+        model = nn.Sequential(nn.Linear(4, 8), nn.ReLU())
+        # Model that ignores edge_index for simplicity.
+        class _SimpleModel(nn.Module):
+            def __init__(self): super().__init__(); self.lin = nn.Linear(4, 8)
+            def forward(self, x, ei): return self.lin(x)
+        m = _SimpleModel()
+        ei = torch.tensor([[0,1],[1,2]], dtype=torch.long)
+        x = torch.randn(3, 4)
+        emb = extract_node_embeddings(m, ei, x, no_grad=True)
+        assert emb.shape == (3, 8)
+        assert not emb.requires_grad
+
+    def test_extract_graph_embeddings_shape(self):
+        class _M(torch.nn.Module):
+            def __init__(self): super().__init__(); self.lin = torch.nn.Linear(4, 6)
+            def forward(self, x, ei): return self.lin(x)
+        m = _M()
+        graphs = [
+            {"node_features": torch.randn(3, 4), "edge_index": torch.tensor([[0],[1]], dtype=torch.long)},
+            {"node_features": torch.randn(4, 4), "edge_index": torch.tensor([[0,1],[1,2]], dtype=torch.long)},
+        ]
+        embs = extract_graph_embeddings(m, graphs, pooling="mean")
+        assert embs.shape == (2, 6)
+
+    def test_embedding_similarity_cosine_symmetric(self):
+        emb = torch.randn(5, 8)
+        S = embedding_similarity_matrix(emb, method="cosine")
+        assert S.shape == (5, 5)
+        assert torch.allclose(S, S.t(), atol=1e-5)
+        # Diagonal should be ~1.
+        assert (S.diagonal() - 1.0).abs().max() < 1e-4
+
+    def test_embedding_pairwise_distances_non_negative(self):
+        emb = torch.randn(4, 8)
+        D = embedding_pairwise_distances(emb)
+        assert (D >= 0).all()
+        assert (D.diagonal() < 1e-5).all()
+
+    def test_embedding_nearest_neighbors(self):
+        emb = torch.eye(5)  # orthogonal — nearest is self
+        idx, scores = embedding_nearest_neighbors(emb, emb, k=2, method="cosine")
+        assert idx.shape == (5, 2)
+        # First nearest neighbour of each is itself.
+        assert (idx[:, 0] == torch.arange(5)).all()
+
+    def test_analyze_graph_runs(self):
+        ei, N = path_graph(8)
+        result = analyze_graph(ei, N, include_spectral=True)
+        assert "summary" in result
+        assert "motifs" in result
+        assert "centrality" in result
+        assert isinstance(result["summary"], dict)

tgraphx-0.4.2/tests/test_neural_mining_batched.py

@@ -0,0 +1,174 @@
+"""Tests for batched PrototypeMembershipScorer and neural mining benchmark.
+
+Covers:
+- score_batch_fast output shape matches score_batch
+- backward works through score_batch_fast
+- no cross-graph edge leakage in batched forward
+- benchmark_neural_mining --help and --small --json run
+- benchmark JSON schema validated
+- loss decreased in benchmark tasks
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+import torch
+
+from tgraphx.mining import PrototypeMembershipScorer
+
+BENCH_DIR = Path(__file__).resolve().parent.parent / "benchmarks" / "mining"
+
+
+# ── Batched scorer ────────────────────────────────────────────────────────────
+
+
+def _make_candidates(n: int = 3, N: int = 5, D: int = 4):
+    """Build n candidate graph dicts.  N must be >= 5 for the default edge_index."""
+    N = max(N, 5)  # edge_index goes up to node 4
+    ei = torch.tensor([[0,1,2,3],[1,2,3,4]], dtype=torch.long)
+    candidates = []
+    for _ in range(n):
+        x = torch.randn(N, D)
+        candidates.append({
+            "node_features": x,
+            "edge_index": ei,
+            "query_idx": N - 1,
+        })
+    return candidates
+
+
+class TestBatchedMembershipScorer:
+    def test_shape_matches_sequential(self):
+        model = PrototypeMembershipScorer(in_dim=4, hidden_dim=8, out_dim=4)
+        cands = _make_candidates(3)
+        seq = model.score_batch(cands)
+        fast = model.score_batch_fast(cands)
+        assert seq.shape == fast.shape == (3,)
+
+    def test_values_close_to_sequential(self):
+        """Fast and sequential results should be identical (same forward)."""
+        model = PrototypeMembershipScorer(in_dim=4, hidden_dim=8, out_dim=4)
+        model.eval()
+        cands = _make_candidates(2, N=4, D=4)
+        with torch.no_grad():
+            seq = model.score_batch(cands)
+            fast = model.score_batch_fast(cands)
+        assert torch.allclose(seq, fast, atol=1e-5), f"seq={seq} fast={fast}"
+
+    def test_backward_through_fast(self):
+        model = PrototypeMembershipScorer(in_dim=4, hidden_dim=8, out_dim=4)
+        cands = _make_candidates(2)
+        logits = model.score_batch_fast(cands)
+        logits.sum().backward()
+        for name, p in model.named_parameters():
+            assert p.grad is not None, f"No grad for {name}"
+
+    def test_gradients_finite(self):
+        model = PrototypeMembershipScorer(in_dim=4, hidden_dim=8, out_dim=4)
+        cands = _make_candidates(3)
+        model.score_batch_fast(cands).sum().backward()
+        for p in model.parameters():
+            if p.grad is not None:
+                assert torch.isfinite(p.grad).all()
+
+    def test_no_cross_graph_edge(self):
+        """Different query positions should give different logits."""
+        model = PrototypeMembershipScorer(in_dim=4, hidden_dim=8, out_dim=4)
+        model.eval()
+        x = torch.randn(5, 4)
+        ei = torch.tensor([[0,1,2,3],[1,2,3,4]], dtype=torch.long)
+        cands = [
+            {"node_features": x.clone(), "edge_index": ei, "query_idx": 4},
+            {"node_features": x.clone(), "edge_index": ei, "query_idx": 0},
+        ]
+        with torch.no_grad():
+            logits = model.score_batch_fast(cands)
+        # Different query positions → different scores.
+        # (Not guaranteed but almost certain with random weights)
+        assert logits.shape == (2,)
+        assert torch.isfinite(logits).all()
+
+    def test_empty_raises(self):
+        model = PrototypeMembershipScorer(in_dim=4, hidden_dim=8, out_dim=4)
+        with pytest.raises(ValueError):
+            model.score_batch_fast([])
+        with pytest.raises(ValueError):
+            model.score_batch([])
+
+    def test_single_node_graph(self):
+        model = PrototypeMembershipScorer(in_dim=4, hidden_dim=8, out_dim=4)
+        x = torch.randn(1, 4)
+        ei = torch.zeros((2, 0), dtype=torch.long)
+        cands = [{"node_features": x, "edge_index": ei, "query_idx": 0}]
+        logits = model.score_batch_fast(cands)
+        assert logits.shape == (1,)
+        assert torch.isfinite(logits).all()
+
+    @pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA not available")
+    def test_cuda_fast_batch(self):
+        model = PrototypeMembershipScorer(in_dim=4, hidden_dim=8, out_dim=4).cuda()
+        ei = torch.tensor([[0,1],[1,2]], dtype=torch.long).cuda()
+        cands = [
+            {"node_features": torch.randn(3, 4).cuda(), "edge_index": ei, "query_idx": 2},
+            {"node_features": torch.randn(3, 4).cuda(), "edge_index": ei, "query_idx": 1},
+        ]
+        logits = model.score_batch_fast(cands)
+        assert logits.device.type == "cuda"
+        assert logits.shape == (2,)
+
+
+# ── Neural mining benchmark ───────────────────────────────────────────────────
+
+
+def _run_bench(*args):
+    cmd = [sys.executable, str(BENCH_DIR / "benchmark_neural_mining.py"), *args]
+    return subprocess.run(cmd, capture_output=True, text=True)
+
+
+class TestNeuralMiningBenchmark:
+    def test_help(self):
+        res = _run_bench("--help")
+        assert res.returncode == 0
+        assert "--small" in res.stdout + res.stderr
+
+    def test_small_runs(self):
+        res = _run_bench("--small")
+        assert res.returncode == 0, res.stderr + res.stdout
+
+    def test_small_json_parseable(self):
+        res = _run_bench("--small", "--json")
+        assert res.returncode == 0, res.stderr
+        data = json.loads(res.stdout)
+        assert "benchmark" in data
+        assert "tasks" in data
+        assert "prototype_membership" in data["tasks"]
+        assert "graph_pattern_classifier" in data["tasks"]
+        assert "anomaly_autoencoder" in data["tasks"]
+
+    def test_loss_decreased_on_all_tasks(self):
+        res = _run_bench("--small", "--json", "--seed", "42", "--epochs", "5")
+        assert res.returncode == 0, res.stderr
+        data = json.loads(res.stdout)
+        for task_name, task in data["tasks"].items():
+            assert task["loss_decreased"], (
+                f"Loss did not decrease for {task_name}: "
+                f"{task['initial_loss']} → {task['final_loss']}"
+            )
+
+    def test_json_schema(self):
+        res = _run_bench("--small", "--json")
+        data = json.loads(res.stdout)
+        assert data["tgraphx_version"]
+        assert data["device"]
+        assert isinstance(data["epochs"], int)
+        for task in data["tasks"].values():
+            for key in ["train_time_s", "initial_loss", "final_loss",
+                        "loss_decreased", "gradient_health"]:
+                assert key in task, f"Missing key {key} in {task}"
+            gh = task["gradient_health"]
+            assert gh["has_nonzero"], f"All-zero gradients in {task}"
+            assert not gh["any_nan"], f"NaN gradients in {task}"