torchdrug
Build and troubleshoot TorchDrug 0.2.1 workflows for molecular graphs, property prediction, self-supervised pretraining, molecule generation, retrosynthesis, protein representation learning, and knowledge graph reasoning. Use when code imports torchdrug or needs its datasets, models, tasks, or Engine.
Install this skill
Works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, and 70+ other harnesses.
npx skills add KalarisLabs/research-agent-skills --skill torchdruguvx research-agent-skills install torchdrugDocumentation & Instructions
TorchDrug
Use TorchDrug as a modular PyTorch graph-learning stack:
- load a
datasets.*dataset, - choose a
models.*representation model, - wrap it in a
tasks.*objective, - train and evaluate it with
core.Engine.
The current official documentation and latest release are both 0.2.1. Treat newer Python or PyTorch combinations as unverified rather than silently assuming compatibility.
Start with the version guard
Before generating or debugging code, inspect the environment:
python --version
python -c "import torch; print(torch.__version__)"
python -c "import torchdrug; print(torchdrug.__version__)"
The supported matrix for TorchDrug 0.2.1 is:
- Python 3.7 through 3.10
- PyTorch 1.8 through 2.0
- Linux, Windows, or macOS
- Apple Silicon: PyTorch 1.13 or later, CPU only; no MPS support
If the project uses Python 3.11+ or PyTorch 2.1+, create a compatible environment or explicitly test a source build. Do not present such combinations as supported.
Installation
Prefer a dedicated Python 3.10 environment and pin the TorchDrug release:
uv venv --python 3.10
source .venv/bin/activate
uv pip install "torch==2.0.0"
Install torch-scatter and torch-cluster wheels matched to the exact PyTorch
and CUDA pair, following the
official installation page. For a
CPU-only PyTorch 2.0 environment, one reproducible wheel combination is:
uv pip install "torch-scatter==2.1.1" "torch-cluster==1.6.1" \
--find-links "https://data.pyg.org/whl/torch-2.0.0+cpu.html"
uv pip install "torchdrug==0.2.1"
Do not copy a CUDA wheel URL between environments. Match the PyTorch version,
CUDA build, Python ABI, and platform. On Apple Silicon, the official docs require
building torch-scatter and torch-cluster from source; pin reviewed source
revisions and expect CPU execution.
Canonical property-prediction workflow
Use the documented ClinTox → GIN → PropertyPrediction → Engine pattern:
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)
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")
Add gpus=[0] only when a supported CUDA device is available. Omit gpus for
CPU execution.
For binary classification, task.predict(batch) returns logits; apply
torch.sigmoid when probabilities are needed. In 0.2.1, normalized regression
predictions are returned on the original target scale, which is a breaking change
from older releases.
Choose the official workflow
Molecular property prediction
- Dataset:
datasets.ClinTox,BBBP,Tox21,QM9, or another documented molecule dataset. - Model: start with
models.GIN; useedge_input_dimwhen the selected feature configuration supplies edge features. - Task:
tasks.PropertyPrediction. - Read molecular property prediction.
Self-supervised molecular pretraining
- InfoGraph:
models.InfoGraph(gin_model, separate_model=False)wrapped bytasks.Unsupervised. - Attribute masking:
tasks.AttributeMasking(model, mask_rate=0.15). - Recreate the same encoder for fine-tuning, then load the checkpoint with
strict=Falsebefore trainingtasks.PropertyPrediction. - Read molecular property prediction.
Molecule generation
- Dataset:
datasets.ZINC250k(..., kekulize=True, atom_feature="symbol"). - GCPN: an
models.RGCNencoder wrapped bytasks.GCPNGeneration. - GraphAF: node and edge
models.GraphAFflows wrapped bytasks.AutoregressiveGeneration. - Supported optimization tasks in the tutorial are
"qed"and"plogp"; criteria are"nll"and/or"ppo". - Read molecular generation.
Retrosynthesis
- Create two synchronized
datasets.USPTO50kviews: reaction mode for center identification andas_synthon=Truefor synthon completion. - Train
tasks.CenterIdentificationandtasks.SynthonCompletionseparately. - Combine the trained tasks with
tasks.Retrosynthesis; do not pass raw models directly to the end-to-end task. - Read retrosynthesis.
Knowledge graph reasoning
- Embedding workflow:
datasets.FB15k237→models.RotatE→tasks.KnowledgeGraphCompletion. - Neural reasoning workflow:
models.NeuralLPwithfact_ratio=0.75. - Read knowledge graph reasoning.
Protein modeling
- Build proteins with
data.Protein.from_sequence,from_pdb, orfrom_molecule. - Sequence encoders include
models.ESM,ProteinCNN,ProteinResNet,ProteinLSTM, andProteinBERT; structure encoders includemodels.GearNet. - Use documented graph-construction layers rather than a nonexistent
protein.residue_graph()convenience method. - Read protein modeling.
Rules for reliable TorchDrug code
- Follow the 0.2.1 API. The official docs are not a rolling latest-version site.
- Prefer documented feature names. Use
atom_feature,bond_feature,residue_feature, andmol_feature;node_feature,edge_feature, andgraph_featureare deprecated aliases in relevant dataset constructors. - Let
Enginepreprocess tasks. If composing pre-trained tasks without constructing their solvers, call each task'spreprocess()manually. - Keep paired splits synchronized. For retrosynthesis, reset the same random seed before splitting reaction and synthon datasets.
- Use TorchDrug collation. Use
data.graph_collateorcore.Engine; generic PyTorch collation does not know how to pack TorchDrug graphs. - Separate model, task, and engine arguments. A common source of invented code is passing task options to a model or passing raw models where a composed task is required.
- Validate generated chemistry. Treat model outputs as candidates, not as experimentally valid or synthesizable compounds.
Troubleshooting
Installation or import failure
Check Python, PyTorch, torch-scatter, and torch-cluster as one compatibility
set. Most failures are binary-wheel mismatches, unsupported Python versions, or
attempts to use MPS.
Feature dimension mismatch
Build model dimensions from the loaded dataset:
dataset.node_feature_dimdataset.edge_feature_dimdataset.num_bond_typedataset.num_entityanddataset.num_relationfor knowledge graphs
Do not hard-code dimensions copied from a different feature configuration.
Device mismatch
Pass gpus=[0] to core.Engine for supported CUDA execution. For manual
prediction, collate first and move the entire nested batch with utils.cuda.
Checkpoint mismatch
Recreate the same model and feature configuration. For pretraining-to-fine-tuning
transfer, load the checkpoint's "model" state with strict=False; for a complete
solver, use solver.save() and solver.load().
Reference index
- Core concepts and data structures
- Datasets
- Models and architectures
- Molecular property prediction and pretraining
- Protein modeling
- Molecular generation
- Retrosynthesis
- Knowledge graph reasoning
Upstream sources
- TorchDrug 0.2.1 documentation
- Tutorial index
- Installation
- Package reference
- TorchDrug 0.2.1 release notes
Agent operating procedure
- Check the environment. Confirm toolkit versions and input formats (SMILES, SDF, PDB, CIF), and sanitize molecules before computing.
- Pin down the inputs. Confirm formats, identifiers and parameters from the data or the user. Ask rather than guess any value that changes the result.
- Run a small version first. Process a few molecules or one target first and inspect the outputs.
- Execute the full task using the instructions and references above.
- Validate the result. Check for invalid structures, unit consistency, and applicability domain of predictive models.
- Report. State what was run (versions, commands, parameters), what was checked, and what is still uncertain.
| If this happens | Do this |
|---|---|
| Molecules fail to parse or sanitize | Report and skip them with reasons; never silently drop or alter structures. |
| A function, flag or endpoint in these instructions is missing in the installed version | Check the installed version's own documentation (help(), --help, official docs), adapt, and tell the user. Never invent an API. |
| A required input, identifier or parameter is ambiguous | Ask the user, or state the assumption explicitly before running. |
Integrity rules
- Never fabricate results, parameters, identifiers, citations or statistics. If something cannot be run or verified, say so plainly.
- Computational predictions are hypotheses, not experimental results; label them as such.
- Treat version-specific details here as possibly outdated: confirm them against the official documentation for the installed version.
- Ask before actions that cost money, consume shared GPUs or cloud quota, touch personal or patient data, or cannot be undone.
Related skills
deepchem: Molecular ML with diverse featurizers and pre-built datasets.neurokit2: Use NeuroKit2 to build or audit reproducible research workflows for physiological time-series preprocessing, event/interval analysis, multi…rowan: Rowan is a cloud-native molecular modeling and medicinal-chemistry workflow platform with a Python API.
Trigger Prompts & Evaluation Corpus
These evaluation prompts test that the agent correctly selects torchdrug for relevant tasks and leaves it out for near misses.
Should trigger (3)
- should trigger
“How do I fine-tune a GIN on BBBP with torchdrug?”
expects Gives the documented 0.2.1 workflow: datasets.BBBP, models.GIN built from dataset.node_feature_dim, wrapped in tasks.PropertyPrediction, trained with core.Engine (gpus=[0] only if CUDA is available). Mentions a split and a metric, and that predict() returns logits for binary tasks.
- should trigger
“I'm on Python 3.11 with torch 2.2 and `import torchdrug` fails with an error about torch_scatter (undefined symbol / no module named torch_scatter). My script train_clintox.py uses datasets.ClinTox, models.GIN and core.Engine. How do I fix it?”
expects Runs the version guard and says Python 3.11 and PyTorch 2.2 are outside the supported matrix for TorchDrug 0.2.1 (Python 3.7-3.10, PyTorch 1.8-2.0). Recommends a Python 3.10 environment with pinned torchdrug==0.2.1 and torch-scatter/torch-cluster wheels matched to the exact PyTorch/CUDA pair, and does not invent a workaround or claim 3.11 is supported.
- should trigger
“I have a set of ~50k USPTO reaction records and want to train a model that proposes the precursor molecules for a target product, then evaluate top-k accuracy. What pipeline should I set up?”
expects Describes the two-stage retrosynthesis setup: two synchronized USPTO50k views (reaction mode for center identification, as_synthon=True for synthon completion) split with the same random seed. Trains tasks.CenterIdentification and tasks.SynthonCompletion separately, then combines them in tasks.Retrosynthesis (not raw models), calling preprocess() if no solver was built. Notes that outputs are candidates needing chemical validation.
Near misses (2)
- near miss
“I want to predict Tox21 toxicity endpoints with a random forest on Morgan fingerprints and compare against MoleculeNet benchmark splits. Which featurizers should I use?”
expects Recognizes this as a classical-ML featurizer and MoleculeNet benchmarking task better handled by the deepchem skill. It does not use TorchDrug's Engine or GNN workflow.
- near miss
“Write a script that computes heart rate variability metrics from an ECG recording and plots the R-peaks.”
expects Recognizes this as physiological signal processing unrelated to molecular graph learning. It should use the neurokit2 skill rather than TorchDrug.