README.md

---
license: apache-2.0
language:
- en
- zh
tags:
- OneScience
- life-science
- protein
- directed-evolution
- multi-mutant
- protein-language-model
- MULTI-evolve
frameworks: PyTorch
---

<p align="center">
  <strong>
    <span style="font-size: 30px;">MULTI-evolve</span>
  </strong>
</p>

# Model Introduction

MULTI-evolve (model-guided, universal, targeted installation of multi-mutants) is an end-to-end framework for protein directed evolution. It trains sequence-to-fitness prediction models, proposes combinatorial multi-mutants, generates MULTI-assembly site-directed mutagenesis oligonucleotides, and supports screening single-mutant candidates through a protein language model zero-shot ensemble method.

Paper:

> **Rapid directed evolution guided by protein language models and epistatic interactions**  
> Science, 2026  
> https://doi.org/10.1126/science.aea1820

# Model Description

The core workflow of MULTI-evolve includes:

1. Train fully connected neural networks using experimental sequence-to-fitness data.
2. Compare different data splits, sequence representations, and machine learning models.
3. Select the best-performing prediction model to score combinatorial mutants and propose candidates.
4. Generate MULTI-assembly site-directed mutagenesis oligonucleotides from the selected multi-mutants.
5. In selected iterations, use a protein language model zero-shot ensemble method to screen single-mutant candidates.

# Use Cases

| Use case | Description |
| --- | --- |
| Protein directed evolution | Train fitness prediction models from experimental data and screen candidate mutations |
| Multi-mutant design | Predict combinatorial mutations and screen multi-mutants with high predicted fitness |
| Protein complex optimization | Support mutation formats and inputs for multichain proteins |
| Zero-shot mutation screening | Use a protein language model ensemble method to screen candidate single mutations |

# Usage

## 1. Using OneCode

Experience intelligent one-click AI4S programming in the OneCode online environment:

[Try intelligent one-click AI4S programming](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home)

## 2. Manual Installation and Usage

**Hardware Requirements**

- Supervised model training and standard combinatorial mutation prediction in MULTI-evolve can run on a CPU or GPU/DCU.
- Protein language model zero-shot prediction uses models such as ESM and ESM-IF; a GPU/DCU is recommended.

### Set Up the Runtime Environment

#### DCU Environment

```bash
# Activate DTK and CONDA first
conda create -n onescience311 python=3.11 -y
conda activate onescience311

pip install onescience[bio] \
  -i http://mirrors.onescience.ai:3141/pypi/simple/ \
  --trusted-host mirrors.onescience.ai
```

#### Environment Notes

- If you encounter missing dependencies or version incompatibilities during execution, refer to the dependency versions specified in `env.yml` and install or adjust the relevant dependencies as needed.

### Prepare Models and Data

The different MULTI-evolve functions have different model and data requirements. Prepare the resources for standard supervised training, combinatorial multi-mutant recommendation, MULTI-assembly design, protein language model zero-shot screening, and benchmark reproduction separately.

#### 1) Supervised Learning Input Data

To train your own protein fitness prediction model with MULTI-evolve, prepare:

```text
Wild-type protein FASTA
+
Experimental training data CSV
```

The training data CSV must contain at least:

```text
mutation
property_value
```

For example, the mutation format for a single-chain protein is:

```text
A40P/E61Y
```

For multichain proteins, use `:` to separate different chains:

```text
A40P/E61Y:WT
```

Where:

```text
/   Separates multiple mutations on the same chain
:   Separates different protein chains
WT  Indicates that the corresponding chain remains wild type
```

The official repository provides example data:

```text
data/
├── example_protein/
└── example_multichain_protein/
```

Therefore, no additional training data download is required to run the official basic examples.

#### 2) Combinatorial Mutation Candidate Pool

When running combinatorial multi-mutant recommendation, in addition to the wild-type FASTA and training data, provide a mutation pool: a list of candidate single mutations eligible for combinatorial design.

Example:

```text
data/example_protein/combo_muts.csv
```

Pass this file as the:

```text
--mutation-pool
```

parameter, for example:

```bash
p2_propose.py \
  --experiment-name multievolve_example \
  --protein-name example_protein \
  --wt-files apex.fasta \
  --training-dataset example_dataset.csv \
  --mutation-pool combo_muts.csv \
  --top-muts-per-load 3 \
  --export-name multievolve_proposals
```

#### 3) Protein Language Model Zero-Shot Mode

The MULTI-evolve protein language model zero-shot ensemble workflow requires:

```text
Wild-type FASTA
+
PDB/CIF protein structure
```

The current official code uses the following models:

```text
ESM-1v:
esm1v_t33_650M_UR90S_1
esm1v_t33_650M_UR90S_2
esm1v_t33_650M_UR90S_3
esm1v_t33_650M_UR90S_4
esm1v_t33_650M_UR90S_5

ESM-2:
esm2_t36_3B_UR50D

ESM-IF1:
esm_if1_gvp4_t16_142M_UR50
```

MULTI-evolve calls these models through `fair-esm`. On the first run, if the corresponding weights are not available locally, `fair-esm` automatically downloads the models and caches them in the PyTorch Hub checkpoint directory.

The default cache location is:

```text
~/.cache/torch/hub/checkpoints/
```

ESM-2 also uses the corresponding contact regression weights:

```text
esm2_t36_3B_UR50D-contact-regression.pt
```
- The current repository already includes `esm2_t36_3B_UR50D-contact-regression.pt` under `hub/checkpoints/`.

For network-restricted or offline environments, download the weights in advance:

```bash
mkdir -p ~/.cache/torch/hub/checkpoints
cd ~/.cache/torch/hub/checkpoints

wget https://dl.fbaipublicfiles.com/fair-esm/models/esm1v_t33_650M_UR90S_1.pt
wget https://dl.fbaipublicfiles.com/fair-esm/models/esm1v_t33_650M_UR90S_2.pt
wget https://dl.fbaipublicfiles.com/fair-esm/models/esm1v_t33_650M_UR90S_3.pt
wget https://dl.fbaipublicfiles.com/fair-esm/models/esm1v_t33_650M_UR90S_4.pt
wget https://dl.fbaipublicfiles.com/fair-esm/models/esm1v_t33_650M_UR90S_5.pt

wget https://dl.fbaipublicfiles.com/fair-esm/models/esm2_t36_3B_UR50D.pt
wget https://dl.fbaipublicfiles.com/fair-esm/regression/esm2_t36_3B_UR50D-contact-regression.pt

wget https://dl.fbaipublicfiles.com/fair-esm/models/esm_if1_gvp4_t16_142M_UR50.pt
```

To save the models in the current project or another location, set the PyTorch Hub cache root with `TORCH_HOME`. For example, to use a directory in the current project:

```bash
cd /path/to/MULTI-evolve
export TORCH_HOME=$PWD
mkdir -p ${TORCH_HOME}/hub/checkpoints
```

Then save or symlink the weights above to:

```text
/path/to/MULTI-evolve/hub/checkpoints/
```

This avoids modifying the MULTI-evolve source code.

#### 4) Benchmark DMS Data

To run the official benchmark and reproduce the performance comparison across different:

```text
data splitting methods
sequence representation methods
machine learning models
```

you must additionally prepare the official benchmark DMS data by downloading it separately from Zenodo.

Download:

```text
DOI: 10.5281/zenodo.17620759
https://zenodo.org/records/17620759
```

After downloading, place the DMS CSV files directly in the following directory. If the directory does not exist, create it manually first:

```text
data/benchmark/datasets/
```

The benchmark script entry point in the current repository is:

```text
scripts/notebooks/benchmark/multievolve_hyperparameter_tuning.py
```

## 3. Quick Start

### Download the Model Package

```bash
hf download OneScience-Group/MULTI-evolve \
  --local-dir ./MULTI-evolve

cd MULTI-evolve
```

- Standard supervised training and combinatorial mutation recommendation in MULTI-evolve do not require additional large fixed datasets; you can use the example data in the repository or your own experimental data.

- The protein language model zero-shot mode may require additional ESM/ESM-IF model caches; prepare them in advance in offline environments.

### Quick Verification

Install the current repository:

```bash
python -m pip install -e . --no-deps
```

Check the commands:

```bash
p1_train.py --help
p2_propose.py --help
p3_assembly_design.py --help
plm_zeroshot_ensemble.py --help
```


# Example Data

The official repository provides:

```text
data/
├── example_protein/
├── example_multichain_protein/
└── benchmark/
```

The official command-line examples primarily use:

```bash
cd data/example_protein
```

Typical inputs include:

```text
apex.fasta
example_dataset.csv
combo_muts.csv
APEX_33overhang.fasta
apex.cif
```

These files are used for:

| File | Purpose |
| --- | --- |
| `apex.fasta` | Wild-type protein amino acid sequence |
| `example_dataset.csv` | Training data |
| `combo_muts.csv` | Combinatorial mutation candidate pool |
| `APEX_33overhang.fasta` | DNA input required for MULTI-assembly oligonucleotide design |
| `apex.cif` | Structure-conditioned scoring for protein language models |

# Inference and Training Examples

## Step 1: Train the Neural Network Model

```bash
# If the runtime environment is not active, activate the conda environment in use, such as onescience311
conda activate onescience311
cd data/example_protein

p1_train.py \
  --experiment-name multievolve_example \
  --protein-name example_protein \
  --wt-files apex.fasta \
  --training-dataset-fname example_dataset.csv \
  --wandb-key dummy \
  --mode test
```

Key parameters:

| Parameter | Description |
| --- | --- |
| `--experiment-name` | Current experiment name; keep it consistent in subsequent steps |
| `--protein-name` | Protein name |
| `--wt-files` | Wild-type FASTA; use commas to separate multiple FASTA files for multichain proteins |
| `--training-dataset-fname` | Training data CSV |
| `--mode` | `test` or `standard` |

## Step 2: Propose Combinatorial Multi-Mutants

```bash
p2_propose.py \
  --experiment-name multievolve_example \
  --protein-name example_protein \
  --wt-files apex.fasta \
  --training-dataset example_dataset.csv \
  --mutation-pool combo_muts.csv \
  --top-muts-per-load 3 \
  --export-name multievolve_proposals
```

The script loads the trained model saved to the local cache in Step 1 and scores the combinatorial mutation candidates.

Typical output:

```text
multievolve_proposals.csv
```

For protein complexes, candidate files are also generated separately for each chain.

## Step 3: Design MULTI-assembly Oligonucleotides

```bash
p3_assembly_design.py \
  --mutations-file multievolve_proposals.csv \
  --wt-fasta APEX_33overhang.fasta \
  --overhang 33 \
  --species human \
  --oligo-direction top \
  --tm 80 \
  --output design
```

Where:

| Parameter | Description |
| --- | --- |
| `--mutations-file` | Candidate mutation CSV generated in Step 2 |
| `--wt-fasta` | Wild-type DNA FASTA containing overhangs at both ends |
| `--overhang` | Overhang length |
| `--species` | `human`, `ecoli`, or `yeast` |
| `--oligo-direction` | `top` or `bottom` |
| `--tm` | Target oligonucleotide melting temperature; the official recommendation is 80 °C |
| `--output` | `design` or `update` |

Outputs:

```text
cloning_sheet.csv
oligos.csv
```

## Protein Language Model Zero-Shot Ensemble

```bash
plm_zeroshot_ensemble.py \
  --wt-file apex.fasta \
  --pdb-files apex.cif \
  --chain-id A \
  --variants 24 \
  --excluded-positions 1,14,41,112 \
  --normalizing-method aa_substitution_type
```

Where:

| Parameter | Description |
| --- | --- |
| `--wt-file` | Wild-type protein FASTA |
| `--pdb-files` | PDB/CIF structure files; use commas to separate multiple structures |
| `--chain-id` | Chain ID of the target protein in the structure file |
| `--variants` | Number of mutations nominated by each method |
| `--excluded-positions` | Positions excluded from mutation |
| `--normalizing-method` | `aa_substitution_type` or `aa_mutation` |

This workflow ensembles four methods and produces:

```text
plm_zeroshot_ensemble_nominated_mutations.csv
```

# Output Description

MULTI-evolve generates model caches, evaluation results, and candidate sequences at different stages.

The official repository automatically creates the following after execution:

```text
proteins/
└── <protein_name>/
    ├── feature_cache/
    ├── model_cache/
    │   └── <dataset>/
    │       ├── objects/
    │       └── results/
    ├── proposers/
    │   └── results/
    └── split_cache/
        └── <dataset>/
```

The main outputs include:

| Output | Description |
| --- | --- |
| `model_cache/` | Trained models and comparison results |
| `feature_cache/` | Cached sequence representations |
| `multievolve_proposals.csv` | Recommended multi-mutant candidates |
| `cloning_sheet.csv` | MULTI-assembly cloning design sheet |
| `oligos.csv` | Site-directed mutagenesis oligonucleotide sequences |
| `plm_zeroshot_ensemble_nominated_mutations.csv` | Protein language model zero-shot ensemble recommendations |


# Official OneScience Information

| Platform | Main OneScience repository | Skills repository |
| --- | --- | --- |
| Gitee | https://gitee.com/onescience-ai/onescience | https://gitee.com/onescience-ai/oneskills |
| GitHub | https://github.com/onescience-ai/OneScience | https://github.com/onescience-ai/oneskills |


# Citation and License

- Original MULTI-evolve paper: [Rapid directed evolution guided by protein language models and epistatic interactions](https://doi.org/10.1126/science.aea1820).
- The `LICENSE` in the repository root is currently **Apache License 2.0**. This license permits use, modification, distribution, and commercial use, but redistribution requires retaining the license, copyright, and attribution notices, and clearly indicating modified files.
- Apache-2.0 also includes a patent license and explicitly does not grant rights to use the project's trademarks.
- `setup.py` still contains an `MIT License` classifier, which is inconsistent with the actual `LICENSE` file in the repository root. For SCNet/ModelScope redistribution, use the Apache-2.0 `LICENSE` in the repository root as the authoritative license, and retain the original license file.
- This repository is a DCU-adapted version of MULTI-evolve, with some environment configurations, dependencies, and execution procedures adjusted. Use of the repository code, model weights, and related data remains subject to the licenses and terms of use of their respective original projects.