oteam/membranempnn-global

MembraneMPNN

This repository contains oteam/membranempnn-global, converted from global_label_membrane_mpnn_v_48_020.pt.

MembraneMPNN designs amino-acid sequences on a fixed protein backbone with global or per-residue membrane labels.

Disclaimer

This is an unofficial OFoldX implementation of the membrane-conditioned ProteinMPNN models distributed by LigandMPNN. The upstream authors did not write, review, or endorse this implementation or model card.

Model Details

MembraneMPNN encodes N, CA, C and O backbone geometry as a spatial residue graph and predicts amino-acid identities with an autoregressive message-passing decoder. Membrane labels supply additional residue conditioning. Design can retain fixed positions, tie residue identities and apply position-specific amino-acid constraints and logit biases.

Variants

The upstream download script provides two checkpoints:

• global_label_membrane_mpnn_v_48_020.pt: Global conditioning, with label 0 for soluble proteins and 1 for transmembrane proteins.
• per_residue_label_membrane_mpnn_v_48_020.pt: Residue conditioning, with label 0 for exposed/other residues, 1 for membrane-interface residues and 2 for membrane-buried residues.

Use the label meanings belonging to the selected checkpoint. Both variants use the same Model and Pipeline classes. A scalar membrane_labels value applies to every retained protein residue. A mapping assigns labels to canonical component occurrences; unspecified residues receive label 0.

Model Specification

Backbone Atoms	Hidden Size	Encoder Blocks	Decoder Blocks	Neighbors
N, CA, C, O	128	3	3	48

Links

• Code: ofoldx.models.membranempnn
• ProteinMPNN architecture: Robust deep learning-based protein sequence design using ProteinMPNN
• Model type: Membrane-conditioned autoregressive fixed-backbone protein sequence design
• Original Repository: dauparas/LigandMPNN

Usage

Install the ofoldx library:

pip install ofoldx

Checkpoint Conversion

Download the original weights with the upstream download script, then convert each selected checkpoint to a local OFoldX repository:

python -m ofoldx.models.membranempnn.convert \
    model_params/global_label_membrane_mpnn_v_48_020.pt ./membrane-global
python -m ofoldx.models.membranempnn.convert \
    model_params/per_residue_label_membrane_mpnn_v_48_020.pt ./membrane-per-residue

Global Sequence Design

from ofoldx.io import read_structure
from ofoldx.models.membranempnn import MembraneMpnnPipeline

structure, report = read_structure("backbone.cif")
pipeline = MembraneMpnnPipeline.from_repository("oteam/membranempnn-global")
output = pipeline.design(structure, membrane_labels=1, num_candidates=4, seed=7)

The repository also supports task selection through ofoldx.pipeline("design", model="oteam/membranempnn-global").

Per-Residue Sequence Design

Label residues by reference (instance symbol, component position); unnamed residues read zero:

from ofoldx.data.molecular import ComponentRef
from ofoldx.io import read_structure
from ofoldx.models.membranempnn import MembraneMpnnPipeline

structure, report = read_structure("backbone.cif")
labels = {ComponentRef("A", 0): 2, ComponentRef("A", 1): 1}
pipeline = MembraneMpnnPipeline.from_repository("oteam/membranempnn-per-residue")
output = pipeline.design(structure, membrane_labels=labels, num_candidates=4, seed=7)

Sequence Scoring and Probabilities

from ofoldx.models.membranempnn import MembraneMpnnScorePipeline

pipeline = MembraneMpnnScorePipeline.from_repository("oteam/membranempnn-global")
result = pipeline.score(structure, membrane_labels=1, num_decoding_orders=8, seed=7)
result.scores["designed_sequence_nll"]

score returns designed and global sequence NLL in nats per residue, retaining the exact position scopes and per-order evaluations. It evaluates the input sequence by default; use_sequence=False uses sequence-free predictions.

The Pipeline also exposes autoregressive_probabilities, sequence_free_autoregressive_probabilities, conditional_probabilities and unconditional_probabilities. These probability results retain the canonical residue references, logits and decoding ranks.

The raw MembraneMpnnModel consumes the Processor's ProteinMpnnInput and provides differentiable encode and forward, plus sampling and probability operations. MembraneMpnnDesignAndPackPipeline(designer=designer, packer=packer) combines a membrane Pipeline with an independently loaded MPNN Packer for side-chain packing.

The design and score Pipelines expose prepare, forward and postprocess. Calling a Pipeline executes those stages for its own task. For example:

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

The design-and-pack composition stores its complete design child in design/ and packing child in packer/. Its prepared input retains the original structure and designed residue scope, while one generator advances through design and packing. It shares ProteinMpnnDesignAndPackPipelineInput with ProteinMPNN and retains filter_by_occupancy from preparation for packing. The policy is supplied once to prepare, including when observed zero-occupancy atoms must remain available.

Training Details

The upstream model descriptions identify the global model as ProteinMPNN trained with an additional binary soluble/transmembrane input. The per-residue model is trained with a separate environment label for each residue, distinguishing buried hydrophobic regions, polar interfaces and other regions. Both variants predict protein sequences conditioned on backbone geometry and the supplied labels.

Citation

For the underlying ProteinMPNN architecture:

@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: 26ec57ac976ade5379920dbd43c7f97a91cf82de.