ESM-IF1

License: ESM-IF1 is open source and free for academic and commercial use under an MIT license. Please refer to the license for full terms.

Proto is not affiliated with Meta AI and Biohub. This toolkit is open source and builds on the implementations produced by these organizations. Product names, logos, and trademarks are the property of their respective owners.

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

facebookresearch/esm

View repo

Learning inverse folding from millions of predicted structures

Chloe Hsu, Robert Verkuil, … Alexander Rives

bioRxiv (2022)

Read preprint

@inproceedings{hsu2022learning,
  title={Learning inverse folding from millions of predicted structures},
  author={Hsu, Chloe and Verkuil, Robert and Liu, Jason and Lin, Zeming and Hie, Brian and Sercu, Tom and Lerer, Adam and Rives, Alexander},
  booktitle={International Conference on Machine Learning},
  pages={8946--8970},
  year={2022},
  organization={PMLR}
}

@article{widatalla2024aligning,
  title={Aligning protein generative models with experimental fitness via Direct Preference Optimization},
  author={Widatalla, Talal and Rafailov, Rafael and Hie, Brian},
  journal={bioRxiv},
  doi={10.1101/2024.05.20.595026},
  year={2024}
}

Copy citation

evo-design/proto-tools/proto_tools/tools/inverse_folding/esm_if1

View source

Open Notebook

Open notebook

ESM-IF1 Sampling ESM-IF1 Scoring

Toolkit contributors

Function	Description
`run_esm_if1_sample()`	Sample protein sequences conditioned on backbone structure using ESM-IF1 or ProteinDPO (DPO-align… (GPU)	Docs Source
`run_esm_if1_score()`	Score protein sequences against backbone structures using ESM-IF1 or ProteinDPO. Computes average… (GPU)	Docs Source

Background

ESM-IF1 (Hsu et al., 2022) solves the inverse-folding problem: given a protein backbone, it predicts an amino-acid sequence that will fold into that structure. This is the inverse of structure prediction and a core step in protein design, where a backbone is proposed first and a sequence that encodes it is designed afterwards. Internally, ESM-IF1 is a sequence-to-sequence transformer with geometric input layers. A Geometric Vector Perceptron graph network encodes the backbone atom coordinates (N, C-alpha, C) into rotation-invariant per-residue features, and an autoregressive decoder then generates the sequence one residue at a time. Because experimentally determined structures are limited, the model was trained on roughly 12 million UniRef50 sequences whose structures were predicted with AlphaFold2, alongside experimental structures from CATH. This raised native-sequence recovery to about 51% on structurally held-out backbones, and about 72% for buried residues. ESM-IF1 also handles complexes, partially masked structures, and binding interfaces. The reference implementation is maintained by Meta AI in facebookresearch/esm and distributed in the fair-esm package. ProteinDPO (Widatalla et al., 2024) is a variant of ESM-IF1 fine-tuned with Direct Preference Optimization (DPO) on a mega-scale experimental protein-stability dataset. It keeps the ESM-IF1 architecture but is trained to prefer stabilizing over destabilizing sequences for a given backbone, which improves both its designs and its stability scoring. ProteinDPO’s implementation is available at evo-design/protein-dpo.

Learning Resources

ESM inverse folding examples (Meta AI) - the official notebooks and scripts for running ESM-IF1 sequence design and scoring, including multi-chain complexes.

Tools

ESM-IF1 Sampling (`esm-if1-sample`)

Designs new sequences for a given backbone. Each input structure is encoded once and decoded into one or more candidate sequences, each returned with its average log-likelihood under the model.

API Reference

Source

Input: InverseFoldingInput

List[InverseFoldingStructureInput]

required

Per-structure inputs, each containing a structure plus optional chains_to_redesign and fixed_positions selections.

Show InverseFoldingStructureInput

ChainSelection

Chains to redesign. None means redesign every chain in the structure. Accepts shorthand "A" or ["A", "B"] at construction.

ResidueSelection

Per-chain positions whose residue identity is held fixed during design (1-indexed). Accepts shorthand {"A": [1, 2, 3]} at construction.

Structure

required

Protein structure. 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: ESMIF1SampleConfig

enum

default:"protein_dpo"

Which model weights to use. ‘esmif’ loads vanilla ESM-IF1, ‘protein_dpo’ loads DPO-aligned weights optimized for protein stability.Available options: esmif, protein_dpo

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. Options include ‘cuda’ (NVIDIA GPU), ‘cpu’ (CPU execution), or specific GPU devices like ‘cuda:0’. Defaults to ‘cuda’.

integer

default:"3600"

Maximum execution time in seconds. None waits indefinitely.

integer

Random seed for sampling reproducibility.

integer

default:"1"

Total number of sequences to generate per structure.

integer

Number of sequences to process simultaneously on GPU.

number

default:"1.0"

Sampling temperature; ESM-IF1’s tuned default is 1.0.

Source

Output: ESMIF1SampleOutput

List[ESMIF1DesignSet]

required

One ESMIF1DesignSet per input structure, in input order.

Show ESMIF1DesignSet

List[ESMIF1Design]

required

The complexes generated for one input, each a complete multi-chain complex with a per-design log-likelihood.

Applications

Use this to redesign a natural protein or to generate sequences for a de novo backbone, including multi-chain complexes and binding interfaces where the surrounding chains are kept as context. With the default ProteinDPO weights the designs are biased toward higher experimental stability, which suits stabilization campaigns.

Usage Tips

temperature defaults to 1.0, rather than the 0.1 used by the other inverse-folding tools. ESM-IF1’s reference inference samples at 1.0, and this toolkit retains that default, so its designs are more diverse than those produced by the backbone-MPNN models. Lower it toward 0.1 for conservative, near-greedy designs, and raise it for greater variation.
batch_size controls how many sequences are produced per worker dispatch. It defaults to num_sequences_per_structure, so the whole request is handled in one dispatch; the model still decodes the sequences one at a time. Lower it to bound peak GPU memory when a large request or long backbone exhausts memory.
Non-redesigned chains still shape the design. Chains you do not select stay as fixed structural context rather than being ignored, so designing one chain of a complex accounts for its partners. fixed_positions is counted from 1, not 0 to follow biological conventions for residue selection.
Output is structured per design. output.design_sets[i].complexes[j] is an ESMIF1Design; the designed target sequence is design.designed_chains[0].sequence and the log-likelihood is design.metrics["log_likelihood"]. ESMIF1Design is a Complex subclass and can be passed directly to structure predictors.

ESM-IF1 Scoring (`esm-if1-score`)

Evaluates how well existing sequences fit a structure. Each sequence is scored against its paired structure using the full multi-chain context, returning the average log-likelihood and perplexity.

API Reference

Source

Input: ESMIF1ScoringInput

List[ESMIF1ScoringPair]

required

List of pairs to score. Each pair contains a target chain sequence, a structure, and the chain ID within that structure whose sequence is being scored.

Show ESMIF1ScoringPair

string

required

Target chain sequence to score. Length must equal the number of residues in the chain identified by target_chain.

Structure

required

Protein structure providing the (optionally multi-chain) coordinate context.

SingleChainSelection

Chain within structure whose sequence is being scored. None is permitted only for single-chain structures, in which case the sole chain is used. For multi-chain structures this field is required.

Source

Config: ESMIF1ScoringConfig

enum

default:"protein_dpo"

Which model weights to use. ‘esmif’ loads vanilla ESM-IF1, ‘protein_dpo’ loads DPO-aligned weights optimized for protein stability.Available options: esmif, protein_dpo

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: InverseFoldingScoringOutput

List[InverseFoldingScoringMetrics]

required

List of scoring outputs, one per input sequence-structure pair. Each entry is a Metrics subclass with scalar metrics (accessed via score.perplexity or score["perplexity"]) plus declared logits / vocab fields.

Show InverseFoldingScoringMetrics

array

Per-position logits array (seq_len, vocab_size). None unless the tool returns logits.

array

Token ordering for logits.

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
`log_likelihood`	float	≤ 0.0	always
`avg_log_likelihood`	float	≤ 0.0	always
`perplexity`	float	≥ 1.0	always

Applications

Use this to rank candidate sequences or assess point mutations by structural compatibility without generating new ones. With the default ProteinDPO weights the score also better reflects predicted stability, which is useful for prioritizing stabilizing variants.

Usage Tips

Lower perplexity is better, and it tracks the log-likelihood directly. Perplexity is exp(-avg_log_likelihood), so the two metrics rank candidates identically. Treat the score as compatibility under the model, not a guarantee the sequence folds, and confirm shortlisted candidates with a structure predictor.

Toolkit Notes

These apply to every ESM-IF1 tool in this toolkit (esm-if1-sample, esm-if1-score).

Requires a GPU. The geometric encoder and autoregressive decoder are not practical on CPU. Model weights download automatically on first use through the fair-esm package.
ProteinDPO is the default for both tools. esm-if1-sample and esm-if1-score both default weights_variant to protein_dpo, the stability-aligned variant, so by default designs are biased toward stability and scores reflect predicted stability rather than the original ESM-IF1 likelihood. Set weights_variant to esmif for the original ESM-IF1 model in either tool.

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

ESM-IF1 Sampling (`esm-if1-sample`)

API Reference

Applications

Usage Tips

ESM-IF1 Scoring (`esm-if1-score`)

API Reference

Applications

Usage Tips

Toolkit Notes

Infrastructure Guides

Tool Persistence

Device Management

Parallel Execution

​Background

​Learning Resources

​Tools

​ESM-IF1 Sampling (esm-if1-sample)

​API Reference

​Applications

​Usage Tips

​ESM-IF1 Scoring (esm-if1-score)

​API Reference

​Applications

​Usage Tips

​Toolkit Notes

​Infrastructure Guides

Tool Persistence

Device Management

Parallel Execution

Background

Learning Resources

Tools

ESM-IF1 Sampling (`esm-if1-sample`)

API Reference

Applications

Usage Tips

ESM-IF1 Scoring (`esm-if1-score`)

API Reference

Applications

Usage Tips

Toolkit Notes

Infrastructure Guides