> ## Documentation Index
> Fetch the complete documentation index at: https://proto.evodesign.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Caliby

> [Caliby](https://github.com/ProteinDesignLab/caliby) designs sequences for a fixed protein backbone with a Potts model: a graph neural network reads backbone geometry and emits an explicit pairwise energy function, which is then sampled by Monte Carlo. Because that energy is explicit, it can be averaged across a set of conformers, so a sequence is designed against a distribution of backbones rather than one static snapshot. The toolkit also scores the native sequence of a structure and packs sidechains onto a designed backbone.

![Caliby](https://proto-bio.github.io/proto-assets/images/tool/caliby/hero.png)[![](https://mintcdn.com/bio-pro/Bgc19Em8MDwlJakq/assets/images/cached/30c2d8dfa42f.png?fit=max\&auto=format\&n=Bgc19Em8MDwlJakq\&q=85\&s=e0427cf93eecd8fadd924cc436b3a639) Stanford University](https://proto.evodesign.org/docs/tools/organizations/stanford-university.md)

> [!NOTE]
>
> **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](https://github.com/ProteinDesignLab/caliby/blob/main/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 ![](https://huggingface.co/front/assets/huggingface_logo-noborder.svg) HuggingFace![](https://huggingface.co/front/assets/huggingface_logo-noborder.svg) HuggingFace  Preprint Preprint  Cite Cite  Tool Source Tool Source  Open as Notebook Open as Notebook  Open on Proto Open on Proto

![ProteinDesignLab/caliby](https://opengraph.githubassets.com/1/ProteinDesignLab/caliby)

 ProteinDesignLab/calibyPotts model-based protein sequence design 120 stars

 View repo

[Open](https://github.com/ProteinDesignLab/caliby)

![ProteinDesignLab/caliby-weights](https://cdn-thumbnails.huggingface.co/social-thumbnails/models/ProteinDesignLab/caliby-weights.png)

![](https://huggingface.co/front/assets/huggingface_logo-noborder.svg) ProteinDesignLab/caliby-weights

![](https://huggingface.co/front/assets/huggingface_logo-noborder.svg) View model

[Open](https://huggingface.co/ProteinDesignLab/caliby-weights)

Ensemble-conditioned protein sequence design with CalibyRichard W. Shuai, Tianyu Lu, ... Po-Ssu HuangbioRxiv (2025)

 Read preprint

[Open](https://doi.org/10.1101/2025.09.30.679633)

@articleshuai2025caliby

```bibtex theme={null}
@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

![Proto](https://mintcdn.com/bio-pro/cMLt8hAqaP9M3LKy/assets/logo/logo-light.svg?fit=max\&auto=format\&n=cMLt8hAqaP9M3LKy\&q=85\&s=f5e5dfd1b8f9b9db3a0be0e2eb01f678)

evo-design/proto-tools

 View source

[Open](https://github.com/evo-design/proto-tools/tree/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/inverse_folding/caliby)

Open Notebook

 Open notebook

[Open](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/inverse_folding/caliby/examples/example.ipynb)

![Proto](https://mintcdn.com/bio-pro/KVh0EKV-IKblvXR8/assets/logo/evo-logo-light.svg?fit=max\&auto=format\&n=KVh0EKV-IKblvXR8\&q=85\&s=0cb66034ba45618505501aee6ea5f5c1)

[Install MCP](https://proto.evodesign.org/docs/mcp/installation.md)

Toolkit contributors[![](https://avatars.githubusercontent.com/u/17075373?v=4\&s=64)sophial05](https://github.com/sophial05)

| Function | Description | |
| - | - | - |
| `run_caliby_pack()` | Pack protein sidechains onto a backbone using Caliby's diffusion packer (GPU) | [ Docs](#api-run-caliby-pack) [ Source](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/inverse_folding/caliby/caliby_pack.py#L188) |
| `run_caliby_sample()` | Design protein sequences with Caliby, optionally conditioned on a conformer ensemble (GPU) | [ Docs](#api-run-caliby-sample) [ Source](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/inverse_folding/caliby/caliby_sample.py#L773) |
| `run_caliby_score()` | Score a structure's native sequence under the Caliby Potts model (GPU) | [ Docs](#api-run-caliby-score) [ Source](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/inverse_folding/caliby/caliby_score.py#L303) |

## Background

Caliby ([Shuai et al., 2025](https://doi.org/10.1101/2025.09.30.679633)) 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](https://github.com/dauparas/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](https://www.nature.com/articles/s41586-023-06728-8)) projects the node and edge embeddings into the sitewise fields and pairwise couplings of a [Potts model](https://en.wikipedia.org/wiki/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](https://doi.org/10.1101/2025.08.18.670959)), 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](https://www.nature.com/articles/s41586-024-07601-y)) 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](https://github.com/ProteinDesignLab/caliby) and was developed at Stanford University.

### Learning Resources

* [Caliby Python API guide](https://github.com/ProteinDesignLab/caliby/blob/main/python_api.md) (Protein Design Lab, Stanford) - the upstream programmatic interface, covering checkpoint loading, ensemble layout, positional constraints, scoring, and the input-structure cleaner.
* [Caliby Colab notebook](https://colab.research.google.com/github/ProteinDesignLab/caliby/blob/main/notebooks/Caliby.ipynb) (Protein Design Lab, Stanford) - an interactive walk-through of ensemble generation followed by ensemble-conditioned design.
* [Protpardelle-1c](https://github.com/ProteinDesignLab/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](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/inverse_folding/caliby/caliby_sample.py#L382)

> **Input: CalibySampleInput**
>
> **inputs** `List[CalibyStructureInput]` *required*
>
> Per-structure inputs, each a primary conformer plus optional ensemble members and design constraints.
>
> **CalibyStructureInput**
>
> **conformers** `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.
>
> **symmetric\_chains** `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.
>
> **pinned\_residues** `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** `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`.
>
> **chains\_to\_redesign** `ChainSelection`
>
> Chains to redesign. `None` means redesign every chain. Inherited from :class:`InverseFoldingStructureInput`.
>
> **fixed\_positions** `ResidueSelection`
>
> Per-chain positions whose residue identity is held fixed (1-indexed). Inherited from :class:`InverseFoldingStructureInput`.

[ Source](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/inverse_folding/caliby/caliby_sample.py#L396)

> **Config: CalibySampleConfig**
>
> **model\_checkpoint** `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.
>
> **num\_sequences\_per\_structure** `integer` (default: 1)
>
> Sequences to design per input structure.
>
> **batch\_size** `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.
>
> **temperature** `number` (default: 0.01)
>
> Final Potts sampling temperature. Caliby anneals from 1.0 down to this value; raise it for more diverse sequences.
>
> **potts\_sweeps** `integer` (default: 500)
>
> MCMC sweeps per designed sequence. More sweeps converge closer to the Potts optimum at proportional cost.
>
> **excluded\_amino\_acids** `array`
>
> One-letter codes never placed at any designed position.
>
> **use\_primary\_res\_type** `boolean` (default: True)
>
> Take residue identities from the primary conformer rather than each conformer's own. Ensemble-conditioned design only.
>
> **verbose** `integer` (default: 0)
>
> Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`.
>
> **device** `string` (default: cuda)
>
> Device to run the model on.
>
> **timeout** `integer` (default: 3600)
>
> Maximum execution time in seconds. `None` waits indefinitely.
>
> **seed** `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](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/inverse_folding/caliby/caliby_sample.py#L578)

> **Output: CalibySampleOutput**
>
> **design\_sets** `List[CalibyDesignSet]` *required*
>
> One `CalibyDesignSet` per input structure, in input order.
>
> **CalibyDesignSet**
>
> **complexes** `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](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/inverse_folding/caliby/caliby_score.py#L72)

> **Input: CalibyScoreInput**
>
> **inputs** `List[CalibyScoreStructureInput]` *required*
>
> Per-structure inputs, each a structure whose native sequence is scored plus optional ensemble members.
>
> **CalibyScoreStructureInput**
>
> **conformers** `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** `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](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/inverse_folding/caliby/caliby_score.py#L86)

> **Config: CalibyScoreConfig**
>
> **model\_checkpoint** `string` (default: caliby)
>
> Bundled design checkpoint name or a path to a `.ckpt` file. Scoring uses the same models as design.
>
> **batch\_size** `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.
>
> **return\_local\_energies** `boolean` (default: False)
>
> Include the per-position local conditional energy matrix in the output. Adds roughly `seq_len x 22` floats per structure.
>
> **verbose** `integer` (default: 0)
>
> Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`.
>
> **device** `string` (default: cuda)
>
> Device to run the model on.
>
> **timeout** `integer` (default: 3600)
>
> Maximum execution time in seconds. `None` waits indefinitely.
>
> **seed** `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](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/inverse_folding/caliby/caliby_score.py#L205)

> **Output: CalibyScoreOutput**
>
> **scores** `List[CalibyScoringMetrics]` *required*
>
> One entry per input structure, in input order.
>
> **CalibyScoringMetrics**
>
> **sequence** `string`
>
> The scored sequence, with `':'` separating chains in alphabetical chain order.
>
> **local\_conditional\_energies** `array`
>
> Per-position local conditional energies, shape `(seq_len, len(potts_tokens))`. `None` unless `return_local_energies` is set.
>
> **potts\_tokens** `array`
>
> Token ordering for `local_conditional_energies`. `None` when those are absent.
>
> **primary\_metric** `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.
>
> **metric\_type** `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](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/inverse_folding/caliby/caliby_pack.py#L35)

> **Input: CalibyPackInput**
>
> **structures** `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.
>
> **Structure**
>
> **structure** `string` *required*
>
> Raw structure content in PDB or CIF format.
>
> **structure\_format** `string`
>
> Format of the content string (auto-detected if omitted).
>
> **b\_factor\_type** `BFactorType` (default: unspecified)
>
> What the B-factor column represents.
>
> **source** `string`
>
> Optional source identifier (filepath or tool name).
>
> **metrics** `Metrics`
>
> Associated metrics (e.g., pLDDT, pTM scores, per-chain lists, pairwise matrices). None values are stripped at construction.

[ Source](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/inverse_folding/caliby/caliby_pack.py#L59)

> **Config: CalibyPackConfig**
>
> **model\_checkpoint** `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.
>
> **diffusion\_steps** `integer` (default: 50)
>
> Sidechain diffusion denoising steps.
>
> **step\_scale** `number` (default: 1.5)
>
> Step scale (eta) for sidechain diffusion.
>
> **verbose** `integer` (default: 0)
>
> Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`.
>
> **device** `string` (default: cuda)
>
> Device to run the model on.
>
> **timeout** `integer` (default: 3600)
>
> Maximum execution time in seconds. `None` waits indefinitely.
>
> **seed** `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](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/inverse_folding/caliby/caliby_pack.py#L117)

> **Output: CalibyPackOutput**
>
> **packed\_structures** `List[Structure]` *required*
>
> Packed full-atom structures, one per input structure, in input order.
>
> **Structure**
>
> **structure** `string` *required*
>
> Raw structure content in PDB or CIF format.
>
> **structure\_format** `string`
>
> Format of the content string (auto-detected if omitted).
>
> **b\_factor\_type** `BFactorType`
>
> What the B-factor column represents.
>
> **source** `string`
>
> Optional source identifier (filepath or tool name).
>
> **metrics** `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](https://huggingface.co/ProteinDesignLab/caliby-weights) 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](../ligandmpnn/README.md) instead.

> [!TIP]
>
> **Example notebook:** See the [full working example](https://github.com/evo-design/proto-tools/blob/2cb961a77981438592bc527f8469b6b0c18cb98e/proto_tools/tools/inverse_folding/caliby/examples/example.ipynb) for a copy-paste-ready walkthrough.

## Infrastructure Guides

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

> **[Tool Persistence](https://proto.evodesign.org/docs/tools/guides/tool-persistence.md)**
>
> Keep a tool's model warm across calls instead of reloading it every invocation.

> **[Device Management](https://proto.evodesign.org/docs/tools/guides/device-management.md)**
>
> How GPUs are allocated to tools and how to target specific devices.

> **[Parallel Execution](https://proto.evodesign.org/docs/tools/guides/parallel-execution.md)**
>
> Fan a batch of inputs out across multiple GPUs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.