ESM-IF1

Released in 2022, ESM-IF1 is an inverse-folding model that predicts which amino-acid sequences fold into a given protein backbone. It was the first inverse-folding model trained at scale on millions of AlphaFold2-predicted structures, and it generalizes to complexes and binding interfaces. This toolkit also includes ProteinDPO, a fine-tuned variant of ESM-IF1 aligned to experimental stability measurements to favor more stable designs. Both design sequences for a backbone and score how well a sequence fits a structure.

Meta AI Biohub

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 4.0k GitHub 4.0k Preprint Preprint Cite Cite Tool Source Tool Source Open as Notebook Open as Notebook Open on Proto Open on Proto

facebookresearch/esm

Evolutionary Scale Modeling (esm): Pretrained language models for proteins

4.0k stars

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

proto-bio/proto-tools/proto_tools/tools/inverse_folding/esm_if1

View source

Open Notebook

Open notebook

Coming soon!

Run this tool directly in Proto with no setup required.

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

inputs · List[InverseFoldingStructureInput] · required

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

Show InverseFoldingStructureInput

chains_to_redesign · ChainSelection

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

fixed_positions · ResidueSelection

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

structure · 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

weights_variant · 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

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

timeout · integer · default: "600"

Maximum execution time in seconds. None waits indefinitely.

seed · integer

Random seed for sampling reproducibility.

num_sequences_per_structure · integer · default: "1"

Total number of sequences to generate per structure.

batch_size · integer

Number of sequences to process simultaneously on GPU.

temperature · number · default: "1.0"

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

Source

Output: ESMIF1SampleOutput

design_sets · List[ESMIF1DesignSet] · required

One ESMIF1DesignSet per input structure, in input order.

Show ESMIF1DesignSet

complexes · 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 trades GPU memory against throughput. It defaults to num_sequences_per_structure, so all requested sequences are generated in a single forward pass. Increase it to generate more sequences per pass and improve throughput. Decrease it to lower 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"]. ESMIF1Designs are 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

sequence_structure_pairs · 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

sequence · string · required

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

structure · Structure · required

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

target_chain · 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

weights_variant · 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

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: "600"

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

Output: InverseFoldingScoringOutput

scores · 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

logits · array

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

vocab · array

Token ordering for logits.

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.

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.

Cloud Inference

Run tools on managed cloud infrastructure with no local setup.