boltz

# Boltz-2

Boltz-2 is the open-weights diffusion co-folder closest in surface to
AlphaFold3: a YAML describing protein, DNA, RNA, and ligand chains in, mmCIF
plus pTM/ipTM/pLDDT confidences out, with an optional small-molecule affinity
head. Among our four co-fold skills it is the default for binder-validation
campaigns — fully open MIT weights and the fastest sampler; pick `chai1` when
you want a second independent model for consensus, `openfold3` when AF3-faithful
settings matter, and `esmfold2` when you can live without an MSA. Code and
weights are MIT (PyPI `boltz`, github.com/jwohlwend/boltz).

## Running it

```yaml
# complex.yaml
version: 1
sequences:
  - protein:
      id: A
      sequence: MVTPEGNVSLVDESLLVGVTDEDRAVRS...   # target
  - protein:
      id: B
      sequence: AIQRTPKIQVYSRHPAENG...            # binder
  - ligand:
      id: L
      smiles: 'N[C@@H](Cc1ccc(O)cc1)C(=O)O'      # or  ccd: SAH
```

```bash
boltz predict complex.yaml \
    --use_msa_server --out_dir out/ --recycling_steps 3 --diffusion_samples 5
```

Each protein chain needs an MSA; without one the run exits before the model
loads. `--use_msa_server` queries `api.colabfold.com` (expect a 30–90 s pause
per chain) and is the right default unless you already have an `.a3m` to name
under `msa:` in the YAML. Setting `msa: empty` forces single-sequence mode —
that is an accuracy sacrifice, not a speed or memory optimization, because the
MSA search runs on CPU before the GPU stage starts.

Per input the output lands at `out/boltz_results_complex/predictions/complex/`.
Read `confidence_complex_model_0.json` first: `iptm` > 0.5 is the community
pass line for an interface, `complex_plddt` > 0.7 for the fold itself, and
`confidence_score` is the weighted aggregate the structures are ranked by.
Structures themselves are `complex_model_{0..N-1}.cif` (or `.pdb` with
`--output_format pdb`).

## Affinity head

Add a `properties:` block naming one `ligand` chain as the binder and Boltz-2
predicts protein–small-molecule binding affinity alongside the structure:

```yaml
properties:
  - affinity:
      binder: L            # the ligand chain id, not the protein
```

Output gains `affinity_complex.json` next to the confidence file:
`affinity_pred_value` is log10(IC50 in μM) — lower is tighter (≈0 → 1 μM,
−3 → 1 nM); `affinity_probability_binary` is the 0–1 binder-vs-non-binder
score and is what to rank hits by. One affinity ligand per input; the binder
must be a `ligand` chain (no protein–protein affinity), and Boltz v2.2.x caps
affinity ligands at 128 atoms. FASTA inputs cannot request affinity at all.

## `msa: empty` is an accuracy hit, not a memory save

Single-sequence mode has been suggested elsewhere as a way to fit smaller GPUs.
It does not help: the MSA search is CPU-side, so `--use_msa_server` versus
`msa: empty` changes nothing about peak VRAM. If you OOM, lower
`--diffusion_samples` or `--max_parallel_samples`, or move to an 80 GB tier;
do not trade away the MSA for it.

## Missing fast kernels are slow, not fatal

`ImportError` for `cuequivariance_ops_torch` or its `libcue_ops.so` means the
compiled triangle-kernel package is not on the loader path. `--no_kernels`
falls back to the reference PyTorch path — roughly 2× slower, numerically
identical, so it is the right unblock for a one-off and the wrong choice for a
campaign.

## Errors worth recognizing

| You see | It means / do this |
|---|---|
| `Missing MSA's in input and --use_msa_server flag not set` | A protein chain has no MSA — add `--use_msa_server` or set `msa:` to an `.a3m` path in the YAML. |
| `ImportError: ... cuequivariance_ops_torch` / `libcue_ops.so` | Fast-kernel wheel not visible — add `--no_kernels` (slower, correct) or fix the env's `LD_LIBRARY_PATH`. |
| `KeyError: 'iptm'` reading the confidence JSON | Single-chain input — ipTM is interface-only; read `ptm` instead. |
| No `affinity_*.json` in output | Used FASTA input, or the YAML is missing the `properties:` block — see *Affinity head* above. |

---

**Next:** compute clash and interface metrics on passing complexes, or feed
them back to `proteinmpnn` for another design round.