bioemu samples a protein's equilibrium ensemble from its sequence

From a sequence to a distribution of structures

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. That sentence is the whole claim, and it is worth unpacking.

The target is a distribution, not a single answer. A structure prediction tool gives you the most likely conformation of a protein, which is one point in a space that is genuinely large. BioEmu instead produces a sample from that space, so you get a set of structures that the model believes are plausible, which is the input a binding study, a mutation scan or a folding pathway analysis actually needs.

The audience is a computational biologist or a structural biologist with a sequence and a question that needs more than one structure. The repository contains the inference code and the model weights, and the paper is linked from the README with a DOI badge, so the intent is that you run the model, not that you read the paper about it.

The project is a Microsoft research release rather than a general purpose tool, and the repository reflects that. There is a MODEL_CARD.md and a NOTICE.md at the root, a SECURITY.md and a CODE_OF_CONDUCT.md, a cgmanifest.json, and an AZURE_AI_FOUNDRY.md describing a hosted option. The recent releases are v1.4.0 on 2026-07-20, v1.3.1 on 2026-04-15 and v1.3.1a3, and the last push was on 2026-10-15.

The one-line description of the repository calls it inference code for scalable emulation of protein equilibrium ensembles with generative deep learning, and that word scalable is the interesting engineering claim, since the cost of a diffusion sampler grows with the number of structures you want.

Linux only, and the MSA stack arrives inside the package

The installation section is short, and one word in it is a hard constraint. BioEmu is provided as a Linux-only pip-installable package, and the README says it supports Python 3.10 and above.

pip install bioemu

With CUDA support, the extra is named:

pip install bioemu[cuda]

There is a mismatch worth flagging here, because the packaging is the more precise source. The pyproject.toml declares requires-python as ">=3.11", while the README and the badge say Python 3.10+. If you are on 3.10, the pip install is the thing that will refuse, so treat 3.11 as the real floor.

The more interesting part of the install is what does not need installing. The README explains that BioEmu uses an inlined version of ColabFold and AlphaFold2 for MSA retrieval and embedding generation, and that these are bundled with the package, so no separate environment or installation is needed. On first use, the AlphaFold2 model weights, around 3.5 GB, are downloaded automatically to the colabfold cache directory in your home.

That is a deliberate packaging decision with a real cost and a real benefit. The benefit is that a user does not have to assemble a multi-repository environment of a folding engine, a multiple sequence alignment retrieval stack and a diffusion model before they can sample a ten residue peptide. The cost is that the install is large and that a first run needs network access and disk for the weights, and the ColabFold and AlphaFold2 code is now inside the wheel rather than at a version you can audit separately.

The BioEmu model parameters themselves are fetched separately, from the microsoft/bioemu repository on huggingface, and a path to a single-sequence FASTA file can be passed to the sequence argument if you prefer to work from a file.

The sample module works from the command line or from Python

Structures are sampled with the sample module, and the README gives a tiny test using the default model parameters and denoising settings, on a ten residue sequence:

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

The same thing through the Python API, which is the form you would use from a script or a notebook:

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

The command line interface is built with typer and fire, both of which are in the dependency list, so the flags you see are the same names the Python function accepts.

The cost model is stated plainly in the README, with a table of times for collecting 1000 samples measured on an A100 GPU with 80 GB VRAM, using a batch_size_100 setting of 20 in sample.py.

| sequence length | time / min | | --------------: | ---------: | | 100 | 4 | | 300 | 40 | | 600 | 150 |

The scaling is close to quadratic in sequence length, which is what you would expect from a diffusion process whose cost is dominated by the number of denoising steps over all the coordinates of the chain. A hundred residue protein costs four minutes, a six hundred residue one costs two and a half hours, and the README is explicit that sampling times also depend on the available infrastructure.

That table is the number to plan around. A 600 residue target is a job for a machine you own overnight, not a demo.

You will get fewer structures than you asked for, by design

The default behaviour of the sampler is worth understanding before you write a pipeline around it, because the output count will not match the request count.

By default, unphysical structures, meaning steric clashes or chain discontinuities, are filtered out, so you will typically get fewer samples in the output than requested. The README warns that the difference can be very large if your protein has large disordered regions, which are very likely to produce clashes. If you want all the generated samples in the output regardless of whether they are physically valid, there is an argument to turn the filtering off:

use the `--filter_samples=False` argument.

So the choice is between a set of structures that are physically plausible and a set that is the raw model output. A user building an ensemble for statistics probably wants the filtered set, and a user debugging the model wants the unfiltered one, and the flag is the only thing separating them.

The same section explains how to depart from the default data source. If you want to use your own generated MSA instead of the ones retrieved through the ColabFold MMseqs2 server, you can pass an A3M file containing the query sequence as the first row to the sequence argument, and the msa_host_url argument can override the default MSA query server. The sample.py file in the source tree is where to look for the rest of the options.

That last point is the important operational one. The default path sends your sequence to a public alignment server, which is a dependency on someone else's infrastructure and, in some organisations, a data governance question. Both are answerable, since the argument exists, but you have to answer them deliberately.

Steering trades compute for fewer broken structures

The steering system is the most interesting part of the release, and it is a separate paper of its own, cited in the README.

Steering applies potential energy functions during denoising to favour conformations that satisfy physical constraints. Two algorithms are available. SMC, Sequential Monte Carlo, simulates multiple candidate samples, called particles, per desired output sample, where the candidates are denoised in an unbiased way and resampled between them according to the favourability of the provided potentials, and it is the default for physical steering. FKC, the Feynman-Kac Corrector, uses importance weighting and may perform effective sample size based resampling between particles, and it is useful when targeting a specific collective variable value, for example the RMSD to a reference, with the samples denoised with bias from the bias potential.

The claimed effect is empirical and worth quoting: using three, or up to 10, steering particles per output sample greatly reduces the number of unphysical samples produced by the model.

Steering is configured through a single YAML file passed as denoiser_config, and the file specifies the denoiser, the potentials and the steering parameters together. From the command line:

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

The parameters inside that file are the knobs:

- `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 to 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)

The potentials available in the physical steering configuration are CaCaDistance with UmbrellaPotential, which prevents backbone discontinuities by penalising large alpha carbon to alpha carbon distances, and PairwiseClash with UmbrellaPotential, which avoids steric clashes between non neighbouring residues. For custom steering you can write your own YAML targeting any combination of potentials and collective variables, and the repository ships cv_steer.yaml as an example that steers toward a target RMSD value using FKC.

The Hydra instantiation in fk_potentials is the mechanism to understand, because it is why the configuration is YAML and not a Python dictionary. The potentials are constructed from the configuration rather than hard coded, which is what makes the system extensible to a new physical constraint without touching the sampler.

Monomers only, and four machine learning frameworks at once

Two limits define the scope of the tool, and one of them is hard.

The first is that this code only supports sampling structures of monomers. The README says you can try to sample multimers using the linker trick, but that in their limited experiments this has not worked well. That is a candid statement, and it means a multi chain complex is out of scope for a user without a lot of patience.

The second is the dependency set, which is unusual. The pyproject.toml lists mdtraj for trajectory handling, torch_geometric and torch for the graph network parts, modelcif and bio for the structure file formats, fire and typer for the command line, einops for tensor layout, hydra-core for the configuration system, dm-tree, stackprinter, matplotlib, requests and tqdm for the rest, and then dm-haiku, ml-collections, absl-py, tensorflow-cpu and jax on top of that.

So a single install brings in PyTorch, JAX, TensorFlow and Haiku. The JAX dependency carries its own extra:

  cuda = [
    "jax[cuda12]>=0.4.35,<0.11",
    "nvidia-cuda-nvcc-cu12>=12.8.93",
  ]

and there is a separate md extra pulling openmm and openmm-cuda-12 for molecular dynamics. The reason is visible in the repository listing, where there is a src/_vendor directory and the mypy configuration excludes it, and the mypy overrides list a long set of third party modules whose imports are skipped. The ColabFold and AlphaFold2 code is vendored in, and those projects are built on different frameworks than the diffusion model itself.

That is a heavy install, and it is the price of bundling an MSA and embedding stack that would otherwise be several separate projects. The project also maintains MODEL_CARD.md and NOTICE.md at the root, which is what you would expect from a release that vendors code it does not own, and the citation request in the README is explicit about how the work should be credited.

Editorial conclusion

Adopt bioemu if you are a computational biologist who needs an ensemble of plausible structures for a monomer from its sequence, and if you have a CUDA GPU and the appetite for a dependency set that spans PyTorch, JAX, TensorFlow and Haiku. Do not adopt it for multimer prediction, because the README says this code only supports sampling structures of monomers and that the linker trick has not worked well in their limited experiments, and do not adopt it on a non-Linux machine, because the package is Linux only. Before you run it, read MODEL_CARD.md and the citation requirements, plan for the AlphaFold2 weights download of roughly 3.5 GB on first use, and decide how you will handle the physical sample filtering, since by default you get fewer structures than you asked for.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. microsoft/bioemu on GitHub
4. README
5. Releases