Proteinmpnn

ProteinMPNN

ProteinMPNN is the default inverse-folding step in the binder pipeline: a

message-passing network that sees backbone geometry only, so it is the right

choice when the design surface is protein–protein and the wrong one as soon as

a ligand, nucleic acid, or metal is part of the interface — ligandmpnn adds

those atoms to the graph with a near-identical CLI, and solublempnn swaps in

weights trained on soluble structures for an expression-biased prior. Code and

weights are MIT (github.com/dauparas/ProteinMPNN). The model is small enough

to run on CPU — for a handful of sequences on one backbone that is seconds and

usually faster than dispatching a remote job; a GPU helps for batched

campaigns (hundreds of backbones or large --num_seq_per_target). Either way

the repo is cloned in-job — there is no PyPI dist and the checkpoints are

bundled in the repo.

Running it

pip install torch numpy   # if not already present
git clone --depth 1 https://github.com/dauparas/ProteinMPNN.git proteinmpnn
cd proteinmpnn
python protein_mpnn_run.py \
  --pdb_path backbone.pdb --pdb_path_chains "A" \
  --out_folder out --num_seq_per_target 16 --sampling_temp "0.1"

Two flags trip almost everyone the first time. --sampling_temp is parsed as a

space-separated string so one run can sweep several temperatures; a single

value needs no quoting, but a multi-value sweep must be quoted

("0.1 0.2 0.3"), and commas never split — "0.1,0.2" fails the float cast. --pdb_path_chains is also space-separated inside

one quoted argument ("A B"); a comma is kept as part of the chain ID.

Designs land in out/seqs/<pdb_stem>.fa. The first record is the input

sequence; each design header carries score= (mean negative log-likelihood —

lower is more confident), global_score=, and seq_recovery=. ProteinMPNN

writes sequences only — it does not thread them back onto the backbone; if you

need designed-sequence PDBs, the ligandmpnn runner writes them to

backbones/ automatically and accepts --model_type protein_mpnn for the

same weights.

A flat chain map in --fixed_positions_jsonl silently redesigns every residue

--fixed_positions_jsonl expects one JSON object per line keyed by the **PDB

stem** first, then chain, then a list of 1-indexed residue numbers:

{"backbone": {"A": [10, 11, 12], "B": []}}. Passing the inner

{"A": [...]} directly — the obvious guess — is silently treated as "no PDB

matched," and every position is redesigned. The bundled

helper_scripts/make_fixed_positions_dict.py writes the correct shape from a

chain and range string and is worth the extra call; the same outer-stem rule

applies to --chain_id_jsonl and --tied_positions_jsonl.

Checkpoints — which one to pick

| --model_name | training noise | use |

|---|---|---|

| v_48_002 | 0.02 Å | highest recovery; close-to-native redesigns |

| v_48_020 (default) | 0.20 Å | de novo backbones — tolerates RFdiffusion imperfection |

| v_48_030 | 0.30 Å | very rough backbones; lowest recovery |

| --use_soluble_model | — | swaps to the soluble-trained set; see solublempnn |

Wisp execution

Use python only for bounded interactive checks. For a long or GPU-backed

workload, require a selected and probed ssh:<alias> context and load

remote-compute-ssh. Put the documented invocation in a self-contained project

script, activate the remote environment explicitly, stage only small files with

input_paths, and make the command write to a known absolute remote result

path. Submit it with run_in_context and register that exact ssh:// path in

output_specs. Call monitor_run once when waiting is needed, get_run once

for a snapshot, or cancel_run to stop. Do not send a scheduler submission

through the SSH-direct runner.

Errors worth recognizing

| You see | It means / do this |

|---|---|

| KeyError: 'A' | Chain letter not in the PDB — grep '^ATOM' file.pdb \| cut -c22 \| sort -u to see what is. |

| JSONDecodeError on a *_jsonl flag | The flag wants a file path, not inline JSON; write the file first. |

| All positions redesigned despite --fixed_positions_jsonl | Outer PDB-stem key missing — see the gotcha above. |

| ModuleNotFoundError for relative imports | Script run from the wrong cwd — cd into the cloned repo first; the imports are repo-relative. |

Next: fold the designs in complex with the target via boltz, chai1, or

esmfold2 and filter on ipTM.