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

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

PoseBusters Problem (Critical)

PoseBusters benchmark (Buttenschoen 2024) showed:

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

Common Errors

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