TorchDrug

Use TorchDrug como uma pilha modular de aprendizado em grafos com PyTorch:

1. carregue um conjunto de datasets.*,
2. escolha um modelo de representação models.*,
3. envolva-o em um objetivo tasks.*,
4. treine e avalie-o com core.Engine.

A documentação oficial atual e a versão publicada mais recente são ambas 0.2.1 (lançada em julho de 2023; verificada novamente em 1º de outubro de 2026). Trate combinações mais novas de Python ou PyTorch como não verificadas em vez de assumir silenciosamente compatibilidade.

Comece com o controle de versão

Antes de gerar ou depurar código, inspecione o ambiente:

python --version
python -c "import torch; print(torch.__version__)"
python -c "import torchdrug; print(torchdrug.__version__)"

A matriz suportada para TorchDrug 0.2.1 é:

• Python 3.7 a 3.10
• PyTorch 1.8 a 2.0
• Linux, Windows ou macOS
• Apple Silicon: PyTorch 1.13 ou posterior, apenas CPU; sem suporte a MPS

Se o projeto usar Python 3.11+ ou PyTorch 2.1+, crie um ambiente compatível ou teste explicitamente uma compilação a partir do código-fonte. Não apresente tais combinações como suportadas.

Instalação

Prefira um ambiente dedicado de Python 3.10 e fixe a versão do TorchDrug:

uv venv --python 3.10
source .venv/bin/activate
uv pip install "torch==2.0.0" "numpy==1.26.4" "setuptools<81" wheel

Instale os pacis torch-scatter e torch-cluster compatíveis com o par exato de PyTorch e CUDA, seguindo a página oficial de instalação. Para um ambiente PyTorch 2.0 apenas com CPU em uma plataforma listada nesse índice de pacis, use:

uv pip install --only-binary :all: "torch-scatter==2.1.2" "torch-cluster==1.6.3" \
  --find-links "https://data.pyg.org/whl/torch-2.0.0+cpu.html"
uv pip install "torchdrug==0.2.1" "numpy==1.26.4" "scipy==1.13.1" \
  "rdkit-pypi==2022.9.5" "fair-esm==2.0.0" "decorator==5.1.1"

Não copie um URL de paci CUDA entre ambientes. Corresponda a versão do PyTorch, a compilação CUDA, a ABI do Python e a plataforma. Em Apple Silicon, a documentação oficial exige a compilação de torch-scatter e torch-cluster a partir do código-fonte; o índice de pacis acima não possui pacis para macOS ARM64. Instale o PyTorch antes de compilar com --no-build-isolation. Um compilador/SDK funcional também é necessário; ter o PyTorch instalado sozinho não garante uma compilação nativa bem-sucedida. Veja revisão e evidências do ambiente para a pilha de auditoria exata. Use a distribuição fair-esm, que importa como esm; a distribuição mais nova nomeada esm é um SDK diferente. Não instale ambas as distribuições RDKit (rdkit e rdkit-pypi) em um único ambiente. NumPy 1.x evita a incompatibilidade da ABI do NumPy 2 da antiga pilha binária; setuptools<81 retém pkg_resources para PyTorch 2.0.

Fluxo de trabalho canônico de predição de propriedades

Use o padrão documentado ClinTox → GIN → PropertyPrediction → Engine. A divisão aleatória abaixo é uma linha de base para tutorial. Para generalização para novos esqueletos moleculares, use data.scaffold_split ou a divisão especificada no benchmark, mantenha moléculas duplicadas em uma partição e registre os tamanhos reais da divisão e as contagens de classes. A alocação por grupo de esqueletos pode não corresponder exatamente aos comprimentos solicitados.

Primeiro, execute a preparação do cache ClinTox. A URL de download HTTP antiga da versão falha; o ativo HTTPS oficial atual possui o mesmo MD5 da versão. Os exemplos de treinamento completos são ilustrativos e não foram executados até a convergência durante esta revisão.

import torch
from torchdrug import core, datasets, models, tasks

dataset = datasets.ClinTox("~/molecule-datasets/")
lengths = [int(0.8 * len(dataset)), int(0.1 * len(dataset))]
lengths.append(len(dataset) - sum(lengths))
train_set, valid_set, test_set = torch.utils.data.random_split(
    dataset, lengths, generator=torch.Generator().manual_seed(1)
)

model = models.GIN(
    input_dim=dataset.node_feature_dim,
    hidden_dims=[256, 256, 256, 256],
    short_cut=True,
    batch_norm=True,
    concat_hidden=True,
)
task = tasks.PropertyPrediction(
    model,
    task=dataset.tasks,
    criterion="bce",
    metric=("auprc", "auroc"),
)

optimizer = torch.optim.Adam(task.parameters(), lr=1e-3)
solver = core.Engine(
    task,
    train_set,
    valid_set,
    test_set,
    optimizer,
    batch_size=1024,
)
solver.train(num_epoch=100)
solver.evaluate("valid")

Adicione gpus=[0] apenas quando um dispositivo CUDA suportado estiver disponível. Omita gpus para execução em CPU.

Para classificação binária, task.predict(batch) retorna logits; aplique

…