Add ProteinMPNN-compatible BindMPNN checkpoints and usage instructions

9f054b3 verified 9 days ago

5.7 kB

---
language:
- en
tags:
- biology
- protein-design
- inverse-folding
- ligandmpnn
- proteinmpnn
- bindmpnn
---
# BindMPNN

BindMPNN provides **LigandMPNN-compatible and ProteinMPNN-compatible checkpoints** for amino-acid sequence design from protein structures. Use them with the [official LigandMPNN implementation](https://github.com/dauparas/LigandMPNN); the model options and examples for each architecture are given below.

## LigandMPNN-compatible checkpoints

| Checkpoint | Backbone noise level | Protein neighbors | Atom context size |
|---|---:|---:|---:|
| `BindMPNN_v_32_010_25.pt` | 0.10 Å | 32 | 25 |
| `BindMPNN_v_32_020_25.pt` | 0.20 Å | 32 | 25 |

The noise level identifies the checkpoint variant; it is **not** the sampling temperature and does not require adding noise to your input structure. Both files contain inference weights and the metadata required by LigandMPNN's checkpoint loader.

## Installation and download

Use a Python 3.11 environment and install LigandMPNN according to its [installation instructions](https://github.com/dauparas/LigandMPNN#dependencies). For example:

```bash
git clone https://github.com/dauparas/LigandMPNN.git
cd LigandMPNN
python -m pip install -r requirements.txt
python -m pip install huggingface_hub
```

Download the checkpoints into this checkout:

```python
from huggingface_hub import hf_hub_download
for filename in ("BindMPNN_v_32_010_25.pt", "BindMPNN_v_32_020_25.pt"):
    hf_hub_download(
        repo_id="MurrellLab/SeqGivenStruct",
        filename=filename,
        local_dir="checkpoints",
    )
```

## Sequence design

This example redesigns chain **B** of a target–binder complex while keeping the amino-acid identities of the other chains fixed:

```bash
python run.py \
  --model_type ligand_mpnn \
  --checkpoint_ligand_mpnn checkpoints/BindMPNN_v_32_010_25.pt \
  --pdb_path complex.pdb \
  --chains_to_design B \
  --ligand_mpnn_use_side_chain_context 1 \
  --temperature 0.1 \
  --seed 123 \
  --batch_size 1 \
  --number_of_batches 8 \
  --out_folder outputs/bindmpnn
```

Replace `B` with the chain you want to redesign and `complex.pdb` with your input structure. To use the 0.20 Å variant, change the checkpoint filename to `BindMPNN_v_32_020_25.pt`.

- `--chains_to_design` specifies the mutable chains; other chains remain fixed.
- `--ligand_mpnn_use_side_chain_context 1` exposes sidechain atoms of fixed residues as context. Use `0` to omit that sidechain context.
- `--temperature` controls sequence sampling diversity independently of the checkpoint's noise label. The example uses 0.1; adjust it for your application.
- `--seed` controls reproducibility. Sequence files are written under the output folder's `seqs/` directory.

These are sequence-design checkpoints. Sidechain packing uses LigandMPNN's separate packing checkpoint and options; consult the upstream documentation for that workflow and for residue-level constraints, scoring, and batching.

## Programmatic loading

The checkpoint files are PyTorch dictionaries with `model_state_dict`, `num_edges`, `atom_context_num`, and `noise_level`. A compatible loader can use:

```python
import torch
checkpoint = torch.load(
    "checkpoints/BindMPNN_v_32_010_25.pt",
    map_location="cpu",
    weights_only=True,
)
# Instantiate the upstream ProteinMPNN with model_type="ligand_mpnn",
# k_neighbors=checkpoint["num_edges"], and
# atom_context_num=checkpoint["atom_context_num"], then:
# model.load_state_dict(checkpoint["model_state_dict"], strict=True)
```

## ProteinMPNN-compatible checkpoints

These additional BindMPNN checkpoints use the **ProteinMPNN architecture** and can be loaded through the `soluble_mpnn` or `protein_mpnn` model options in the official LigandMPNN repository.

| Checkpoint | Backbone noise level | Protein neighbors |
|---|---:|---:|
| `BindMPNN_soluble_v_48_010.pt` | 0.10 Å | 48 |
| `BindMPNN_soluble_v_48_020.pt` | 0.20 Å | 48 |

Download them with:

```python
from huggingface_hub import hf_hub_download
for filename in ("BindMPNN_soluble_v_48_010.pt", "BindMPNN_soluble_v_48_020.pt"):
    hf_hub_download(
        repo_id="MurrellLab/SeqGivenStruct",
        filename=filename,
        local_dir="checkpoints",
    )
```

Using the same installation described above, redesign chain B while keeping the other chains fixed:

```bash
python run.py \
  --model_type soluble_mpnn \
  --checkpoint_soluble_mpnn checkpoints/BindMPNN_soluble_v_48_010.pt \
  --pdb_path complex.pdb \
  --chains_to_design B \
  --temperature 0.1 \
  --seed 123 \
  --batch_size 1 \
  --number_of_batches 8 \
  --out_folder outputs/bindmpnn_soluble
```

Replace the checkpoint filename with `BindMPNN_soluble_v_48_020.pt` for the 0.20 Å variant. Alternatively, use `--model_type protein_mpnn` with `--checkpoint_protein_mpnn` pointing to the same file.

These models use protein backbone coordinates and fixed-chain amino-acid identities. They do **not** accept target side-chain or nonprotein atom context; `--ligand_mpnn_use_side_chain_context` applies only to the LigandMPNN-compatible checkpoints above. Noise labels identify checkpoint variants and are independent of sampling temperature.

For programmatic loading, use `torch.load(path, map_location="cpu", weights_only=True)`, instantiate the upstream `ProteinMPNN` with `model_type="soluble_mpnn"` and `k_neighbors=checkpoint["num_edges"]`, then load `checkpoint["model_state_dict"]` strictly. The files contain only inference weights, `num_edges`, and `noise_level`.

## Attribution

Please acknowledge the corresponding upstream implementations: [LigandMPNN](https://github.com/dauparas/LigandMPNN) and [ProteinMPNN](https://github.com/dauparas/ProteinMPNN).

	---
	language:
	- en
	tags:
	- biology
	- protein-design
	- inverse-folding
	- ligandmpnn
	- proteinmpnn
	- bindmpnn
	---

	# BindMPNN

	BindMPNN provides LigandMPNN-compatible and ProteinMPNN-compatible checkpoints for amino-acid sequence design from protein structures. Use them with the [official LigandMPNN implementation](https://github.com/dauparas/LigandMPNN); the model options and examples for each architecture are given below.

	## LigandMPNN-compatible checkpoints

	\| Checkpoint \| Backbone noise level \| Protein neighbors \| Atom context size \|
	\|---\|---:\|---:\|---:\|
	\| `BindMPNN_v_32_010_25.pt` \| 0.10 Å \| 32 \| 25 \|
	\| `BindMPNN_v_32_020_25.pt` \| 0.20 Å \| 32 \| 25 \|

	The noise level identifies the checkpoint variant; it is not the sampling temperature and does not require adding noise to your input structure. Both files contain inference weights and the metadata required by LigandMPNN's checkpoint loader.

	## Installation and download

	Use a Python 3.11 environment and install LigandMPNN according to its [installation instructions](https://github.com/dauparas/LigandMPNN#dependencies). For example:

	```bash
	git clone https://github.com/dauparas/LigandMPNN.git
	cd LigandMPNN
	python -m pip install -r requirements.txt
	python -m pip install huggingface_hub
	```

	Download the checkpoints into this checkout:

	```python
	from huggingface_hub import hf_hub_download

	for filename in ("BindMPNN_v_32_010_25.pt", "BindMPNN_v_32_020_25.pt"):
	hf_hub_download(
	repo_id="MurrellLab/SeqGivenStruct",
	filename=filename,
	local_dir="checkpoints",
	)
	```

	## Sequence design

	This example redesigns chain B of a target–binder complex while keeping the amino-acid identities of the other chains fixed:

	```bash
	python run.py \
	--model_type ligand_mpnn \
	--checkpoint_ligand_mpnn checkpoints/BindMPNN_v_32_010_25.pt \
	--pdb_path complex.pdb \
	--chains_to_design B \
	--ligand_mpnn_use_side_chain_context 1 \
	--temperature 0.1 \
	--seed 123 \
	--batch_size 1 \
	--number_of_batches 8 \
	--out_folder outputs/bindmpnn
	```

	Replace `B` with the chain you want to redesign and `complex.pdb` with your input structure. To use the 0.20 Å variant, change the checkpoint filename to `BindMPNN_v_32_020_25.pt`.

	- `--chains_to_design` specifies the mutable chains; other chains remain fixed.
	- `--ligand_mpnn_use_side_chain_context 1` exposes sidechain atoms of fixed residues as context. Use `0` to omit that sidechain context.
	- `--temperature` controls sequence sampling diversity independently of the checkpoint's noise label. The example uses 0.1; adjust it for your application.
	- `--seed` controls reproducibility. Sequence files are written under the output folder's `seqs/` directory.

	These are sequence-design checkpoints. Sidechain packing uses LigandMPNN's separate packing checkpoint and options; consult the upstream documentation for that workflow and for residue-level constraints, scoring, and batching.

	## Programmatic loading

	The checkpoint files are PyTorch dictionaries with `model_state_dict`, `num_edges`, `atom_context_num`, and `noise_level`. A compatible loader can use:

	```python
	import torch

	checkpoint = torch.load(
	"checkpoints/BindMPNN_v_32_010_25.pt",
	map_location="cpu",
	weights_only=True,
	)
	# Instantiate the upstream ProteinMPNN with model_type="ligand_mpnn",
	# k_neighbors=checkpoint["num_edges"], and
	# atom_context_num=checkpoint["atom_context_num"], then:
	# model.load_state_dict(checkpoint["model_state_dict"], strict=True)
	```

	## ProteinMPNN-compatible checkpoints

	These additional BindMPNN checkpoints use the ProteinMPNN architecture and can be loaded through the `soluble_mpnn` or `protein_mpnn` model options in the official LigandMPNN repository.

	\| Checkpoint \| Backbone noise level \| Protein neighbors \|
	\|---\|---:\|---:\|
	\| `BindMPNN_soluble_v_48_010.pt` \| 0.10 Å \| 48 \|
	\| `BindMPNN_soluble_v_48_020.pt` \| 0.20 Å \| 48 \|

	Download them with:

	```python
	from huggingface_hub import hf_hub_download

	for filename in ("BindMPNN_soluble_v_48_010.pt", "BindMPNN_soluble_v_48_020.pt"):
	hf_hub_download(
	repo_id="MurrellLab/SeqGivenStruct",
	filename=filename,
	local_dir="checkpoints",
	)
	```

	Using the same installation described above, redesign chain B while keeping the other chains fixed:

	```bash
	python run.py \
	--model_type soluble_mpnn \
	--checkpoint_soluble_mpnn checkpoints/BindMPNN_soluble_v_48_010.pt \
	--pdb_path complex.pdb \
	--chains_to_design B \
	--temperature 0.1 \
	--seed 123 \
	--batch_size 1 \
	--number_of_batches 8 \
	--out_folder outputs/bindmpnn_soluble
	```

	Replace the checkpoint filename with `BindMPNN_soluble_v_48_020.pt` for the 0.20 Å variant. Alternatively, use `--model_type protein_mpnn` with `--checkpoint_protein_mpnn` pointing to the same file.

	These models use protein backbone coordinates and fixed-chain amino-acid identities. They do not accept target side-chain or nonprotein atom context; `--ligand_mpnn_use_side_chain_context` applies only to the LigandMPNN-compatible checkpoints above. Noise labels identify checkpoint variants and are independent of sampling temperature.

	For programmatic loading, use `torch.load(path, map_location="cpu", weights_only=True)`, instantiate the upstream `ProteinMPNN` with `model_type="soluble_mpnn"` and `k_neighbors=checkpoint["num_edges"]`, then load `checkpoint["model_state_dict"]` strictly. The files contain only inference weights, `num_edges`, and `noise_level`.

	## Attribution

	Please acknowledge the corresponding upstream implementations: [LigandMPNN](https://github.com/dauparas/LigandMPNN) and [ProteinMPNN](https://github.com/dauparas/ProteinMPNN).