Boltz-2

An open-weights cofolding model in the AlphaFold3 family, plus something AlphaFold3 does not have: a trained binding-affinity head. Give it a protein sequence and a ligand SMILES and it returns a complex structure, per-interface confidence, and a predicted potency — with weights licensed for commercial use.

Repo: github.com/jwohlwend/boltz Checked against: boltz 2.2.1 (PyPI), Python ≥3.10 <3.13.

Read references/yaml-schema.md before writing an input, references/confidence-and-affinity.md before believing an output, and references/running.md for install, GPU sizing, flags, and errors.

When to reach for this

Situation	Use
No experimental structure, and you need a ligand in the pocket	Boltz — folding and docking in one step
Experimental structure exists, defined site, need to rank thousands	autodock-vina
Experimental structure exists, need a pose without a box	diffdock
Need a defensible free energy for a congeneric series	Alchemical FEP, not this
No GPU	tamarind runs Boltz as a service

The loop

# 1. write the input
python skills/boltz/scripts/make_boltz_yaml.py \
    --protein-fasta target.fasta \
    --ligand-smiles "Cc1ccc(cc1Nc1nccc(n1)c1cccnc1)NC(=O)c1ccc(CN2CCN(C)CC2)cc1" \
    --affinity --out complex.yaml

# 2. predict (external, needs a GPU)
boltz predict complex.yaml --out_dir predictions/ --use_msa_server \
    --use_potentials --diffusion_samples 5

# 3. read the results with the units converted
python skills/boltz/scripts/collect_results.py predictions/

name  sample  confidence_score  iptm  ligand_iptm  binder_probability  pIC50  IC50_uM  dG_kcal_mol
lig1  0       0.84              0.82  0.79         0.93                8.10   0.0079   -11.05
lig2  0       0.51              0.42  0.31         0.21                4.60   25.1189  -6.27

make_boltz_yaml.py catches at write time the four things that otherwise fail after the GPU has already spun up: non-amino-acid characters in a sequence, an affinity binder that is not a ligand chain, --pocket with no ligand, and an out-of-range max_distance. It also quotes SMILES — an unquoted # (an alkyne) starts a YAML comment and silently truncates the molecule.

The affinity number, and its sign

affinity_pred_value is log10 of an IC50 in micromolar. It runs the opposite way to everything else in the field: −3 is a nanomolar binder, +2 is a decoy.

pIC50 = 6 - value        IC50 = 10**value  µM        ΔG = -1.364 × pIC50  kcal/mol

collect_results.py emits pIC50, IC50_uM, and dG_kcal_mol so the sign cannot be misread downstream. Report those, never the raw value.

There are two affinity outputs and they answer different questions:

• affinity_probability_binary — probability the ligand binds at all. This is the hit-discovery output; use it to triage a screen.
• affinity_pred_value — relative potency. Only meaningful between active molecules, for hit-to-lead and lead optimisation. Applying it to inactives is a category error.

The two ensemble members are reported separately in the JSON; collect_results.py turns their disagreement into an ensemble_spread column, which is the cheapest uncertainty estimate on offer. More than one log unit of spread means the number should not be quoted alone.

Read ipTM before anything else

complex_plddt high and iptm low is the classic trap: both partners folded correctly, and their arrangement is a guess. For a binding question, the interface score is the score.

ipTM / ligand_ipTM	Reading
> 0.8	Confident interface; the pose is usable
0.6 – 0.8	Plausible; check it against known site residues
< 0.6	The model does not believe its own interface — an affinity computed on it is meaningless

collect_results.py --min-iptm 0.6 filters, and warns about what it dropped. Note that pde and ipde are in Angstrom, so for those alone lower is better.

Constrain the pocket when you know it

Without a pocket constraint, Boltz decides where the ligand goes — usually right for a well-defined site, less so for a shallow or multi-site protein.

python skills/boltz/scripts/make_boltz_yaml.py --protein-fasta target.fasta \
    --ligand-ccd SAH --pocket A:790,A:797,A:855 --pocket-distance 6 --out cofactor.yaml

--pocket-force makes it a hard constraint rather than a bias. Use it only when you are sure: forcing a wrong pocket produces a confident wrong answer, which is worse than an unconstrained one.

Screening a library

python skills/boltz/scripts/screen_library.py --protein-fasta target.fasta \
    --smiles library.smi --out-dir screen/ --affinity --msa-path target.a3m

boltz predict screen/ --out_dir screen/predictions --use_potentials --diffusion_samples 5
python skills/boltz/scripts/collect_results.py screen/predictions --min-iptm 0.6 --out hits.tsv

One YAML per ligand, plus a manifest. Precompute the MSA and pass --msa-path — every input shares the same protein, and rebuilding its MSA N times is the single largest waste in a screen. The script says so if you forget.

It also flags compounds above the affinity head's 128-atom limit (--skip-oversized drops them); past that limit Boltz returns a number that means nothing.

Scale honestly: a few minutes per ligand on a 24 GB GPU with a precomputed MSA. This is a hundreds-to-low-thousands method. Filter a large library with autodock-vina or medchem first and bring the survivors here.

What it is, and is not

The affinity head is trained on measured bioactivity, so it behaves like a very good structure-aware QSAR model, not a physics calculation. It reflects the chemistry and target classes in its training data; a novel scaffold against an under-studied target is extrapolation, and there is no thermodynamic cycle to check it against.

Treat agreement with an orthogonal method as the evidence — a docking score from autodock-vina, measured analogues from chembl, or a stability check in molecular-dynamics. Report the release, the ipTM, and the pIC50 with its ensemble spread.

Composing with the rest of the bundle

• uniprot-rcsb → here: the sequence, and a template CIF if an apo structure exists.
• binding-site-analysis → before: which site to focus on, and whether it is druggable.
• chembl → here: known actives against the target, to calibrate what the affinity head says about chemistry you already have data for.
• medchem / rdkit → before: triage and standardise the library.
• autodock-vina → alongside: an orthogonal score on the same compounds.
• molecular-dynamics → after: does the predicted pose survive 10 ns?
• tamarind → instead: hosted Boltz when there is no local GPU.