/diffdock

name: diffdock
description: DiffDock and DiffDock-L molecular docking. Use for protein-small-molecule pose prediction from PDB or sequence plus SMILES/SDF/MOL2, batch docking, virtual screening, and pose-confidence interpretation. Not for binding affinity prediction.
allowed-tools: Read Write Edit Bash Glob Grep
compatibility: Requires the DiffDock repository, Python 3.9 environment from upstream environment.yml or the official Docker image, RDKit, PyTorch/PyG, and optional CUDA GPU acceleration. Current guidance targets DiffDock v1.1.3 / DiffDock-L.
license: MIT license
metadata:
  version: "1.3"
  skill-author: K-Dense Inc.

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. It represents the state-of-the-art in computational docking, crucial for structure-based drug discovery and chemical biology.

**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

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
• Current upstream release is DiffDock v1.1.3; DiffDock-L is the default model line in `default_inference_args.yaml`

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_description "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_description ligand.sdf \
  --out_dir results/sequence_docking/

**Output Structure:**

results/single_docking/
└── complex_0/
    ├── rank1.sdf                    # Convenience copy of top-ranked pose
    ├── rank1_confidence0.87.sdf     # Top-ranked pose with confidence in filename
    ├── rank2_confidence0.42.sdf     # Second-ranked pose
    ├── ...
    └── rank10_confidence-1.23.sdf   # 10th pose (default: 10 samples)

Current `inference.py` registers `--ligand_description` for single-complex runs. Some upstream README text still says `--ligand`; use `--ligand_description` unless your local checkout explicitly supports a `--ligand` alias.

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):**

Pre-compute protein embeddings for faster processing:

# Pre-compute embeddings
python datasets/esm_embedding_preparation.py \
  --protein_ligand_csv screening_input.csv \
  --out_file protein_embeddings.pt

# Run with pre-computed embeddings
python -m inference \
  --config default_inference_args.yaml \
  --protein_ligand_csv screening_input.csv \
  --esm_embeddings_path protein_embeddings.pt \
  --out_dir results/screening/

Workflow 3: Analyzing Results

After docking completes, analyze confidence scores and rank predictions:

# Analyze all result