oteam/solublempnn

ProteinMPNN

This repository contains oteam/solublempnn, converted from v_48_020.pt.

ProteinMPNN is OFoldX's implementation of the ProteinMPNN message-passing inverse-folding family for amino-acid sequence design on a fixed protein backbone.

Disclaimer

This is an unofficial OFoldX implementation of ProteinMPNN. The upstream authors did not write, review, or endorse this implementation or model card.

Model Details

ProteinMPNN is an autoregressive inverse-folding model that designs an amino-acid sequence for a fixed protein backbone. It represents residues as a spatial nearest-neighbor graph, encodes backbone geometry with message-passing blocks, and decodes residues in a sampled causal order. Fixed positions, tied positions, position-specific amino-acid constraints, and sequence profiles can be applied during generation.

Variants

• oteam/proteinmpnn: General-purpose ProteinMPNN using N, CA, C, and O backbone atoms.
• oteam/solublempnn: ProteinMPNN trained for soluble-protein sequence design.
• oteam/proteinmpnn-ca-only: Reduced model for backbones represented only by CA atoms.

All variants share the same autoregressive design interface. The standard and soluble models differ in training distribution, while the CA-only model uses a reduced geometric input. The converter covers the complete released artifact surface: four full-backbone noise-level checkpoints, four soluble checkpoints, three CA-only checkpoints, and the official training-example checkpoint. PXDesign uses the standard v_48_020.pt checkpoint.

Model Specification

Variant	Backbone Atoms	Hidden Size	Encoder Blocks	Decoder Blocks	Neighbors	Num Parameters (M)
Standard	N, CA, C, O	128	3	3	48	1.660
Soluble	N, CA, C, O	128	3	3	48	1.660
CA-only	CA	128	3	3	48	1.629

Links

• Code: ofoldx.models.proteinmpnn
• Paper: Robust deep learning-based protein sequence design using ProteinMPNN
• Developed by: Justas Dauparas, Ivan Anishchenko, Nathaniel Bennett, Hua Bai, Robert J. Ragotte, Lukas F. Milles, Basile I. M. Wicky, Alexis Courbet, Rob J. de Haas, Neil Bethel, Philip J. Y. Leung, Timothy F. Huddy, Sam Pellock, Doug Tischer, Frederick Chan, Brian Koepnick, Hannah Nguyen, Alex Kang, Banumathi Sankaran, Asim K. Bera, Neil P. King, and David Baker
• Model type: Autoregressive message-passing neural network for fixed-backbone protein sequence design
• Original Repository: dauparas/ProteinMPNN

Usage

The model depends on the ofoldx library. Install it with pip:

pip install ofoldx

Sequence Design

Load the concrete design Pipeline:

import ofoldx
from ofoldx.io import read_structure

structure, report = read_structure("backbone.cif")
pipeline = ofoldx.pipeline("design", model="oteam/solublempnn")
output = pipeline.design(structure)

The design Pipeline also exposes autoregressive, sequence-free autoregressive, conditional, and unconditional probability routes. The raw ProteinMpnnModel provides differentiable encode and forward, as well as sample, score, and decoded design. For workflows that relax side chains after sequence design, ProteinMpnnDesignAndPackPipeline composes this family with an explicitly provided MPNN Packer without registering a second ProteinMPNN architecture.

The design-and-pack prepare stage returns a ProteinMpnnDesignAndPackPipelineInput containing the design input and its observation policy. Set filter_by_occupancy=False during preparation to retain observed zero-occupancy atoms through both design and packing; forward consumes the retained policy without requiring it again.

Staged Execution and Scoring

The callable design Pipeline uses the same preparation, computation and decoding as its explicit stages:

prepared = pipeline.prepare(structure)
raw = pipeline.forward(prepared.input, seed=7)
result = pipeline.postprocess(prepared, raw)
result = pipeline(structure, seed=7)

Scoring has its own task Pipeline and reuses the same converted weights:

scorer = ofoldx.pipeline("score", model="oteam/solublempnn")
score = scorer(structure, num_decoding_orders=8, seed=7)

For an in-memory model, construct ProteinMpnnScorePipeline with the designer's model and processor. Its prepare, forward and postprocess stages evaluate the observed or explicitly supplied sequence without sampling new identities.

Training Details

Training Data

ProteinMPNN was trained on fixed protein backbones paired with native amino-acid sequences. The soluble variant focuses its training distribution on soluble proteins, while the CA-only variant uses reduced backbone geometry.

Training Procedure

ProteinMPNN uses an autoregressive sequence-recovery objective with coordinate perturbations for robustness. ProteinMpnnModel.forward is differentiable and exposes the logits needed to train or fine-tune the model. [MpnnSequenceLoss][ofoldx.modules.mpnn.MpnnSequenceLoss] is the masked, label-smoothed training loss. Training the differentiable raw model on caller-supplied structures does not reproduce the upstream training-set construction, parser, clustering, or training program.

Citation

@article{dauparas2022robust,
  author = {Dauparas, Justas and Anishchenko, Ivan and Bennett, Nathaniel and others},
  title = {Robust deep learning-based protein sequence design using ProteinMPNN},
  journal = {Science},
  volume = {378},
  number = {6615},
  pages = {49--56},
  year = {2022},
  doi = {10.1126/science.add2187}
}

If OFoldX supports your research, also cite the OFoldX software:

@software{chen2026ofoldx,
  author = {Chen, Zhiyuan},
  title  = {OFoldX},
  year   = {2026},
  url    = {https://github.com/OTeam-AI4S/OFoldX},
}

Contact

Please use OFoldX GitHub issues for questions about this implementation or model card.

License

The original model parameters are distributed under the MIT license, retained in LICENSE.

The OFoldX implementation is separately licensed under AGPL-3.0-or-later; see license.md and license-faq.md.

These converted parameters use native OFoldX tensor names and the canonical vocabulary. Conversion changes the parameter representation and vocabulary axes; it does not change the upstream weight license.

Upstream source revision: 8907e6671bfbfc92303b5f79c4b5e6ce47cdef57.