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

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

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:

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

Common Errors

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