Caliby

License: Caliby is open source and free for academic and commercial use under an Apache-2.0 license and may require explicit attribution when utilized. Please refer to the license for full terms.

Proto is not affiliated with Stanford University. This toolkit is open source and builds on the implementation produced by this organization. Product names, logos, and trademarks are the property of their respective owners.

GitHub 120 GitHub 120

HuggingFace

HuggingFace Preprint Preprint Cite Cite Tool Source Tool Source Open as Notebook Open as Notebook Open on Proto Open on Proto

ProteinDesignLab/caliby

Potts model-based protein sequence design

120 stars

View repo

ProteinDesignLab/caliby-weights

View model

Ensemble-conditioned protein sequence design with Caliby

Richard W. Shuai, Tianyu Lu, … Po-Ssu Huang

bioRxiv (2025)

Read preprint

@articleshuai2025caliby

@article{shuai2025caliby,
  title={Ensemble-conditioned protein sequence design with {Caliby}},
  author={Shuai, Richard W. and Lu, Tianyu and Bhatti, Subhang and Kouba, Petr and Huang, Po-Ssu},
  journal={bioRxiv},
  year={2025},
  publisher={Cold Spring Harbor Laboratory},
  doi={10.1101/2025.09.30.679633},
  url={https://www.biorxiv.org/content/10.1101/2025.09.30.679633}
}

Copy citation

evo-design/proto-tools

Toolkit contributors

Function	Description
`run_caliby_pack()`	Pack protein sidechains onto a backbone using Caliby’s diffusion packer (GPU)	Docs Source
`run_caliby_sample()`	Design protein sequences with Caliby, optionally conditioned on a conformer ensemble (GPU)	Docs Source
`run_caliby_score()`	Score a structure’s native sequence under the Caliby Potts model (GPU)	Docs Source

Background

Caliby (Shuai et al., 2025) starts from the hypothesis that training a sequence designer to maximize native sequence recovery rewards reproducing non-structural signal, such as phylogenetic relatedness, neutral drift, and dataset sampling bias, instead of a broadly generalizable structure-to-sequence mapping. Its response is to make the learned energy explicit. A ProteinMPNN-style graph network, three encoder layers and three decoder layers with the decoder’s causal mask removed, encodes the backbone, and a Potts decoder adapted from ChromaDesign (Ingraham et al., 2023) projects the node and edge embeddings into the sitewise fields and pairwise couplings of a Potts model over amino-acid identities. Training maximizes the composite pseudo-likelihood of the native sequence; design then samples that energy by discrete Langevin Monte Carlo at a temperature annealed from 1.0, under a local composition restraint that penalizes low-complexity sequences. An energy built only from sitewise and pairwise terms is linear in its parameters, so the average of the energies of several backbones is itself one Potts model whose fields and couplings are the per-structure averages. Those averaged parameters are computed once, which makes ensemble-conditioned sampling no more expensive than single-structure sampling, and the distribution they define is the normalized geometric mean of the per-structure distributions. The paper conditions on the input backbone plus 15 conformers drawn from Protpardelle-1c partial diffusion (Lu et al., 2025), and the reference implementation’s batch pipeline defaults to 32 per ensemble. Averaging in this way suppresses the native-sequence bias carried by any single snapshot: ensemble-conditioned design lowers native sequence recovery yet substantially raises AlphaFold2 self-consistency, outperforming ProteinMPNN and ChromaDesign on both native and de novo backbones. A soluble-only variant further shows, in silico, that Protpardelle-1c binder designs previously filtered out as undesignable by SolubleMPNN (Goverde et al., 2024) are designable, which the authors read as a limitation of the filtering pipelines rather than of the backbones. That result is computational; the paper reports no experimental validation of those binders. That explicit, pairwise form is what makes the averaging possible, and it is the structural difference from the autoregressive decoding of ProteinMPNN and LigandMPNN or the iterative unmasking of FAMPNN, where there is no single closed-form scoring function to combine across structures. Design itself only assigns residue identities and leaves coordinates untouched, so Caliby ships a separate diffusion-based sidechain packer that predicts sidechain coordinates by denoising in each residue’s local backbone frame. The reference implementation is maintained at ProteinDesignLab/caliby and was developed at Stanford University.

Learning Resources

Caliby Python API guide (Protein Design Lab, Stanford) - the upstream programmatic interface, covering checkpoint loading, ensemble layout, positional constraints, scoring, and the input-structure cleaner.
Caliby Colab notebook (Protein Design Lab, Stanford) - an interactive walk-through of ensemble generation followed by ensemble-conditioned design.
Protpardelle-1c (Protein Design Lab, Stanford) - the partial-diffusion backbone model used to generate the synthetic ensembles Caliby conditions on, and the source of the binder designs re-evaluated in the paper.

Tools

Caliby Sampling (`caliby-sample`)

Designs sequences for one or more fixed backbones by sampling the Potts model, optionally conditioned on a conformer ensemble supplied per structure. Each design comes back as a complex with its threaded structure, its Potts energy, and its recovery against the input structure’s native sequence.

API Reference

Source

Input: CalibySampleInput

List[CalibyStructureInput]

required

Per-structure inputs, each a primary conformer plus optional ensemble members and design constraints.

Show CalibyStructureInput

List[Structure]

Additional conformers of the same molecule. Each must have the same chain IDs and per-chain residue counts as structure. Empty means single-structure design.

array

Chain groups designed to a single shared sequence, one group per set of tied chains. Caliby folds each group’s Potts parameters into one variable before sampling, so the tied chains are identical by construction and the reported energy describes that assembly. Without it the chains of a homooligomer are designed independently and come out different. Chains in a group must share residue numbering.

ResidueIdentitySelection

Residue identities to place at chosen positions and hold fixed (1-indexed). Unlike fixed_positions, which conditions on whatever the structure already carries, this supplies the identity, so it can pin a residue the structure does not have. Caliby conditions on these positions, so they must not also appear in fixed_positions.

Structure

required

Primary conformer. Accepts a file path, raw PDB/CIF content string, Structure object, or a dict in the shape produced by Structure.model_dump(mode='json'). Inherited from :class:InverseFoldingStructureInput.

ChainSelection

Chains to redesign. None means redesign every chain. Inherited from :class:InverseFoldingStructureInput.

ResidueSelection

Per-chain positions whose residue identity is held fixed (1-indexed). Inherited from :class:InverseFoldingStructureInput.

Source

Config: CalibySampleConfig

string

default:"caliby"

Bundled design checkpoint name or a path to a .ckpt file. 'caliby' is the default all-chain model; 'soluble_caliby' excludes transmembrane proteins; the _distill variants skip ensemble generation and suit fast screening but are not recommended for multistate design.

integer

default:"1"

Sequences to design per input structure.

integer

default:"4"

Conformers passed through the model per forward pass when conditioning on an ensemble. Reduce on GPU out-of-memory errors. Has no effect without conformers, since designs are sampled sequentially from one set of Potts parameters rather than batched.

number

default:"0.01"

Final Potts sampling temperature. Caliby anneals from 1.0 down to this value; raise it for more diverse sequences.

integer

default:"500"

MCMC sweeps per designed sequence. More sweeps converge closer to the Potts optimum at proportional cost.

array

One-letter codes never placed at any designed position.

boolean

default:"True"

Take residue identities from the primary conformer rather than each conformer’s own. Ensemble-conditioned design only.

integer

default:"0"

Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). True is coerced to 1 and False to 0.

string

default:"cuda"

Device to run the model on.

integer

default:"3600"

Maximum execution time in seconds. None waits indefinitely.

integer

Random seed. When set, tools run reproducibly up to small GPU float noise (see BaseToolOutput.approx_equal), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.

Source

Output: CalibySampleOutput

List[CalibyDesignSet]

required

One CalibyDesignSet per input structure, in input order.

Show CalibyDesignSet

List[CalibyDesign]

required

The complexes designed for one input structure.

Metrics (one set per design_sets item)

Metric	Type	Range	Availability
`potts_energy`	float	unbounded	always
`avg_potts_energy`	float	unbounded	always
`sequence_recovery`	float	0.0 to 1.0	always

Applications

Use this for fixed-backbone design, and in particular for backbones that are not idealized: native scaffolds, loop-rich folds, and diffusion-generated binders whose designs tend to fail refolding checks. Conditioning on an ensemble is the lever for exactly those cases, since the sequence is then scored against the conformational freedom the backbone actually has rather than one snapshot of it. For a first pass over many candidate backbones, a _distill checkpoint gives ensemble-conditioned behavior without the cost of generating an ensemble.

Usage Tips

conformers is what switches on ensemble-conditioned design. Leave it empty for ordinary single-structure design. When it is set, structure acts as the primary conformer: its residue identities are the ones broadcast across the ensemble, and it is the reference frame the other members align to. Every conformer must carry the same chain IDs and the same per-chain residue counts, which is checked when the input is constructed. Upstream recommends at least 32 conformers, with 8 or 16 also giving good results.
Designs are backbone-only. Caliby threads the designed residue identities onto the input coordinates without generating sidechains, so design.structure has no sidechain atoms. Pass it to caliby-pack to place them before docking, full-atom scoring, or molecular dynamics.
temperature (default 0.01) and potts_sweeps (default 500) set the diversity and convergence trade-off. Sampling anneals from 1.0 down to temperature, so raising it to 0.1 or 0.2 yields more diverse sequences at some cost in energy. More sweeps converge closer to the Potts optimum at proportional runtime.
model_checkpoint selects the training distribution. caliby is the default, trained on PDB chains with 0.3 Å Gaussian backbone noise, and soluble_caliby is its analog trained with annotated transmembrane proteins excluded; both see monomers only, so soluble_caliby_v1, trained on monomers and interfaces, is the better fit for interface design. The distilled caliby_distill and soluble_caliby_distill checkpoints skip ensemble generation and suit fast screening, but they are less sensitive to small backbone changes and are not recommended for multistate design.

Caliby Scoring (`caliby-score`)

Evaluates the Potts energy of the sequence an input structure already carries, optionally against a conformer ensemble. There is no separate sequence field: the sequence is read from the structure, so scoring a variant means supplying a structure that carries it.

API Reference

Source

Input: CalibyScoreInput

List[CalibyScoreStructureInput]

required

Per-structure inputs, each a structure whose native sequence is scored plus optional ensemble members.

Show CalibyScoreStructureInput

List[Structure]

Additional conformers of the same molecule. Each must have the same chain IDs and per-chain residue counts as structure. Empty means single-structure scoring.

Structure

required

Primary conformer, whose native sequence is scored. Accepts a file path, raw PDB/CIF content string, Structure object, or a dict in the shape produced by Structure.model_dump(mode='json').

Source

Config: CalibyScoreConfig

string

default:"caliby"

Bundled design checkpoint name or a path to a .ckpt file. Scoring uses the same models as design.

integer

default:"4"

Conformers per forward pass when scoring against an ensemble. Scoring a single structure passes one structure through at a time, so this has no effect there. Lower it first when an ensemble score runs out of GPU memory.

boolean

default:"False"

Include the per-position local conditional energy matrix in the output. Adds roughly seq_len x 22 floats per structure.

integer

default:"0"

Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). True is coerced to 1 and False to 0.

string

default:"cuda"

Device to run the model on.

integer

default:"3600"

Maximum execution time in seconds. None waits indefinitely.

integer

Source

Output: CalibyScoreOutput

List[CalibyScoringMetrics]

required

One entry per input structure, in input order.

Show CalibyScoringMetrics

string

The scored sequence, with ':' separating chains in alphabetical chain order.

array

Per-position local conditional energies, shape (seq_len, len(potts_tokens)). None unless return_local_energies is set.

array

Token ordering for local_conditional_energies. None when those are absent.

string

Name of the metric that best summarizes the result overall (e.g. "avg_plddt" for AlphaFold2). Used by downstream UI and reporting to pick a headline value.

string

Concrete Metrics subclass tag; enables typed reconstruction after a serialization round-trip.

Metrics (one set per scores item)

Metric	Type	Range	Availability
`potts_energy`	float	unbounded	always
`avg_potts_energy`	float	unbounded	always

Applications

Use this to rank sequence-structure pairs under the same energy that drives design, for example comparing a design against the native sequence on the same backbone, checking how a candidate holds up across a conformational ensemble before committing to it, or choosing between checkpoints on a held-out set. return_local_energies additionally exposes the per-position conditional energy matrix for residue-level analysis.

Usage Tips

The Potts energy is unnormalized, not a log-likelihood. Probability is proportional to exp(-U/T) for a sampling temperature T that scoring never fixes, so there is no perplexity to read off; the number is a ranking quantity, not a calibrated one. Lower is more favorable.
potts_energy scales with sequence length, so compare avg_potts_energy across structures of different sizes. The summed energy is the right quantity only when ranking sequences on one backbone.
Energies are comparable only within one checkpoint. Each checkpoint defines a different energy function, so designs scored under caliby cannot be ranked against designs scored under soluble_caliby.
return_local_energies (default False) adds a per-position matrix of shape (seq_len, len(potts_tokens)). Read its columns through the returned potts_tokens ordering, which is a reduced alphabet rather than a full token vocabulary. Leave it off when scoring many structures, since it adds roughly seq_len x 22 floats per input.
With an ensemble, only the primary conformer’s sequence is scored. The other members contribute backbone geometry alone; their residue identities are ignored.

Caliby Sidechain Packing (`caliby-pack`)

Places sidechain atoms for the residue identities each input structure already carries, by diffusion in that residue’s local backbone frame. Returns one packed full-atom structure per input.

API Reference

Source

Input: CalibyPackInput

List[Structure]

required

Structures to pack sidechains onto. Accepts file paths, raw PDB/CIF content strings, or Structure objects per item. Each must already carry the sequence to pack. Packing places sidechain atoms for the residue identities the structure already has.

Show Structure

string

required

Raw structure content in PDB or CIF format.

string

Format of the content string (auto-detected if omitted).

BFactorType

default:"unspecified"

What the B-factor column represents.

string

Optional source identifier (filepath or tool name).

Metrics

Associated metrics (e.g., pLDDT, pTM scores, per-chain lists, pairwise matrices). None values are stripped at construction.

Source

Config: CalibyPackConfig

string

default:"caliby_packer_010"

Bundled packer checkpoint name or a path to a .ckpt file. The suffix is the training noise level in Angstroms: 'caliby_packer_010' (0.1 A) is recommended for most cases, 'caliby_packer_000' for noise-free backbones, 'caliby_packer_030' for noisier ones. Packing needs a packer checkpoint; design checkpoints are rejected.

integer

default:"50"

Sidechain diffusion denoising steps.

number

default:"1.5"

Step scale (eta) for sidechain diffusion.

integer

default:"0"

Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). True is coerced to 1 and False to 0.

string

default:"cuda"

Device to run the model on.

integer

default:"3600"

Maximum execution time in seconds. None waits indefinitely.

integer

Source

Output: CalibyPackOutput

List[Structure]

required

Packed full-atom structures, one per input structure, in input order.

Show Structure

string

required

Raw structure content in PDB or CIF format.

string

Format of the content string (auto-detected if omitted).

BFactorType

What the B-factor column represents.

string

Optional source identifier (filepath or tool name).

Metrics

Associated metrics (e.g., pLDDT, pTM scores, per-chain lists, pairwise matrices). None values are stripped at construction.

Applications

Use this as the companion step to caliby-sample, whose designs carry no sidechains, and more generally to build a full-atom model from a backbone plus a known sequence before docking, full-atom scoring, or molecular dynamics. It also serves to rebuild sidechains on structures that arrive incomplete from another pipeline.

Usage Tips

Packing requires a caliby_packer_* checkpoint. Packing and design are distinct model tasks trained with different objectives, which is why they are separate tools; a design checkpoint passed here is rejected during config validation, as is a packer checkpoint passed to caliby-sample or caliby-score.
The packer suffix is the training noise level in angstroms. caliby_packer_010 (0.1 Å) is the default and the upstream recommendation for most cases, caliby_packer_000 targets noise-free backbones, and caliby_packer_030 noisier ones.
diffusion_steps (default 50) and step_scale (default 1.5) match the reference implementation. They control the denoising trajectory and are worth changing only for a specific packing experiment.

Toolkit Notes

These apply to every Caliby tool in this toolkit (caliby-sample, caliby-score, caliby-pack).

Requires a GPU. Both the Potts network and the diffusion packer are impractical on CPU for anything beyond a smoke test.
Checkpoints download automatically when the tool environment is built. They are hosted on HuggingFace under the same Apache-2.0 terms as the code, with no token or terms acceptance required. A model_checkpoint value ending in .ckpt is treated as a path to a custom local checkpoint instead of a bundled name.
Clean externally sourced PDB and CIF files before design. Upstream recommends it for any structure that came out of another pipeline, and especially for ensembles: blank chain IDs, unresolved atoms, and inconsistent residue indexing are what make conformers misalign with the primary conformer, and a misalignment silently degrades the aggregated Potts parameters rather than failing loudly.
The ensemble is declared per structure, not per run. conformers lives on each structure input, so one call can mix single-structure and ensemble-conditioned designs.
batch_size counts conformers, not designs. It sets how many ensemble members pass through the model at once, so it applies to ensemble-conditioned design only and is the first thing to lower when such a run hits GPU out-of-memory. Designs are sampled one at a time from a single set of Potts parameters, so raising num_sequences_per_structure costs sampling time but no extra memory.
Positions are 1-indexed ordinals within each chain, not residue numbers. Position i in fixed_positions or pinned_residues is the chain’s i-th residue, whatever the file numbers it, so offset numbering, gaps and insertion codes (10, 10A, 11) all resolve correctly. Structures reach Caliby renumbered 1..N per chain, because its position syntax cannot express insertion codes; designed and packed structures come back in the input’s original numbering. The same ordinal applies to every conformer, so conformers only need matching per-chain residue counts.
Tie the chains of a homooligomer with symmetric_chains. Chains are otherwise designed independently, so the copies of a homooligomer come out with different sequences and the reported energy describes an assembly that cannot be built from one gene. symmetric_chains=["A", "B", "C"] folds the tied positions into a single variable before sampling, so the copies are identical by construction and the energy covers the interface couplings between them. Chains tied together must share residue numbering, insertion codes included.
pinned_residues places a residue; fixed_positions keeps the one already there. fixed_positions conditions on whatever identity the input structure carries, so it cannot pin a residue the structure lacks. pinned_residues={"A": {26: "W"}} supplies the identity, writes it into the design, and conditions on it. A position cannot appear in both. Pinned positions also shift sequence_recovery: it is measured against the supplied identities rather than the structure’s original sequence, and those positions count as recovered by construction.
Protein chains of at least five residues are all the model sees. Caliby’s sequence-design featurizer keeps peptide polymers of five residues or more and discards everything else, so ligands, ions, and nucleic acids never reach the model. A bound ligand is dropped silently: design succeeds, but the binding site is designed as though it were empty. A DNA or RNA chain, or a peptide shorter than five residues, is counted as a polymer chain here but dropped by Caliby, so such a structure is rejected with a message naming the mismatch. To design against a bound ligand or nucleic acid, use LigandMPNN instead.

Example notebook: See the full working example for a copy-paste-ready walkthrough.

Infrastructure Guides

The following guides cover how to run tools efficiently and at scale.

Tool Persistence

Keep a tool’s model warm across calls instead of reloading it every invocation.

Device Management

How GPUs are allocated to tools and how to target specific devices.

Parallel Execution

Fan a batch of inputs out across multiple GPUs.

Tools

Guides

Tool Catalog

Concepts

Implementing a Tool

Background

Learning Resources

Tools

Caliby Sampling (`caliby-sample`)

API Reference

Applications

Usage Tips

Caliby Scoring (`caliby-score`)

API Reference

Applications

Usage Tips

Caliby Sidechain Packing (`caliby-pack`)

API Reference

Applications

Usage Tips

Toolkit Notes

Infrastructure Guides

Tool Persistence

Device Management

Parallel Execution

​Background

​Learning Resources

​Tools

​Caliby Sampling (caliby-sample)

​API Reference

​Applications

​Usage Tips

​Caliby Scoring (caliby-score)

​API Reference

​Applications

​Usage Tips

​Caliby Sidechain Packing (caliby-pack)

​API Reference

​Applications

​Usage Tips

​Toolkit Notes

​Infrastructure Guides

Tool Persistence

Device Management

Parallel Execution

Background

Learning Resources

Tools

Caliby Sampling (`caliby-sample`)

API Reference

Applications

Usage Tips

Caliby Scoring (`caliby-score`)

API Reference

Applications

Usage Tips

Caliby Sidechain Packing (`caliby-pack`)

API Reference

Applications

Usage Tips

Toolkit Notes

Infrastructure Guides