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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: naity
• Source: naity/FM4Life
• License: MIT

Install and usage instructions live in the source repository linked above.