alterlab-diffdock

DiffDock: Molecular Docking with Diffusion Models

Overview

DiffDock is a diffusion-based deep learning tool for molecular docking that predicts 3D binding poses of small molecule ligands to protein targets. The repository's default model is DiffDock-L (Feb 2024); it is widely used for blind docking, though co-folding models (Boltz-2, Chai-1) and physics-based rescoring are now common complements, and predicted poses should be checked for physical validity (e.g. with PoseBusters).

Core Capabilities:

Predict ligand binding poses with high accuracy using deep learning
Support protein structures (PDB files) or sequences (via ESMFold)
Process single complexes or batch virtual screening campaigns
Generate confidence scores to assess prediction reliability
Handle diverse ligand inputs (SMILES, SDF, MOL2)

Key Distinction: DiffDock predicts binding poses (3D structure) and confidence (prediction certainty), NOT binding affinity (ΔG, Kd). Always combine with scoring functions (GNINA, MM/GBSA) for affinity assessment.

When to Use This Skill

This skill should be used when:

"Dock this ligand to a protein" or "predict binding pose"
"Run molecular docking" or "perform protein-ligand docking"
"Virtual screening" or "screen compound library"
"Where does this molecule bind?" or "predict binding site"
Structure-based drug design or lead optimization tasks
Tasks involving PDB files + SMILES strings or ligand structures
Batch docking of multiple protein-ligand pairs

Does NOT Trigger

Scenario	Use Instead
Binding affinity / docking score on a cloud platform (AutoDock Vina)	`alterlab-rowan`
MD simulation of a complex, pose-stability / RMSD over a trajectory	`alterlab-molecular-dynamics`
Protein–protein or protein–nucleic-acid complex structure prediction	`alterlab-boltz` or `alterlab-chai`
Predicting the apo protein structure itself (no ligand)	`alterlab-alphafold`
Looking up measured protein–ligand affinities for the target	`alterlab-bindingdb`

Installation and Environment Setup

Check Environment Status

Before proceeding with DiffDock tasks, verify the environment setup:

# Use the provided setup checker
python scripts/setup_check.py

This script validates Python version, PyTorch with CUDA, PyTorch Geometric, RDKit, ESM, and other dependencies.

Installation Options

Option 1: Conda (Recommended)

git clone https://github.com/gcorso/DiffDock.git
cd DiffDock
conda env create --file environment.yml
conda activate diffdock

Option 2: Docker

docker pull rbgcsail/diffdock
docker run -it --gpus all --entrypoint /bin/bash rbgcsail/diffdock
micromamba activate diffdock

Important Notes:

GPU strongly recommended (10-100x speedup vs CPU)
First run pre-computes SO(2)/SO(3) lookup tables (~2-5 minutes)
Model checkpoints (~500MB) download automatically if not present

Core Workflows

Workflow 1: Single Protein-Ligand Docking

Use Case: Dock one ligand to one protein target

Input Requirements:

Protein: PDB file OR amino acid sequence
Ligand: SMILES string OR structure file (SDF/MOL2)

Command:

python -m inference \
  --config default_inference_args.yaml \
  --protein_path protein.pdb \
  --ligand "CC(=O)Oc1ccccc1C(=O)O" \
  --out_dir results/single_docking/

Alternative (protein sequence):

python -m inference \
  --config default_inference_args.yaml \
  --protein_sequence "MSKGEELFTGVVPILVELDGDVNGHKF..." \
  --ligand ligand.sdf \
  --out_dir results/sequence_docking/

Output Structure: DiffDock writes one subdirectory per complex (even for a single run), with the confidence embedded in each pose's filename:

results/single_docking/
└── complex_0/
    ├── rank1.sdf                   # Top pose (no score in name)
    ├── rank1_confidence-0.42.sdf   # Same pose, confidence in filename
    ├── rank2_confidence-1.10.sdf   # 2nd-ranked pose
    ├── ...
    └── rank10_confidence-3.05.sdf  # 10th pose (default: 10 samples)

There is no separate confidence_scores.txt; the confidence value is the confidenceN.NN suffix. Poses are ranked by descending confidence (rank1 = best).

Workflow 2: Batch Processing Multiple Complexes

Use Case: Dock multiple ligands to proteins, virtual screening campaigns

Step 1: Prepare Batch CSV

Use the provided script to create or validate batch input:

# Create template
python scripts/prepare_batch_csv.py --create --output batch_input.csv

# Validate existing CSV
python scripts/prepare_batch_csv.py my_input.csv --validate

CSV Format:

complex_name,protein_path,ligand_description,protein_sequence
complex1,protein1.pdb,CC(=O)Oc1ccccc1C(=O)O,
complex2,,COc1ccc(C#N)cc1,MSKGEELFT...
complex3,protein3.pdb,ligand3.sdf,

Required Columns:

complex_name: Unique identifier
protein_path: PDB file path (leave empty if using sequence)
ligand_description: SMILES string or ligand file path
protein_sequence: Amino acid sequence (leave empty if using PDB)

Step 2: Run Batch Docking

python -m inference \
  --config default_inference_args.yaml \
  --protein_ligand_csv batch_input.csv \
  --out_dir results/batch/ \
  --batch_size 10

For Large Virtual Screening (>100 compounds):

Put every protein–ligand pair in one CSV and run a single inference call. At start-up inference.py computes the ESM2 (esm2_t33_650M_UR50D) embeddings for all complexes in the CSV in one batched pass and reuses them for the confidence model — there is no separate pre-computation step and no --esm_embeddings_path flag for inference. (datasets/esm_embedding_preparation.py / esm_embeddings_to_pt.py exist only for the training/evaluation benchmarks.) Split very large libraries into several CSVs if GPU memory or run time is a concern.

Config gotcha: values in the --config YAML are applied after the CLI flags and override them. samples_per_complex, inference_steps, and the temp_* parameters are in default_inference_args.yaml, so passing e.g. --samples_per_complex 20 alongside --config default_inference_args.yaml has no effect — edit a copy of the YAML instead (--batch_size is not in the default YAML, so the CLI flag works).

Workflow 3: Analyzing Results

After docking completes, analyze confidence scores and rank predictions:

# Analyze all results
python scripts/analyze_results.py results/batch/

# Show top 5 per complex
python scripts/analyze_results.py results/batch/ --top 5

# Filter by confidence threshold
python scripts/analyze_results.py results/batch/ --threshold 0.0

# Export to CSV
python scripts/analyze_results.py results/batch/ --export summary.csv

# Show top 20 predictions across all complexes
python scripts/analyze_results.py results/batch/ --best 20

The analysis script:

Parses confidence scores from all predictions
Classifies as High (>0), Moderate (-1.5 to 0), or Low (<-1.5)
Ranks predictions within and across complexes
Generates statistical summaries
Exports results to CSV for downstream analysis

Confidence Score Interpretation

Understanding Scores:

Score Range	Confidence Level	Interpretation
> 0	High	Strong prediction, likely accurate
-1.5 to 0	Moderate	Reasonable prediction, validate carefully
< -1.5	Low	Uncertain prediction, requires validation

Critical Notes:

Confidence ≠ Affinity: High confidence means model certainty about structure, NOT strong binding
Context Matters: Adjust expectations for:
- Large ligands (>500 Da): Lower confidence expected
- Multiple protein chains: May decrease confidence
- Novel protein families: May underperform
Multiple Samples: Review top 3-5 predictions, look for consensus

For detailed guidance: Read references/confidence_and_limitations.md using the Read tool

Parameter Customization

Using Custom Configuration

Create custom configuration for specific use cases:

# Copy template
cp assets/custom_inference_config.yaml my_config.yaml

# Edit parameters (see template for presets)
# Then run with custom config
python -m inference \
  --config my_config.yaml \
  --protein_ligand_csv input.csv \
  --out_dir results/

Key Parameters to Adjust

Sampling Density:

samples_per_complex: 10 → Increase to 20-40 for difficult cases
More samples = better coverage but longer runtime

Inference Steps:

inference_steps: 20 → Increase to 25-30 for higher accuracy
More steps = potentially better quality but slower

Temperature Parameters (control diversity):

temp_sampling_tor: 7.04 → Increase for flexible ligands (8-10)
temp_sampling_tor: 7.04 → Decrease for rigid ligands (5-6)
Higher temperature = more diverse poses

Presets Available in Template:

High Accuracy: More samples + steps, lower temperature
Fast Screening: Fewer samples, faster
Flexible Ligands: Increased torsion temperature
Rigid Ligands: Decreased torsion temperature

For complete parameter reference: Read references/parameters_reference.md using the Read tool

Advanced Techniques

Ensemble Docking (Protein Flexibility)

For proteins with known flexibility, dock to multiple conformations:

# Create ensemble CSV
import pandas as pd

conformations = ["conf1.pdb", "conf2.pdb", "conf3.pdb"]
ligand = "CC(=O)Oc1ccccc1C(=O)O"

data = {
    "complex_name": [f"ensemble_{i}" for i in range(len(conformations))],
    "protein_path": conformations,
    "ligand_description": [ligand] * len(conformations),
    "protein_sequence": [""] * len(conformations)
}

pd.DataFrame(data).to_csv("ensemble_input.csv", index=False)

Run docking with increased sampling (set samples_per_complex: 20 in a copy of the YAML — a --samples_per_complex flag would be overwritten by the default config):

cp default_inference_args.yaml ensemble_args.yaml   # edit: samples_per_complex: 20
python -m inference \
  --config ensemble_args.yaml \
  --protein_ligand_csv ensemble_input.csv \
  --out_dir results/ensemble/

Integration with Scoring Functions

DiffDock generates poses; combine with other tools for affinity:

GNINA (Fast neural network scoring):

for pose in results/*.sdf; do
    gnina -r protein.pdb -l "$pose" --score_only
done

MM/GBSA (More accurate, slower): Use AmberTools MMPBSA.py or gmx_MMPBSA after energy minimization

Free Energy Calculations (Most accurate): Use OpenMM + OpenFE or GROMACS for FEP/TI calculations

Recommended Workflow:

DiffDock → Generate poses with confidence scores
Visual inspection → Check structural plausibility
GNINA or MM/GBSA → Rescore and rank by affinity
Experimental validation → Biochemical assays

Limitations and Scope

DiffDock IS Designed For:

Small molecule ligands (typically 100-1000 Da)
Drug-like organic compounds
Small peptides (<20 residues)
Single or multi-chain proteins

DiffDock IS NOT Designed For:

Large biomolecules (protein-protein docking) → Use DiffDock-PP or AlphaFold-Multimer
Large peptides (>20 residues) → Use alternative methods
Covalent docking → Use specialized covalent docking tools
Binding affinity prediction → Combine with scoring functions
Membrane proteins → Not specifically trained, use with caution

For complete limitations: Read references/confidence_and_limitations.md using the Read tool

Troubleshooting

Common Issues

Issue: Low confidence scores across all predictions

Cause: Large/unusual ligands, unclear binding site, protein flexibility
Solution: Increase samples_per_complex (20-40), try ensemble docking, validate protein structure

Issue: Out of memory errors

Cause: GPU memory insufficient for batch size
Solution: Reduce --batch_size 2 or process fewer complexes at once

Issue: Slow performance

Cause: Running on CPU instead of GPU
Solution: Verify CUDA with python -c "import torch; print(torch.cuda.is_available())", use GPU

Issue: Unrealistic binding poses

Cause: Poor protein preparation, ligand too large, wrong binding site
Solution: Check protein for missing residues, remove far waters, consider specifying binding site

Issue: "Module not found" errors

Cause: Missing dependencies or wrong environment
Solution: Run python scripts/setup_check.py to diagnose

Performance Optimization

For Best Results:

Use GPU (essential for practical use)
Pre-compute ESM embeddings for repeated protein use
Batch process multiple complexes together
Start with default parameters, then tune if needed
Validate protein structures (resolve missing residues)
Use canonical SMILES for ligands

Graphical User Interface

For interactive use, launch the web interface:

python app/main.py
# Navigate to http://localhost:7860

Or try the online demo (https://huggingface.co/spaces/reginabarzilaygroup/DiffDock-Web), though the Space is often down — prefer a local or Docker install for reliable runs.

Resources

Helper Scripts (`scripts/`)

prepare_batch_csv.py: Create and validate batch input CSV files

Create templates with example entries
Validate file paths and SMILES strings
Check for required columns and format issues

analyze_results.py: Analyze confidence scores and rank predictions

Parse results from single or batch runs
Generate statistical summaries
Export to CSV for downstream analysis
Identify top predictions across complexes

setup_check.py: Verify DiffDock environment setup

Check Python version and dependencies
Verify PyTorch and CUDA availability
Test RDKit and PyTorch Geometric installation
Provide installation instructions if needed

Reference Documentation (`references/`)

parameters_reference.md: Complete parameter documentation

All command-line options and configuration parameters
Default values and acceptable ranges
Temperature parameters for controlling diversity
Model checkpoint locations and version flags

Read this file when users need:

Detailed parameter explanations
Fine-tuning guidance for specific systems
Alternative sampling strategies

confidence_and_limitations.md: Confidence score interpretation and tool limitations

Detailed confidence score interpretation
When to trust predictions
Scope and limitations of DiffDock
Integration with complementary tools
Troubleshooting prediction quality

Read this file when users need:

Help interpreting confidence scores
Understanding when NOT to use DiffDock
Guidance on combining with other tools
Validation strategies

workflows_examples.md: Comprehensive workflow examples

Detailed installation instructions
Step-by-step examples for all workflows
Advanced integration patterns
Troubleshooting common issues
Best practices and optimization tips

Read this file when users need:

Complete workflow examples with code
Integration with GNINA, OpenMM, or other tools
Virtual screening workflows
Ensemble docking procedures

Assets (`assets/`)

batch_template.csv: Template for batch processing

Pre-formatted CSV with required columns
Example entries showing different input types
Ready to customize with actual data

custom_inference_config.yaml: Configuration template

Annotated YAML with all parameters
Four preset configurations for common use cases
Detailed comments explaining each parameter
Ready to customize and use

Best Practices

Always verify environment with setup_check.py before starting large jobs
Validate batch CSVs with prepare_batch_csv.py to catch errors early
Start with defaults then tune parameters based on system-specific needs
Generate multiple samples (10-40) for robust predictions
Visual inspection of top poses before downstream analysis
Combine with scoring functions for affinity assessment
Use confidence scores for initial ranking, not final decisions
Pre-compute embeddings for virtual screening campaigns
Document parameters used for reproducibility
Validate results experimentally when possible

Citations

When using DiffDock, cite the appropriate papers:

DiffDock-L (current default model):

Corso et al. (2024) "Deep Confident Steps to New Pockets: Strategies for Docking Generalization"
ICLR 2024, arXiv:2402.18396

Original DiffDock:

Corso et al. (2023) "DiffDock: Diffusion Steps, Twists, and Turns for Molecular Docking"
ICLR 2023, arXiv:2210.01776

Additional Resources

GitHub Repository: https://github.com/gcorso/DiffDock
Online Demo: https://huggingface.co/spaces/reginabarzilaygroup/DiffDock-Web
DiffDock-L Paper: https://arxiv.org/abs/2402.18396
Original Paper: https://arxiv.org/abs/2210.01776

Part of the AlterLab Academic Skills suite.

About this skill

Overview

When to Use This Skill

Does NOT Trigger

Installation and Environment Setup

Check Environment Status

Installation Options

Core Workflows

Workflow 1: Single Protein-Ligand Docking

Workflow 2: Batch Processing Multiple Complexes

Workflow 3: Analyzing Results

Confidence Score Interpretation

Parameter Customization

Using Custom Configuration

Key Parameters to Adjust

Advanced Techniques

Ensemble Docking (Protein Flexibility)

Integration with Scoring Functions

Limitations and Scope

Troubleshooting

Common Issues

Performance Optimization

Graphical User Interface

Resources

Helper Scripts (scripts/)

Reference Documentation (references/)

Assets (assets/)

Best Practices

Citations

Additional Resources

Helper Scripts (`scripts/`)

Reference Documentation (`references/`)

Assets (`assets/`)