alterlab-boltz

Files (3)

• SKILL.md
• evals.json · evals/
• boltz_usage.md · references/

SKILL.md (first lines)

# Boltz-2 (open AlphaFold3-style co-folding)

## Overview

**Boltz-2** (Passaro, Wohlwend et al. 2025; `jwohlwend/boltz`) is an open, commercially usable
biomolecular structure model in the AlphaFold3 family: it **co-folds** proteins together with
small-molecule **ligands**, nucleic acids, and multiple chains in a single prediction, and can
predict **binding affinity** — capabilities AlphaFold2/ColabFold does not have. Use it when the
biology is a *complex with a ligand or other molecule types*, not a bare protein.

## When to Use This Skill

Use this skill when the user wants to:
- Co-fold a protein **with a small-molecule ligand** (SMILES or CCD code) into a holo complex.
- Predict a **binding affinity** alongside a co-folded pose.
- Fold **protein–nucleic-acid** or multi-entity assemblies in one pass.
- Get an open AlphaFold3-style prediction without proprietary access.

### Does NOT Trigger

| Scenario | Use instead |
|----------|-------------|
| Protein-only or protein–protein folding, no ligand | `alterlab-alphafold` |
| Antibody–antigen / general one-FASTA multi-entity complex | `alterlab-chai` |
| Dock a ligand into an **existing, fixed** receptor structure | `alterlab-diffdock` |
| Retrieve an experimentally determined structure | `alterlab-pdb` |
| Design a binding-pocket sequence around a ligand | `alterlab-ligandmpnn` |

## Core Capabilities

### 1. Protein + ligand co-folding

Describe the complex in a YAML spec (chains + ligand by SMILES or CCD), then predict:

```yaml
# complex.yaml
version: 1
sequences:
  - protein: { id: A, sequence: "MKT...GGG" }        # msa: path.a3m, or omit with --use_msa_server
  - ligand:  { id: L, smiles: "CC(=O)Oc1ccccc1C(=O)O" }   # or: ccd: SAH
```

```bash
boltz predict complex.yaml --out_dir out/ --use_msa_server --use_potentials
```

Outputs the co-folded structure (mmCIF by default, `--output_format pdb` for PDB) plus a
`confidence_*.json` per sample. `--use_msa_server` fetches the protein MSA from the hosted
MMseqs2 server (it sends your sequence out — disclose that for unpublished work); supply
`msa: my.a3m` per chain to stay offline, or `msa: empty` to force single-sequence mode.
`--use_potentials` applies inference-time potentials that improve the physical plausibility
of poses. Useful knobs: `--diffusion_samples N`, `--recycling_steps N`, `--override`.

### 2. Binding-affinity prediction

Ask for affinity in the YAML, naming the ligand chain to score:

```yaml
properties:
  - affinity:
      binder: L
```

`affinity_[input].json` then carries two distinct numbers, trained on different data and
meant for different jobs:

- **`affinity_probability_binary`** (0–1) — probability the ligand is a binder at all. Use
  it for hit discovery / binder-vs-decoy triage.
- **`affinity_pred_value`** — predicted `log10(IC50)` with IC50 in µM, so -3 ≈ 1 nM (strong),
  0 ≈ 1 µM, 2 ≈ 100 µM. It is calibrated for comparing *active* molecules during hit-to-lead
  optimisation, not for separating actives from inactives. Convert to pIC50-style kcal/mol
  with `(6 - y) * 1.364`.

Limits worth knowing before you queue a screen: one small-molecule binder per prediction,
at most 128 heavy+kept hydrogens (the training limit was ~56 atoms), and protein targets
only — an RNA/DNA "target" runs without error but the number is unreliable. Treat every
predicted affinity as a ranking signal and confirm against measured data
(`alterlab-bindingdb`) or experiment.

### 3. Confidence and validation

Each sample gets a `confidence_*.json` with `confidence_score` (the ranking score,
0.8·complex_plddt + 0.2·iptm), `ptm`, `iptm`, **`ligand_iptm`** (interface confidence at
protein–ligand interfaces specifically), `protein_iptm`, `complex_plddt`, `complex_iplddt`,
`chains_ptm` and `pair_chains_iptm`. For a ligand pose, `ligand_iptm` plus the pLDDT around
the pocket is the pair to read — a high overall score with a weak ligand interface means the
protein folded well and the ligand did not dock convincingly. Cross-check with
`alterlab-diffdock` when the receptor structure is already known and fixed.

### 4. Running on a GPU

Boltz-2 wants a CUDA GPU and downloads weights once into `~/.boltz`. Point `boltz predict` at
a *directory* of YAML files to batch a ligand series against one target in a single run, and
dispatch it via `alterlab-remote-compute`: submit → poll → harvest `out/predictions/`.

## Resources

- `references/boltz_usage.md` — install/pinning, YAML/FASTA input schema, MSA options,
  affinity output, and multi-entity examples. Loaded on demand.

Part of the AlterLab Academic Skills suite.

From AlterLab-IEU/AlterLab-Academic-Skills, MIT.

More from AlterLab-IEU/AlterLab-Academic-Skills