---

name: pytorch-geometric description: "Use PyTorch Geometric to build graph data, loaders, GNN models, heterogeneous workflows, explainers, scalable/distributed jobs, and GraphGym experiments." disable-model-invocation: true metadata: disco-role: operating license: MIT

PyTorch Geometric

Use this repo skill when a task involves PyTorch Geometric (PyG), the torch_geometric Python package, graph neural networks, graph data containers, mini-batch/neighbor loaders, heterogeneous graphs, explainability, distributed graph learning, or GraphGym experiment configs.

First Checks

• Read repo provenance before deciding whether this skill matches a local PyG checkout or should be refreshed.
• Read install and optional dependencies when setting up PyG, choosing CPU/GPU wheels, or deciding which extras/extensions are needed.
• Read cross-cutting troubleshooting for import failures, missing torch, optional extension issues, dataset downloads, CUDA/backend mismatches, or stale generated skill concerns.
• Run check_pyg_environment.py for a safe import/backend diagnostic that does not download data, allocate GPUs by default, or write files.

Minimal Install Pattern

PyG imports torch, so install a compatible PyTorch build first, then install PyG:

python -m pip install torch
python -m pip install torch-geometric
python - <<'PY'
import torch
import torch_geometric
print(torch.__version__)
print(torch_geometric.__version__)
PY

For CUDA, ROCm, Apple Silicon, or extension-heavy sampling workflows, choose the PyTorch wheel and optional PyG extension wheels that match the target backend. Do not mix CPU PyTorch with CUDA-only extension wheels.

Route by Task

• Use data-and-datasets for Data, HeteroData, Batch, custom Dataset/InMemoryDataset, transforms, dataset splitting, and local graph validation.
• Use loaders-and-sampling for DataLoader, NeighborLoader, LinkNeighborLoader, mini-batching, sampler parameters, temporal/link sampling, and optional sampler backend errors.
• Use gnn-modeling for MessagePassing, common convolution layers, pooling, metrics, training loops, torch.compile, TorchScript/JIT, and tiny model smoke tests.
• Use heterogeneous-graphs for typed graph metadata, HeteroData, HeteroConv, to_hetero, hetero loaders, bipartite relations, and hetero link prediction.
• Use explainability for Explainer, GNNExplainer, masks, thresholds, explanation metrics, and model-config recovery.
• Use scalable-distributed for large-graph scaling, remote FeatureStore/GraphStore, distributed PyG, multi-GPU/multi-node planning, CPU affinity, profiling, and backend diagnostics.
• Use graphgym-experiments for GraphGym YAML configs, custom registry hooks, run-single/run-batch concepts, and safe config validation.

Shared Decision Rules

• Prefer tiny synthetic Data or HeteroData fixtures for smoke checks before running dataset-download or benchmark examples.
• Validate graph tensors early: edge_index is torch.long with shape [2, num_edges], node features align with num_nodes, masks index the right supervision target, and hetero edge types are (src, relation, dst) triplets.
• Treat optional packages as workflow-specific: pyg-lib, torch-sparse, torch-scatter, and related extension wheels are often needed for fast sampling or sparse operations, while GraphGym and RAG workflows need their own extras.
• Keep training, explainability, GraphGym, distributed, and multi-GPU runs small unless the user explicitly accepts downloads, long runtime, result writes, credentials, or hardware use.
• When a task spans routes, start with the data/schema owner, then move to loaders/modeling/explainability/scaling as needed.

Safe Shared Command

python scripts/check_pyg_environment.py --json

Use --require-torch, --require-pyg, or --require-neighbor-backend when the user needs a hard pass/fail diagnostic for a specific workflow.