TGraphX FAQ for PyTorch Users
If you already know PyTorch and want to understand TGraphX quickly, this FAQ
covers the practical questions: how to install it, how the graph object works,
what shapes to expect, and when to use it vs other tools.
How do I install TGraphX?
pip install tgraphx
Pin the version in requirements.txt since TGraphX is Beta:
tgraphx==1.4.1
What is the Graph object, and why does it exist?
Graph is a validated container for four tensors:
from tgraphx import Graph
import torch
g = Graph(
node_features=torch.randn(N, d), # [N, *]
edge_index=torch.randint(0, N, (2, E)), # [2, E]
edge_features=torch.randn(E, de), # [E, *]
node_labels=torch.randint(0, C, (N,)), # [N, *]
)
It exists because graph learning code has specific, common shape errors
(wrong edge index orientation, device mismatches, count mismatches) that a
validated container catches at construction time rather than during a
forward pass.
What does "tensor-valued" mean for graph nodes?
Node features can be arbitrary tensors, not just vectors. A node can have
shape [3, 16, 16] (an image patch), [T, D] (a time series), or [d]
(a standard vector). All forms are valid; the [N, ...] contract just requires
that the first dimension is the node count.
# Image-patch nodes
g = Graph(
node_features=torch.randn(32, 3, 16, 16), # [N=32, C=3, H=16, W=16]
edge_index=torch.randint(0, 32, (2, 100)),
...
)
How do I move a graph to GPU?
from tgraphx.performance import recommended_device
device = recommended_device() # 'cuda' if available, else 'cpu'
g = g.to(device) # moves all four tensors atomically
model = model.to(device)
recommended_device() checks torch.cuda.is_available() and returns the
appropriate device string.
How is TGraphX related to PyG (PyTorch Geometric)?
They are separate projects with different focuses:
- TGraphX: Beta library focused on tensor-valued nodes, shape validation,
built-in experiment infrastructure
- PyG: Stable, production-ready, large community, many more layers and datasets
TGraphX is not a fork of PyG and does not depend on it. For general GNN
research, PyG has more community resources. TGraphX is specifically suited
to workflows with structured tensor-valued node features.
How does validation work at construction?
The Graph constructor checks:
1. edge_index.shape == [2, E] — orientation must be [2, E], not [E, 2]
2. edge_features.shape[0] == edge_index.shape[1] — E must match
3. node_labels.shape[0] == node_features.shape[0] — N must match
4. All tensors on the same device
These errors surface immediately at Graph(...), not during training.
How do I batch multiple graphs for training?
from tgraphx import GraphBatch
batch = GraphBatch.from_graphs([g1, g2, g3, ...])
# batch.node_features: [N1+N2+N3+..., ...] concatenated
# batch.edge_index: offset per graph so indices don't collide
Use GraphDataLoader to automate this in a training loop:
from tgraphx import GraphDataLoader
loader = GraphDataLoader(
dataset=my_dataset,
batch_size=32,
num_workers=4,
shuffle=True,
)
What layers are available?
From tgraphx.layers:
- TensorGraphSAGELayer — SAGE-style convolution
- TensorGATLayer — attention-based (upcasts float16 to float32 for softmax)
- TensorGINLayer — GIN-style isomorphism-motivated layer
- GCNConv — spectral GCN
- GATv2Conv — improved GAT
- APPNP — Personalized PageRank-based propagation
How do I set a random seed?
from tgraphx.reproducibility import set_seed
set_seed(42, deterministic=True)
# Sets Python, NumPy, and PyTorch seeds.
# deterministic=True enables PyTorch's deterministic algorithm mode.
# Note: may reduce throughput.
Available from Beta v0.4.1.
How do I check my environment?
from tgraphx.performance import env_report
info = env_report(include_hardware=True)
print(info)
# Returns: python version, PyTorch version, TGraphX version, CUDA info
Call this at the start of every experiment script and save the output.
Does TGraphX support distributed / multi-GPU training?
No. distributed.py provides rank-zero printing helpers only. The source
explicitly states TGraphX does not ship a distributed training framework.
For multi-GPU, use nn.DataParallel or DistributedDataParallel around
your model. TGraphX works normally within each process.
How mature is TGraphX?
Development Status :: 4 - Beta in pyproject.toml. This means:
- Core functionality works
- API may change between versions — pin your version
- Not production-stable like PyG or DGL
For research experiments, this is fine. For production systems that depend
on API stability, wait for a production/stable release or use an alternative.
What experiment infrastructure is built in?
from tgraphx import CSVLogger, TensorBoardLogger, MLflowLogger
from tgraphx import write_graph_stats, write_experiment_config, write_hardware_report
from tgraphx.experiments import Runner, ExperimentConfig, GridRunner
from tgraphx.experiments import EarlyStopping, ModelCheckpoint
These cover logging, configuration recording, early stopping, and model
checkpointing without external dependencies (except TensorBoard/MLflow for
their respective loggers).
How do I estimate memory usage for a large graph?
from tgraphx.performance import estimate_message_memory
import torch
estimate = estimate_message_memory(
num_edges=500_000,
node_feature_shape=(64,),
dtype=torch.float32,
)
print(estimate) # memory for scatter buffers
This estimates scatter buffer memory only — does not account for model
weights, optimizer state, or activation memory.
Where can I find examples?
TGraphX is hosted at github.com/arashsajjadi/tgraphx. The repository
includes examples in the examples/ directory. For questions, use GitHub
Issues. Given the library's Beta status and small community, issues are
the primary support channel.
Installation and Setup
Q: How do I install TGraphX?
pip install tgraphx
PyTorch is a dependency. Install a CUDA-enabled PyTorch first if you need GPU support. Check pyproject.toml for the exact version requirements.
Q: How do I check my TGraphX version?
import tgraphx
print(tgraphx.__version__) # e.g., '1.4.1'
Q: What Python and PyTorch versions are supported?
From pyproject.toml: Python >=3.10. Check the classifiers for PyTorch version compatibility. Pin both in your requirements.txt.
Q: How do I report a bug?
The package uses GitHub Issues. Check the repository at github.com/arashsajjadi/tgraphx (or the canonical URL from PyPI) and open an issue with your Python, PyTorch, and TGraphX versions.
Common Patterns
Q: How do I get the number of nodes from a Graph?
g.num_nodes # integer N
g.num_edges # integer E (from edge_index.shape[1])
Q: How do I check if a Graph is on GPU?
g.node_features.device # device info
g.is_cuda # convenience property
Q: How do I convert from PyG Data to TGraphX Graph?
from tgraphx import Graph
import torch
# PyG Data object
# data.x: [N, D], data.edge_index: [2, E], data.y: [N]
g = Graph(
node_features=data.x,
edge_index=data.edge_index,
node_labels=data.y,
)
Shape validation runs at construction. If shapes are inconsistent, you get a clear error immediately.
Q: How do I add edges to an existing graph?
Graph objects are immutable in the sense that you do not add edges in-place. Create a new Graph with the updated edge_index:
import torch
new_edges = torch.tensor([[0, 1], [1, 0]]) # shape [2, 2]
new_edge_index = torch.cat([g.edge_index, new_edges], dim=1)
g_updated = Graph(node_features=g.node_features, edge_index=new_edge_index)