# microsoft/mu-protein architecture

> Architecture diagram of the GitHub repository microsoft/mu-protein, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/mu-protein
- Repository: https://github.com/microsoft/mu-protein

## Overview

μProtein combines protein-language-model pretraining, μFormer fitness prediction, and μSearch exploration. A typical workflow trains or loads a PMLM, fits a fitness predictor to mutation data, exposes that predictor as a landscape oracle, and searches for promising sequences. The graph also preserves the documented pretraining and modeling stages. Some internal links are based on SOURCE INDEX references or README descriptions rather than fully sampled implementations; those limits are marked with dashed edges where appropriate.

Main entry points: [`mu-former/src/trainer.py`](https://github.com/microsoft/mu-protein/blob/main/mu-former/src/trainer.py) (Model trainer), [`pmlm/src/protein/models/pmlm.py`](https://github.com/microsoft/mu-protein/blob/main/pmlm/src/protein/models/pmlm.py) (PMLM model), [`pmlm/src/protein/tasks/pmlm.py`](https://github.com/microsoft/mu-protein/blob/main/pmlm/src/protein/tasks/pmlm.py) (Pretraining tasks), [`mu-search/src/flexs/flexs/explorer.py`](https://github.com/microsoft/mu-protein/blob/main/mu-search/src/flexs/flexs/explorer.py) (Search loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pretraining["PMLM pretraining"]
  node_tokenizer["Sequence tokenizer<br/>[tokenizers.py]"]
  node_datasets["Training datasets<br/>[datasets.py]"]
  node_encoder["Transformer encoder<br/>[encoder.py]"]
  node_attention["Attention layers"]
  node_pmlm["PMLM model<br/>[pmlm.py]"]
  node_prediction["Prediction heads<br/>[prediction.py]"]
  node_objectives["Pretraining objectives<br/>[pmlm.py]"]
  node_pretrain_task["Pretraining tasks<br/>[pmlm.py]"]
end

subgraph group_modeling["Fitness modeling"]
  node_muformer_entry["Training interface<br/>[main.py]"]
  node_paired_data["Mutation datasets<br/>[data.py]"]
  node_vocabulary["Model vocabulary<br/>[vocab.py]"]
  node_predictor["Fitness predictor<br/>[model.py]"]
  node_criterion["Fitness objective<br/>[criterion.py]"]
  node_trainer["Model trainer<br/>[trainer.py]"]
  node_scheduler["Learning-rate schedule<br/>[lr_scheduler.py]"]
end

subgraph group_search["Landscape search"]
  node_fitness_oracle["Muformer landscape<br/>[muformer.py]"]
  node_explorer["Search loop<br/>[explorer.py]"]
  node_random_search["Random strategy<br/>[random.py]"]
  node_sequence_utils["Sequence mutation<br/>[sequence_utils.py]"]
  node_results["Measured sequences"]
end

node_engineer(("Protein engineer"))

node_engineer -->|"configures training"| node_muformer_entry
node_muformer_entry -->|"starts training"| node_trainer
node_trainer -->|"loads data"| node_paired_data
node_trainer -->|"trains model"| node_predictor
node_trainer -->|"selects loss"| node_criterion
node_trainer -->|"configures schedule"| node_scheduler
node_trainer -->|"uses vocabulary"| node_vocabulary
node_engineer -.->|"pretrains model"| node_pretrain_task
node_pretrain_task -.->|"uses datasets"| node_datasets
node_datasets -->|"tokenizes sequences"| node_tokenizer
node_pretrain_task -.->|"trains model"| node_pmlm
node_pmlm -->|"uses encoder"| node_encoder
node_encoder -->|"uses layers"| node_attention
node_pmlm -->|"uses heads"| node_prediction
node_pretrain_task -.->|"computes objective"| node_objectives
node_pmlm -.->|"provides pretrained model"| node_muformer_entry
node_trainer -.->|"supplies trained model"| node_fitness_oracle
node_engineer -.->|"initiates search"| node_explorer
node_explorer -.->|"runs strategy"| node_random_search
node_random_search -->|"generates mutants"| node_sequence_utils
node_random_search -->|"scores candidates"| node_fitness_oracle
node_explorer -.->|"measures candidates"| node_fitness_oracle
node_explorer -.->|"records measurements"| node_results
node_fitness_oracle -->|"loads predictor"| node_predictor

click node_tokenizer "https://github.com/microsoft/mu-protein/blob/main/pmlm/src/protein/tokenizers.py"
click node_datasets "https://github.com/microsoft/mu-protein/blob/main/pmlm/src/protein/datasets.py"
click node_encoder "https://github.com/microsoft/mu-protein/blob/main/pmlm/src/protein/models/encoder.py"
click node_attention "https://github.com/microsoft/mu-protein/blob/main/pmlm/src/protein/models/multihead_attention.py"
click node_pmlm "https://github.com/microsoft/mu-protein/blob/main/pmlm/src/protein/models/pmlm.py"
click node_prediction "https://github.com/microsoft/mu-protein/blob/main/pmlm/src/protein/models/prediction.py"
click node_objectives "https://github.com/microsoft/mu-protein/blob/main/pmlm/src/protein/criterions/pmlm.py"
click node_pretrain_task "https://github.com/microsoft/mu-protein/blob/main/pmlm/src/protein/tasks/pmlm.py"
click node_muformer_entry "https://github.com/microsoft/mu-protein/blob/main/mu-former/main.py"
click node_paired_data "https://github.com/microsoft/mu-protein/blob/main/mu-former/src/data.py"
click node_vocabulary "https://github.com/microsoft/mu-protein/blob/main/mu-former/src/vocab.py"
click node_predictor "https://github.com/microsoft/mu-protein/blob/main/mu-former/src/model.py"
click node_criterion "https://github.com/microsoft/mu-protein/blob/main/mu-former/src/criterion.py"
click node_trainer "https://github.com/microsoft/mu-protein/blob/main/mu-former/src/trainer.py"
click node_scheduler "https://github.com/microsoft/mu-protein/blob/main/mu-former/src/lr_scheduler.py"
click node_fitness_oracle "https://github.com/microsoft/mu-protein/blob/main/mu-search/src/flexs/flexs/landscapes/muformer.py"
click node_explorer "https://github.com/microsoft/mu-protein/blob/main/mu-search/src/flexs/flexs/explorer.py"
click node_random_search "https://github.com/microsoft/mu-protein/blob/main/mu-search/src/flexs/flexs/baselines/explorers/random.py"
click node_sequence_utils "https://github.com/microsoft/mu-protein/blob/main/mu-search/src/flexs/flexs/utils/sequence_utils.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tokenizer,node_datasets,node_encoder,node_attention,node_pmlm,node_prediction,node_objectives,node_pretrain_task toneBlue
class node_muformer_entry,node_paired_data,node_vocabulary,node_predictor,node_criterion,node_trainer,node_scheduler toneAmber
class node_fitness_oracle,node_explorer,node_random_search,node_sequence_utils,node_results toneMint
class node_engineer toneIndigo
```

## Components

### PMLM pretraining

- [Sequence tokenizer](https://github.com/microsoft/mu-protein/blob/main/pmlm/src/protein/tokenizers.py): `pmlm/src/protein/tokenizers.py`
- [Training datasets](https://github.com/microsoft/mu-protein/blob/main/pmlm/src/protein/datasets.py): `pmlm/src/protein/datasets.py`
- [Transformer encoder](https://github.com/microsoft/mu-protein/blob/main/pmlm/src/protein/models/encoder.py): `pmlm/src/protein/models/encoder.py`
- [Attention layers](https://github.com/microsoft/mu-protein/blob/main/pmlm/src/protein/models/multihead_attention.py): `pmlm/src/protein/models/multihead_attention.py`
- [PMLM model](https://github.com/microsoft/mu-protein/blob/main/pmlm/src/protein/models/pmlm.py): `pmlm/src/protein/models/pmlm.py`
- [Prediction heads](https://github.com/microsoft/mu-protein/blob/main/pmlm/src/protein/models/prediction.py): `pmlm/src/protein/models/prediction.py`
- [Pretraining objectives](https://github.com/microsoft/mu-protein/blob/main/pmlm/src/protein/criterions/pmlm.py): `pmlm/src/protein/criterions/pmlm.py`
- [Pretraining tasks](https://github.com/microsoft/mu-protein/blob/main/pmlm/src/protein/tasks/pmlm.py): `pmlm/src/protein/tasks/pmlm.py`

### Fitness modeling

- [Training interface](https://github.com/microsoft/mu-protein/blob/main/mu-former/main.py): `mu-former/main.py`
- [Mutation datasets](https://github.com/microsoft/mu-protein/blob/main/mu-former/src/data.py): `mu-former/src/data.py`
- [Model vocabulary](https://github.com/microsoft/mu-protein/blob/main/mu-former/src/vocab.py): `mu-former/src/vocab.py`
- [Fitness predictor](https://github.com/microsoft/mu-protein/blob/main/mu-former/src/model.py): `mu-former/src/model.py`
- [Fitness objective](https://github.com/microsoft/mu-protein/blob/main/mu-former/src/criterion.py): `mu-former/src/criterion.py`
- [Model trainer](https://github.com/microsoft/mu-protein/blob/main/mu-former/src/trainer.py): `mu-former/src/trainer.py`
- [Learning-rate schedule](https://github.com/microsoft/mu-protein/blob/main/mu-former/src/lr_scheduler.py): `mu-former/src/lr_scheduler.py`

### Landscape search

- [Muformer landscape](https://github.com/microsoft/mu-protein/blob/main/mu-search/src/flexs/flexs/landscapes/muformer.py): `mu-search/src/flexs/flexs/landscapes/muformer.py`
- [Search loop](https://github.com/microsoft/mu-protein/blob/main/mu-search/src/flexs/flexs/explorer.py): `mu-search/src/flexs/flexs/explorer.py`
- [Random strategy](https://github.com/microsoft/mu-protein/blob/main/mu-search/src/flexs/flexs/baselines/explorers/random.py): `mu-search/src/flexs/flexs/baselines/explorers/random.py`
- [Sequence mutation](https://github.com/microsoft/mu-protein/blob/main/mu-search/src/flexs/flexs/utils/sequence_utils.py): `mu-search/src/flexs/flexs/utils/sequence_utils.py`
- **Measured sequences**

### Other components

- **Protein engineer**

## Connections

- Protein engineer → Training interface: configures training (evidence: `mu-former/main.py`)
- Training interface → Model trainer: starts training (evidence: `mu-former/main.py`)
- Model trainer → Mutation datasets: loads data (evidence: `mu-former/src/trainer.py`)
- Model trainer → Fitness predictor: trains model (evidence: `mu-former/src/trainer.py`)
- Model trainer → Fitness objective: selects loss (evidence: `mu-former/src/trainer.py`)
- Model trainer → Learning-rate schedule: configures schedule (evidence: `mu-former/src/trainer.py`)
- Model trainer → Model vocabulary: uses vocabulary (evidence: `mu-former/src/trainer.py`)
- Protein engineer → Pretraining tasks: pretrains model (evidence: `README.md`)
- Pretraining tasks → Training datasets: uses datasets
- Training datasets → Sequence tokenizer: tokenizes sequences (evidence: `pmlm/src/protein/datasets.py`)
- Pretraining tasks → PMLM model: trains model
- PMLM model → Transformer encoder: uses encoder (evidence: `pmlm/src/protein/models/pmlm.py`)
- Transformer encoder → Attention layers: uses layers
- PMLM model → Prediction heads: uses heads (evidence: `pmlm/src/protein/models/pmlm.py`)
- Pretraining tasks → Pretraining objectives: computes objective
- PMLM model → Training interface: provides pretrained model (evidence: `README.md`)
- Model trainer → Muformer landscape: supplies trained model (evidence: `README.md`)
- Protein engineer → Search loop: initiates search (evidence: `README.md`)
- Search loop → Random strategy: runs strategy
- Random strategy → Sequence mutation: generates mutants (evidence: `mu-search/src/flexs/flexs/baselines/explorers/random.py`)
- Random strategy → Muformer landscape: scores candidates (evidence: `mu-search/src/flexs/flexs/baselines/explorers/random.py`)
- Search loop → Muformer landscape: measures candidates
- Search loop → Measured sequences: records measurements
- Muformer landscape → Fitness predictor: loads predictor (evidence: `mu-search/src/flexs/flexs/landscapes/muformer.py`)
