RosettaCommons · roccomoretti · Jul 29, 2026 · Jul 29, 2026
diff --git 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"]
 

diff --git 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
-
-<details>
-<summary><strong>ProteinMPNN</strong></summary>
-
-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
-```
-<details>
-<summary>Additional ProteinMPNN Weights</summary>
-
-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
-```
-</details>
-</details>
-
-<details>
-<summary><strong>LigandMPNN</strong></summary>
-
-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
-```
-
-<details>
-<summary>Additional LigandMPNN Weights</summary>
-
-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
-```
-</details>
-</details>
-
-<details>
-<summary><strong>SolubleMPNN</strong></summary>
-
-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.
 
-<details>
-<summary>Additional SolubleMPNN Weights</summary>
+## 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
-```
-</details> 
-</details>
-
-## 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.
+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
@@ -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> 
+		]
+	}
+
+`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
@@ -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