MULTI-evolve
# 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/ └──