PyTorch Geometric (PyG)

PyG é a biblioteca padrão para Redes Neurais de Grafos construída sobre PyTorch. Ela fornece estruturas de dados para grafos, mais de 60 implementações de camadas GNN, treinamento escalável com mini-batches e suporte para grafos heterogêneos.

Instalação

Revisado o lançamento torch-geometric 2.8.0.post1 (01/10/2026); exemplos de CPU testados com Python 3.13 / PyTorch 2.14.1. A documentação em andamento latest identifica 2.9.0; verifique a versão instalada antes de adotar novas APIs. PyG 2.8 requer PyTorch 2.9+; sua tabela de lançamento original cobre 2.9–2.12. Nossos testes principais com 2.14.1 não estabelecem todas as combinações de extensões/backends.

# Install the PyTorch build for your platform from https://pytorch.org/get-started/locally/
uv pip install torch==2.14.1
uv pip install torch-geometric==2.8.0.post1
python -c "import torch, torch_geometric; print(torch.__version__, torch.version.cuda, torch_geometric.__version__)"

Camadas básicas baseadas em tensores não precisam de extensões. Amostragem de vizinhos requer pyg-lib ou torch-sparse; operadores espaciais k-NN requerem pyg-lib em 2.8. torch-cluster e torch-spline-conv foram descontinuados e ignorados. Inspecione o índice de wheels para sua combinação exata de Python/OS/Torch/CUDA. Nunca instale wheels para uma versão diferente do Torch apenas porque as importações principais funcionam. A extensão de CPU macOS ARM testada está abaixo; escolha um wheel correspondente diferente para outras plataformas e verifique seus operadores:

uv pip install --only-binary=:all: "pyg-lib==0.9.0+pt214" \
  -f https://data.pyg.org/whl/torch-2.14.0+cpu.html

Pacotes Conda não são mais fornecidos para Torch >2.5. Veja instalação e mudanças no lançamento 2.8. Exemplos opcionais de amostragem/GPU/distribuídos/download abaixo são ilustrativos, a menos que cobertos pelas verificações de CPU nas notas de revisão.

Conceitos Principais

Dados de Grafo: Data e HeteroData

Um grafo vive em um objeto Data. Os atributos chave:

from torch_geometric.data import Data

data = Data(
    x=node_features,          # [num_nodes, num_node_features]
    edge_index=edge_index,     # [2, num_edges] — COO format, dtype=torch.long
    edge_attr=edge_features,   # [num_edges, num_edge_features]
    y=labels,                  # node-level [num_nodes, *] or graph-level [1, *]
    pos=positions,             # [num_nodes, num_dimensions] (for point clouds/spatial)
)

O formato edge_index é crítico: é um tensor [2, num_edges] onde edge_index[0] = nós de origem, edge_index[1] = nós de destino. NÃO é uma lista de tuplas. Se você tem pares de arestas como linhas, transponha e chame .contiguous():

# If edges are [[src1, dst1], [src2, dst2], ...] — transpose first:
edge_index = edge_pairs.t().contiguous()

Para grafos não direcionados, inclua ambas as direções: a aresta (0,1) precisa de [0,1] e [1,0] em edge_index.

Se as features dos nós estiverem ausentes, defina data.num_nodes explicitamente a partir da tabela de nós. Inferi-lo de edge_index.max() + 1 perde nós isolados, o que pode corromper os offsets de batching e os resultados. Verifique data.validate(raise_on_error=True) após a construção, incluindo um caso sem arestas ou com nós isolados.

Para grafos heterogêneos, use HeteroData — veja a seção Grafos Heterogêneos abaixo.

Datasets

PyG agrupa muitos datasets padrão que fazem download e pré-processamento automáticos:

from torch_geometric.datasets import Planetoid, TUDataset

# Single-graph node classification (Cora, Citeseer, Pubmed)
dataset = Planetoid(root='./data/Cora', name='Cora', split='public')
data = dataset[0]  # single graph with train/val/test masks

# Multi-graph classification (ENZYMES, MUTAG, IMDB-BINARY, etc.)
dataset = TUDataset(root='./data/TU', name='ENZYMES')
# dataset[0], dataset[1], ... are individual graphs

Datasets comuns por tarefa:

• Classificação de nós: Planetoid (Cora/Citeseer/Pubmed), OGB (ogbn-arxiv, ogbn-products, ogbn-mag)
• Classificação de grafos: TUDataset (MUTAG, ENZYMES, PROTEINS, IMDB-BINARY), OGB (ogbg-molhiv)
• Previsão de links: OGB (ogbl-collab, ogbl-citation2)
• Molecular: QM7b, QM9, MoleculeNet
• Nuvem de pontos/malha: ShapeNet, ModelNet(name="10" ou "40"), FAUST (download manual)

…