Proteinmpnn

ProteinMPNN: Inverse Folding for Protein Sequence Design

Overview

ProteinMPNN designs amino acid sequences for a given protein backbone structure. It is the sequence design step in the modern protein design pipeline:

RFdiffusion (backbone) → ProteinMPNN (sequence) → AlphaFold2 (validation)

Given a backbone PDB, ProteinMPNN outputs sequences that are predicted to fold into that structure. It can design multiple chains simultaneously, lock specific residues, enforce symmetry, and score existing sequences.

Core capabilities:

• Sequence design — generate sequences for any protein backbone
• Scoring — evaluate how well a given sequence fits a structure
• Fixed positions — lock active site or interface residues
• Tied positions — enforce symmetric sequences across chains (homooligomers)
• Amino acid bias — favor or disfavor specific amino acids globally or per-residue
• PSSM guidance — incorporate evolutionary information

Installation

# Create conda environment
conda create --name mlfold python=3.9
conda activate mlfold

# Install PyTorch with CUDA
conda install pytorch torchvision torchaudio cudatoolkit=11.3 -c pytorch

# Clone repository
git clone https://github.com/dauparas/ProteinMPNN.git
cd ProteinMPNN

No pip install — run directly from the repository.

Model Checkpoints

Checkpoint	Use case
v_48_020.pt	Default; best general-purpose model
v_48_030.pt	Latest checkpoint
v_48_010.pt	Intermediate checkpoint
v_48_002.pt	Early checkpoint
soluble_model_weights/v_48_020.pt	Soluble proteins only
ca_model_weights/v_48_020.pt	CA-only backbone (faster)

Default: v_48_020.pt. Use --use_soluble_model or --ca_only to switch model families.

Core Workflows

1. Minimal monomer design

python protein_mpnn_run.py \
  --pdb_path input.pdb \
  --pdb_path_chains "A" \
  --num_seq_per_target 8 \
  --sampling_temp "0.1" \
  --out_folder results/

Generates 8 sequences for chain A at temperature 0.1. Output: results/seqs/input.fa.

2. Multi-chain complex

Parse first, then design:

# Step 1: parse PDB directory to JSONL
python helper_scripts/parse_multiple_chains.py \
  --input_path pdbs/ --output_path parsed.jsonl

# Step 2: assign which chains to design
python helper_scripts/assign_fixed_chains.py \
  --input_path parsed.jsonl \
  --output_path chain_ids.jsonl \
  --chain_list "A B"

# Step 3: run design
python protein_mpnn_run.py \
  --jsonl_path parsed.jsonl \
  --chain_id_jsonl chain_ids.jsonl \
  --num_seq_per_target 2 \
  --sampling_temp "0.1" \
  --out_folder results/

3. Fixed positions (lock active site)

# Create fixed positions dict
python helper_scripts/make_fixed_positions_dict.py \
  --input_path parsed.jsonl \
  --output_path fixed.jsonl \
  --chain_list "A" \
  --position_list "1 2 3 45 46 47"

# Run with fixed positions
python protein_mpnn_run.py \
  --jsonl_path parsed.jsonl \
  --fixed_positions_jsonl fixed.jsonl \
  --num_seq_per_target 4 \
  --sampling_temp "0.1" \
  --out_folder results/

To specify designable positions instead (all others fixed): add --specify_non_fixed.

4. Homooligomer / symmetric design

# Tie equivalent positions across all chains
python helper_scripts/make_tied_positions_dict.py \
  --input_path parsed.jsonl \
  --output_path tied.jsonl \
  --homooligomer 1

python protein_mpnn_run.py \
  --jsonl_path parsed.jsonl \
  --tied_positions_jsonl tied.jsonl \
  --num_seq_per_target 4 \
  --sampling_temp "0.2" \
  --out_folder results/

All chains get the same sequence. Works for C2, C3, C6, etc.

5. Score existing sequences

python protein_mpnn_run.py \
  --pdb_path structure.pdb \
  --path_to_fasta sequences.fasta \
  --score_only 1 \
  --out_folder results/

Reports score (negative log probability) and seq_recovery for each sequence.

6. Amino acid bias (avoid cysteine)

python helper_scripts/make_bias_AA.py \
  --output_path bias.jsonl \
  --AA_list "C" \
  --bias_list "-1.0"

python protein_mpnn_run.py \
  --jsonl_path parsed.jsonl \
  --bias_AA_jsonl bias.jsonl \
  --omit_AAs "C" \
  --out_folder results/

Use --omit_AAs "C M" to fully exclude amino acids.

Key Parameters

Parameter	Default	Description
--num_seq_per_target	1	Sequences to generate per structure
--sampling_temp	—	Sampling temperature (0.1–0.3 typical; higher = more diverse)
--model_name	v_48_020	Model checkpoint
--use_soluble_model	—	Use soluble-only model weights
--ca_only	—	Use CA-only model (faster, less accurate)
--backbone_noise	0.0	Gaussian noise on atom coordinates
--batch_size	1	GPU batch size
--seed	0 (random)	Random seed for reproducibility
--save_score	0	Save scores to NPZ
--save_probs	0	Save AA probabilities to NPZ
--score_only	0	Score without generating
--omit_AAs	—	Exclude amino acids (e.g. "C M")

Output Format

results/
├── seqs/
│   ├── protein_name.fa          ← designed sequences (FASTA)
├── scores/                      ← NPZ score files (if --save_score 1)
└── probs/                       ← probability NPZ files (if --save_probs 1)

FASTA header format:

>native, score=-0.45, global_score=-0.42, seq_recovery=1.0, model_name=v_48_020
>T=0.1, sample=1, score=-0.48, global_score=-0.46, seq_recovery=0.87

• score — negative log probability over designed residues (lower = better fit)
• global_score — negative log probability over all residues
• seq_recovery — fraction of positions that match the input sequence

Scripts

• scripts/design.py — design sequences from PDB files; see scripts/design.py --help

Resources

• GitHub: https://github.com/dauparas/ProteinMPNN
• Paper: Dauparas et al., Science 2022 — https://doi.org/10.1126/science.add2187

References

• references/cli-reference.md — full CLI parameter reference, all input/output formats, PSSM guidance, conditional probabilities