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. 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 ### Related Skills - **molecular-docking**: Full end-to-end pipeline including target prep, pocket detection, AutoDock Vina, scoring, and interaction analysis. Use when you need the complete workflow, not just DiffDock. - **denovo-design**: For generating new molecules (not docking). Use diffdock afterwards to dock generated molecules. ## Running DiffDock on Modal (Recommended for openscience) Use Modal for on-demand GPU access without local GPU setup. ### Prerequisites ```bash # Verify Modal credentials (auto-injected by openscience) [ -n "$MODAL_TOKEN_ID" ] && echo "MODAL_TOKEN_ID set" || echo "NOT SET" [ -n "$MODAL_TOKEN_SECRET" ] && echo "MODAL_TOKEN_SECRET set" || echo "NOT SET" ``` If not set: authenticate the user-owned Modal CLI locally with `modal token set`. ### Modal DiffDock Wrapper ```python import modal app = modal.App("diffdock") diffdock_image = ( modal.Image.from_registry("rbgcsail/diffdock") .pip_install("rdkit-pypi", "pandas", "biopython") ) vol = modal.Volume.from_name("diffdock-results", create_if_missing=True) @app.function( image=diffdock_image, gpu="A10G", timeout=3600, volumes={"/results": vol}, ) def dock(protein_path: str, ligand_smiles: str, samples: int = 10): """Run DiffDock docking on Modal GPU.""" import subprocess cmd = [ "python", "-m", "inference", "--config", "default_inference_args.yaml", "--protein_path", protein_path, "--ligand", ligand_smiles, "--samples_per_complex", str(samples), "--out_dir", "/results/docking_output/", ] result = subprocess.run(cmd, capture_output=True, text=True) vol.commit() return {"stdout": result.stdout, "stderr": result.stderr, "returncode": result.returncode} @app.function( image=diffdock_image, gpu="A10G", timeout=7200, volumes={"/results": vol}, ) def batch_dock(csv_path: str, samples: int = 10): """Run DiffDock batch docking on Modal GPU.""" import subprocess cmd = [ "python", "-m", "inference", "--config", "default_inference_args.yaml", "--protein_ligand_csv", csv_path, "--samples_per_complex", str(samples), "--out_dir", "/results/batch_output/", ] result = subprocess.run(cmd, capture_output=True, text=True) vol.commit() return {"stdout": result.stdout, "stderr": result.stderr, "returncode": result.returncode} @app.local_entrypoint() def main(): result = dock.remote("protein.pdb", "CC(=O)Oc1ccccc1C(=O)O", samples=10) print(result) ``` ### GPU Selection | Scenario | GPU | VRAM | |----------|-----|------| | Single docking (1 pair) | T4 or A10G | 16-24 GB | | Batch docking (<50 complexes) | A10G | 24 GB | | Large virtual screening (>100) | A100 40GB | 40 GB | | Very large screening + embeddings | A100 80GB | 80 GB | ### Cost Estimate - Single docking: ~2-5 min on A10G = ~$0.04-0.09 - Batch of 50 compounds: ~30-60 min on A10G = ~$0.55-1.10 - Screen 1000 compounds: ~4-8 hrs on A100 = ~$13-27 **CRITICAL**: Present cost estimate to user before launching any GPU job. ## Local Installation and Environment Setup ### Check Environment Status Before proceeding with DiffDock tasks, verify the environment setup: ```bash # 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)** ```bash git clone https://github.com/gcorso/DiffDock.git cd DiffDock conda env create --file environment.yml conda activate diffdock ``` **Option 2: Docker** ```bash 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:** ```bash 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):** ```bash python -m inference \ --config default_inference_args.yaml \ --protein_sequence "MSKGEELFTGVVPILVELDGDVNGHKF..." \ --ligand ligand.sdf \ --out_dir results/sequence_docking/ ``` **Output Structure:** ``` results/single_docking/ ├── rank_1.sdf # Top-ranked pose ├── rank_2.sdf # Second-ranked pose ├── ... ├── rank_10.sdf # 10th pose (default: 10 samples) └── confidence_scores.txt ``` ### 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: ```bash # 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:** ```csv 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** ```bash 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: ```bash # 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: ```bash # 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:** 1. **Confidence ≠ Affinity**: High confidence means model certainty about structure, NOT strong binding 2. **Context Matters**: Adjust expectations for: - Large ligands (>500 Da): Lower confidence expected - Multiple protein chains: May decrease confidence - Novel protein families: May underperform 3. **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: ```bash # 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:** 1. High Accuracy: More samples + steps, lower temperature 2. Fast Screening: Fewer samples, faster 3. Flexible Ligands: Increased torsion temperature 4. 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: ```python # 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: ```bash python -m inference \ --config default_inference_args.yaml \ --protein_ligand_csv ensemble_input.csv \ --samples_per_complex 20 \ --out_dir results/ensemble/ ``` ### Integration with Scoring Functions DiffDock generates poses; combine with other tools for affinity: **GNINA (Fast neural network scoring):** ```bash 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:** 1. DiffDock → Generate poses with confidence scores 2. Visual inspection → Check structural plausibility 3. GNINA or MM/GBSA → Rescore and rank by affinity 4. 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)