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

Hard rules

1. No fabricated citations. Every cited work must resolve to a verifiable
2. No claim without provenance. Every quantitative or factual claim
3. No silent failure. Every script invocation, API call, or tool use must declare its exit status and what to do on non-zero. A skill that silently swallows errors is a violation.

When to use

Load this skill when the user asks a question that matches its declared trigger conditions (see the frontmatter description for the most common ones). Do not load it for questions outside its scope — defer to the appropriate ORS skill instead.

When NOT to use

Do not load this skill if the question is in a sibling skill's domain (see ## Cross-references), if the user explicitly asks for a different tool, or if the task is outside the skill's declared category.

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.

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
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/top_poses.sdf \
      --autobox_ligand reference_ligand.sdf \
      --cnn_scoring rescore \
      -o gnina_rescored.sdf.gz

# Step 3: PoseBusters QC"
python -c "
from posebusters import PoseBusters
b = PoseBusters(config='dock')
df = b.bust(mol_pred='gnina_rescored.sdf.gz', mol_cond='receptor.pdb')
print(df.filter(regex='pass').sum().sum(), 'checks passed')
"

Boltz-2 Affinity Prediction (Fast FEP Replacement)

Goal: Predict binding affinity at ~10s/ligand on GPU vs hours for FEP.

Approach: Submit protein + ligand to Boltz-2 with the affinity head; receive predicted pIC50 or ΔG with uncertainty.

boltz predict input.yaml --use_affinity --output_dir boltz2_out/

Validation: Boltz-2 reports Pearson 0.66 vs experimental on 4-target FEP+ subset; RMSE ~1.5 kcal/mol on ChEMBL holdout. Faster than FEP (10s vs hours) but ~3x less accurate.

Foundation Models: Boltz-1 and Chai-1

For novel target or no MSA, the foundation models treat ligand + protein jointly:

# Boltz-1
boltz predict input.yaml --output_dir boltz1_out/

# Chai-1
chai-lab predict input.fasta --output-dir chai_out/

Boltz-1 / Chai-1 caveats: Both accept MSA but treat ligand in pocket as constraints; output is the full complex structure. Ligand pose quality matches PoseBusters benchmarks in the table above.

Per-Tool Failure Modes

DiffDock-L -- PB-invalid poses

Trigger: Default DiffDock-L output.

Mechanism: Diffusion lacks explicit physical-plausibility term; ~50% of poses fail planarity, vdW overlap, or chirality tests.

Symptom: Poses look reasonable in 2D depiction but fail QC.

Fix: Always apply PoseBusters filter; rescore with GNINA.

Boltz-2 -- poor affinity for novel chemotype

Trigger: Ligand chemotype outside ChEMBL training distribution.

Mechanism: Affinity head trained on public bioactivity data; extrapolation is unreliable.

Symptom: Predicted pIC50 far from experimental; uncertainty band very wide.

Fix: Use Boltz-2 for first-pass triage only; FEP for top hits.

EquiBind -- worst accuracy

Trigger: Default EquiBind without ensemble.

Mechanism: Single-shot equivariant network; no refinement step.

Symptom: Poses within RMSD > 5 Å.

Fix: Avoid EquiBind; use DiffDock-L or Boltz-1 for sampling, then refine with GNINA.

AlphaFold3 -- restricted API

Trigger: Academic users without commercial agreement.

Mechanism: AF3 server requires Google Cloud account + quota.

Symptom: Cannot submit jobs; rate-limited.

Fix: Use Boltz-1 (open source) for similar performance; AF3 only for cross-validation.

ML methods ignore cryptic pockets

Trigger: Binding site not in receptor conformation.

Mechanism: ML methods score poses against static receptor.

Symptom: All poses report poor affinity; known active missed.

Fix: Pre-generate receptor ensemble via MD or use AlphaFold3 holo prediction.

Reconciliation: ML vs Classical

Production hybrid: ML for pose sampling (broader search), classical for affinity + physical validation.

Common Errors

References

• Corso et al., Nat. Mach. Intell. -- DiffDock-L.
• Wohlwend et al., 2024 -- Boltz-1; 2025 -- Boltz-2 with affinity.
• Buttenschoen et al., Chem. Sci. 15:3130 -- PoseBusters benchmark.
• McNutt et al., J. Cheminformatics 13:43 -- GNINA 1.0 CNN.
• Krishna et al., 2024 -- AlphaFold3 server.

Related Skills

• chemoinformatics/virtual-screening - Classical docking
• chemoinformatics/pose-validation - PoseBusters QC
• chemoinformatics/free-energy-calculations - Post-docking FEP
• chemoinformatics/covalent-design - Covalent docking
• chemoinformatics/protac-degraders - Ternary complex prediction

Cross-references

Other skills in this category:

• admet-prediction
• conformer-generation
• covalent-design
• free-energy-calculations
• generative-design
• molecular-descriptors
• molecular-io
• molecular-standardization
• pharmacophore-modeling
• pose-validation
• protac-degraders
• qsar-modeling
• retrosynthesis
• scaffold-analysis
• shape-similarity
• similarity-searching
• substructure-search
• virtual-screening

Changelog

• 1.1.0 (migration) — Bulk-migrated to v0.4.0 schema: canonical metadata block, base Hard rules, Cross-references. Body content unchanged; author should review and fill in any domain-specific extensions to the Hard rules.
• 1.0.0 — Initial release.