TT-Bio
████████╗████████╗ ██████╗ ██╗ ██████╗
╚══██╔══╝╚══██╔══╝ ██╔══██╗ ██║ ██╔═══██╗
██║ ██║ █████╗ ██████╔╝ ██║ ██║ ██║
██║ ██║ ╚════╝ ██╔══██╗ ██║ ██║ ██║
██║ ██║ ██████╔╝ ██║ ╚██████╔╝
╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═════╝
[!IMPORTANT] TT-Boltz is now TT-Bio
TT-Bio runs Boltz-2, ESMFold2, Protenix-v2, and OpenDDE structure prediction, BoltzGen binder design, ProteinMPNN sequence design, and ESMC protein embeddings, and SaProt structure-aware protein embeddings on Tenstorrent Blackhole and Wormhole, supporting single-card and multi-card configurations (e.g. QuietBox with 4 cards or Galaxy server with 32 cards). Multiple machines can also be combined into a single prediction run.
Installation
Create a Python virtual environment with Python 3.10 or 3.12, install, then install the matching Tenstorrent system dependencies.
python3.10 -m venv env
source env/bin/activate
pip install tt-bio
tt-bio install-deps
tt-bio install-deps installs the Tenstorrent system dependencies that match this release. It may ask for your sudo password.
From GitHub / source
Pin to a tagged release, track nightly main (may be untested), or work from an editable clone:
pip install "tt-bio @ git+https://github.com/moritztng/tt-bio.git@v0.3.1" # pinned release, see Releases for the latest
pip install "tt-bio @ git+https://github.com/moritztng/tt-bio.git@main" # nightly
# or
git clone https://github.com/moritztng/tt-bio.git
cd tt-bio
pip install -e .
tt-bio install-deps
Optional: Build TT-Metal / TT-NN from Source
If you need to build from source, follow the Tenstorrent Installation Guide.
Verify Installation
tt-bio --help
tt-bio predict --help
tt-bio msa --help
Basic Usage
Structure Prediction
tt-bio predict examples/prot.yaml --model boltz2 --override
Every command names its model with --model:
boltz2: folds complexes of proteins, DNA, RNA, and ligands and predicts binding affinity. MSA-dependent (uses an MSA by default).esmfold2/esmfold2-fast: fold a single protein sequence on-device, no MSA required (esmfold2-fastis the lighter, faster checkpoint).protenix-v2: folds complexes of proteins, RNA, DNA, and ligands (an AlphaFold3-family model, the Protenix reproduction); MSA-dependent for proteins (uses an MSA by default), and also emits a PAE/PDE matrix with--write_pae.saprot: structure-aware protein embeddings — an ESM-2 encoder over a fused amino-acid + Foldseek-3Di vocabulary (446 tokens). Needs a structure for the 3Di structural tokens (--structure); runs sequence-only without it. Use for variant-effect / mutation-fitness scoring and function prediction.opendde/opendde-abag: antibody-antigen co-folding built on the Protenix-v2 stack plus a structural-token expander;opendde-abagselects the antibody-antigen checkpoint. Protein-only for now; proteins are MSA-dependent (uses an MSA by default, like Protenix-v2).
tt-bio predict examples/prot.fasta --model esmfold2-fast --fast
tt-bio predict examples/prot.yaml --model protenix-v2 # MSA on by default; NA/ligand chains are single-sequence
tt-bio predict examples/9dsg_abag.yaml --model opendde-abag # antibody-antigen co-fold, MSA on by default
| Feature | Boltz-2 | ESMFold2 | Protenix-v2 | OpenDDE |
|---|---|---|---|---|
| Input | protein/DNA/RNA/ligand complex | single protein | protein/DNA/RNA/ligand complex | protein complex (antibody-antigen) |
| MSA | MSA-dependent (on by default) | single-sequence | proteins MSA-dependent (on by default), NA/ligand single-sequence | proteins MSA-dependent (on by default) |
| Affinity / potentials / templates | yes | no | no | no |
| Pocket / contact constraints | yes | no | no | no |
Covalent bond constraints |
yes | no | yes | no |
PAE/PDE output (--write_pae) |
no | no | yes | no |
All structure models support the sampling, output-format, and scheduling options. MSA, affinity, constraint, and auxiliary-output options apply only where listed below. Each model downloads its weights automatically on first use.
Boltz-2, Protenix-v2, and OpenDDE are MSA-dependent and use an MSA by default, a local
ColabFold DB (~/.boltz/msa_db) if one is set up (see Offline MSA),
otherwise the online ColabFold server. Sending sequences to the online server (api.colabfold.com)
leaves your machine; a one-line notice is printed when that fallback is used. Pass
--msa_db_path for a private offline database, or --single_sequence to deliberately fold
without an MSA (lower accuracy; for batch-screening orphan sequences). OpenDDE multi-chain
predictions still request paired MSAs from --msa_server_url; use --single_sequence to
prevent all network MSA requests. ESMFold2 is single-sequence.
--fast makes some operations use a lower-precision numeric format that runs faster. Accuracy is typically very close.
OpenDDE-abag matches the upstream checkpoint on the standard 1AHW antibody-antigen target. Both implementations perform poorly on 9DSG.
predict accepts either a single YAML/FASTA file or a directory containing many input files.
A live display shows the progress of each target. Prediction uses up to one card
per pending target, labelled in the display (quietbox:tt0, quietbox:tt1, ...).
Models load once per active card and stay resident:
tt-bio predict proteins/ --model boltz2 --out_dir results --fast
Pass --devices 0,1,2,3 to pick or limit the available cards. A single target
remains a single-card fold; additional cards increase throughput only when
multiple targets are queued.
If you have additional machines with Tenstorrent cards, you can add them to a single run; see Optional: Multi-Machine Prediction.
Protein Embeddings (ESMC)
Turn protein sequences into ESMC language-model embeddings on-device (no
folding, no MSA). DATA is a FASTA file, a directory of them, a YAML
{id: sequence} mapping, or a bare sequence string:
tt-bio embed proteins.fasta --model esmc-600m --out_dir embeddings
tt-bio embed "MQIFVKTLTGKTITLEV..." --model esmc-600m # one-off sequence
--model selects the ESMC variant (esmc-300m, esmc-600m, esmc-6b). For
each sequence you get its per-residue embeddings ([length, d_model]
float32, one row per amino acid, row order == input order) and a pooled
whole-sequence vector ([d_model] float32, --pool mean/max/cls).
--out_dir (default ./embeddings) gets:
<id>.npzper sequence:per_residue,pooled(+logitswith--logits);--format npz, defaultembeddings.parquet: pooled vectors, one row per sequence;--format parquetmanifest.json: model/pool/shapes/dtype and which file holds each sequence
Add --logits for the per-residue amino-acid predictions (300M/600M only),
and --fast for the lower-precision weight path. Weights download automatically on
first use.
Sequences batch automatically on 300M/600M (--batch_size, default 8): a
padded, length-bucketed device forward per batch, masked so results are
identical to running each sequence alone.
To embed a large batch faster, shard it across several cards with
--devices 0,1,2,3: one worker per card, results reassembled in input order
and identical to a single-card run:
tt-bio embed proteins.fasta --model esmc-600m --devices 0,1,2,3
Measured, not assumed: fanout only pays off when there's enough work per shard to amortize each worker's model-load and device-init cost. On small batches it can be flat or worse than a single card. esmc-6b scales to 4 cards on suitably large batches. See docs/esmc-multicard-scaling.md for the numbers before reaching for --devices on a small job.
For repeated/production embedding, submit to a persistent pool instead: a worker loads its model once and keeps it resident across every call, so the reload cost above is paid once per worker, not once per invocation:
tt-bio controller --listen 8765 # starts + keeps a worker per local card
tt-bio embed proteins.fasta --model esmc-6b --controller http://localhost:8765
The same capability is available from Python:
from tt_bio import esmc
emb = esmc.embed("MQIFVKTLTGKTITLEV...", model="esmc-600m")[0]
emb.per_residue # [L, d_model] float32
emb.pooled # [d_model] float32
# Shard a large set across cards (data-parallel, order preserved):
embs = esmc.embed(sequences, model="esmc-600m", devices=[0, 1, 2, 3])
Structure-Aware Protein Embeddings (SaProt)
SaProt is a structure-aware protein language model — an ESM-2 encoder over a fused
amino-acid + Foldseek 3Di vocabulary (446 tokens). Where ESMC is sequence-only, SaProt
also encodes local structure, so its embeddings and MLM logits reflect both sequence
and shape. Use it for variant-effect / mutation-fitness scoring and function prediction
when you have a structure (predicted or experimental — fold it with tt-bio predict
first, then score it with SaProt).
tt-bio saprot proteins.fasta --model saprot-650m --structure structs/ --out_dir embeddings
tt-bio saprot proteins.fasta --model saprot-650m # sequence-only (3Di = '#')
--structure is a PDB/cif file (single sequence) or a directory of <id>.pdb/<id>.cif
files, one per FASTA id. The 3Di structural tokens are computed on host with
Foldseek (conda install -c bioconda foldseek,
or set FOLDSEEK_BIN); it runs off-device. Omit --structure for sequence-only mode
(lower accuracy for 35M/650M; the 1.3B works sequence-only).
For each sequence you get per-residue structure-aware embeddings ([length, d_model]
float32) and a pooled vector, plus per-residue MLM logits ([length, 446] with
--logits) over the fused vocabulary — the log-likelihoods used for zero-shot mutation
scoring. Output layout matches tt-bio embed (<id>.npz / embeddings.parquet /
manifest.json).
--model selects the variant (saprot-35m, saprot-650m, saprot-1.3b). Parity vs
the reference HuggingFace checkpoint and warm throughput are in
docs/saprot-parity.md. The 35M port is deferred; use 650M.
Python:
from tt_bio import saprot
emb = saprot.embed(("MQIFVKTLTGKTITLEV...", "dweweaepvrdidi..."), model="saprot-650m")[0]
emb.per_residue # [L, d_model] float32, structure-aware
emb.logits # [L, 446] float32 (with return_logits=True)
Offline MSA (Optional)
Use this if you have enough disk and RAM and want local MSA. This avoids external MSA server calls and is faster for repeated runs.
tt-bio msa
tt-bio predict examples/prot.yaml --model boltz2 --override
tt-bio msa downloads UniRef30 to ~/.boltz/msa_db (~100GB download, ~500GB on disk after indexing). predict auto-detects this path.
To add EnvDB and use it in prediction: EnvDB can improve MSA coverage when UniRef30 hits are weak, at higher disk/RAM cost.
tt-bio msa --db all
tt-bio predict examples/prot.yaml --model boltz2 --use_envdb --override
Key Options:
--override: Re-run from scratch, ignoring cached files--use_msa_server: Generate MSA via ColabFold API--msa_db_path: Use a local database at a custom path (e.g.--msa_db_path /data/colabfold_db)--use_envdb: Include EnvDB in offline MSA (tt-bio msa --db all)--accelerator=tenstorrent: Use Tenstorrent hardware (default, or usecpu/gpu)--fast: Makes some operations use a lower-precision numeric format that runs faster; accuracy is typically very close--debug: Show all raw output from the hardware and libraries instead of the progress display--debug --log: Same as--debug, but also print what each device is currently working on
Shared MSA Server (Optional)
Host the database on one machine and let others fetch MSAs from it over HTTP, so each prediction machine need not keep its own ~500GB copy.
# On the machine with the database:
tt-bio msa-server --listen 0.0.0.0:8765
# On any other machine (no local database needed):
tt-bio predict examples/prot.yaml --model protenix-v2 --msa_endpoint http://HOST:8765
The server runs the same offline colabfold_search and serves unpaired {hash}.a3m, with a shared cache and a search-concurrency cap (--max_concurrent). Add --token to require Authorization: Bearer <token>. --msa_endpoint applies to --model esmfold2/protenix-v2.
Binding Affinity Prediction (Boltz-2)
Predict binding affinity for protein-ligand complexes:
tt-bio predict examples/affinity.yaml --model boltz2 --use_msa_server --override --affinity_mw_correction
The --affinity_mw_correction flag applies molecular weight correction for more accurate predictions.
Input Format
ESMFold2 accepts protein inputs only. Protenix-v2 accepts proteins, DNA, RNA,
ligands, and covalent bond constraints. OpenDDE currently accepts proteins
only. Boltz-2 additionally supports affinity, pocket/contact constraints,
potentials, and user-supplied templates.
Create a YAML file describing your complex:
version: 1
sequences:
- protein:
id: A
sequence: MVTPEGNVSLVDESLLVGVTDEDRAVRSAHQFYERLIGLWAPAVMEAAHELGVFAALAEAPADSGELARRLDCDARAMRVLLDALYAYDVIDRIHDTNGFRYLLSAEARECLLPGTLFSLVGKFMHDINVAWPAWRNLAEVVRHGARDTSGAESPNGIAQEDYESLVGGINFWAPPIVTTLSRKLRASGRSGDATASVLDVGCGTGLYSQLLLREFPRWTATGLDVERIATLANAQALRLGVEERFATRAGDFWRGGWGTGYDLVLFANIFHLQTPASAVRLMRHAAACLAPDGLVAVVDQIVDADREPKTPQDRFALLFAASMTNTGGGDAYTFQEYEEWFTAAGLQRIETLDTPMHRILLARRATEPSAVPEGQASENLYFQ
- ligand:
id: B
smiles: 'N[C@@H](Cc1ccc(O)cc1)C(=O)O'
properties:
- affinity:
binder: B
Entity Types:
- Polymers (
protein,dna,rna): providesequence - Ligands (
ligand): providesmilesorccdcode
Multiple Identical Chains:
- protein:
id: [A, B] # Two identical chains
sequence: ...
Understanding Results
Output Structure
boltz_results_prot/
├── structures/
│ ├── prot.cif # Best-ranked predicted structure
│ └── prot_model_1.cif # Additional samples (if diffusion_samples > 1)
├── results.json # One entry per target with confidence/affinity metrics
├── power_profile.csv # (optional, --report-energy)
├── power_profile.png # (optional, --report-energy)
├── prot_pae.npz # (optional, --write_pae)
├── prot_pde.npz # (optional, --write_pde)
└── prot_embeddings.npz # (optional, --write_embeddings)
MSA results are cached in <out_dir>/msa/ (default ./msa/), keyed by sequence hash. The same protein sequence is never searched twice, even across different input files or runs. The MSA search uses all available CPU threads and keeps the database index memory-mapped for maximum speed.
Confidence Scores
Each target entry in results.json contains confidence metrics. The fields below are Boltz-2's; Protenix-v2 reports the same confidence_score / ptm / iptm / plddt (and all_runs when --diffusion_samples > 1, ranked best-first), while an ESMFold2 entry instead carries plddt (mean, 0-1), ptm when available, and n_residues / n_chains.
{
"id": "prot",
"status": "ok",
"confidence_score": 0.84,
"ptm": 0.84,
"iptm": 0.82,
"complex_plddt": 0.84,
"chains_ptm": {
"0": 0.85,
"1": 0.83
},
"pair_chains_iptm": {
"0": {"0": 0.85, "1": 0.72},
"1": {"0": 0.82, "1": 0.83}
}
}
confidence_score: Overall confidence (0-1, higher is better), calculated as 0.8 ×complex_plddt+ 0.2 ×iptm. Models are ranked by this scoreptm: Predicted TM-score for complex (0-1)iptm: Interface TM-score (0-1)complex_plddt: Average per-residue confidence (0-1)chains_ptm: Per-chain TM-scores (0-1)pair_chains_iptm: Per-chain-pair interface TM-scores (0-1)
Affinity Predictions
For affinity targets, the same results.json entry also contains:
{
"affinity_pred_value": 2.47,
"affinity_probability_binary": 0.41,
"affinity_pred_value1": 2.55,
"affinity_pred_value2": 2.19,
"affinity_probability_binary1": 0.50,
"affinity_probability_binary2": 0.42
}
affinity_probability_binary: Probability of binding (0-1). Use for hit discovery (higher = more likely to bind)affinity_pred_value: Predicted binding affinity as log10(IC50) in μM. Use for ligand optimization (lower = stronger binding). Only compare between known active moleculesaffinity_pred_value1,affinity_pred_value2: Individual model predictions for binding affinityaffinity_probability_binary1,affinity_probability_binary2: Individual model predictions for binding probability
Advanced Usage
Input Format Details
Proteins with Custom MSA
- protein:
id: A
sequence: MVTPEGNVSLVDES...
msa: ./path/to/msa.a3m
Proteins with Modifications
- protein:
id: A
sequence: MVTPEGNVSLVDES...
modifications:
- position: 5
ccd: PTR # Modified residue code
Ligands
- ligand:
id: B
smiles: 'CC1=CC=CC=C1' # SMILES string
# OR
ccd: ATP # CCD code
Constraints
Pocket and contact constraints are Boltz-2 only (they need a trained constraint embedder). Covalent bond constraints work with Boltz-2 and Protenix-v2.
Pocket Constraints (binding site):
constraints:
- pocket:
binder: B # Ligand chain
contacts: [[A, 10], [A, 11], [A, 12]] # Binding site residues
max_distance: 6.0 # Angstroms (4-20A, default 6A)
force: false # Use potential to enforce (default: false)
Contact Constraints:
constraints:
- contact:
token1: [A, 10]
token2: [A, 50]
max_distance: 8.0
force: false
Bond Constraints (covalent link, e.g. a covalent inhibitor, glycosylation, or disulfide; works with Boltz-2 and Protenix-v2):
constraints:
- bond:
atom1: [A, 10, SG] # [chain, residue, atom]
atom2: [B, 1, C12] # ligand atom by name; polymer atoms by residue
Templates
Use experimental structures as templates:
templates:
- cif: ./template.cif
chain_id: A
template_id: A
force: true # Enforce template alignment
threshold: 2.0 # Max deviation in Angstroms
Command-Line Options
Model-specific options are labelled below.
Common Options:
| Option | Default | Description |
|---|---|---|
--model |
boltz2 |
boltz2, esmfold2, esmfold2-fast (single-sequence ESMFold2), protenix-v2 (AlphaFold3-family folder; protein / RNA / DNA / ligand complexes), or opendde / opendde-abag (antibody-antigen co-folding on the Protenix-v2 stack plus a structural-token expander; opendde-abag selects the antibody-antigen checkpoint; protein-only for now) |
--out_dir |
./ |
Output directory |
--cache |
~/.boltz |
(Boltz-2) model cache directory; ESMFold2 uses the Hugging Face cache |
--accelerator |
tenstorrent |
(Boltz-2) tenstorrent, cpu, or gpu; other models run on Tenstorrent |
--recycling_steps |
model-specific | 3 for Boltz-2/ESMFold2; 10 for Protenix-v2/OpenDDE |
--sampling_steps |
200 |
Diffusion sampling steps |
--diffusion_samples |
1 |
Number of structure samples |
--output_format |
cif |
cif or pdb |
--override |
False |
Re-run from scratch |
--use_msa_server |
auto | Use the online ColabFold API; auto-enabled for Boltz-2/Protenix-v2/OpenDDE when no local DB is found |
--single_sequence |
False |
(Boltz-2/Protenix-v2/OpenDDE) Skip all MSA requests; lower accuracy |
--msa_endpoint |
— | Fetch unpaired MSAs from a tt-bio msa-server; OpenDDE pairing still uses --msa_server_url |
--use_potentials |
False |
(Boltz-2) Apply physical constraints |
--affinity_mw_correction |
False |
(Boltz-2) Apply MW correction to affinity |
--num_devices |
0 |
Number of TT devices (0=all available) |
--device_ids, --devices |
— | Comma-separated TT device IDs (e.g. 0,2); --devices is the shorter alias (matches tt-bio embed) |
--fast |
False |
Makes some operations use a lower-precision numeric format that runs faster; accuracy is typically very close |
--listen |
— | Accept worker connections from other machines; see Multi-Machine Prediction |
--report-energy |
False |
(Boltz-2) Enables optional energy profiling for one TT device (requires tt-mgmt add-on); writes power_profile.csv and power_profile.png |
--energy-metric |
both |
(Boltz-2) Choose power channel(s): tdp, input, or both |
--energy-sample-hz |
20.0 |
(Boltz-2) Sampling rate in Hz for both power_w and input_power_w channels |
Affinity-Specific Options (Boltz-2):
| Option | Default | Description |
|---|---|---|
--sampling_steps_affinity |
200 |
Sampling steps for affinity |
--diffusion_samples_affinity |
5 |
Number of affinity samples |
MSA Options (Boltz-2, Protenix-v2, and OpenDDE use an MSA by default; ESMFold2 only when requested):
| Option | Default | Description |
|---|---|---|
--msa_db_path |
auto-detect | Path to local ColabFold database (~/.boltz/msa_db if present) |
--use_envdb |
False |
Also search environmental database |
--use_msa_server |
auto | Use ColabFold API for MSA (auto-enabled when no local DB is found) |
--single_sequence |
False |
Fold without an MSA (Boltz-2/Protenix-v2/OpenDDE) |
--msa_server_url |
https://api.colabfold.com |
MSA server URL |
--msa_pairing_strategy |
greedy |
greedy or complete |
--max_msa_seqs |
8192 |
Maximum MSA sequences |
--subsample_msa |
False |
Subsample MSA |
--num_subsampled_msa |
1024 |
Number of subsampled sequences |
MSA Database Setup Options:
| Option | Default | Description |
|---|---|---|
--db |
uniref30 |
uniref30 (~500GB), envdb (~800GB), or all |
--path |
~/.boltz/msa_db |
Where to store the databases |
--install-tools |
True |
Auto-install missing mmseqs/colabfold_search |
MSA Server Authentication
For --use_msa_server:
Basic Authentication:
export BOLTZ_MSA_USERNAME=myuser
export BOLTZ_MSA_PASSWORD=mypassword
tt-bio predict ... --model boltz2 --use_msa_server
API Key Authentication:
export MSA_API_KEY_VALUE=your-api-key
tt-bio predict ... --model boltz2 --use_msa_server
Optional: Multi-Machine Prediction
Combine the cards across any mix of Tenstorrent machines (a workstation, one or more QuietBoxes, one or more Galaxy servers) into a single run.
On the machine driving the run:
tt-bio predict ./proteins --model boltz2 --listen 8765 --use_msa_server --fast
On every additional machine, replace HOST with the driving machine's
hostname or IP:
tt-bio worker --connect http://HOST:8765
Optional: Energy Measurement (Boltz-2)
Use --report-energy to profile energy during prediction:
tt-bio predict examples/686.yaml --model boltz2 --override --device_ids 0 --report-energy --energy-metric both --energy-sample-hz 5
Behavior:
- Select metric channel(s) with
--energy-metric(tdp,input,both) - Uses one sampling rate (
--energy-sample-hz, default 20 Hz) - Supports only Tenstorrent runs with one selected device
- Records two power channels when available:
power_w:tt-mgmtUMD telemetry power (TDP channel)input_power_w:tt-mgmtUMD telemetry input power
- Requires optional
tt-mgmtinstallation:git clone --recursive https://github.com/aperezvicente-TT/tt-mgmt.gitpip install -e ./tt-mgmt
- Prints energy summary metrics for selected channels
- Always writes:
power_profile.csvpower_profile.png
BoltzGen
BoltzGen designs protein binders against a target. The pipeline runs design → inverse folding → folding → analysis → filtering and writes the top-ranked binders to <output>/final_ranked_designs/.
tt-bio gen run examples/binder.yaml --num_designs 10
This automatically uses every available card (splitting the designs across them and merging the results) and writes to ./binder/. Add --device_ids 0,2 to run on specific cards only.
Input Format
entities:
- protein:
id: B
sequence: 80..120 # designed chain, sampled length per design
- file:
path: target.cif # target structure (path relative to this yaml)
include:
- chain:
id: A
80..120 randomises the binder length per design; a fixed integer pins it. Ligand, DNA, and RNA targets use the same YAML grammar as tt-bio predict. See the BoltzGen examples for binding sites, scaffolds, and residue constraints.
Protocols
--protocol sets defaults appropriate for the binder type.
| Protocol | Use for |
|---|---|
protein-anything (default) |
de-novo protein binder |
peptide-anything |
peptide binder |
nanobody-anything |
nanobody / VHH |
antibody-anything |
antibody |
protein-small_molecule |
binder against a small-molecule target (adds affinity step) |
protein-redesign |
re-design existing residues (e.g. symmetric dimers) |
Running a Subset
--steps restricts the pipeline.
tt-bio gen run examples/binder.yaml --steps design --num_designs 10
tt-bio gen run examples/binder.yaml --output existing/ --steps analysis filtering
Command-Line Options
| Option | Default | Description |
|---|---|---|
--protocol |
protein-anything |
Protocol; sets defaults appropriate for the binder type |
--num_designs |
10000 |
Number of binders to generate |
--budget |
30 |
Number of top designs kept after filtering |
--output |
./<basename>/ |
Output directory |
--steps |
(all) | Run only specific stages |
--config STEP key=val |
— | Override per-stage config (e.g. --config design sampling_steps=200) |
--device_ids |
all cards | Restrict to specific cards (e.g. 0,2) |
--fast |
False |
Use a lower-precision path for some ops (slightly lower precision, faster) |
--cache |
~/.boltz/boltzgen |
Cache for downloaded weights |
--debug |
False |
Disable live display; show raw stage output |
--debug --log |
False |
Add per-stage progress markers |
Sequence Design (ProteinMPNN)
ProteinMPNN designs the amino-acid sequence most likely to fold into a fixed backbone (inverse folding) — the step run after a backbone generator like BoltzGen, or any bring-your-own-backbone PDB.
tt-bio design backbone.pdb --num-sequences 8 --checkpoint v_48_020.pt
Runs on CPU; a data-parallel fanout of processes scales throughput near-linearly (see docs/proteinmpnn-port.md). Writes <name>.fasta to --out-dir.
Command-Line Options
| Option | Default | Description |
|---|---|---|
--sequence-model |
proteinmpnn |
Inverse-folding model |
--num-sequences |
1 |
Sequences to sample per backbone |
--temperature |
0.1 |
Sampling temperature (lower = higher recovery, less diverse) |
--seed |
— | RNG seed for reproducible designs |
--checkpoint |
$PROTEINMPNN_CKPT |
ProteinMPNN checkpoint (v_48_0XX.pt) |
--out-dir |
./design |
Output directory |
Cite
If you use this code or the models in your research, please cite the following papers:
@article{passaro2025boltz2,
author = {Passaro, Saro and Corso, Gabriele and Wohlwend, Jeremy and Reveiz, Mateo and Thaler, Stephan and Somnath, Vignesh Ram and Getz, Noah and Portnoi, Tally and Roy, Julien and Stark, Hannes and Kwabi-Addo, David and Beaini, Dominique and Jaakkola, Tommi and Barzilay, Regina},
title = {Boltz-2: Towards Accurate and Efficient Binding Affinity Prediction},
year = {2025},
doi = {10.1101/2025.06.14.659707},
journal = {bioRxiv}
}
@article{stark2025boltzgen,
author = {Stark, Hannes and Faltings, Felix and Choi, MinGyu and Xie, Yuxin and Hur, Eunsu and O'Donnell, Timothy John and Bushuiev, Anton and U{\c c}ar, Talip and Passaro, Saro and Mao, Weian and Reveiz, Mateo and Bushuiev, Roman and Pluskal, Tom{\'a}{\v s} and Sivic, Josef and Kreis, Karsten and Vahdat, Arash and Ray, Shamayeeta and Goldstein, Jonathan T. and Savinov, Andrew and Hambalek, Jacob A. and Gupta, Anshika and Taquiri-Diaz, Diego A. and Zhang, Yaotian and Hatstat, A. Katherine and Arada, Angelika and Kim, Nam Hyeong and Tackie-Yarboi, Ethel and Boselli, Dylan and Schnaider, Lee and Liu, Chang C. and Li, Gene-Wei and Hnisz, Denes and Sabatini, David M. and DeGrado, William F. and Wohlwend, Jeremy and Corso, Gabriele and Barzilay, Regina and Jaakkola, Tommi},
title = {BoltzGen: Toward Universal Binder Design},
year = {2025},
doi = {10.1101/2025.11.20.689494},
journal = {bioRxiv}
}
@article{wohlwend2024boltz1,
author = {Wohlwend, Jeremy and Corso, Gabriele and Passaro, Saro and Getz, Noah and Reveiz, Mateo and Leidal, Ken and Swiderski, Wojtek and Atkinson, Liam and Portnoi, Tally and Chinn, Itamar and Silterra, Jacob and Jaakkola, Tommi and Barzilay, Regina},
title = {Boltz-1: Democratizing Biomolecular Interaction Modeling},
year = {2024},
doi = {10.1101/2024.11.19.624167},
journal = {bioRxiv}
}
@misc{candido2026language,
author = {Candido, Salvatore and Hayes, Thomas and Derry, Alexander and Rao, Roshan and Lin, Zeming and Verkuil, Robert and others},
title = {Language Modeling Materializes a World Model of Protein Biology},
year = {2026},
url = {https://biohub.ai/papers/esm_protein.pdf},
note = {Preprint; ESMC / ESMFold2}
}
@misc{protenix2025,
author = {{ByteDance AML AI4Science Team}},
title = {Protenix: An AlphaFold3 Reproduction for Biomolecular Structure Prediction},
year = {2025},
url = {https://github.com/bytedance/Protenix}
}
In addition if you use the automatic MSA generation, please cite:
@article{mirdita2022colabfold,
title={ColabFold: making protein folding accessible to all},
author={Mirdita, Milot and Sch{\"u}tze, Konstantin and Moriwaki, Yoshitaka and Heo, Lim and Ovchinnikov, Sergey and Steinegger, Martin},
journal={Nature methods},
year={2022}
}
License
tt-bio is released under the MIT License (see LICENSE) and is built on the MIT-licensed Boltz-2 / Boltz-1 code. It bundles third-party code, each under its upstream license: the ESMFold2 host-side reference under tt_bio/_vendor/ (the esm pipeline, MIT, © Chan Zuckerberg Biohub; and the HuggingFace ESMFold2 model definition, Apache-2.0) and the BoltzGen binder-design source under tt_bio/boltzgen/ (MIT, © Hannes Stärk). Protenix-v2 is an independent ttnn reimplementation (no upstream code is vendored) and its weights download from ByteDance's Hugging Face mirror under Apache-2.0. See NOTICE for sources, versions, and modifications.
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file tt_bio-0.3.1.tar.gz.
File metadata
- Download URL: tt_bio-0.3.1.tar.gz
- Upload date:
- Size: 774.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ba9523c55c80f7a65defca8154fdedd90a294999320398ef1eb519264b9b1fb1
|
|
| MD5 |
e0b7d8bf770821fe5a7581c2a2d5bd4a
|
|
| BLAKE2b-256 |
ef5d3b2af3df5c21e5460d94c6ae4864b7839492fd3ee14fe3a1ee7f361e22fa
|
Provenance
The following attestation bundles were made for tt_bio-0.3.1.tar.gz:
Publisher:
release.yaml on moritztng/tt-bio
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
tt_bio-0.3.1.tar.gz -
Subject digest:
ba9523c55c80f7a65defca8154fdedd90a294999320398ef1eb519264b9b1fb1 - Sigstore transparency entry: 2199785141
- Sigstore integration time:
-
Permalink:
moritztng/tt-bio@19cf0a1fb7fa2705c0fdc54cfc8ac59d105e87ae -
Branch / Tag:
refs/tags/v0.3.1 - Owner: https://github.com/moritztng
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yaml@19cf0a1fb7fa2705c0fdc54cfc8ac59d105e87ae -
Trigger Event:
push
-
Statement type:
File details
Details for the file tt_bio-0.3.1-py3-none-any.whl.
File metadata
- Download URL: tt_bio-0.3.1-py3-none-any.whl
- Upload date:
- Size: 766.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
005924a188e1a14d73533fa8c2148f8ddbb248efb63be1edcee9dd32ad187851
|
|
| MD5 |
a68693aaa8463fdc0ede57aba855bfcc
|
|
| BLAKE2b-256 |
cb153cd40f44a9647d6f38b9b1bbc3d86eb3512664dbcbfc008050e3c9eade84
|
Provenance
The following attestation bundles were made for tt_bio-0.3.1-py3-none-any.whl:
Publisher:
release.yaml on moritztng/tt-bio
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
tt_bio-0.3.1-py3-none-any.whl -
Subject digest:
005924a188e1a14d73533fa8c2148f8ddbb248efb63be1edcee9dd32ad187851 - Sigstore transparency entry: 2199785203
- Sigstore integration time:
-
Permalink:
moritztng/tt-bio@19cf0a1fb7fa2705c0fdc54cfc8ac59d105e87ae -
Branch / Tag:
refs/tags/v0.3.1 - Owner: https://github.com/moritztng
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yaml@19cf0a1fb7fa2705c0fdc54cfc8ac59d105e87ae -
Trigger Event:
push
-
Statement type: