bio-ml-docking-rescoring

Version Compatibility

Reference examples tested with: DiffDock-L (Corso et al. 2024), Boltz-1 1.0+, Boltz-2 (Passaro et al. 2025), Chai-1 0.4+, AlphaFold 3 (DeepMind), EquiBind, TANKBind, GNINA 1.1+, and 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. Foundation models such as AlphaFold 3, Boltz, and Chai-1 handle protein-ligand complex prediction, while DiffDock-L extends the original DiffDock method for ligand-pose sampling (Corso et al. 2023, 2024). Boltz-2 reports affinity prediction approaching physics-based free-energy methods on its evaluated benchmarks at substantially lower computational cost. Physical plausibility remains a separate requirement: on the PoseBusters Benchmark, the original DiffDock produced a correct and physically valid pose for 12% of complexes, compared with 58% for Vina and 55% for GOLD (Buttenschoen et al. 2024). Use ML sampling with independent scoring and physical validation rather than treating model confidence as sufficient.

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 et al. 2024)	Equivariant diffusion	GPU; hardware-dependent	Diverse pose sampling for cross-docking	Requires physical validation; OOD risk
Boltz-1 (Wohlwend et al. 2024)	AlphaFold-style foundation	GPU; hardware-dependent	Full complex prediction	Confidence is not affinity or physical validation
Boltz-2 (Passaro et al. 2025)	Boltz-1 + affinity module	GPU; hardware-dependent	Joint pose and affinity triage	Benchmark- and chemotype-dependent accuracy
Chai-1 (Chai Discovery 2024)	AlphaFold-style + language model	GPU; hardware-dependent	Open-weight complex prediction	Validate ligands and cofactors independently
AlphaFold 3 (Abramson et al. 2024)	Foundation model	Local code/weights or public server	Complex prediction with proteins and ligands	Server and local distributions have different terms and limits
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 generative model	GPU; hardware-dependent	Protein-ligand structure prediction	Validate geometry and confidence on the target domain
Glide (Schrödinger)	Grid-based docking and empirical scoring	License and hardware-dependent	Commercial docking workflow	License cost
GNINA 1.1 CNN	Classical sampling + CNN scoring	GPU; hardware-dependent	CNN-assisted pose ranking	Validate transfer to the target and chemotype

Decision: For pose prediction when the complex structure must also be predicted, benchmark an open model such as Boltz or Chai-1 on target-relevant controls. For a known holo receptor, DiffDock-L sampling followed by GNINA rescoring and PoseBusters checks is one auditable hybrid option. Compare it with an appropriate classical-docking baseline rather than assuming one workflow is universally superior.

Candidate Workflows to Benchmark 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	Use a model/interface that explicitly supports the component; validate coordination geometry independently
PROTAC / bivalent	Boltz-1 / Chai-1 with multimer + constraints
Production with auditable poses	GNINA classical + Boltz-2 score

The library fractions in this table are repository starting heuristics. Calibrate stage cutoffs using target-relevant controls, measured throughput, and chemotype-retention analysis.

PoseBusters Problem (Critical)

The PoseBusters paper evaluated DeepDock, DiffDock, EquiBind, TankBind, Uni-Mol, Vina, and GOLD. It did not benchmark DiffDock-L, GNINA, AlphaFold 3, Chai-1, Boltz-1, or Boltz-2. On the 308-complex PoseBusters Benchmark, the reported fraction of predictions that were both within 2 Å RMSD and physically valid was:

Tool/version evaluated in the paper	RMSD <= 2 Å and PB-valid
Vina	58%
GOLD	55%
DiffDock	12%

Conclusion: Pose accuracy and chemical plausibility are different axes. Require PoseBusters-style checks for generated poses; calculate RMSD only when a reference pose is available. Do not transfer these percentages to newer model versions without a matched benchmark.

DiffDock-L + GNINA Hybrid Workflow

Goal: Evaluate DiffDock-L pose sampling, GNINA CNN rescoring, and PoseBusters checks as separate stages whose contributions can be audited.

# Step 1: run from the official DiffDock checkout.
# --ligand accepts one SMILES or ligand file; use --protein_ligand_csv for batches.
cd /path/to/DiffDock
python3 -m inference \
    --config default_inference_args.yaml \
    --protein_path receptor.pdb \
    --ligand 'CC(=O)c1ccccc1' \
    --out_dir diffdock_out/ \
    --samples_per_complex 40 \
    --inference_steps 20

# Step 2: GNINA CNN rescoring
# DiffDock writes rank*.sdf files inside a per-complex output directory.
gnina -r receptor.pdb -l diffdock_out/<complex_name>/rank1.sdf \
      --cnn_scoring rescore \
      -o rescored.sdf \
      --score_only

# Step 3: PoseBusters validation
bust rescored.sdf -p receptor.pdb --outfmt=csv > pb_results.csv

import pandas as pd
pb_df = pd.read_csv('pb_results.csv')
bool_cols = pb_df.select_dtypes(include='bool').columns
pb_df['pb_valid'] = pb_df[bool_cols].all(axis=1)
valid_poses = pb_df[pb_df['pb_valid']]

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

Use the official Boltz input schema and boltz predict CLI for the installed release; do not rely on an invented Boltz2.from_pretrained() Python interface. The Boltz-2 paper reports affinity accuracy approaching FEP on its evaluated benchmarks and at least a 1,000-fold speed advantage, but those results are benchmark-specific and do not establish a universal RMSE or correlation for arbitrary ChEMBL data.

When to use Boltz-2: Use affinity_probability_binary for hit-discovery triage and affinity_pred_value for comparing binders during hit-to-lead or lead optimization, following the official output semantics. Benchmark both heads on target-relevant controls, and reserve FEP or experiment for decisions that require higher confidence.

When not to rely on Boltz-2 alone: Novel chemotypes or modalities outside the demonstrated training/benchmark domain, or production decisions without target-relevant validation.

AlphaFold3 Ligand Prediction

AlphaFold 3 supports ligand-aware complex prediction. It can be run with the official local code after obtaining model parameters, or through the public AlphaFold Server under its separate terms and limits.

# From the official alphafold3 checkout; request.json follows its input schema.
python run_alphafold.py \
    --json_path=request.json \
    --model_dir=/path/to/af3_models \
    --output_dir=af3_out

AlphaFold3 strengths:

• Supports complexes containing proteins, nucleic acids, ligands, ions, and modified residues under its documented input schema
• Multiple diffusion samples per seed (five by default in the official local implementation), with all samples retained and a top-ranked prediction copied to the job root
• Official local implementation and a public web server

AlphaFold3 limitations:

• Cannot dock without protein sequence (no template-based)
• Public-server features and throughput differ from local execution
• Local weights require an approved access request and substantial compute

Chai-1 (Open Alternative to AlphaFold3)

Chai-1 (Chai Discovery 2024) provides open code and model weights for biomolecular complex prediction. Validate performance on target-relevant controls rather than assuming equivalence to another model.

from pathlib import Path
from chai_lab.chai1 import run_inference

# Chai represents every entity, including a SMILES ligand, in the input FASTA.
fasta_file = Path('target.fasta')
fasta_file.write_text(
    '>protein|name=target\nMSEQUENCE...\n'
    '>ligand|name=ligand\nCC(=O)c1ccccc1\n'
)
result = run_inference(
    fasta_file=fasta_file,
    output_dir=Path('chai_out'),
    num_trunk_recycles=3,
    num_diffn_timesteps=200,
    seed=42,
    device='cuda:0',
    use_esm_embeddings=True,
)

Chai-1 advantages:

• Apache-2.0 code and model weights permit academic and commercial use
• Local execution avoids public-server 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: Some poses fail PoseBusters through distorted geometry or van der Waals clashes even when model confidence is high.

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

EquiBind -- implausible intermediate or output geometry

Trigger: EquiBind single-shot prediction.

Mechanism: EquiBind's uncorrected predicted point cloud is not guaranteed to satisfy local geometry. Its final ligand-fitting stage is designed to change rotatable-bond torsions while keeping local atomic structure, including bond lengths and adjacent bond angles, fixed.

Symptom: An uncorrected intermediate or a failed/misapplied post-processing workflow contains implausible local geometry.

Fix: Use the released ligand-fitting/post-processing path, then validate the resulting pose with PoseBusters. If additional relaxation is used, constrain it deliberately and recheck stereochemistry and local geometry.

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: A novel scaffold may fall outside the model's demonstrated benchmark domain.

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 or inconsistent model confidence. For AlphaFold 3, ligand-atom pLDDT only measures ligand-to-polymer local-distance confidence; inspect the full ranking score and ligand-relevant chain/interface confidence rather than applying a universal pLDDT cutoff.

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: Retain DiffDock confidence, GNINA score, Boltz-2 affinity, and physical-validity results as separate columns; prioritize consensus and inspect disagreements. RMSD is available only when a reference pose exists.

Reconciliation: ML vs Classical

Scenario	Practical comparison
Self-dock with a known holo receptor	Compare redocking recovery, geometry, and runtime for classical and ML workflows
Cross-dock or uncertain receptor conformation	Compare ML sampling, ensemble docking, and classical controls on related complexes
Novel chemotype or target family	Treat all model scores as extrapolative until target-relevant controls are available
Ultralarge screening	Use a fast first stage and reserve expensive rescoring for a documented subset
Production validation	Preserve sampler confidence, independent scores, and physical-validity checks as separate evidence

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 a supported accelerator; for the current CLI check --accelerator gpu
AlphaFold Server job limit reached	Public-server limit	Use approved local AlphaFold 3 weights or an open local alternative such as Chai-1
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	Preserve both rankings and inspect disagreements on validated controls
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) -- original DiffDock. https://arxiv.org/abs/2210.01776
• Corso et al., ICLR (2024) -- DiffDock-L. https://proceedings.iclr.cc/paper_files/paper/2024/file/db334db287337b2a365120b524300ef3-Paper-Conference.pdf
• Buttenschoen et al., Chem. Sci. 15:3130-3139 (2024) -- PoseBusters benchmark. https://doi.org/10.1039/D3SC04185A
• Wohlwend et al., bioRxiv (2024) -- Boltz-1. https://doi.org/10.1101/2024.11.19.624167
• Passaro et al., bioRxiv (2025) -- Boltz-2 with affinity module. https://doi.org/10.1101/2025.06.14.659707
• Boltz, official repository -- affinity-output semantics and current prediction interface. https://github.com/jwohlwend/boltz
• Chai Discovery, Chai-1 Technical Report (2024). https://doi.org/10.1101/2024.10.10.615955
• Chai Discovery, Chai-1 official repository -- code and model-weight licensing. https://github.com/chaidiscovery/chai-lab
• Abramson et al., Nature 630:493-500 (2024) -- AlphaFold 3. https://doi.org/10.1038/s41586-024-07487-w
• Google DeepMind, AlphaFold 3 official repository -- local code and model-parameter access. https://github.com/google-deepmind/alphafold3
• McNutt et al., J. Cheminformatics 13:43 (2021) -- GNINA 1.0. https://doi.org/10.1186/s13321-021-00522-2
• Stärk et al., ICML (2022) -- EquiBind. https://proceedings.mlr.press/v162/stark22b.html
• Lu et al., NeurIPS 35 (2022) -- TANKBind. https://proceedings.neurips.cc/paper_files/paper/2022/hash/2f89a23a19d1617e7fb16d4f7a049ce2-Abstract-Conference.html
• Qiao et al., Nat. Mach. Intell. 6:195-208 (2024) -- NeuralPLexer. https://doi.org/10.1038/s42256-024-00792-z

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