tgraphx 1.2.0__tar.gz → 1.3.0__tar.gz

{tgraphx-1.2.0/tgraphx.egg-info → tgraphx-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tgraphx
-Version: 1.2.0
+Version: 1.3.0
 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-1.2.0 → tgraphx-1.3.0}/pyproject.toml

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

tgraphx-1.3.0/tests/test_kg_hpo_v130.py

@@ -0,0 +1,162 @@
+"""KG HPO (hyperparameter search) tests (v1.3)."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+import torch
+
+
+@pytest.fixture
+def tiny_kg():
+    from tgraphx.kg import KnowledgeGraph
+    torch.manual_seed(0)
+    heads = torch.randint(0, 15, (60,))
+    rels = torch.randint(0, 2, (60,))
+    tails = torch.randint(0, 15, (60,))
+    return KnowledgeGraph.from_hrt(
+        heads, rels, tails, num_entities=15, num_relations=2
+    )
+
+
+class TestKGHPOGrid:
+    def test_grid_search_covers_all_combos(self, tiny_kg):
+        from tgraphx.kg import run_kg_hpo
+        result = run_kg_hpo(
+            tiny_kg,
+            model_names=["TransE", "DistMult"],
+            search_space={"embedding_dim": [8, 16]},
+            strategy="grid",
+            epochs=1, seed=0,
+        )
+        # 2 models × 2 embedding dims = 4 trials
+        assert len(result.trials) == 4
+
+    def test_max_trials_cap(self, tiny_kg):
+        from tgraphx.kg import run_kg_hpo
+        result = run_kg_hpo(
+            tiny_kg,
+            model_names=["TransE", "DistMult", "SimplE"],
+            search_space={"embedding_dim": [8, 16]},
+            strategy="grid",
+            max_trials=3,
+            epochs=1, seed=0,
+        )
+        assert len(result.trials) <= 3
+
+
+class TestKGHPORandom:
+    def test_random_strategy_deterministic(self, tiny_kg):
+        from tgraphx.kg import run_kg_hpo
+        r1 = run_kg_hpo(
+            tiny_kg,
+            model_names=["TransE", "DistMult"],
+            search_space={"embedding_dim": [8, 16]},
+            strategy="random",
+            max_trials=2,
+            epochs=1, seed=42,
+        )
+        r2 = run_kg_hpo(
+            tiny_kg,
+            model_names=["TransE", "DistMult"],
+            search_space={"embedding_dim": [8, 16]},
+            strategy="random",
+            max_trials=2,
+            epochs=1, seed=42,
+        )
+        # Same seed → same trial order → same best model.
+        assert r1.best_model_name == r2.best_model_name
+        assert r1.best_config == r2.best_config
+
+
+class TestKGHPOBestSelection:
+    def test_best_trial_has_highest_mrr(self, tiny_kg):
+        from tgraphx.kg import run_kg_hpo
+        result = run_kg_hpo(
+            tiny_kg,
+            model_names=["TransE", "DistMult"],
+            search_space={"embedding_dim": [8]},
+            metric="mrr",
+            epochs=2, seed=0,
+        )
+        ok_trials = [t for t in result.trials if t.status == "ok"]
+        best_mrr = max(t.metrics["mrr"] for t in ok_trials)
+        assert result.best_metrics["mrr"] == pytest.approx(best_mrr, abs=1e-6)
+
+    def test_mr_uses_lower_is_better(self, tiny_kg):
+        from tgraphx.kg import run_kg_hpo
+        result = run_kg_hpo(
+            tiny_kg,
+            model_names=["TransE", "DistMult"],
+            search_space={"embedding_dim": [8]},
+            metric="mr",
+            epochs=2, seed=0,
+        )
+        ok_trials = [t for t in result.trials if t.status == "ok"]
+        best_mr = min(t.metrics["mr"] for t in ok_trials)
+        assert result.best_metrics["mr"] == pytest.approx(best_mr, abs=1e-6)
+
+
+class TestKGHPOResultObject:
+    def test_result_to_dict_json_serialisable(self, tiny_kg):
+        from tgraphx.kg import run_kg_hpo
+        result = run_kg_hpo(
+            tiny_kg,
+            model_names=["SimplE"],
+            search_space={"embedding_dim": [8]},
+            epochs=1, seed=0,
+        )
+        d = result.to_dict()
+        json.dumps(d)  # Must not raise.
+
+    def test_summary_returns_string(self, tiny_kg):
+        from tgraphx.kg import run_kg_hpo
+        result = run_kg_hpo(
+            tiny_kg,
+            model_names=["TransE"],
+            search_space={"embedding_dim": [8]},
+            epochs=1, seed=0,
+        )
+        s = result.summary()
+        assert isinstance(s, str)
+        assert "best model" in s.lower() or "Best model" in s
+
+    def test_write_dashboard_artifacts(self, tmp_path, tiny_kg):
+        from tgraphx.kg import run_kg_hpo
+        result = run_kg_hpo(
+            tiny_kg,
+            model_names=["TransE"],
+            search_space={"embedding_dim": [8]},
+            epochs=1, seed=0,
+            dashboard_dir=str(tmp_path / "hpo_run"),
+        )
+        assert (tmp_path / "hpo_run" / "kg_hpo_results.json").exists()
+        assert (tmp_path / "hpo_run" / "metrics_summary.json").exists()
+        # JSON must be valid.
+        data = json.loads((tmp_path / "hpo_run" / "kg_hpo_results.json").read_text())
+        assert "best_model_name" in data
+
+
+class TestKGHPOErrors:
+    def test_unknown_metric(self, tiny_kg):
+        from tgraphx.kg import run_kg_hpo
+        with pytest.raises(ValueError, match="metric"):
+            run_kg_hpo(tiny_kg, metric="bad_metric", epochs=1)
+
+    def test_unknown_strategy(self, tiny_kg):
+        from tgraphx.kg import run_kg_hpo
+        with pytest.raises(ValueError, match="strategy"):
+            run_kg_hpo(tiny_kg, strategy="bayesian", epochs=1)
+
+    def test_unknown_model_name(self, tiny_kg):
+        from tgraphx.kg import run_kg_hpo
+        with pytest.raises(ValueError, match="model"):
+            run_kg_hpo(tiny_kg, model_names=["FakeModel"], epochs=1)
+
+    def test_no_mutation_of_input_kg(self, tiny_kg):
+        from tgraphx.kg import run_kg_hpo
+        original_triples = tiny_kg.triples.clone()
+        run_kg_hpo(tiny_kg, model_names=["TransE"],
+                   search_space={"embedding_dim": [8]}, epochs=1, seed=0)
+        assert torch.equal(tiny_kg.triples, original_triples)

tgraphx-1.3.0/tests/test_kg_simple_v130.py

@@ -0,0 +1,162 @@
+"""SimplE KG model tests (v1.3).
+
+SimplE: f(h, r, t) = 0.5 * (⟨h_head, r_fwd, t_tail⟩ + ⟨t_head, r_inv, h_tail⟩)
+Reference: Kazemi & Poole, NeurIPS 2018.
+
+These tests pin shape, hand-computed values, gradient flow, dtype/device,
+asymmetry behavior, and a tiny overfit sanity check.
+"""
+from __future__ import annotations
+
+import pytest
+import torch
+
+
+class TestSimplEShape:
+    def test_score_shape(self):
+        from tgraphx.kg import SimplEModel
+        model = SimplEModel(num_entities=6, num_relations=3, embedding_dim=4)
+        triples = torch.tensor([[0, 0, 1], [2, 1, 3], [4, 2, 5]], dtype=torch.long)
+        scores = model.score_triples(triples)
+        assert scores.shape == (3,)
+        assert scores.dtype == torch.float32
+
+    def test_forward_alias(self):
+        from tgraphx.kg import SimplEModel
+        model = SimplEModel(num_entities=4, num_relations=2, embedding_dim=4)
+        triples = torch.tensor([[0, 0, 1]], dtype=torch.long)
+        assert torch.equal(model.score_triples(triples), model.forward(triples))
+
+
+class TestSimplEHandComputed:
+    """Hand-computed reference values for SimplE scoring.
+
+    Setup:
+        D=1 (scalar embeddings for easy hand-calculation).
+        entity_head = [h0=1, h1=2, h2=3, h3=4]
+        entity_tail = [t0=5, t1=6, t2=7, t3=8]
+        relation_fwd = [r0=2, r1=3]
+        relation_inv = [r0=4, r1=5]
+
+    Triple (h=0, r=0, t=1):
+        fwd  = h_head[0] * r_fwd[0] * t_tail[1] = 1 * 2 * 6 = 12
+        inv  = t_head[1] * r_inv[0] * h_tail[0] = 2 * 4 * 5 = 40
+        score = 0.5 * (12 + 40) = 26
+    """
+
+    def _setup_d1_model(self):
+        from tgraphx.kg import SimplEModel
+        model = SimplEModel(num_entities=4, num_relations=2, embedding_dim=1)
+        with torch.no_grad():
+            # D=1 so each weight is a column vector [N, 1].
+            model.entity_head.weight.data = torch.tensor([[1.0], [2.0], [3.0], [4.0]])
+            model.entity_tail.weight.data = torch.tensor([[5.0], [6.0], [7.0], [8.0]])
+            model.relation_fwd.weight.data = torch.tensor([[2.0], [3.0]])
+            model.relation_inv.weight.data = torch.tensor([[4.0], [5.0]])
+        return model
+
+    def test_hand_computed_triple_0_0_1(self):
+        model = self._setup_d1_model()
+        triples = torch.tensor([[0, 0, 1]], dtype=torch.long)
+        score = model.score_triples(triples)
+        # fwd = 1 * 2 * 6 = 12; inv = 2 * 4 * 5 = 40; score = 0.5*(12+40) = 26
+        assert score.item() == pytest.approx(26.0, abs=1e-5)
+
+    def test_hand_computed_triple_1_1_2(self):
+        model = self._setup_d1_model()
+        triples = torch.tensor([[1, 1, 2]], dtype=torch.long)
+        score = model.score_triples(triples)
+        # fwd = entity_head[1] * r_fwd[1] * entity_tail[2]
+        #     = 2 * 3 * 7 = 42
+        # inv = entity_head[2] * r_inv[1] * entity_tail[1]
+        #     = 3 * 5 * 6 = 90
+        # score = 0.5 * (42 + 90) = 66
+        assert score.item() == pytest.approx(66.0, abs=1e-5)
+
+    def test_asymmetry(self):
+        """f(h, r, t) ≠ f(t, r, h) in general — SimplE can model asymmetric relations."""
+        model = self._setup_d1_model()
+        fwd = model.score_triples(torch.tensor([[0, 0, 1]], dtype=torch.long))
+        rev = model.score_triples(torch.tensor([[1, 0, 0]], dtype=torch.long))
+        # fwd=26 as computed above; rev:
+        # fwd_term = entity_head[1] * r_fwd[0] * entity_tail[0] = 2*2*5 = 20
+        # inv_term = entity_head[0] * r_inv[0] * entity_tail[1] = 1*4*6 = 24
+        # rev_score = 0.5*(20+24) = 22  (different from 26)
+        assert rev.item() == pytest.approx(22.0, abs=1e-5)
+        assert not torch.allclose(fwd, rev)
+
+    def test_symmetric_when_head_eq_tail_embeddings(self):
+        """If head_emb == tail_emb and fwd_rel == inv_rel, score is symmetric."""
+        from tgraphx.kg import SimplEModel
+        model = SimplEModel(num_entities=4, num_relations=2, embedding_dim=2)
+        with torch.no_grad():
+            same = torch.randn(4, 2)
+            model.entity_head.weight.data = same.clone()
+            model.entity_tail.weight.data = same.clone()
+            same_r = torch.randn(2, 2)
+            model.relation_fwd.weight.data = same_r.clone()
+            model.relation_inv.weight.data = same_r.clone()
+        # With identical embeddings, f(h,r,t) and f(t,r,h) should be equal.
+        fwd = model.score_triples(torch.tensor([[0, 0, 1]], dtype=torch.long))
+        rev = model.score_triples(torch.tensor([[1, 0, 0]], dtype=torch.long))
+        assert torch.allclose(fwd, rev, atol=1e-5)
+
+
+class TestSimplEGradient:
+    def test_finite_nonzero_gradient(self):
+        from tgraphx.kg import SimplEModel
+        torch.manual_seed(0)
+        model = SimplEModel(num_entities=6, num_relations=3, embedding_dim=8)
+        triples = torch.tensor([[0, 0, 1], [2, 1, 3], [4, 2, 5]], dtype=torch.long)
+        scores = model.score_triples(triples)
+        scores.sum().backward()
+        for emb in [model.entity_head, model.entity_tail, model.relation_fwd, model.relation_inv]:
+            assert emb.weight.grad is not None
+            assert torch.isfinite(emb.weight.grad).all()
+        # Referenced entities/relations must have nonzero gradient.
+        assert model.entity_head.weight.grad[0].abs().sum() > 0
+
+
+class TestSimplEDeviceDtype:
+    def test_cpu_float32(self):
+        from tgraphx.kg import SimplEModel
+        model = SimplEModel(num_entities=4, num_relations=2, embedding_dim=4)
+        assert model.entity_head.weight.device.type == "cpu"
+        assert model.entity_head.weight.dtype == torch.float32
+
+    def test_cuda_smoke(self):
+        from tgraphx.kg import SimplEModel
+        if not torch.cuda.is_available():
+            pytest.skip("CUDA unavailable")
+        model = SimplEModel(num_entities=4, num_relations=2, embedding_dim=4).cuda()
+        triples = torch.tensor([[0, 0, 1]], device="cuda", dtype=torch.long)
+        scores = model.score_triples(triples)
+        assert scores.device.type == "cuda"
+        assert torch.isfinite(scores).all()
+
+
+class TestSimplETinyOverfit:
+    def test_margin_loss_decreases(self):
+        from tgraphx.kg import SimplEModel
+        torch.manual_seed(42)
+        model = SimplEModel(num_entities=6, num_relations=2, embedding_dim=8)
+        opt = torch.optim.Adam(model.parameters(), lr=1e-2)
+        pos = torch.tensor([[0, 0, 1], [2, 1, 3]], dtype=torch.long)
+        neg = torch.tensor([[0, 0, 3], [2, 1, 1]], dtype=torch.long)
+        initial = (1.0 + model.score_triples(neg) - model.score_triples(pos)).clamp(min=0).mean()
+        for _ in range(60):
+            loss = (1.0 + model.score_triples(neg) - model.score_triples(pos)).clamp(min=0).mean()
+            opt.zero_grad(); loss.backward(); opt.step()
+        final = (1.0 + model.score_triples(neg) - model.score_triples(pos)).clamp(min=0).mean()
+        assert final.item() <= initial.item() + 0.3, \
+            f"Loss did not decrease: {initial.item():.4f} -> {final.item():.4f}"
+
+
+class TestSimplERegistry:
+    def test_in_list_kg_models(self):
+        from tgraphx.kg import list_kg_models
+        assert "SimplE" in list_kg_models()
+
+    def test_importable_from_kg(self):
+        from tgraphx.kg import SimplEModel
+        assert SimplEModel is not None

tgraphx-1.3.0/tests/test_notebooks_v130.py

@@ -0,0 +1,126 @@
+"""Notebook structural tests (v1.3).
+
+Validates every notebook/*.ipynb without executing code.
+"""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+import pytest
+
+NOTEBOOKS_DIR = Path("notebooks")
+NOTEBOOKS = sorted(NOTEBOOKS_DIR.glob("*.ipynb"))
+
+_PRIVATE_PATH_RE = re.compile(r"/home/[a-zA-Z0-9_]+|/Users/[a-zA-Z0-9_]+")
+_SECRET_RE = re.compile(r"(?i)(token\s*=|password\s*=|api_key\s*=)['\"]?\w{8,}")
+
+
+@pytest.fixture(scope="module")
+def all_notebooks():
+    assert NOTEBOOKS_DIR.exists(), f"notebooks/ directory not found: {NOTEBOOKS_DIR}"
+    assert len(NOTEBOOKS) > 0, f"No .ipynb files in {NOTEBOOKS_DIR}"
+    return {nb.name: json.loads(nb.read_text(encoding="utf-8")) for nb in NOTEBOOKS}
+
+
+class TestNotebooksExist:
+    def test_notebooks_dir_exists(self):
+        assert NOTEBOOKS_DIR.exists()
+
+    def test_at_least_7_notebooks(self):
+        assert len(NOTEBOOKS) >= 7, f"Expected >=7 notebooks, found {len(NOTEBOOKS)}"
+
+    @pytest.mark.parametrize("name", [
+        "01_easy_tensor_node_classification.ipynb",
+        "02_image_patch_tensor_graph.ipynb",
+        "03_kg_completion_rescal_simple_hpo.ipynb",
+        "04_graph_generation_and_optimization.ipynb",
+        "05_graph_rl_coloring_and_navigation.ipynb",
+        "06_graph_io_roundtrip.ipynb",
+        "07_benchmark_suite_and_dashboard.ipynb",
+    ])
+    def test_specific_notebook_exists(self, name):
+        assert (NOTEBOOKS_DIR / name).exists(), f"Missing: {name}"
+
+
+class TestNotebookStructure:
+    def test_all_valid_json(self, all_notebooks):
+        # Already validated by the fixture (json.loads raises on invalid).
+        assert len(all_notebooks) >= 7
+
+    def test_all_have_nbformat_4(self, all_notebooks):
+        for name, nb in all_notebooks.items():
+            assert nb.get("nbformat") == 4, f"{name}: expected nbformat 4"
+
+    def test_all_have_cells(self, all_notebooks):
+        for name, nb in all_notebooks.items():
+            assert len(nb.get("cells", [])) >= 3, f"{name}: too few cells"
+
+    def test_all_have_markdown_cells(self, all_notebooks):
+        for name, nb in all_notebooks.items():
+            md = [c for c in nb["cells"] if c.get("cell_type") == "markdown"]
+            assert len(md) >= 2, f"{name}: needs at least 2 Markdown cells"
+
+    def test_all_have_code_cells(self, all_notebooks):
+        for name, nb in all_notebooks.items():
+            code = [c for c in nb["cells"] if c.get("cell_type") == "code"]
+            assert len(code) >= 2, f"{name}: needs at least 2 code cells"
+
+    def test_first_cell_is_heading(self, all_notebooks):
+        for name, nb in all_notebooks.items():
+            first = nb["cells"][0]
+            src = "".join(first.get("source", []))
+            assert first["cell_type"] == "markdown", f"{name}: first cell must be Markdown"
+            assert src.strip().startswith("#"), f"{name}: first cell must start with #"
+
+
+class TestNotebookContent:
+    def _all_source(self, nb: dict) -> str:
+        return "\n".join(
+            "".join(c.get("source", [])) for c in nb.get("cells", [])
+        )
+
+    def test_references_tgraphx(self, all_notebooks):
+        for name, nb in all_notebooks.items():
+            assert "tgraphx" in self._all_source(nb).lower(), \
+                f"{name}: does not reference tgraphx"
+
+    def test_no_private_paths(self, all_notebooks):
+        for name, nb in all_notebooks.items():
+            matches = _PRIVATE_PATH_RE.findall(self._all_source(nb))
+            assert not matches, f"{name}: private path found: {matches}"
+
+    def test_no_secrets(self, all_notebooks):
+        for name, nb in all_notebooks.items():
+            matches = _SECRET_RE.findall(self._all_source(nb))
+            assert not matches, f"{name}: potential secret: {matches}"
+
+    def test_no_excessive_outputs(self, all_notebooks):
+        for name, nb in all_notebooks.items():
+            for i, cell in enumerate(nb.get("cells", [])):
+                for out in cell.get("outputs", []):
+                    text = out.get("text", [])
+                    n = len(text) if isinstance(text, list) else text.count("\n")
+                    assert n < 200, f"{name} cell {i}: excessive output ({n} lines)"
+
+
+class TestNotebookValidationTool:
+    def test_validate_notebooks_passes(self):
+        import subprocess, sys
+        result = subprocess.run(
+            [sys.executable, "tools/validate_notebooks.py"],
+            capture_output=True, text=True,
+        )
+        assert result.returncode == 0, \
+            f"tools/validate_notebooks.py failed:\n{result.stdout}\n{result.stderr}"
+
+
+class TestColabGallery:
+    def test_colab_gallery_doc_exists(self):
+        assert Path("docs/colab_gallery.md").exists()
+
+    def test_colab_gallery_lists_notebooks(self):
+        text = Path("docs/colab_gallery.md").read_text()
+        for i in range(1, 8):
+            assert f"0{i}_" in text, f"Notebook {i} not in colab_gallery.md"

{tgraphx-1.2.0 → tgraphx-1.3.0}/tgraphx/__init__.py

@@ -10,7 +10,7 @@ Common one-liner imports::
 """
 
 # Keep this in sync with [project].version in pyproject.toml.
-__version__ = "1.2.0"
+__version__ = "1.3.0"
 
 # ── Core data structures ──────────────────────────────────────────────────────
 from .core.graph import Graph, GraphBatch

{tgraphx-1.2.0 → tgraphx-1.3.0}/tgraphx/kg/__init__.py

@@ -46,7 +46,7 @@ from .sampling import (
     TypedNegativeSampler,
 )
 from .evaluation import KGEvaluator, evaluate_filtered_ranking
-from .models import TransEModel, DistMultModel, ComplExModel, RotatEModel, RESCALModel
+from .models import TransEModel, DistMultModel, ComplExModel, RotatEModel, RESCALModel, SimplEModel
 from .losses import MarginRankingLoss, BCEKGLoss, SoftplusKGLoss
 from .trainer import KGTrainer, KGTrainingConfig
 from .gnn import KGRGCNModel, kg_to_edge_index
@@ -58,6 +58,7 @@ from .datasets import (
     MultimodalKG,
     generate_synthetic_kg,
 )
+from .hpo import run_kg_hpo, KGSearchResult, KGTrialResult
 from .reports import (
     write_kg_summary,
     write_kg_evaluation_report,
@@ -76,6 +77,7 @@ _KG_MODELS: dict = {
     "ComplEx": "Complex-valued embeddings (Trouillon et al., 2016).",
     "RotatE": "Rotation-based relational embedding (Sun et al., 2019).",
     "RESCAL": "Bilinear matrix scoring h^T M_r t (Nickel et al., 2011).",
+    "SimplE": "Symmetric bilinear with inverse embeddings (Kazemi & Poole, 2018).",
 }