Biomolecular Emulator (BioEmu)

Biomolecular Emulator (BioEmu for short) is a model that samples from the approximated equilibrium distribution of structures for a protein monomer, given its amino acid sequence.

For more information see our paper, citation below.

This repository contains inference code and model weights.

Table of Contents

• Installation
• Sampling structures
• Steering to avoid chain breaks and clashes
• Azure AI Foundry
• Training data
• Get in touch
• Citation

Installation

bioemu is provided as a Linux-only pip-installable package. We support Python 3.10 and above:

pip install bioemu

To install with CUDA support:

pip install bioemu[cuda]

Sampling structures

You can sample structures for a given protein sequence using the sample module. To run a tiny test using the default model parameters and denoising settings:

python -m bioemu.sample --sequence GYDPETGTWG --num_samples 10 --output_dir ~/test-chignolin

Alternatively, you can use the Python API:

from bioemu.sample import main as sample
sample(sequence='GYDPETGTWG', num_samples=10, output_dir='~/test_chignolin')

The model parameters will be automatically downloaded from huggingface. A path to a single-sequence FASTA file can also be passed to the sequence argument.

Sampling times will depend on sequence length and available infrastructure. The following table gives times for collecting 1000 samples measured on an A100 GPU with 80 GB VRAM for sequences of different lengths (using a batch_size_100=20 setting in sample.py):

By default, unphysical structures (steric clashes or chain discontinuities) will be filtered out, so you will typically get fewer samples in the output than requested. The difference can be very large if your protein has large disordered regions which are very likely to produce clashes. If you want to get all generated samples in the output, irrespective of whether they are physically valid, use the --filter_samples=False argument.

This code only supports sampling structures of monomers. You can try to sample multimers using the linker trick, but in our limited experiments, this has not worked well.

Steering to avoid chain breaks and clashes

BioEmu includes a steering system that guides the diffusion process toward more physically plausible protein structures. Steering applies potential energy functions during denoising to favor conformations that satisfy physical constraints. Two steering algorithms are available:

• SMC (Sequential Monte Carlo): Simulates multiple candidate samples (particles) per desired output sample, where the candidates are denoised in an unbiased way, and resamples between them according to the favorability of the provided potentials. This is the default for physical steering.
• FKC (Feynman–Kac Corrector): Uses importance weighting and may perform ESS-based resampling between particles; useful when targeting a specific collective variable value (e.g., RMSD to a reference). The samples are denoised with bias from the bias potential (reward).

Empirically, using three (or up to 10) steering particles per output sample greatly reduces the number of unphysical samples (steric clashes or chain breaks) produced by the model.

Quick start with steering

Steering is configured via a single YAML file passed as denoiser_config. This file specifies the denoiser, potentials, and steering parameters together.

Enable steering with physical constraints using the CLI:

python -m bioemu.sample \
    --sequence GYDPETGTWG \
    --num_samples 100 \
    --output_dir ~/steered-samples \
    --denoiser_config src/bioemu/config/steering/physical_steering.yaml

Or using the Python API:

from bioemu.sample import main as sample

sample(
    sequence='GYDPETGTWG',
    num_samples=100,
    output_dir='~/steered-samples',
    denoiser_config="src/bioemu/config/steering/physical_steering.yaml",
)

Key steering parameters

Inside the steering YAML config (e.g., physical_steering.yaml):

• num_particles: Number of particles per sample (higher = stronger steering, more compute)
• ess_threshold: Effective sample size threshold for resampling (0.0–1.0)
• start: Diffusion time to start steering (0.0–1.0, default: 0.1; reverse process goes 1→0)
• end: Diffusion time to stop steering (0.0–1.0, default: 0.0)
• fk_potentials: List of potential energy functions to apply (Hydra-instantiated)

Available potentials

The physical_steering.yaml configuration provides potentials for physical realism:

• CaCaDistance + UmbrellaPotential: Prevents backbone discontinuities by penalizing large Cα–Cα distances
• PairwiseClash + UmbrellaPotential: Avoids steric clashes between non-neighboring residues

For custom steering, you can write your own YAML config targeting any combination of potentials and collective variables. See cv_steer.yaml for an example that steers toward a target RMSD value using FKC.

Azure AI Foundry

BioEmu is also available on Azure AI Foundry. See How to run BioEmu on Azure AI Foundry for more details.

Training data

The molecular dynamics training data used for BioEmu is available on Zenodo:

• CATH
• Octapeptides
• MegaSim

For a full description of these, see the paper.

Reproducing results from the paper

You can use this code together with code from bioemu-benchmarks to approximately reproduce results from our paper.

• The bioemu-v1.0 checkpoint contains the model weights used to produce the results in the preprint. Due to simplifications made in the embedding computation and a more efficient sampler, the results obtained with this code are not identical but consistent with the preprint statistics, i.e., mode coverage and free energy errors averaged over the proteins in a test set. Results for individual proteins may differ.
• [Default] The bioemu-v1.1 checkpoint contains the model weights used to produce the results in the published Science paper.
• The bioemu-v1.2 checkpoint contains the model weights trained from an extended set of MD simulations and experimental measurements of folding free energies.

For more details, please check the BIOEMU_RESULTS.md document on the bioemu-benchmarks repository.

To use a specific checkpoint, you can specify the model_name in the bioemu.sample args, for example, --model_name="bioemu-v1.1".

Side-chain reconstruction and MD-relaxation

BioEmu outputs structures in backbone frame representation. To reconstruct the side-chains, several tools are available. As an example, we interface with HPacker to conduct side-chain reconstruction, and also provide basic tooling for running a short molecular dynamics (MD) equilibration.

Install optional dependencies:

pip install bioemu[md]

You can compute side-chain reconstructions via the bioemu.sidechains_relax module:

python -m bioemu.sidechain_relax --pdb-path path/to/topology.pdb --xtc-path path/to/samples.xtc

By default, side-chain reconstruction and local energy minimization are performed (no full MD integration for efficiency reasons). Note that the runtime of this code scales with the size of the system. We suggest running this code on a selection of samples rather than the full set.

There are two other options:

• To only run side-chain reconstruction without MD equilibration, add --no-md-equil.
• To run a short NVT equilibration (0.1 ns), add --md-protocol nvt_equil

To see the full list of options, call python -m bioemu.sidechain_relax --help.

The script saves reconstructed all-heavy-atom structures in samples_sidechain_rec.{pdb,xtc} and MD-equilibrated structures in samples_md_equil.{pdb,xtc} (filename to be altered with --outname other_name).

Third-party code

• The code in src/bioemu/openfold/ is copied from OpenFold (Apache 2.0) with minor modifications described in the relevant source files.
• The code in src/_vendor/alphafold/ is a vendored, patched subset of AlphaFold2 v2.3.2 (Apache 2.0). See src/_vendor/alphafold/README.md for details on the modifications.
• The code in src/bioemu/colabfold_inline/ contains functions derived from ColabFold v1.5.4 (MIT). See the license headers in each file for details.

Get in touch

If you have any questions not covered here, please create an issue or contact the BioEmu team by writing to the corresponding author on our paper.

Citation

If you are using our code or model, please cite the following paper:

@article{bioemu2025,
  title={Scalable emulation of protein equilibrium ensembles with generative deep learning},
  author={Lewis, Sarah and Hempel, Tim and Jim{\'e}nez-Luna, Jos{\'e} and Gastegger, Michael and Xie, Yu and Foong, Andrew YK and Satorras, Victor Garc{\'\i}a and Abdin, Osama and Veeling, Bastiaan S and Zaporozhets, Iryna and Chen, Yaoyi and Yang, Soojung and Foster, Adam E. and Schneuing, Arne and Nigam, Jigyasa and Barbero, Federico and Stimper Vincent and  Campbell, Andrew and Yim, Jason and Lienen, Marten and Shi, Yu and Zheng, Shuxin and Schulz, Hannes and Munir, Usman and Sordillo, Roberto and Tomioka, Ryota and Clementi, Cecilia and No{\'e},  Frank},
  journal={Science},
  pages={eadv9817},
  year={2025},
  publisher={American Association for the Advancement of Science},
  doi={10.1126/science.adv9817}
}