GPTomics/chemoinformatics/ml-docking-rescoring

Version Compatibility

Reference examples tested with: DiffDock-L (Corso 2024), Boltz-1 1.0+, Boltz-2 (Wohlwend 2025), Chai-1 0.4+, AlphaFold3 (DeepMind), EquiBind, TANKBind, GNINA 1.1+, PoseBusters 0.6+.

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show <package> then help(module.function) to check signatures
• CLI: diffdock --version; boltz --version

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

ML Docking and Rescoring

Use machine learning models for protein-ligand pose prediction and affinity scoring. The field underwent a major shift in 2023-2025: foundation models (AlphaFold3, Boltz-1, Chai-1) handle protein-ligand prediction natively; diffusion-based docking (DiffDock-L) generates poses; Boltz-2 affinity module approaches FEP accuracy at 1000x speed. Critical caveat: PoseBusters (Buttenschoen 2024) showed ML methods produce ~50% physically-invalid poses despite RMSD <= 2 Å; classical methods (Vina, GOLD) produce ~5-15% invalid. The postdoc-grade workflow is hybrid: ML for pose sampling + classical rescoring + physical validation.

For classical docking, see chemoinformatics/virtual-screening. For pose validation (PoseBusters), see chemoinformatics/pose-validation. For free-energy calculations (post-docking), see chemoinformatics/free-energy-calculations. For PROTAC ternary complex prediction, see chemoinformatics/protac-degraders.

ML Docking Method Taxonomy

| Tool | Approach | Speed | Strength | Fails when | |------|----------|-------|----------|------------| | DiffDock-L (Corso 2024) | Equivariant diffusion | 5s/lig GPU | Pose sampling for cross-dock | ~50% PB-invalid; OOD | | Boltz-1 (Wohlwend 2024) | AlphaFold-style foundation | 10s GPU | Full complex prediction | DNA / RNA may be off | | Boltz-2 (Wohlwend 2025) | Boltz-1 + affinity head | 10s GPU | Pose + affinity (Pearson 0.66 on 4-target FEP+ benchmark subset; RMSE ~1.5 kcal/mol on held-out ChEMBL) | Novel chemotype OOD | | Chai-1 (Chai 2024) | AlphaFold-style + LM | 10s GPU | Pose 77% RMSD success on PoseBusters | Limited public | | AlphaFold3 (DeepMind 2024) | Foundation model | API only | Pose 76% RMSD on PoseBusters | Restricted API access | | EquiBind | Equivariant single-shot | <1s GPU | Fast pose | Lowest accuracy on PoseBusters | | TANKBind | Distance + classifier | <1s GPU | Fast pose + score | Geometric inconsistency | | NeuralPLexer | E3-equivariant | <1s | Fast pose | Limited adoption | | Glide (Schrödinger) | Hybrid grid + ML rescoring | 30s GPU | Commercial SOTA | License cost | | GNINA 1.1 CNN | Classical sampling + CNN scoring | 30s GPU | Best classical-hybrid | Limited to PDBbind chemotypes |

Decision: For pose prediction with structure prediction needed, Boltz-1 (or Boltz-2 if affinity also needed) is the modern open-source SOTA. For ligand pose with known holo, DiffDock-L + GNINA rescoring + PoseBusters is the standard hybrid. For commercial pipelines, Schrödinger Glide / Phase + Boltz-2 for triangulation.

Decision Tree by Scenario

| Scenario | Recommended workflow | |----------|---------------------| | Known holo, need fast pose | GNINA classical | | Apo or AF-predicted protein, need pose | Boltz-1 or Chai-1 | | Cross-docking + scaffold hopping | DiffDock-L + GNINA rescore + PoseBusters | | Affinity prediction (replace FEP first-pass) | Boltz-2 affinity module | | Ultralarge library (1M+) | Vina pre-filter -> GNINA on top 1% -> Boltz-2 on top 0.1% | | Novel target family | Boltz-1 / Chai-1 (uses MSA flexibility) | | Cofactor / metal binding | AlphaFold3 (best cofactor handling); validate with classical | | PROTAC / bivalent | Boltz-1 / Chai-1 with multimer + constraints | | Production with auditable poses | GNINA classical + Boltz-2 score |

PoseBusters Problem (Critical)

PoseBusters benchmark (Buttenschoen 2024) showed:

| Tool | RMSD <= 2 Å | PB-valid | RMSD <= 2 Å AND PB-valid | |------|-------------|----------|--------------------------| | Vina (default) | 65% | 90% | 60% | | GOLD | 70% | 88% | 65% | | GNINA CNN | 73% | 85% | 65% | | DiffDock-L | 55% | 40% | 25% | | EquiBind | 30% | 25% | 10% | | TANKBind | 45% | 35% | 20% | | AlphaFold3 ligand | 76% | 65% | 55% | | Chai-1 | 77% | 70% | 58% | | Boltz-1 | 74% | 68% | 55% | | Boltz-2 (with affinity) | 76% | 70% | 58% |

Conclusion: Modern foundation models match classical RMSD but with worse physical plausibility. Always require PB-valid + RMSD <= 2 Å.

DiffDock-L + GNINA Hybrid Workflow (Production Standard)

Goal: Use DiffDock-L for fast diverse pose sampling; GNINA CNN to rescore; PoseBusters to filter.

# Step 1: DiffDock-L pose sampling (DiffDock has no `diffdock_inference` binary;
# the canonical entrypoint is `python -m inference` from the DiffDock checkout
# with either `--protein_ligand_csv` or `--complex_name --protein_path --ligand_description`)
python -m inference \
    --protein_path receptor.pdb \
    --ligand_description smiles.smi \
    --out_dir diffdock_out/ \
    --samples_per_complex 40 \
    --inference_steps 20

# Step 2: GNINA CNN rescoring
gnina -r receptor.pdb -l diffdock_out/poses.sdf \
      --cnn_scoring rescore \
      -o rescored.sdf.gz \
      --score_only

# Step 3: PoseBusters validation
posebusters bust \
    --mol_pred rescored.sdf.gz \
    --mol_cond receptor.pdb \
    --config dock \
    --output pb_results.csv

import pandas as pd
pb_df = pd.read_csv('pb_results.csv')
pb_df['pb_valid'] = pb_df.iloc[:, 4:].all(axis=1)
valid_top = pb_df[pb_df['pb_valid']].nlargest(5, 'gnina_score')

Boltz-2 for Affinity (Modern Alternative to FEP First-Pass)

# Pseudo-code; Boltz-2 has open weights
# from boltz import Boltz2
# model = Boltz2.from_pretrained()
# predictions = model.predict(
#     protein_pdb='receptor.pdb',
#     ligand_smiles='CC(=O)c1ccccc1',
# )
# affinity = predictions['affinity']  # in kcal/mol
# pose = predictions['ligand_pose']

Boltz-2 affinity validation:

• On 4 FEP+ benchmark targets: Pearson correlation 0.66
• 1000x faster than FEP+
• Best for hit triage; FEP for production

When to use Boltz-2: Triage 10k-1M ligands; identify top 100 for FEP follow-up.

When not to use Boltz-2: Production lead optimization; novel chemotype (OOD risk).

AlphaFold3 Ligand Prediction

AlphaFold3 (Abramson 2024, DeepMind) supports ligand-aware structure prediction with the publicly-available API (alphafold.ebi.ac.uk).

# Pseudo-code; depends on AlphaFold3 API access
# from alphafold3 import AlphaFold3
# model = AlphaFold3.from_api()
# result = model.predict(
#     protein_sequence='MGSSHHHHHHSSGLVPR...',
#     ligand_smiles='CC(=O)c1ccccc1',
# )
# pose = result['ligand_pose']
# confidence = result['plddt']  # per-residue confidence

AlphaFold3 strengths:

• Best cofactor handling (ions, metals, prosthetic groups)
• Single pose per complex
• Public API access

AlphaFold3 limitations:

• Cannot dock without protein sequence (no template-based)
• Limited to single ligand per run via API
• Throughput restricted by API rate limits

Chai-1 (Open Alternative to AlphaFold3)

Chai-1 (Chai Discovery 2024) is an open-commercial alternative to AlphaFold3 with comparable performance.

# Pseudo-code; Chai-1 is open
# from chai_lab.chai1 import run_inference
# result = run_inference(
#     fasta_file='target.fasta',
#     ligand_smiles='CC(=O)c1ccccc1',
# )

Chai-1 advantages:

• 77% PoseBusters RMSD success (vs AlphaFold3 76%)
• Open commercial license (no API rate limits)
• Single-sequence mode (no MSA required, faster)

ML Docking Failure Modes by Tool

DiffDock-L -- PB-invalid poses

Trigger: Default DiffDock-L on any input.

Mechanism: Diffusion generates poses without physical-validity loss.

Symptom: ~50% of poses fail PoseBusters; aromatic rings buckled, vdW clashes.

Fix: Filter all output through PoseBusters; rerun with smaller diffusion temperature; use as pose sampler not final ranker.

EquiBind -- bond length distortion

Trigger: EquiBind single-shot prediction.

Mechanism: Equivariant NN doesn't preserve bond lengths.

Symptom: Poses have stretched/compressed bonds.

Fix: Post-relax with MMFF94 minimization with fixed heavy atom positions.

TANKBind -- vdW overlap with protein

Trigger: TANKBind on tight pocket.

Mechanism: Distance prediction not constrained to vdW exclusion.

Symptom: Ligand overlaps protein.

Fix: Constrained energy minimization with frozen protein.

Boltz-2 affinity -- novel chemotype error

Trigger: PROTAC, macrocycle, peptide.

Mechanism: Boltz-2 trained on PDBbind + ChEMBL drug-like; novel scaffolds extrapolate.

Symptom: Predicted affinity disagrees with FEP / experiment.

Fix: Use as triage; validate top 1% with FEP. Check applicability domain (Tanimoto to training).

AlphaFold3 / Boltz-1 -- novel target

Trigger: Target protein with limited MSA evidence.

Mechanism: Foundation models depend on MSA / homologs for confidence.

Symptom: Low pLDDT (<70); pose unreliable.

Fix: Use single-sequence mode (Chai-1); validate experimentally before downstream.

Hybrid workflow -- pose / score mismatch

Trigger: DiffDock pose + Boltz-2 affinity disagree.

Mechanism: Pose-prediction model and affinity-prediction model trained differently.

Symptom: Top pose by DiffDock has low Boltz-2 affinity.

Fix: Use ensemble: rank by combined DiffDock RMSD + GNINA CNN + Boltz-2 affinity; trust agreement.

Reconciliation: ML vs Classical

| Scenario | ML | Classical | Decision | |----------|----|-----------|----------| | Self-dock (holo available) | Match | Match | Classical (faster, simpler) | | Cross-dock (apo, related target) | Better | Worse | ML (DiffDock + GNINA rescore) | | Novel chemotype | Worse | Better | Classical | | Novel target family | Better | Worse | ML (Boltz-1 with MSA) | | Ultra-fast screening (1M+) | Slower per-ligand | Faster | Classical with ML rescore | | Production validation | Hybrid required | Hybrid required | ML pose + classical rescore + PB |

Common Errors

| Symptom | Cause | Fix | |---------|-------|-----| | DiffDock-L generates invalid poses | Default behavior | Filter via PoseBusters; expected | | Boltz-1 prediction takes hours | CPU instead of GPU | Use NVIDIA GPU; check --device cuda | | AlphaFold3 API quota exceeded | Free tier limit | Use Chai-1 open alternative | | Chai-1 setup complex | Multi-dependency | Use Tamarind Bio web service | | PoseBusters PB-invalid for known active | Edge case | Sometimes valid; manual review | | GNINA rescore changes ranking | Different scoring | Expected; trust hybrid ranking | | OOM on small molecule | Wrong batch size | Reduce batch_size=1 | | Boltz-2 affinity all 0 | Input format wrong | Check SMILES validity; standardize first |

References

• Corso et al., ICLR (2023) -- DiffDock-L original.
• Buttenschoen et al., Chem. Sci. 15:3130 (2024) -- PoseBusters benchmark.
• Wohlwend et al., bioRxiv (2024) -- Boltz-1.
• Wohlwend et al., bioRxiv (2025) -- Boltz-2 with affinity module.
• Chai Discovery (2024) -- Chai-1 foundation model.
• Abramson et al., Nature 630:493 (2024) -- AlphaFold3 paper.
• McNutt et al., J. Cheminformatics 13:43 (2021) -- GNINA 1.0.
• Stärk H, Ganea OE, Pattanaik L, Barzilay R, Jaakkola T 2022 ICML -- EquiBind.
• Lu W et al 2022 NeurIPS -- TANKBind.
• (DL hybrid virtual-screening benchmark: consult current literature; the earlier "Yang 2024 J Chem Inf Model" citation could not be verified and has been removed.)

Related Skills

• chemoinformatics/virtual-screening - Classical docking foundation
• chemoinformatics/pose-validation - PoseBusters QC (mandatory after ML docking)
• chemoinformatics/free-energy-calculations - Boltz-2 as FEP first-pass
• chemoinformatics/molecular-io - Format conversion for tool inputs
• chemoinformatics/conformer-generation - Pre-conformer for some ML tools
• chemoinformatics/admet-prediction - ADMET on ML-docked hits
• structural-biology/modern-structure-prediction - Protein structure prediction
• structural-biology/structure-io - PDB / mmCIF handling