ThermoMPNN¶

Structure-based prediction of protein thermal stability changes (ddG) for single-point mutations, using transfer learning from ProteinMPNN.

License: MIT · Molecules: protein · Tasks: stability_prediction

Actions: predict · Variants: 1

At a glance¶

Use it when

You have an experimental or high-confidence predicted 3D structure and want to identify stabilizing single-point mutations for a protein engineering campaign
You need a complete site-saturation mutagenesis landscape to find all positions and substitutions that could improve thermostability
You are engineering thermostable industrial enzymes and want to computationally screen all possible single mutations before experimental validation
You want to understand which positions in a protein are structurally critical (most mutations destabilizing) versus tolerant of substitution
You need a structure-aware stability predictor that runs quickly on a T4 GPU for integration into automated protein design workflows
You are interpreting disease-causing missense mutations and want to assess whether they destabilize protein structure

Strengths

Structure-based stability prediction using ProteinMPNN message-passing neural network backbone, directly modeling the 3D context of each mutation rather than relying on sequence statistics alone
Transfer learning from ProteinMPNN's structural representations achieves state-of-the-art single-mutation ddG prediction (PCC ~0.75, RMSE ~0.71 kcal/mol on Megascale dataset)
Full site-saturation mutagenesis (SSM) scanning mode predicts ddG for all 20 amino acid substitutions at every position in a single call, producing a comprehensive stability landscape
Lightweight T4 GPU requirement (8 GB RAM) makes it one of the least resource-intensive structure-based stability predictors in this catalog
MIT license with no usage restrictions -- suitable for commercial therapeutic protein engineering and academic research
Fast inference for single mutations and moderate-length proteins (up to 1024 residues), enabling integration into iterative protein design pipelines
Well-validated in peer-reviewed literature (PNAS 2024), with clear benchmarks against competing methods on standardized datasets

Limitations

Requires a 3D structure (PDB format with backbone atoms N, CA, C, O) as input -- cannot score mutations from sequence alone; use TemBERTure or ESM2 log-likelihoods when no structure is available
Single-point mutations only -- cannot predict combined effects of two or more simultaneous mutations; use ThermoMPNN-D for double mutations with epistasis modeling
Limited to single-chain proteins up to 1024 residues -- multi-chain complexes and very large proteins are not supported
Membrane proteins are under-represented in training data; stability predictions in a membrane context are unreliable
Intrinsically disordered proteins cannot be analyzed because a stable folded structure is required as the reference state
No uncertainty estimates on predictions -- single point estimate per mutation without confidence intervals
Training data biased toward globular soluble proteins from structural genomics databases; performance may degrade on protein families outside this distribution

Reach for something else when

You do not have a 3D structure and cannot generate one -- use TemBERTure for sequence-only thermostability prediction
You need to evaluate double or multiple simultaneous mutations -- use ThermoMPNN-D (epistatic mode) for paired mutations or SPURS for multi-mutation ddG prediction
You need whole-protein melting temperature (Tm) rather than per-mutation ddG values -- use TemBERTure for global Tm prediction
You are working with membrane proteins where stability depends on the lipid bilayer environment -- structure-based ddG models do not capture this context
You need variant effect prediction driven by evolutionary conservation rather than structural features -- use an MSA-based evolutionary conservation method for evolution-informed scoring
You want a sequence-only tool for rapid screening of millions of sequences without requiring structure prediction as a preprocessing step

Alternatives

Model	Better when	Worse when
thermompnn_d	Handles both single and double mutations with an epistatic interaction mode, capturing combinatorial mutation effects ThermoMPNN cannot assess.	Higher resource use (12 GB vs 8 GB) and loads two checkpoints; for pure single-mutation SSM scanning ThermoMPNN is lighter and sufficient.
spurs	Supports multi-mutation ddG with pairwise epistasis, emits full DMS matrices, and combines ESM2 + GNN priors for potentially broader coverage.	Heavier (16 GB RAM) and additionally requires the sequence alongside the structure; ThermoMPNN is lighter with a longer single-mutation track record.

API & schema¶

Call an action with POST /api/v1/{slug}/{action} — the request envelope is {"items": [...], "params": {...}} and a success returns {"results": [...]}. See the HTTP API page for the base URL, error shape, and full contract.

`predict`¶

Call it

curl -X POST http://127.0.0.1:8000/api/v1/thermompnn/predict \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "pdb": "<contents of a .pdb file>"
    }
  ]
}'

Request — ThermoMPNNPredictRequest

Field	Type	Required	Constraints	Description
`params`	ThermoMPNNPredictParams	no		Optional parameters controlling this action (defaults are used when omitted).
`items`	list[ThermoMPNNPredictRequestItem]	yes	items 1–1	Batch of inputs to process in a single request. Exactly 1 PDB structure per request.

Nested types

ThermoMPNNPredictParams

Field	Type	Required	Constraints	Description
`chain`	string \| null	no		Chain ID to use for prediction. If not specified, uses first chain in PDB.

ThermoMPNNPredictRequestItem

Field	Type	Required	Constraints	Description
`pdb`	string	yes	len 1–2500000	Input structure in PDB format.
`mutations`	list[string] \| null	no		Optional list of mutations in format 'WT{position}MUT' (e.g., 'A100V' for Ala->Val at position 100). Position is 1-indexed within the selected chain's modeled sequence (not PDB residue numbers). If not provided, performs site-saturation mutagenesis (SSM) scan for all positions.

Raw JSON Schema

{
  "$defs": {
    "ThermoMPNNPredictParams": {
      "additionalProperties": false,
      "description": "Parameters for ThermoMPNN prediction",
      "properties": {
        "chain": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Chain ID to use for prediction. If not specified, uses first chain in PDB.",
          "title": "Chain"
        }
      },
      "title": "ThermoMPNNPredictParams",
      "type": "object"
    },
    "ThermoMPNNPredictRequestItem": {
      "additionalProperties": false,
      "properties": {
        "pdb": {
          "description": "Input structure in PDB format.",
          "maxLength": 2500000,
          "minLength": 1,
          "title": "Pdb",
          "type": "string"
        },
        "mutations": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional list of mutations in format 'WT{position}MUT' (e.g., 'A100V' for Ala->Val at position 100). Position is 1-indexed within the selected chain's modeled sequence (not PDB residue numbers). If not provided, performs site-saturation mutagenesis (SSM) scan for all positions.",
          "title": "Mutations"
        }
      },
      "required": [
        "pdb"
      ],
      "title": "ThermoMPNNPredictRequestItem",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "params": {
      "$ref": "#/$defs/ThermoMPNNPredictParams",
      "description": "Optional parameters controlling this action (defaults are used when omitted)."
    },
    "items": {
      "description": "Batch of inputs to process in a single request. Exactly 1 PDB structure per request.",
      "items": {
        "$ref": "#/$defs/ThermoMPNNPredictRequestItem"
      },
      "maxItems": 1,
      "minItems": 1,
      "title": "Items",
      "type": "array"
    }
  },
  "required": [
    "items"
  ],
  "title": "ThermoMPNNPredictRequest",
  "type": "object"
}

Response — ThermoMPNNPredictResponse

Field	Type	Required	Constraints	Description
`results`	list[ThermoMPNNPredictResponseItem]	yes		Per-input results, returned in the same order as the request items.

Nested types

ThermoMPNNPredictResponseItem

Field	Type	Required	Description
`mutation`	string	yes	Mutation in format 'WT{position}MUT'.
`position`	integer	yes	Residue position (1-indexed within the selected chain's modeled sequence, not PDB residue numbers).
`wildtype`	string	yes	Wildtype amino acid.
`mutation_aa`	string	yes	Mutant amino acid.
`ddg`	number	yes	Predicted change in free energy (ddG) in kcal/mol.

Raw JSON Schema

{
  "$defs": {
    "ThermoMPNNPredictResponseItem": {
      "description": "Response item for a single mutation prediction",
      "properties": {
        "mutation": {
          "description": "Mutation in format 'WT{position}MUT'.",
          "title": "Mutation",
          "type": "string"
        },
        "position": {
          "description": "Residue position (1-indexed within the selected chain's modeled sequence, not PDB residue numbers).",
          "title": "Position",
          "type": "integer"
        },
        "wildtype": {
          "description": "Wildtype amino acid.",
          "title": "Wildtype",
          "type": "string"
        },
        "mutation_aa": {
          "description": "Mutant amino acid.",
          "title": "Mutation Aa",
          "type": "string"
        },
        "ddg": {
          "description": "Predicted change in free energy (ddG) in kcal/mol.",
          "title": "Ddg",
          "type": "number"
        }
      },
      "required": [
        "mutation",
        "position",
        "wildtype",
        "mutation_aa",
        "ddg"
      ],
      "title": "ThermoMPNNPredictResponseItem",
      "type": "object"
    }
  },
  "properties": {
    "results": {
      "description": "Per-input results, returned in the same order as the request items.",
      "items": {
        "$ref": "#/$defs/ThermoMPNNPredictResponseItem"
      },
      "title": "Results",
      "type": "array"
    }
  },
  "required": [
    "results"
  ],
  "title": "ThermoMPNNPredictResponse",
  "type": "object"
}

Usage¶

One-line summary: Structure-based prediction of protein thermal stability changes (ddG) for single-point mutations, using transfer learning from ProteinMPNN.

Overview¶

ThermoMPNN is a graph neural network developed by Dieckhaus et al. (2023) at the Kuhlman Lab that predicts changes in protein thermostability (ddG in kcal/mol) upon single amino acid substitutions. It leverages transfer learning from ProteinMPNN -- a protein sequence design model -- by fine-tuning its structural representations for stability prediction. The model takes a PDB structure as input and supports both targeted mutation predictions and full site-saturation mutagenesis (SSM) scans.

Architecture¶

Property	Value
Architecture	Message-passing neural network (GNN)
Base model	ProteinMPNN (v_48_020)
Prediction head	2 dense layers ([64, 32]) with light attention
Input	PDB structure + mutations
Output	ddG in kcal/mol
Max sequence length	1024 residues
Batch size	1 PDB per request

Capabilities & Limitations¶

CAN be used for: - Predicting ddG for specific single-point mutations given a PDB structure - Running complete site-saturation mutagenesis (SSM) scans over all positions - Identifying stabilizing mutations for protein engineering - Evaluating the stability impact of disease-associated mutations

CANNOT be used for: - Sequence-only prediction (requires PDB structure input) - Double or multi-point mutations (use ThermoMPNN-D instead) - Proteins longer than 1024 residues - Membrane protein stability in lipid bilayer context

Other considerations: - Mutations use 1-indexed positions within the selected chain's modeled sequence (not PDB residue numbers) in format WT{position}MUT (e.g., A100V means the 100th residue in the parsed chain sequence) - When mutations is null, a full SSM scan is performed (20 substitutions x N positions) - Chain ID can be specified; defaults to first chain if not provided

Usage Examples¶

from models.thermompnn.schema import (
    ThermoMPNNPredictParams,
    ThermoMPNNPredictRequest,
    ThermoMPNNPredictRequestItem,
)

# Predict ddG for specific mutations
request = ThermoMPNNPredictRequest(
    params=ThermoMPNNPredictParams(chain="A"),
    items=[
        ThermoMPNNPredictRequestItem(
            pdb=pdb_string,
            mutations=["M1V", "V2A", "L3I"],
        )
    ],
)

# Full SSM scan (mutations=None)
ssm_request = ThermoMPNNPredictRequest(
    params=ThermoMPNNPredictParams(chain="A"),
    items=[
        ThermoMPNNPredictRequestItem(
            pdb=pdb_string,
            mutations=None,
        )
    ],
)

Architecture & training¶

Architecture¶

Model Type & Innovation¶

ThermoMPNN is a graph neural network (GNN) for predicting changes in protein thermal stability (ddG) upon single-point mutations. It uses transfer learning from ProteinMPNN -- a message-passing neural network originally trained for protein sequence design -- and fine-tunes it for stability prediction. The key innovation is leveraging ProteinMPNN's learned structural representations to predict thermostability changes, achieving strong performance with relatively little stability-specific training data.

Parameters & Layers¶

Component	Details
Architecture	Message-passing neural network (GNN)
Base model	ProteinMPNN (v_48_020)
Transfer learning head	2 final layers, hidden dims [64, 32]
Light attention	Enabled
Subtract mutation	Enabled
Freeze base weights	Yes (ProteinMPNN backbone frozen)
Input	PDB structure (3D coordinates)
Output	ddG in kcal/mol

Training Data¶

From Dieckhaus et al. (2023): ThermoMPNN was trained on two complementary datasets. The Megascale dataset (Tsuboyama et al.) contains 272,712 single-point mutation ddG values across 298 proteins, derived from protease sensitivity experiments on small proteins (<75 residues). The Fireprot dataset was curated from FireProtDB, containing 3,438 mutations across 100 unique proteins with a wider distribution of protein sizes. Both datasets were clustered at 25% sequence identity using MMseqs2, with cross-referencing to ensure no homology overlap between train and test sets. The Megascale dataset was split approximately 80/10/10 (train/validation/test) by mutation count.

The model was trained on experimental stability measurements (ddG values) from mutation studies, using transfer learning from ProteinMPNN's protein design representations.

Loss Function & Objective¶

Regression loss for predicting ddG (change in Gibbs free energy of unfolding) in kcal/mol upon single-point mutations.

Tokenization / Input Processing¶

Input processing involves:

PDB parsing: Structure parsed using alt_parse_PDB from ProteinMPNN utilities
Chain selection: Target chain extracted (first chain if not specified)
Feature extraction: Backbone coordinates and residue identities extracted
Mutation encoding: Wild-type and mutant amino acids encoded using the 20-letter + X alphabet (ACDEFGHIKLMNPQRSTVWYX)
Graph construction: Structure represented as a k-nearest-neighbors graph of backbone atoms

Performance & Benchmarks¶

Published Benchmarks¶

From Dieckhaus et al. (2023):

Dataset	Metric	ThermoMPNN	ProteinMPNN (naive)
Megascale test	Spearman (SCC)	0.725 +/- 0.003	0.487 +/- 0.006
Fireprot test	Spearman (SCC)	0.657 +/- 0.003	0.50 +/- 0.01
Megascale test	Pearson (PCC)	0.754 +/- 0.004	--
SSYM direct	Pearson (PCC)	0.72	--
SSYM inverse	Pearson (PCC)	0.60	--
S669	Pearson (PCC)	0.43	--

ThermoMPNN outperformed Rosetta, RaSP, and PROSTATA on both Megascale and Fireprot datasets (PCC 0.04-0.05 higher than any other method). Transfer learning from pre-trained ProteinMPNN was critical: training from naive weights reduced Megascale SCC to 0.642 and Fireprot SCC to 0.50. The light attention module provided a small but consistent performance boost across both datasets.

BioLM Verification Results¶

Integration tests use structural validation (checking response format, mutation fields, and numeric ddG values) rather than exact numerical matching, due to the structure-dependent nature of predictions.

Comparison to Alternatives¶

Model	Task	Input	Advantage
ThermoMPNN	Single mutation ddG	PDB structure	Fast, structure-aware single mutations
ThermoMPNN-D	Single + double mutation ddG	PDB structure	Handles epistatic double mutations
TemBERTure	Thermophilicity + Tm	Sequence only	No structure needed

Strengths & Limitations¶

Pros¶

Structure-aware: uses 3D backbone coordinates for predictions
Transfer learning from ProteinMPNN provides strong structural representations
Supports both targeted mutations and full site-saturation mutagenesis (SSM) scans
Per-mutation ddG predictions (not just global stability)
Fast inference on GPU

Cons¶

Requires PDB structure input (not sequence-only)
Batch size limited to 1 PDB at a time
Maximum sequence length of 1024 residues
Single-point mutations only (use ThermoMPNN-D for double mutations)

Known Failure Modes¶

Missing residues in PDB (gaps) are flagged as "-" and handled, but may affect nearby predictions
PDB files with non-standard formatting may fail during parsing
Very large structures (beyond 1024 residues) may exceed GPU memory limits; 1024 residues is the recommended upper bound but is not enforced at the API level

Implementation Details¶

Inference Pipeline¶

Request --> Validate PDB + mutations
  --> Write PDB to temp file
  --> Parse PDB (alt_parse_PDB)
  --> Select chain
  --> Build mutation objects (0-indexed internally, 1-indexed in chain's modeled sequence externally)
  --> [GPU] Forward pass through ThermoMPNN
  --> Extract ddG predictions
  --> Format response (1-indexed positions within chain's modeled sequence)
  --> Cleanup temp files

Memory & Compute Profile¶

Resource	Value
GPU	T4
Memory	8 GB
CPU	2 cores

Determinism & Reproducibility¶

Torch manual seed: Yes (42)
CUDA manual seed: Yes (42)
Model set to eval mode: Yes
Inference under torch.no_grad(): Yes

Caching Behavior¶

Response caching is handled outside the model container and is not the responsibility of the inference code.

Versions & Changelog¶

Version	Date	Changes
v1	2024	Initial implementation

Biology¶

Molecule Coverage¶

Primary Molecule Type(s)¶

ThermoMPNN is designed for globular proteins with known 3D structures (PDB format). It predicts the thermodynamic effect (ddG) of single amino acid substitutions on protein stability. The model handles single-chain proteins up to 1024 residues and requires backbone atom coordinates (N, CA, C, O) for each residue.

Cross-Applicability¶

Molecule Type	Applicability	Evidence	Caveats
Globular proteins	High	Primary training target	Best for well-folded soluble proteins
Enzymes	High	Well-represented in stability datasets	Useful for engineering thermostable enzymes
Antibodies	Moderate	Single-chain Fv or Fab structures may work	Multi-chain requires specifying chain ID
Membrane proteins	Low	Under-represented in training data	Stability in membrane context not modeled
Intrinsically disordered	Not applicable	Requires folded structure	No stable baseline state

Biological Problems Addressed¶

Protein Stability Engineering¶

Protein stability is a critical property for therapeutic proteins, industrial enzymes, and research reagents. The change in Gibbs free energy of unfolding (ddG) quantifies how a mutation affects stability: negative ddG indicates stabilization, positive ddG indicates destabilization.

Experimental methods for measuring ddG (e.g., thermal denaturation, urea unfolding) are laborious and require purified protein for each variant. ThermoMPNN enables computational screening of all possible single-point mutations in a protein, identifying stabilizing candidates for experimental validation.

Applications include: - Identifying stabilizing mutations for therapeutic proteins - Engineering thermostable industrial enzymes - Understanding disease-causing mutations that destabilize proteins - Rational protein design guided by stability predictions

Site-Saturation Mutagenesis (SSM) Scanning¶

When no specific mutations are provided, ThermoMPNN performs a complete SSM scan -- predicting ddG for all 20 possible amino acid substitutions at every position. This produces a comprehensive stability landscape that reveals:

Mutation-tolerant positions (many neutral substitutions)
Critical positions (most substitutions are destabilizing)
Potential stabilizing mutations (negative ddG)

Applied Use Cases¶

ThermoMPNN has been applied in several published studies:

Epistatic double mutations (ThermoMPNN-D): Dieckhaus & Kuhlman (2025, Protein Science) extended ThermoMPNN to double-mutant predictions and demonstrated that stability models fail to capture epistatic interactions, motivating the ThermoMPNN-D variant.
Thermostable protein design: Ertelt et al. (2024, bioRxiv) built on the ProteinMPNN backbone (shared with ThermoMPNN) in HyperMPNN to design thermostable proteins from hyperthermophilic data, achieving designs stable at 95°C from a 65°C starting point.
PNAS peer-reviewed benchmark: The peer-reviewed PNAS (2024) publication of ThermoMPNN established state-of-the-art single-mutation ddG prediction (PCC ~0.75, RMSE ~0.71 kcal/mol) on the Megascale dataset.
Human Domainome benchmarking: Beltran et al. (2025, Nature) benchmarked ThermoMPNN on 500K+ missense variants across 500 human protein domains and found it to be the best stability predictor overall (median rho = 0.50, 0.57 excluding zinc-fingers), outperforming all other dedicated stability predictors.
SPURS comparison: Li & Luo (2025, Nature Communications) introduced SPURS and benchmarked it against ThermoMPNN on the Megascale test set, with ThermoMPNN achieving Spearman correlation of 0.77 (SPURS: 0.83).

Predecessor Models¶

ThermoMPNN builds on ProteinMPNN (Dauparas et al., 2022), a message-passing neural network for protein sequence design. ProteinMPNN was trained to predict amino acid sequences compatible with a given backbone structure. ThermoMPNN transfers these learned structural representations to the task of stability prediction.

Complementary Models¶

ThermoMPNN-D: Extended version supporting double (paired) mutations with epistatic interaction modeling. Use when evaluating combinations of two mutations.
ESM2: General protein language model for sequence-based property prediction. Can provide complementary sequence-based stability signals.
ESMFold / Chai-1: Structure prediction models. Use to generate input PDB structures when experimental structures are unavailable.

Alternative Models¶

Alternative	Advantage over ThermoMPNN	Disadvantage
ThermoMPNN-D	Handles double mutations and epistasis	More complex, higher resource usage
TemBERTure	Sequence-only input, no structure needed	No per-mutation ddG, only global stability
RaSP	Anticipated: rapid stability prediction	Different training data and approach

Biological Background¶

Protein stability refers to the thermodynamic balance between the folded (native) and unfolded states of a protein. The Gibbs free energy of unfolding (delta-G) quantifies this balance: proteins with more negative delta-G are more stable. When a mutation is introduced, the change in stability (ddG = delta-G_mutant - delta-G_wildtype) indicates whether the mutation stabilizes (ddG < 0) or destabilizes (ddG > 0) the protein.

The structural basis of protein stability involves: - Hydrophobic core packing: Mutations that disrupt the hydrophobic core are typically destabilizing - Hydrogen bonds: Loss of hydrogen bonds generally destabilizes the structure - Salt bridges: Charged residue pairs that contribute favorably to stability - Conformational entropy: Mutations to more flexible residues (e.g., Gly) can destabilize through increased unfolded-state entropy - Steric clashes: Large-to-small or small-to-large substitutions that create unfavorable contacts

Graph neural networks like ThermoMPNN are well-suited to this task because protein structures are naturally represented as graphs, where nodes are residues and edges encode spatial proximity and chemical interactions.

Sources & license¶

License: MIT (text) — ThermoMPNN bundles the ProteinMPNN backbone (Dauparas et al., 2022; University of Washington) as a frozen inference dependency; ProteinMPNN is independently MIT-licensed (https://github.com/dauparas/ProteinMPNN/blob/main/LICENSE).

Papers

Transfer learning to leverage larger datasets for improved prediction of protein stability changes — bioRxiv preprint, 2023 · DOI

Source repositories

github: https://github.com/Kuhlman-Lab/ThermoMPNN

Cite

@article{dieckhaus2023thermompnn,
  title={Transfer learning to leverage larger datasets for improved prediction of protein stability changes},
  author={Dieckhaus, Henry and Brocidiacono, Michael and Randolph, Nicholas and Kuhlman, Brian},
  journal={bioRxiv},
  year={2023},
  doi={10.1101/2023.07.27.550881}
}

ThermoMPNN¶

At a glance¶

API & schema¶

predict¶

Usage¶

Overview¶

Architecture¶

Capabilities & Limitations¶

Usage Examples¶

Architecture & training¶

Architecture¶

Model Type & Innovation¶

Parameters & Layers¶

Training Data¶

Loss Function & Objective¶

Tokenization / Input Processing¶

Performance & Benchmarks¶

Published Benchmarks¶

BioLM Verification Results¶

Comparison to Alternatives¶

Strengths & Limitations¶

Pros¶

Cons¶

Known Failure Modes¶

Implementation Details¶

Inference Pipeline¶

Memory & Compute Profile¶

Determinism & Reproducibility¶

Caching Behavior¶

Versions & Changelog¶

Biology¶

Molecule Coverage¶

Primary Molecule Type(s)¶

Cross-Applicability¶

Biological Problems Addressed¶

Protein Stability Engineering¶

Site-Saturation Mutagenesis (SSM) Scanning¶

Applied Use Cases¶

Related Models¶

Predecessor Models¶

Complementary Models¶

Alternative Models¶

Biological Background¶

Sources & license¶

`predict`¶