TGraphX FAQs: Getting Started, Core Concepts, and Common Mistakes

This FAQ addresses the most common questions from researchers new to TGraphX. Questions are organized by theme: installation, graph construction, message passing, reproducibility, and interoperability.

Installation and Setup

Q: Does TGraphX require PyTorch Geometric or DGL?

No. TGraphX's base package depends only on PyTorch, torchvision, and PyYAML. Optional extras ([pyg], [dgl]) provide dataset adapters but are not required for graph learning, mining, KG embedding, generation, RL, or any core workflow.

pip install tgraphx       # no PyG, no DGL required
        pip install tgraphx[pyg]  # optional: add PyG dataset adapter
        

Q: How do I verify TGraphX is installed correctly?

python -m tgraphx doctor
        

This runs installation checks, a minimal forward pass, and reports any missing optional extras.

import tgraphx as tgx
        print(tgx.__version__)
        print(tgx.api_status("Graph"))  # → "stable"
        

Q: Which Python and PyTorch versions are supported?

Python 3.10+ and PyTorch 1.13+. Earlier versions are not tested and may have compatibility issues.

Graph Construction

Q: What is the difference between node_features, x, and labels in Graph()?

node_features (or its alias x) contains the input feature tensor for nodes — the data passed to GNN layers. labels (or node_labels, or y) contains supervision targets used during training.

from tgraphx import Graph
        import torch
        
        g = Graph(
            node_features=torch.randn(50, 32),    # input to layers
            edge_index=torch.randint(0, 50, (2, 150), dtype=torch.long),
            node_labels=torch.randint(0, 4, (50,)),  # supervision targets
        )
        # g.node_features and g.x access the same tensor
        # g.node_labels and g.y access the same tensor
        

Q: My node features are image patches [N, C, H, W]. Does TGraphX support this?

Yes. Pass them directly to Graph():

g = Graph(
            node_features=torch.randn(50, 16, 8, 8),  # [N, C, H, W]
            edge_index=edge_index,
        )
        # Then use ConvMessagePassing or TensorGINLayer with spatial_rank=2
        

Q: How do I construct a graph from a NumPy adjacency matrix?

import tgraphx as tgx
        import torch
        import numpy as np
        
        adj = np.array([[0,1,1],[1,0,0],[1,0,0]])  # 3×3 adjacency matrix
        g = tgx.make_graph(x=torch.randn(3, 16), adjacency=torch.from_numpy(adj).float())
        

Q: How do I build a kNN graph from embeddings?

import tgraphx as tgx
        import torch
        
        embeddings = torch.randn(100, 64)
        edge_index = tgx.knn_graph(embeddings, k=5, metric="cosine", make_symmetric=True)
        

Q: Does Graph validate inputs eagerly?

Yes. Graph() validates shapes, dtypes, and device consistency at construction time. Mismatches raise ValueError or TypeError with descriptive messages. Use validate_graph(g, strict=True) for additional checks.

Message Passing

Q: Which layer should I use for [N, D] vector features?

Use LinearMessagePassing or GCNConv:

from tgraphx import LinearMessagePassing
        from tgraphx.layers.vector_gcn import GCNConv
        
        layer = LinearMessagePassing(in_shape=(32,), out_shape=(64,))
        # or
        layer = GCNConv(in_dim=32, out_dim=64)
        

Q: Which layer should I use for [N, C, H, W] spatial features?

Use ConvMessagePassing, TensorGINLayer, TensorGraphSAGELayer, or TensorGATLayer with spatial_rank=2:

from tgraphx import ConvMessagePassing
        from tgraphx.layers.gin import TensorGINLayer
        
        conv_mp = ConvMessagePassing(in_shape=(16, 8, 8), out_shape=(32, 8, 8))
        gin = TensorGINLayer(in_channels=16, out_channels=32, spatial_rank=2)
        

Q: The layer expects [N, C, H, W] but I have [N, H, W, C] (channels last). What should I do?

TGraphX layers expect channels-first format (PyTorch convention). Convert before passing to the layer:

x_chw = x_hwc.permute(0, 3, 1, 2).contiguous()  # [N, H, W, C] → [N, C, H, W]
        

Q: My graph has no edges (E=0). Will message passing fail?

No. An empty edge index [2, 0] is valid. Message passing produces the self-transformation without aggregation. Verify edge_index.shape == (2, 0) with dtype=torch.long.

Reproducibility

Q: How do I make my experiment fully reproducible?

from tgraphx.reproducibility import set_seed
        import tgraphx as tgx
        
        set_seed(42)  # Seeds torch, torch.cuda, numpy (if installed), random, PYTHONHASHSEED
        
        # Or use the context manager
        with tgx.reproducible(seed=42, deterministic=True):
            # All RNG sources fixed, CUDA deterministic mode enabled
            pass
        

Also seed the NeighborLoader separately:

loader = NeighborLoader(g, fanouts=[10, 5], batch_size=64, seed=42)
        

Q: Are results reproducible across different GPUs or CUDA versions?

No. Even with all seeds fixed and deterministic mode enabled, floating-point accumulation in parallel CUDA kernels can differ between GPU architectures and CUDA versions. Document your hardware and CUDA version alongside results.

Q: How do I report results properly across multiple seeds?

Run 3–10 seeds and report mean ± standard deviation:

import statistics
        results = [run_with_seed(s) for s in [42, 123, 456]]
        print(f"{statistics.mean(results):.4f} ± {statistics.stdev(results):.4f}")
        

Interoperability

Q: Can I convert a NetworkX graph to a TGraphX Graph?

import networkx as nx
        from tgraphx import Graph
        
        G = nx.karate_club_graph()
        g = Graph.from_networkx(G)
        

Note: NetworkX graphs converted this way will have no node features unless you set them explicitly in NetworkX first.

Q: Can I use a PyG dataset with TGraphX?

Yes, with the optional [pyg] extra:

# pip install tgraphx[pyg]
        import tgraphx as tgx
        
        dataset = tgx.load_dataset("cora", format="pyg")
        

Q: Can I save and load a TGraphX graph?

g.save("my_graph.tgx")
        from tgraphx import Graph
        g_loaded = Graph.load("my_graph.tgx")
        

The .tgx format is TGraphX's native format supporting tensor-valued features. GraphML does not support rank-4 tensors.

Q: Can TGraphX graphs be moved to GPU?

g_gpu = g.to("cuda")
        model_gpu = model.to("cuda")
        # All tensors are moved together
        

Common Mistakes

Q: I get edge_index must have dtype torch.long — what am I doing wrong?

Your edge index tensor is float or int32. Cast it:

edge_index = edge_index.long()  # or dtype=torch.long in construction
        

Q: I get edge_index references node 95, but num_nodes=50. Why?

Your edge index contains node indices that exceed the number of nodes. This usually happens when extracting a subgraph without reindexing the edge indices:

# Wrong: edge_index still has original node IDs
        sub_x = full_x[mask]
        sub_ei = full_ei[:, edge_mask]  # still references original 0..N-1 indices
        
        # Fix: reindex to 0..num_sub_nodes-1
        # Use tgraphx's subgraph utilities (coming) or do it manually
        

Q: Training loss decreases but validation accuracy is stuck. What should I check?

1. Verify train/val masks do not overlap: assert not (train_mask & val_mask).any()
2. Verify you are using batch.seed_logits(logits) not logits for supervision
3. Check that the model is in model.eval() mode during validation
4. Check that no gradient is computed during validation: with torch.no_grad():

Q: My model gives identical outputs for all nodes (dead node embeddings). Why?

This can happen from:
1. Learning rate too high (exploding gradients)
2. All-zero features after a normalization step
3. Over-smoothing from too many GNN layers
4. A bug in message passing where aggregation always returns zeros (disconnected graph or empty edge index)

Questions About TGraphX vs Other Libraries

Q: Should I use TGraphX or PyTorch Geometric for my project?

See TGraphX vs PyTorch Geometric for a full comparison. Short answer: if your node features are standard vectors and you need OGB benchmark coverage, use PyG. If your node features are spatial/volumetric or you need integrated graph mining, KGE, graph generation, RL, or reproducibility tooling, TGraphX is designed for your workflow.

Q: Is TGraphX production-ready?

Most APIs are labeled Beta. The Graph core data structure, basic message-passing layers, and core mining utilities are stable. Heterogeneous graphs, temporal graphs, distributed training, and RL are Experimental. Check tgx.api_status("FeatureName") for any feature.

Q: Where can I find TGraphX's API documentation?

• The learn section on this website
• The compare section for framework comparisons
• python -m tgraphx readiness for installed capability status
• Source code at tgraphx/ — all public functions have docstrings

Related Articles

• TGraphX quickstart: from install to first experiment — step-by-step tutorial
• Getting started with tensor-valued nodes — deeper feature tutorial
• Shape-aware validation — understanding validation errors
• GNN research reproducibility — full reproducibility guide
• What is a TGX graph — conceptual introduction