From 46d55f285a68f0bb486235d946eccae47ecea902 Mon Sep 17 00:00:00 2001 From: Rocco Moretti Date: Wed, 29 Jul 2026 15:31:27 -0500 Subject: [PATCH 1/2] docs: Add MPNN documentation Add documentation for MPNN. This documentation is only covering basic usage at the moment. We probably still need/want to convert/add tutorials and examples. --- models/mpnn/README.md | 135 +--------------------------- models/mpnn/docs/config_json.md | 86 ++++++++++++++++++ models/mpnn/docs/conversion.md | 112 +++++++++++++++++++++++ models/mpnn/docs/index.md | 75 +++++++++++++--- models/mpnn/docs/inference_input.md | 133 +++++++++++++++++++++++++++ models/mpnn/docs/outputs.md | 49 ++++++++++ models/mpnn/docs/training.md | 7 ++ models/mpnn/docs/weights.md | 71 +++++++++++++++ 8 files changed, 523 insertions(+), 145 deletions(-) create mode 100644 models/mpnn/docs/config_json.md create mode 100644 models/mpnn/docs/conversion.md create mode 100644 models/mpnn/docs/inference_input.md create mode 100644 models/mpnn/docs/outputs.md create mode 100644 models/mpnn/docs/training.md create mode 100644 models/mpnn/docs/weights.md diff --git a/models/mpnn/README.md b/models/mpnn/README.md index 027e309f..b0d6c815 100644 --- a/models/mpnn/README.md +++ b/models/mpnn/README.md @@ -8,139 +8,10 @@ ProteinMPNN enables protein sequence design given a fixed backbone structure of a protein. LigandMPNN extends this functionality to enable fixed-backbone sequence design of proteins in the context of ligands (i.e. small molecules, ions, DNA/RNA, etc.). This module represents a re-implementation of the original ProteinMPNN and LigandMPNN models within the modelforge/atomworks framework. -For more information on the original models, please see: -- ProteinMPNN: [Robust deep learning–based protein sequence design using ProteinMPNN](https://doi.org/10.1126/science.add2187) | [ProteinMPNN Original Github](https://github.com/dauparas/ProteinMPNN) -- LigandMPNN: [Atomic context-conditioned protein sequence design using LigandMPNN](https://doi.org/10.1038/s41592-025-02626-1) | [LigandMPNN Original Github](https://github.com/dauparas/LigandMPNN) -- SolubleMPNN: [Computational design of soluble and functional membrane protein analogues](https://doi.org/10.1038/s41586-024-07601-y) - -This guide provides instructions on preparing inputs and running inference for ProteinMPNN/LigandMPNN, as well as training these models. - ## Installation -### A. Installation using `uv` -```bash -git clone https://github.com/RosettaCommons/foundry.git \ - && cd foundry \ - && uv python install 3.12 \ - && uv venv --python 3.12 \ - && source .venv/bin/activate \ - && uv pip install -e ".[mpnn]" -``` - -### B. Download Model Weights - -
-ProteinMPNN - -Please use the following settings with these ProteinMPNN weights: -- `model_type`: `"protein_mpnn"` -- `is_legacy_weights`: `True` - -48 Nearest Neighbors, $\sigma = 0.20 Å$ Gaussian noise during training: -```bash -wget https://files.ipd.uw.edu/pub/ligandmpnn/proteinmpnn_v_48_020.pt -``` -
-Additional ProteinMPNN Weights - -48 Nearest Neighbors, $\sigma = 0.02 Å$ Gaussian noise during training: -```bash -wget https://files.ipd.uw.edu/pub/ligandmpnn/proteinmpnn_v_48_002.pt -``` -48 Nearest Neighbors, $\sigma = 0.10 Å$ Gaussian noise during training: -```bash -wget https://files.ipd.uw.edu/pub/ligandmpnn/proteinmpnn_v_48_010.pt -``` -48 Nearest Neighbors, $\sigma = 0.30 Å$ Gaussian noise during training: -```bash -wget https://files.ipd.uw.edu/pub/ligandmpnn/proteinmpnn_v_48_030.pt -``` -
-
- -
-LigandMPNN - -Please use the following settings with these LigandMPNN weights: -- `model_type`: `"ligand_mpnn"` -- `is_legacy_weights`: `True` - -32 Nearest Neighbors, $\sigma = 0.10 Å$ of Gaussian noise during training, 25 ligand atom context: -```bash -wget https://files.ipd.uw.edu/pub/ligandmpnn/ligandmpnn_v_32_010_25.pt -``` - -
-Additional LigandMPNN Weights - -32 Nearest Neighbors, $\sigma = 0.05 Å$ of Gaussian noise during training, 25 ligand atom context: -```bash -wget https://files.ipd.uw.edu/pub/ligandmpnn/ligandmpnn_v_32_005_25.pt -``` -32 Nearest Neighbors, $\sigma = 0.20 Å$ of Gaussian noise during training, 25 ligand atom context: -```bash -wget https://files.ipd.uw.edu/pub/ligandmpnn/ligandmpnn_v_32_020_25.pt -``` -32 Nearest Neighbors, $\sigma = 0.30 Å$ of Gaussian noise during training, 25 ligand atom context: -```bash -wget https://files.ipd.uw.edu/pub/ligandmpnn/ligandmpnn_v_32_030_25.pt -``` -
-
- -
-SolubleMPNN - -Please use the following settings with these SolubleMPNN weights: -- `model_type`: `"protein_mpnn"` -- `is_legacy_weights`: `True` -48 Nearest Neighbors, $\sigma = 0.20 Å$ Gaussian noise during training: -```bash -wget https://files.ipd.uw.edu/pub/ligandmpnn/solublempnn_v_48_020.pt -``` +The MPNN models are installed with the standard foudry install. See the [general README](../../README.md) or the [online documentation](https://rosettacommons.github.io/foundry/index.html) for installation instructions. -
-Additional SolubleMPNN Weights +## Usage -48 Nearest Neighbors, $\sigma = 0.02 Å$ Gaussian noise during training: -```bash -wget https://files.ipd.uw.edu/pub/ligandmpnn/solublempnn_v_48_002.pt -``` -48 Nearest Neighbors, $\sigma = 0.10 Å$ Gaussian noise during training: -```bash -wget https://files.ipd.uw.edu/pub/ligandmpnn/solublempnn_v_48_010.pt -``` -48 Nearest Neighbors, $\sigma = 0.30 Å$ Gaussian noise during training: -```bash -wget https://files.ipd.uw.edu/pub/ligandmpnn/solublempnn_v_48_030.pt -``` -
-
- -## Inference -> [!WARNING] -> **Known Bug**: There is currently an issue with loading MPNN user annotation (temperature, designed residues, etc.) from CIF/atom array annotations. Command line passing of these options works as expected, as does `input_dict` specificiation with MPNNInferenceEngine. - -> [!IMPORTANT] -> **API Instability**: We are currently finalizing some cleanup work on the inference API. Please expect the API (including input formats and outputs) to stabilize in the upcoming weeks. Thank you for your patience! - -> [!IMPORTANT] -> When using weights from the original ProteinMPNN/LigandMPNN/SolubleMPNN repositories, please ensure to set `is_legacy_weights` to `True` when running inference. - -### A. Command Line Inference -Detailed documentation coming soon! - -### B. JSON-based Inference -Detailed documentation coming soon! - -### C. Programmatic (Scripted) Inference -Detailed documentation coming soon! - -> [!IMPORTANT] -> Currently, 'mpnn_bias' and 'mpnn_pair_bias' annotations cannot be saved to CIF files due to shape limitations. As a result, these annotations must be recreated (either directly with annotation on the atom array or via the input config dictionary) when reloading designed structures from CIF files. - -## Training -Instructions for training ProteinMPNN/LigandMPNN/SolubleMPNN models will be updated here shortly. - -> [!IMPORTANT] -> **Training Code and New Weights**: We are working to release the dataframes used for retrianing the ProteinMPNN, LigandMPNN, and SolubleMPNN re-implementations. Also, we are finalizing the retraining runs and will release weights retrained within this repository shortly. \ No newline at end of file +See the [model documentation](docs/index.md) or the [online documentation](https://rosettacommons.github.io/foundry/models/mpnn/index.html) for usage information. diff --git a/models/mpnn/docs/config_json.md b/models/mpnn/docs/config_json.md new file mode 100644 index 00000000..675ebd7f --- /dev/null +++ b/models/mpnn/docs/config_json.md @@ -0,0 +1,86 @@ +# JSON input specification + +The command line option `--config_json` takes a JSON formatted file to specify the input. + +Values have the same meaning as their command line equivalents. + +Only `model_type`, `out_directory` and `structure_path` are required, all other parameters will be set as their defaults. + +## Minimal example + +Design 3 inputs with default settings + + +The config.json file: + +```json +{ + "model_type": "protein_mpnn", + "out_directory": "design", + "inputs": [ + {"structure_path": "file1.cif"}, + {"structure_path": "file2.cif"}, + {"structure_path": "file3.cif"} + ] +} +``` + +To run on the command line: + +```bash +mpnn --config_json config.json +``` + +## Full settings + +Typical defaults are given. + +Top-level settings: + + { + "model_type": null, + "checkpoint_path": null, + "is_legacy_weights": null, + "out_directory": null, + "write_fasta": true, + "write_structures": true, + "inputs": [ + + ] + } + +`inputs` is a list of JSON objects (i.e. dictionaries) which have the parameters for each structure: + + { + "structure_path": null, + "name": null, + "seed": null, + "batch_size": 1, + "number_of_batches": 1, + "remove_ccds": [], + "remove_waters": null, + "occupancy_threshold_sidechain": 0.0, + "occupancy_threshold_backbone": 0.0, + "undesired_res_names": [], + "structure_noise": 0.0, + "decode_type": "auto_regressive", + "causality_pattern": "auto_regressive", + "initialize_sequence_embedding_with_ground_truth": false, + "features_to_return": null, + "atomize_side_chains": false, + "fixed_residues": null, + "designed_residues": null, + "fixed_chains": null, + "designed_chains": null, + "bias": null, + "bias_per_residue": null, + "omit": ["UNK"], + "omit_per_residue": null, + "pair_bias": null, + "pair_bias_per_residue_pair": null, + "temperature": 0.1, + "temperature_per_residue": null, + "symmetry_residues": null, + "symmetry_residues_weights": null, + "homo_oligomer_chains": null + } diff --git a/models/mpnn/docs/conversion.md b/models/mpnn/docs/conversion.md new file mode 100644 index 00000000..23820675 --- /dev/null +++ b/models/mpnn/docs/conversion.md @@ -0,0 +1,112 @@ +# Option conversion for existing scripts + +To help convert existing usage, this page lists the (rough) option correspondence for the standalone ProteinMPNN and LigandMPNN programs. + +Note that the conversion is approximate and functional. Input formats may not match up exactly. + +## ProteinMPNN/SolubleMPNN + + --pdb_path --structure_path + --jsonl_path --structure_path + --out_folder --out_directory + --seed --seed # The same seed will NOT produce the same output. + --batch_size --batch_size + --num_seq_per_target # No exact correspondence: use --batch_size & --number_of_batches together to specify. + --sampling_temp --temperature + --pdb_path_chains --designed_chains # Though comma separated, rather than space separated + --chain_id_jsonl # Use --fixed_chains/--designed_chains/--fixed_residues/--designed_residues + --fixed_positions_jsonl --fixed_residues + --tied_positions_jsonl # Use --homo_oligomer_chains or --symmetry_residues instead + --bias_AA_jsonl --bias + --bias_by_res_jsonl --bias_per_residue + --path_to_model_weights --checkpoint_path # Set --is_legacy_weights too. + --model_name --checkpoint_path + --use_soluble_model --model_type soluble_mpnn + --backbone_noise --structure_noise + --omit_AAs --omit # Three letter code instead of one letter + --omit_AA_jsonl --omit_per_residue + +Options which are not currently supported or are unneeded: + + --suppress_print + --score_only + --save_score + --save_probs + --conditional_probs_only + --conditional_probs_only_backbone + --unconditional_probs_only + --path_to_fasta + --ca_only + --unconditional_probs_only + --pssm_jsonl + --pssm_multi + --pssm_threshold + --pssm_log_odds_flag + --pssm_bias_flag + --max_length + +## LigandMPNN + + --pdb_path --structure_path + --out_folder --out_directory + --model_type --model_type + --seed --seed # The same seed will NOT produce the same output. + --batch_size --batch_size + --number_of_batches --number_of_batches + --temperature --temperature + --fixed_residues --fixed_residues + --redesigned_residues --designed_residues + --bias_AA --bias + --bias_AA_per_residue --bias_per_residue + --omit_AA --omit + --omit_AA_per_residue --omit_per_residue + --symmetry_residues --symmetry_residues + --symmetry_weights --symmetry_residues_weights + --homo_oligomer --homo_oligomer # As a correspondence, rather than a bool + --chains_to_design --designed_chains + --checkpoint_protein_mpnn --checkpoint_path + --checkpoint_ligand_mpnn --checkpoint_path + --checkpoint_soluble_mpnn --checkpoint_path + --use_sequence --initialize_sequence_embedding_with_ground_truth + --ligand_mpnn_use_atom_context # Can mock with --remove_ccds + --ligand_mpnn_use_side_chain_context --atomize_side_chains + --parse_atoms_with_zero_occupancy --occupancy_threshold_sidechain & --occupancy_threshold_backbone + +Multiple structure inputs are not supported on the command line -- provide them in a `--config_json` file. + + --pdb_path_multi + --fixed_residues_multi + --redesigned_residues_multi + --omit_AA_per_residue_multi + --bias_AA_per_residue_multi + +The ability to pack sidechains in the output models is currently not supported: + + --pack_side_chains + --checkpoint_path_sc + --packed_suffix + --number_of_packs_per_design + --pack_with_ligand_context + --repack_everything + --sc_num_denoising_steps + --sc_num_samples + +Options which are not currently or are unneeded: + + --verbose + --save_stats + --file_ending # --name can possibly substitute + --zero_indexed # Zero indexed is the only option for foundry + --parse_these_chains_only + --model_type global_label_membrane_mpnn + --checkpoint_global_label_membrane_mpnn + --global_transmembrane_label + --model_type per_residue_label_membrane_mpnn + --checkpoint_per_residue_label_membrane_mpnn + --transmembrane_buried + --transmembrane_interface + --fasta_seq_separation + --ligand_mpnn_cutoff_for_score + --autoregressive_score + --single_aa_score + --force_hetatm diff --git a/models/mpnn/docs/index.md b/models/mpnn/docs/index.md index d80c6052..92f9a6c9 100644 --- a/models/mpnn/docs/index.md +++ b/models/mpnn/docs/index.md @@ -1,22 +1,71 @@ # MPNN Documentation -```{warning} -The documentation for the MPNN model is currently incomplete. -If you would like to contribute, feel free to open a PR. -``` -```{warning} +```{caution} The MPNN model is still being benchmarked for comparison to the original ProteinMPNN, LigandMPNN, and SolubleMPNN implementations. ``` -The MPNN model in [foundry](https://github.com/RosettaCommons/foundry) -has all of the functionality of [ProteinMPNN](https://www.science.org/doi/10.1126/science.add2187), -[LigandMPNN](https://www.nature.com/articles/s41592-025-02626-1), -and [SolubleMPNN](https://www.nature.com/articles/s41586-024-07601-y), -but with the backend support of [atomworks](https://github.com/RosettaCommons/atomworks) and -[foundry](https://github.com/RosettaCommons/foundry). More MPNN -models and weights will be added to foundry in the future. +## Available Models + +Foundry attempts to collect the functionality of various MPNN design methods under one unified package, +with the backend support of [atomworks](https://github.com/RosettaCommons/atomworks) +and [foundry](https://github.com/RosettaCommons/foundry). The currently supported models and weights are listed below. More MPNN +models and weights will be added to foundry in the future. -Are we missing a model you would like to work with? Create a PR with the +Are we missing a model you would like to work with? Create a PR with the necessary files and/or code changes or open an issue requesting it. +* [ProteinMPNN](https://doi.org/10.1126/science.add2187), ([original repository](https://github.com/dauparas/ProteinMPNN)) enables protein sequence design given a fixed backbone structure of a protein. ProteinMPNN works soley on canonical amino acids, ignoring any non-protein residues. +* [LigandMPNN](https://doi.org/10.1038/s41592-025-02626-1), ([original repository](https://github.com/dauparas/LigandMPNN)) extends ProteinMPNN functionality to enable fixed-backbone sequence design of proteins in the context of ligands (i.e. small molecules, ions, DNA/RNA, etc.). +* [SolubleMPNN](https://doi.org/10.1038/s41586-024-07601-y) is a version of ProteinMPNN which has been trained specifically on soluble (e.g. non-membrane) proteins. This has been shown to perform better with solubilizing proteins with membrane-protein-like folds, as the default ProteinMPNN recapitulates surface hydrophobics. + +Standard weights for ProteinMPNN and LigandMPNN are included with the base-models install. Additional weights for other models/training settings are also available: + +```{toctree} +:maxdepth: 1 + +weights.md +``` + +## Basic Usage + +The foundry version of MPNN can take either PDB or CIF input structures. +Model type, input path and output directory must all be specified. + + mpnn --model_type protein_mpnn --structure_path input.cif --out_directory input/ + + mpnn --model_type ligand_mpnn --structure_path with_ligand.cif --out_directory ligand/ + + mpnn --model_type soluble_mpnn --structure_path input.cif --out_directory soluble/ + +The output directory will be created if it does not already exist. + +```{toctree} +:maxdepth: 1 + +inference_input.md +config_json.md +conversion.md +``` + +## Outputs + +By default, in the output directory there will be a FASTA-formatted file with the sequence outputs, +as well as a backbone-only CIF-formatted output structure of the designs. +(The sidechain packing model of LigandMPNN is not currently implemented.) + +Both the FASTA and CIF output files should contain the sequence and confidence values. The CIF output should also contain additional information in the `_mpnn_input` and `_mpnn_output` tables. These can be extracted via standard CIF-file readers, or through text processing tools (e.g. grep). + +```{toctree} +:maxdepth: 1 + +outputs.md +``` + +## Retraining + +```{toctree} +:maxdepth: 1 + +training.md +``` diff --git a/models/mpnn/docs/inference_input.md b/models/mpnn/docs/inference_input.md new file mode 100644 index 00000000..cfd1962b --- /dev/null +++ b/models/mpnn/docs/inference_input.md @@ -0,0 +1,133 @@ +# Inference Input Options + +Inference (protein design with an already-trained model) can be controlled either through command line parameters, or through a JSON config file. + +To help in converting existing command lines which use the standalone ProteinMPNN and LigandMPNN programs, see [](conversion). + +Below, where options take "complex" data structures, these are generally JSON-formatted. (When passed on the command line, surround JSON-like data in single quotes to prevent your shell from intepreting it as a shell command.) + +## JSON configuration + +For ease of batch usage, a JSON configuration file can be specified, which contains all the settings for the run. + + --config_json CONFIG.json + +If `--config_json` is specified, no other command line parameters will be parsed. See [](config_json) for the format description. + +Currently `--config_json` is the only way to specify running multiple inputs in a single invocation. + +## Required options + +Model type (one of `protein_mpnn`, `ligand_mpnn` or `soluble_mpnn`). + + --model_type TYPE_mpnn + +Input structure file to design (either CIF or PDB). +Note that as MPNN uses atomworks for input, it follows the convention that CIF files are read in as the annotated biounit, rather than the asymetric unit. +(That is, atomworks will add/remove chains to your input CIF on read-in if the asymmetric unit doesn't match the biounit.) PDB files will be read in as-is, even if there is an asymetric unit/biounit mismatch. + + --structure_path INPUT.cif + +Currently there isn't any support for multiple structure input on the command line (Use `--config_json` instead.) + +Output directory (will be created if it doesn't exist) + + --out_directory DIR + +## Commonly used options + +Control the number of output designs (both options default to 1): + + --batch_size BATCH_SIZE + --number_of_batches NUMBER_OF_BATCHES + +Control the randomization used (different seeds will yield different designs for the same inputs): + + --seed SEED + +Control which residues/chains are designed. These options values can either be comma separated or a JSON-formatted list. Note that these cannot be combined -- only one is allowed per run: + + --fixed_chains '["A","B"]' + --designed_chains "A,B" + --fixed_residues "A35,B40,C52" + --designed_residues '["A35","B40","C52"]' + +Skip particular residues in design. (The default is just "UNK" - it is recommended to include this in your list.) + + --omit '["CYS","GLY","UNK"]' + +## Output control + +Change the label on the output files (default is to base it on the input file name): + + --name NAME + +Turn off FASTA writing: + + --write_fasta False + +Turn off CIF structure output: + + --write_structures False + +## Advanced Options + + +### Controlling sampling + +To control the variability of sampling (higher temperature yield more variable results, lower temperatures less variable but higher confidence) +Default is 0.1 + + --temperature TEMPERATURE + +This can be specified on a per-residue level: + + --temperature_per_residue '{"A35": 0.2}' + +To add a small amount of noise to the structure prior to running the prediction (increases variability) + + --structure_noise NOISE_IN_ANG + +By default, the design process ignores the input identities at all designed positions. To include that information in the decoding process: + + --initialize_sequence_embedding_with_ground_truth True + +### Controlling amino acid usage + +To omit certain residues from design for the entire protein (will not affect non-designed positions). + + --omit '["CYS","GLY","UNK"]' + +This can be also controlled on an per-residue level. (If specified, `--omit` is ignored.): + + --omit_per_residue '{"A35":["ALA","GLY","UNK"], "B23":["CYS","GLY","UNK"]}' + +To downweight/upweight certain amino acid identities: + + --bias '{"LEU": 1.0, "GLY": -0.5, "CYS": -2.0}' + +Higher numbers mean the amino acid will be more frequent in the output. More negative numbers reduce the frequency. +Amino acid identities which aren't specified get a value of 0. + +Per-position biases can be specified (positions not specified default to 0): + + --bias_per_residue '{"A35": {"ALA": -2.0}}' + +### Symmetry + +To specify that certain positions should get the same identity during design (e.g. they're symmetric or pseudo-symmetric positions), +specify the tied groups with `--symmetry_residues` + + --symmetry_residues '[["A35","B35"],["A40","B40","C40"]]' + +This is a list-of-lists of tied residues. The residues in each internal list will all share a residue identity. + +Control the weighting of the groups of `--symmetry_residues` (must match the structure): + + --symmetry_residues_weights '[[1.0, 1.0], [1.0, 0.5, -0.5]]' + +If entire chains should be the same, `--homo_oligomer_chains` may be more convienient. + + --homo_oligomer_chains '[["A","B"],["C","D","E","F"]]' + +If `--homo_oligomer_chains` is set, `--symmetry_residues` and `--symmetry_residues_weights` are ignored. diff --git a/models/mpnn/docs/outputs.md b/models/mpnn/docs/outputs.md new file mode 100644 index 00000000..b0fd3905 --- /dev/null +++ b/models/mpnn/docs/outputs.md @@ -0,0 +1,49 @@ +# MPNN outputs + +By default, in the output directory there will be a FASTA-formatted file with the sequence outputs, +as well as a backbone-only CIF-formatted output structure of the designs. +(The sidechain packing model of LigandMPNN is not currently implemented.) + +## Controlling Output + +To specify the output directory (required): + + --out_directory DIR/ + +To turn off FASTA or structure output: + + --write_structures False + --write_fasta False + +To change the label on the output files (default is to base it on the input filename): + + --name NAME + +### Example FASTA Headers + +* ProteinMPNN & SolubleMPNN: + + >input_b0_d0, confidence=0.3901, sequence_recovery=0.3823 + +* LigandMPNN: + + >ligand_b0_d0, confidence=0.4532, ligand_interface_confidence=0.5316, sequence_recovery=0.4187, ligand_interface_sequence_recovery=0.5000 + +### CIF Output + +In addition to the (backbone only) coordinates of the design, the CIF file features `_mpnn_input` and `_mpnn_output` tables recording the parameters of the design. These can be extracted with standard CIF file readers, or through text file processing techniques (e.g. `grep`). + +Standard entries for `_mpnn_output`: + + _mpnn_output.batch_idx + _mpnn_output.design_idx + _mpnn_output.designed_sequence + _mpnn_output.confidence + _mpnn_output.ligand_interface_confidence + _mpnn_output.sequence_recovery + _mpnn_output.ligand_interface_sequence_recovery + _mpnn_output.model_type + _mpnn_output.checkpoint_path + _mpnn_output.is_legacy_weights + +Additionally, the `_atom_site` table will be annotated with `_atom_site.mpnn_temperature` and `_atom_site.mpnn_confidence` records giving the per-residue temperature and confidence for the run. diff --git a/models/mpnn/docs/training.md b/models/mpnn/docs/training.md new file mode 100644 index 00000000..c93900b7 --- /dev/null +++ b/models/mpnn/docs/training.md @@ -0,0 +1,7 @@ +# Re-training MPNN + +Instructions for training ProteinMPNN/LigandMPNN/SolubleMPNN models will be updated here. + +```{important} +**Training Code and New Weights**: We are working to release the dataframes used for retrianing the ProteinMPNN, LigandMPNN, and SolubleMPNN re-implementations. Also, we are finalizing the retraining runs and will release weights retrained within this repository shortly. +``` diff --git a/models/mpnn/docs/weights.md b/models/mpnn/docs/weights.md new file mode 100644 index 00000000..b556a107 --- /dev/null +++ b/models/mpnn/docs/weights.md @@ -0,0 +1,71 @@ +# MPNN Models and Weights + +The trained weights to be used with the model can be specified with + + --checkpoint_path checkpoint.pt + +For all of the checkpoints available below, you must also specify + + --is_legacy_weights True + +To use the standard weights (i.e. those downloaded with `foundry install`), simply omit the `--checkpoint_path` and `--is_legacy_weights` options. + +## ProteinMPNN + +[ProteinMPNN](https://doi.org/10.1126/science.add2187), ([original repository](https://github.com/dauparas/ProteinMPNN)) enables protein sequence design given a fixed backbone structure of a protein. ProteinMPNN works soley on canonical amino acids, ignoring any non-protein residues. + +### Weights + +Standard weights (48 Nearest Neighbors, $\sigma = 0.20 Å$ Gaussian noise) are included with the base-models install, or can be downloaded separately with + + foundry install proteinmpnn + +Additional weights can be downloaded manually: + + # 48 Nearest Neighbors, $\sigma = 0.02 Å$ Gaussian noise during training: + wget https://files.ipd.uw.edu/pub/ligandmpnn/proteinmpnn_v_48_002.pt + # 48 Nearest Neighbors, $\sigma = 0.10 Å$ Gaussian noise during training: + wget https://files.ipd.uw.edu/pub/ligandmpnn/proteinmpnn_v_48_010.pt + # 48 Nearest Neighbors, $\sigma = 0.30 Å$ Gaussian noise during training: + wget https://files.ipd.uw.edu/pub/ligandmpnn/proteinmpnn_v_48_030.pt + +## LigandMPNN + +[LigandMPNN](https://doi.org/10.1038/s41592-025-02626-1), ([original repository](https://github.com/dauparas/LigandMPNN)) extends ProteinMPNN functionality to enable fixed-backbone sequence design of proteins in the context of ligands (i.e. small molecules, ions, DNA/RNA, etc.). + +### Weights + +Standard weights (32 Nearest Neighbors, $\sigma = 0.10 Å$ Gaussian noise during training, 25 ligand atom context) are included with the base-models install, or can be downloaded separately with + + foundry install ligandmpnn + +Additional werights can be downloaded manually: + + # 32 Nearest Neighbors, $\sigma = 0.05 Å$ of Gaussian noise during training, 25 ligand atom context: + wget https://files.ipd.uw.edu/pub/ligandmpnn/ligandmpnn_v_32_005_25.pt + # 32 Nearest Neighbors, $\sigma = 0.20 Å$ of Gaussian noise during training, 25 ligand atom context: + wget https://files.ipd.uw.edu/pub/ligandmpnn/ligandmpnn_v_32_020_25.pt + # 32 Nearest Neighbors, $\sigma = 0.30 Å$ of Gaussian noise during training, 25 ligand atom context: + wget https://files.ipd.uw.edu/pub/ligandmpnn/ligandmpnn_v_32_030_25.pt + + +## SolubleMPNN + +[SolubleMPNN](https://doi.org/10.1038/s41586-024-07601-y) is a version of ProteinMPNN which has been trained specifically on soluble (e.g. non-membrane) proteins. This has been shown to perform better with solubilizing proteins with membrane-protein-like folds, as the default ProteinMPNN recapitulates surface hydrophobics. + +### Weights + +Standard weights (48 Nearest Neighbors, $\sigma = 0.20 Å$ Gaussian noise) are not included with the base-models install, and must be downloaded with + + foundry install solublempnn + +Additional weights can be downloaded manually: + + # 48 Nearest Neighbors, $\sigma = 0.02 Å$ Gaussian noise during training: + wget https://files.ipd.uw.edu/pub/ligandmpnn/solublempnn_v_48_002.pt + # 48 Nearest Neighbors, $\sigma = 0.10 Å$ Gaussian noise during training: + wget https://files.ipd.uw.edu/pub/ligandmpnn/solublempnn_v_48_010.pt + # 48 Nearest Neighbors, $\sigma = 0.30 Å$ Gaussian noise during training: + wget https://files.ipd.uw.edu/pub/ligandmpnn/solublempnn_v_48_030.pt + + From 3e91a0cc4753dd8c9c521d5e6f50e65bbb032576 Mon Sep 17 00:00:00 2001 From: Rocco Moretti Date: Wed, 29 Jul 2026 15:37:02 -0500 Subject: [PATCH 2/2] Add Myst extensions for math & alerts --- docs/source/conf.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index d3b50d9e..9d9ae934 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -18,6 +18,11 @@ "sphinx_copybutton" ] +myst_enable_extensions = [ + "alert", + "dollarmath", +] + templates_path = ['_templates'] exclude_patterns = ["readme.md", "readmelink.md", "readme_link.rst"]