TGraphX and PyTorch Geometric: A Complementary Workflow

Most "X vs Y" framework articles end with one winning. This one does not. PyTorch Geometric and TGraphX are different in design but complementary in practice. A research project that uses both — PyG for its mature layer ecosystem, TGraphX for tensor-valued features and reproducibility tooling — is a perfectly reasonable setup.

This article describes how to use the two together.

The mental model

Treat:

• PyG as the layer library. It has the widest collection of message-passing layers, the most pre-built models, and the deepest community resources.
• TGraphX as the workflow framework. It has tensor-valued graph containers, reproducibility tooling, audit artifacts, and a single-library KG/RL/generation stack.

Neither replaces the other. The integration question is: can you use PyG layers inside a TGraphX workflow?

Partially. Read on.

Where they integrate cleanly

Datasets. TGraphX has a PyG dataset adapter (pip install "tgraphx[pyg]"). You can load any PyG dataset and convert it into a TGraphX graph for the data layer:

import tgraphx as tgx
        from torch_geometric.datasets import Planetoid
        
        pyg_data = Planetoid(root="/tmp/cora", name="Cora")[0]
        
        # Convert to TGraphX
        g = tgx.Graph(
            x=pyg_data.x,
            edge_index=pyg_data.edge_index,
            labels=pyg_data.y,
        )
        tgx.validate_graph(g, strict=True)
        

This is the smoothest integration: PyG handles the dataset download and standard preprocessing, TGraphX handles validation and training.

NetworkX bridges. Both libraries can convert to and from NetworkX graphs:

import networkx as nx
        
        # TGraphX → NetworkX → PyG
        G_nx = g.to_networkx()
        from torch_geometric.utils import from_networkx
        pyg_data2 = from_networkx(G_nx)
        

For graphs with simple features, this round-trips reliably. For tensor-valued features, NetworkX cannot represent them; you would lose information.

Where they do not integrate cleanly

Layers. PyG's GCNConv, GATv2Conv, etc. expect PyG's internal message-passing infrastructure. They do not directly drop into a TGraphX Graph for training. The data formats are compatible at the tensor level (g.node_features and g.edge_index are standard PyTorch tensors), but the layer expects to be called within PyG's training conventions.

In practice:

import torch
        from torch_geometric.nn import GCNConv
        
        # This works — PyG layer applied to raw tensors
        conv = GCNConv(in_channels=64, out_channels=32)
        output = conv(g.node_features, g.edge_index)
        

You can use PyG layers as plain PyTorch modules. What you lose is the integration with TGraphX's build_model(), fit(), and the one-call API.

A practical hybrid pattern

For projects that want PyG layers in a TGraphX-style workflow:

import torch
        import torch.nn.functional as F
        import tgraphx as tgx
        from torch_geometric.nn import GCNConv, GATv2Conv
        
        # Define a hybrid model
        class HybridGNN(torch.nn.Module):
            def __init__(self, in_dim, hidden_dim, out_dim):
                super().__init__()
                self.conv1 = GCNConv(in_dim, hidden_dim)
                self.conv2 = GATv2Conv(hidden_dim, hidden_dim, heads=4, concat=False)
                self.conv3 = GCNConv(hidden_dim, out_dim)
        
            def forward(self, x, edge_index):
                h = F.relu(self.conv1(x, edge_index))
                h = F.relu(self.conv2(h, edge_index))
                return self.conv3(h, edge_index)
        
        # Use TGraphX for data and reproducibility
        with tgx.reproducible(seed=42, deterministic=True):
            g = tgx.Graph(x=pyg_data.x, edge_index=pyg_data.edge_index, labels=pyg_data.y)
            tgx.validate_graph(g, strict=True)
        
            model = HybridGNN(in_dim=g.node_features.shape[1], hidden_dim=64, out_dim=7)
            optimizer = torch.optim.Adam(model.parameters(), lr=2e-3)
        
            # Standard training loop
            for epoch in range(50):
                model.train()
                optimizer.zero_grad()
                out = model(g.node_features, g.edge_index)
                # ... mask-based loss ...
        

The model uses PyG layers (because we want GATv2Conv's heads parameter). The data layer is TGraphX (because we want tgx.Graph and validate_graph). The training is in a reproducible() context (because we want the audit artifacts). Nothing about this combination breaks.

When the hybrid pattern is the right choice

• You want a specific PyG layer not in TGraphX's small layer set.
• You want TGraphX's reproducibility/audit tooling around PyG-based research.
• You are migrating a PyG project to TGraphX incrementally.

When to stay pure

Pure PyG. If your project is standard GNN research on standard benchmarks, the broader PyG ecosystem and documentation will save time. Do not introduce TGraphX just for the sake of it.

Pure TGraphX. If your project uses tensor-valued nodes, KG completion, or the integrated graph RL/generation, the framework's native types are easier than bridging.

A summary table

Limitations of integration

• TGraphX does not officially support PyG's HeteroData directly. For hetero use cases, choose one framework and stick with it.
• The PyG dataset adapter requires pip install "tgraphx[pyg]" and PyG installed separately. They are not always pinned to compatible versions; check compatibility for your specific versions.
• Performance optimizations specific to one framework (e.g., PyG's fused kernels) do not transfer to the hybrid pattern.

On the relationship between projects

PyG and TGraphX are not competitors in any meaningful sense. They serve different research populations: PyG is the field's default; TGraphX is specialized for projects with specific needs (tensor features, integrated tooling). Both can coexist in the same project.

The TGraphX maintainers have been explicit in framing the project as complementary, not competitive. The framework's optional PyG dataset adapter is a deliberate integration point. If you are evaluating whether to use TGraphX, the question is not "instead of PyG" — it is "alongside PyG, for these specific reasons."

FAQ

Q: Can I use TGraphX's reproducibility context with a PyG model?
A: Yes. with tgx.reproducible(seed=42): is a Python context manager; it works regardless of what model you train inside it.

Q: Does tgx.audit_run_dir work for runs that don't use TGraphX's runner?
A: It works on any directory and reports what it finds. If you write your own runner that mimics the framework's artifact layout, the audit utility will recognize the standard files.

Q: Can I install both frameworks side-by-side?
A: Yes, in the same environment. They have minimal dependency overlap.

Q: Are there examples of the hybrid pattern in production research?
A: The TGraphX repository's examples directory does not have a dedicated hybrid example. The pattern is straightforward enough that you can write it from scratch in 30 lines.

Q: What about PyG's HeteroData?
A: Use pure PyG for hetero graphs. TGraphX's heterogeneous GNN support is Experimental.