tgraphx 1.3.0__tar.gz → 1.3.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tgraphx
-Version: 1.3.0
+Version: 1.3.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>
@@ -198,6 +198,8 @@ out.sum().backward()
 A Colab tutorial walks through every workflow:
 [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1agls1xtqE5WxbWthcG0HEa3Gbk3fvoCD?usp=sharing)
 
+**Notebook gallery:** 13 scenario-driven notebooks covering Easy Mode, tensor-native image-patch graphs, sampling, knowledge graphs (including KG HPO and multimodal entity features), and graph generation are available in [docs/colab_gallery.md](docs/colab_gallery.md).
+
 ---
 
 ## Capability map

{tgraphx-1.3.0 → tgraphx-1.3.2}/README.md

@@ -143,6 +143,8 @@ out.sum().backward()
 A Colab tutorial walks through every workflow:
 [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1agls1xtqE5WxbWthcG0HEa3Gbk3fvoCD?usp=sharing)
 
+**Notebook gallery:** 13 scenario-driven notebooks covering Easy Mode, tensor-native image-patch graphs, sampling, knowledge graphs (including KG HPO and multimodal entity features), and graph generation are available in [docs/colab_gallery.md](docs/colab_gallery.md).
+
 ---
 
 ## Capability map

{tgraphx-1.3.0 → tgraphx-1.3.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 = "1.3.0"
+version = "1.3.2"
 description = "Tensor-aware graph neural networks preserving spatial node feature layouts"
 readme = "README.md"
 requires-python = ">=3.10"

tgraphx-1.3.2/tests/test_evolutionary_history_v132.py

@@ -0,0 +1,125 @@
+"""Regression tests for EvolutionResult.history (v1.3.2 bugfix).
+
+Bug fixed: EvolutionResult had no `history` attribute, causing AttributeError
+when users accessed `result.history` after optimization.
+"""
+from __future__ import annotations
+import json
+import pytest
+import torch
+
+from tgraphx.evolutionary import (
+    GraphGenome, GeneticAlgorithmOptimizer, GeneticAlgorithmConfig,
+    NSGAIIOptimizer, EvolutionConfig, connectivity_fitness,
+)
+
+
+def _genome(seed=0):
+    torch.manual_seed(seed)
+    return GraphGenome(edge_index=torch.randint(0, 8, (2, 10)), num_nodes=8)
+
+
+def _ga_result(n_gen=5):
+    cfg = GeneticAlgorithmConfig(population_size=6, n_generations=n_gen, seed=0)
+    return GeneticAlgorithmOptimizer(cfg, connectivity_fitness).optimize([_genome(i) for i in range(6)])
+
+
+class TestGAHistory:
+    def test_history_attribute_exists(self):
+        r = _ga_result()
+        assert hasattr(r, "history")
+
+    def test_history_length_equals_n_generations(self):
+        n = 7
+        r = _ga_result(n)
+        assert len(r.history) == n
+
+    def test_history_entries_are_dicts(self):
+        r = _ga_result()
+        for entry in r.history:
+            assert isinstance(entry, dict)
+
+    def test_history_has_required_keys(self):
+        r = _ga_result()
+        for entry in r.history:
+            assert "generation" in entry
+            assert "best_fitness" in entry
+
+    def test_history_generation_index_correct(self):
+        r = _ga_result(4)
+        assert r.history[0]["generation"] == 0
+        assert r.history[3]["generation"] == 3
+
+    def test_best_fitness_unchanged(self):
+        r = _ga_result()
+        assert isinstance(r.best_fitness, float)
+        assert r.best_fitness > 0
+
+    def test_colab_exact_repro(self):
+        """Exact snippet from the Colab bug report."""
+        config = GeneticAlgorithmConfig(population_size=10, n_generations=15, seed=42)
+        pop = [_genome(i) for i in range(10)]
+        result = GeneticAlgorithmOptimizer(config, connectivity_fitness).optimize(pop)
+        # These were the two print statements that triggered the bug:
+        _ = result.best_fitness          # must not raise
+        _ = len(result.history)          # must not raise (was AttributeError)
+        assert len(result.history) > 0
+
+
+class TestGASummaryToDict:
+    def test_summary_returns_string(self):
+        r = _ga_result()
+        s = r.summary()
+        assert isinstance(s, str)
+        assert "Best fitness" in s
+
+    def test_to_dict_json_serializable(self):
+        r = _ga_result()
+        d = r.to_dict()
+        json.dumps(d)
+
+    def test_to_dict_has_expected_keys(self):
+        r = _ga_result()
+        d = r.to_dict()
+        assert "best_fitness" in d
+        assert "n_generations" in d
+        assert "fitness_history" in d
+
+
+class TestNSGAIIHistory:
+    def _nsga_result(self, n_gen=6, single_fn=True):
+        cfg = EvolutionConfig(population_size=6, n_generations=n_gen, seed=0)
+        fn = connectivity_fitness if single_fn else [connectivity_fitness, connectivity_fitness]
+        return NSGAIIOptimizer(cfg, fn).optimize([_genome(i) for i in range(6)])
+
+    def test_history_attribute_exists(self):
+        r = self._nsga_result()
+        assert hasattr(r, "history")
+
+    def test_history_length_equals_n_generations(self):
+        n = 8
+        r = self._nsga_result(n)
+        assert len(r.history) == n
+
+    def test_history_has_generation_key(self):
+        r = self._nsga_result()
+        for entry in r.history:
+            assert "generation" in entry
+
+    def test_pareto_front_still_present(self):
+        r = self._nsga_result()
+        assert r.pareto_front is not None
+
+    def test_single_callable_accepted(self):
+        """NSGAIIOptimizer must accept a single callable (not just a list)."""
+        cfg = EvolutionConfig(population_size=4, n_generations=3, seed=0)
+        r = NSGAIIOptimizer(cfg, connectivity_fitness).optimize([_genome(i) for i in range(4)])
+        assert len(r.history) == 3
+
+    def test_list_of_fns_still_works(self):
+        """Passing a list of functions must still work."""
+        cfg = EvolutionConfig(population_size=4, n_generations=3, seed=0)
+        r = NSGAIIOptimizer(cfg, [connectivity_fitness, connectivity_fitness]).optimize(
+            [_genome(i) for i in range(4)]
+        )
+        assert len(r.history) == 3

tgraphx-1.3.2/tests/test_kg_feature_aware_v131.py

@@ -0,0 +1,109 @@
+"""Regression tests for feature-aware KG scoring (v1.3.1 bugfix).
+
+Bug fixed: TransEModel._embed_entities called self.entity_proj(feat) instead of
+self.entity_proj(emb, feat), causing:
+  TypeError: _FeatureProjector.forward() missing 1 required positional argument: 'feat'
+
+These tests pin the correct behaviour and prevent regression.
+"""
+from __future__ import annotations
+import pytest
+import torch
+import torch.nn as nn
+
+
+class TestFeatureAwareTransE:
+    """TransEModel with entity_feature_dim and relation_feature_dim."""
+
+    def test_entity_features_score_shape(self):
+        from tgraphx.kg import TransEModel
+        N_e, N_r, D, F_e = 10, 3, 16, 32
+        model = TransEModel(N_e, N_r, embedding_dim=D, entity_feature_dim=F_e)
+        triples = torch.tensor([[0,0,1],[2,1,3]], dtype=torch.long)
+        feats = torch.randn(N_e, F_e)
+        scores = model.score_triples(triples, entity_features=feats)
+        assert scores.shape == (2,)
+
+    def test_entity_features_gradient_flows_into_projector(self):
+        from tgraphx.kg import TransEModel
+        N_e, N_r, D, F_e = 10, 3, 16, 32
+        model = TransEModel(N_e, N_r, embedding_dim=D, entity_feature_dim=F_e)
+        triples = torch.tensor([[0,0,1],[2,1,3]], dtype=torch.long)
+        feats = torch.randn(N_e, F_e)
+        scores = model.score_triples(triples, entity_features=feats)
+        scores.mean().backward()
+        assert model.entity_proj.proj.weight.grad is not None
+        assert torch.isfinite(model.entity_proj.proj.weight.grad).all()
+        assert model.entity_proj.proj.weight.grad.abs().sum() > 0
+
+    def test_relation_features_score_shape(self):
+        from tgraphx.kg import TransEModel
+        N_e, N_r, D, F_r = 10, 3, 16, 8
+        model = TransEModel(N_e, N_r, embedding_dim=D, relation_feature_dim=F_r)
+        triples = torch.tensor([[0,0,1],[2,1,3]], dtype=torch.long)
+        r_feats = torch.randn(N_r, F_r)
+        scores = model.score_triples(triples, relation_features=r_feats)
+        assert scores.shape == (2,)
+
+    def test_both_entity_and_relation_features(self):
+        from tgraphx.kg import TransEModel
+        N_e, N_r, D = 8, 2, 12
+        model = TransEModel(N_e, N_r, embedding_dim=D,
+                            entity_feature_dim=16, relation_feature_dim=8)
+        triples = torch.tensor([[0,0,1],[2,1,3]], dtype=torch.long)
+        scores = model.score_triples(
+            triples,
+            entity_features=torch.randn(N_e, 16),
+            relation_features=torch.randn(N_r, 8),
+        )
+        assert scores.shape == (2,)
+        scores.mean().backward()
+        assert model.entity_proj.proj.weight.grad is not None
+        assert model.relation_proj.proj.weight.grad is not None
+
+    def test_no_features_unchanged(self):
+        """Without entity_features, behaviour is unchanged (no regression)."""
+        from tgraphx.kg import TransEModel
+        model = TransEModel(5, 2, embedding_dim=8)
+        triples = torch.tensor([[0,0,1]], dtype=torch.long)
+        scores = model.score_triples(triples)
+        assert scores.shape == (1,)
+
+    def test_colab_exact_user_repro(self):
+        """Exact code from the Colab bug report."""
+        from tgraphx.kg import KnowledgeGraph, TransEModel
+        torch.manual_seed(0)
+        N_e, N_r, N_t = 10, 3, 30
+        heads = torch.randint(0, N_e, (N_t,))
+        rels  = torch.randint(0, N_r, (N_t,))
+        tails = torch.randint(0, N_e, (N_t,))
+        entity_features = {"visual": torch.randn(N_e, 32)}
+        kg = KnowledgeGraph.from_hrt(
+            heads, rels, tails,
+            num_entities=N_e, num_relations=N_r,
+            entity_features=entity_features,
+        )
+        model = TransEModel(N_e, N_r, embedding_dim=16, entity_feature_dim=32)
+        triples = torch.stack([heads, rels, tails], dim=1)
+        scores = model.score_triples(triples, entity_features=kg.entity_features["visual"])
+        assert scores.shape == (N_t,)
+        scores.mean().backward()
+        assert model.entity_proj.proj.weight.grad is not None
+
+
+class TestFeatureAwareDistMult:
+    """DistMult has entity/relation projector support via _emb_e/_emb_r helpers.
+    Its public score_triples() does not expose entity_features= kwarg, but the
+    projectors must be callable with (emb, feat) — pin this against regression.
+    """
+
+    def test_projector_callable_correctly(self):
+        """The _FeatureProjector must accept (emb, feat) — not just (feat,)."""
+        from tgraphx.kg import DistMultModel
+        N_e, N_r, D, F_e = 8, 2, 16, 24
+        model = DistMultModel(N_e, N_r, embedding_dim=D, entity_feature_dim=F_e)
+        idx = torch.tensor([0, 1], dtype=torch.long)
+        feat = torch.randn(2, F_e)
+        # Call the internal _emb_e with a feature slice — must not raise.
+        out = model._emb_e(idx, feat)
+        assert out.shape == (2, D)

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

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

{tgraphx-1.3.0 → tgraphx-1.3.2}/tgraphx/evolutionary/algorithms.py

@@ -6,7 +6,7 @@ from __future__ import annotations
 
 import math
 from dataclasses import dataclass, field
-from typing import Any, Callable, Dict, List, Optional
+from typing import Any, Callable, Dict, List, Optional, Union
 
 import torch
 
@@ -49,14 +49,24 @@ class GeneticAlgorithmConfig:
 class EvolutionResult:
     """Result of an evolutionary optimization run.
 
-    Args:
+    Attributes:
         best_genome: Best genome found.
-        best_fitness: Best fitness value.
-        fitness_history: Best fitness per generation.
+        best_fitness: Best fitness value (scalar).
+        fitness_history: Best fitness value per generation ``[float, ...]``.
         diversity_history: WL uniqueness fraction per generation.
-        pareto_front: Pareto front (for multi-objective only).
+        pareto_front: Pareto front (multi-objective only; ``None`` otherwise).
         config: Configuration used.
         extra: Additional metadata.
+
+    Derived properties:
+        history: Per-generation list of dicts::
+
+            [{"generation": 0, "best_fitness": ..., "diversity": ...,
+              "pareto_front_size": ..., "population_size": ...}, ...]
+
+    Methods:
+        summary(): Return a human-readable string.
+        to_dict(): Return a JSON-serialisable dict.
     """
 
     best_genome: Optional[GraphGenome]
@@ -67,6 +77,75 @@ class EvolutionResult:
     config: Optional[Any] = None
     extra: Dict[str, Any] = field(default_factory=dict)
 
+    @property
+    def history(self) -> List[Dict[str, Any]]:
+        """Per-generation evolution history.
+
+        Returns a list of dicts, one entry per completed generation::
+
+            [
+              {"generation": 0, "best_fitness": 0.82, "diversity": 0.9,
+               "pareto_front_size": None, "population_size": None},
+              ...
+            ]
+
+        Fields present in every entry:
+            generation (int): 0-based generation index.
+            best_fitness (float or None): Best fitness seen at that generation.
+            diversity (float or None): Population diversity (WL uniqueness).
+            pareto_front_size (int or None): Pareto-front size for
+                multi-objective runs; ``None`` for single-objective.
+            population_size (int or None): Population size if stored in
+                ``extra["population_sizes"]``; else ``None``.
+        """
+        n = max(len(self.fitness_history), len(self.diversity_history))
+        # Pareto-front sizes per generation if available.
+        pf_sizes: List[Optional[int]] = self.extra.get("pareto_front_sizes", [])
+        pop_sizes: List[Optional[int]] = self.extra.get("population_sizes", [])
+        result = []
+        for i in range(n):
+            entry: Dict[str, Any] = {
+                "generation": i,
+                "best_fitness": self.fitness_history[i] if i < len(self.fitness_history) else None,
+                "diversity": self.diversity_history[i] if i < len(self.diversity_history) else None,
+                "pareto_front_size": pf_sizes[i] if i < len(pf_sizes) else None,
+                "population_size": pop_sizes[i] if i < len(pop_sizes) else None,
+            }
+            result.append(entry)
+        return result
+
+    def summary(self) -> str:
+        """Return a human-readable summary string (also prints it)."""
+        lines = [
+            "=" * 50,
+            "TGraphX Evolutionary Optimization Result",
+            "=" * 50,
+            f"Best fitness:  {self.best_fitness:.6f}",
+            f"Generations:   {len(self.fitness_history)}",
+        ]
+        if self.pareto_front:
+            lines.append(f"Pareto front:  {len(self.pareto_front)} solutions")
+        if self.fitness_history:
+            lines.append(f"Initial best:  {self.fitness_history[0]:.6f}")
+            lines.append(f"Final best:    {self.fitness_history[-1]:.6f}")
+        text = "\n".join(lines)
+        print(text)
+        return text
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return a JSON-serialisable dict (excludes non-serialisable genome)."""
+        return {
+            "best_fitness": float(self.best_fitness),
+            "n_generations": len(self.fitness_history),
+            "fitness_history": [float(f) for f in self.fitness_history],
+            "diversity_history": [float(d) for d in self.diversity_history],
+            "pareto_front_size": len(self.pareto_front) if self.pareto_front else None,
+            "extra": {
+                k: v for k, v in self.extra.items()
+                if isinstance(v, (str, int, float, bool, list, dict, type(None)))
+            },
+        }
+
 
 def _compute_diversity(population: List[GraphGenome]) -> float:
     """Compute population diversity as WL uniqueness fraction."""
@@ -333,10 +412,14 @@ class NSGAIIOptimizer:
     def __init__(
         self,
         config: EvolutionConfig,
-        fitness_fn_list: List[Callable[[GraphGenome], float]],
+        fitness_fn_list: Union[Callable[[GraphGenome], float], List[Callable[[GraphGenome], float]]],
     ) -> None:
         self.config = config
-        self.fitness_fn_list = fitness_fn_list
+        # Accept a single callable for convenience (wraps it in a one-element list).
+        if callable(fitness_fn_list) and not isinstance(fitness_fn_list, list):
+            self.fitness_fn_list = [fitness_fn_list]
+        else:
+            self.fitness_fn_list = fitness_fn_list
         self._generator: Optional[torch.Generator] = None
         if config.seed is not None:
             self._generator = torch.Generator()
@@ -358,6 +441,10 @@ class NSGAIIOptimizer:
         """
         population = [g.clone() for g in initial_population]
 
+        fitness_history: List[float] = []
+        diversity_history: List[float] = []
+        pareto_front_sizes: List[int] = []
+
         for gen in range(self.config.n_generations):
             # Generate offspring
             offspring = []
@@ -381,6 +468,13 @@ class NSGAIIOptimizer:
                 n_select=self.config.population_size,
             )
 
+            # Track per-generation history.
+            gen_fitness = [fn(g) for fn in self.fitness_fn_list for g in population]
+            best_f1 = max(self.fitness_fn_list[0](g) for g in population)
+            fitness_history.append(best_f1)
+            diversity_history.append(_compute_diversity(population))
+            pareto_front_sizes.append(len(population))
+
             if progress_callback:
                 progress_callback(gen, len(population))
 
@@ -411,8 +505,11 @@ class NSGAIIOptimizer:
         return EvolutionResult(
             best_genome=best_genome,
             best_fitness=best_fitness,
+            fitness_history=fitness_history,
+            diversity_history=diversity_history,
             pareto_front=pareto_front,
             config=self.config,
+            extra={"pareto_front_sizes": pareto_front_sizes},
         )
 
 

{tgraphx-1.3.0 → tgraphx-1.3.2}/tgraphx/kg/models.py

@@ -151,7 +151,7 @@ class TransEModel(KGScoringModel):
     ) -> torch.Tensor:
         emb = F.normalize(self.entity_emb(idx), p=2, dim=-1)
         if feat is not None and self.entity_proj is not None:
-            emb = emb + self.entity_proj(feat.float())
+            emb = self.entity_proj(emb, feat.float())
         return emb
 
     def _embed_relations(
@@ -159,7 +159,7 @@ class TransEModel(KGScoringModel):
     ) -> torch.Tensor:
         emb = self.relation_emb(idx)
         if feat is not None and self.relation_proj is not None:
-            emb = emb + self.relation_proj(feat.float())
+            emb = self.relation_proj(emb, feat.float())
         return emb
 
     def score_triples(

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tgraphx
-Version: 1.3.0
+Version: 1.3.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>
@@ -198,6 +198,8 @@ out.sum().backward()
 A Colab tutorial walks through every workflow:
 [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1agls1xtqE5WxbWthcG0HEa3Gbk3fvoCD?usp=sharing)
 
+**Notebook gallery:** 13 scenario-driven notebooks covering Easy Mode, tensor-native image-patch graphs, sampling, knowledge graphs (including KG HPO and multimodal entity features), and graph generation are available in [docs/colab_gallery.md](docs/colab_gallery.md).
+
 ---
 
 ## Capability map

{tgraphx-1.3.0 → tgraphx-1.3.2}/tgraphx.egg-info/SOURCES.txt

@@ -27,6 +27,7 @@ tests/test_edge_features.py
 tests/test_edge_weight.py
 tests/test_estimators_v05.py
 tests/test_evolutionary_graph_optimization.py
+tests/test_evolutionary_history_v132.py
 tests/test_experiments.py
 tests/test_explainability.py
 tests/test_factories.py
@@ -58,6 +59,7 @@ tests/test_kg_benchmarks_smoke.py
 tests/test_kg_data_model.py
 tests/test_kg_datasets.py
 tests/test_kg_evaluation.py
+tests/test_kg_feature_aware_v131.py
 tests/test_kg_gnn_integration.py
 tests/test_kg_hpo_v130.py
 tests/test_kg_models.py