pH-sensitive binder design with Proton-PottsMPNN

A PottsMPNN with an explicit protonation-state alphabet, for designing pH-switchable binders. Histidine is HIS-P (charged, +1) vs HIS-S (neutral); acids are ASP-P/GLU-P (protonated, neutral COOH) vs ASP-D/GLU-D (deprotonated, −1). Because the learned Potts energy is protonation-aware, the design engine can pin protonated centres and redesign around them so that binding switches with pH.

This is the code for "pH-sensitive binder design with Proton-PottsMPNN" (Jacobsen et al., 2026). It extends PottsMPNN — the Potts-energy inverse-folding model of Birnbaum & Keating (github.com/KeatingLab/PottsMPNN; PNAS 2026, 10.1073/pnas.2535494123) — by adding explicit protonation-state tokens so that a single energy function scores alternative protonation assignments on a fixed backbone, which is what makes pH-conditioned design possible.

Figure 1. (a) Local geometric features predict per-residue protonation states, encoded as sequence tokens to train Proton-PottsMPNN; backbone node/edge embeddings feed a shared encoder, then an autoregressive decoder (token likelihoods) and a Potts head (single-site fields + pairwise couplings). (b) Protonation-conditioned redesign for a fixed ASP-P centre (pink) vs ASP-D (blue): neighbours are mutated to balance global Potts energy against the selective gap E_selective = E_P − E_D, weighted by λ. (c) Flow cytometry of enriched yeast-display binders incubated with PD-L1 at pH 5.0 vs 7.4.

The project has two halves, and this folder is self-contained for both:

1. Label — a FLAML labeller assigns a protonation state to every titratable residue of every training structure (the supervision the model learns from).
2. Design — the trained Potts model drives a block-descent optimiser that places protonated centres and redesigns their neighbourhood.

cd ProtonPottsMPNN
./install.sh                     # uv venv (Python 3.12) + uv pip install -e ./foundry + extras
source .venv/bin/activate

install.sh runs uv venv --clear then a single uv pip install -e ./foundry -r requirements-extra.txt (the one resolution keeps both the foundry core — torch, lightning, atomworks[ml] — and the extras — the FLAML stack, jupyter, propka), verifies import mpnn resolves inside this folder, and registers the venv as a Jupyter kernel ProtonPottsMPNN (.venv). Scripts just import mpnn; there are no sys.path hacks.

• Python 3.12 is required (mpnn/foundry pin >=3.12,<3.13).
• HBPLUS is an external C binary (not pip-installable) used by the labeller and the fold scoring to read H-bond geometry. Point HBPLUS_PATH at your build (export HBPLUS_PATH=/path/to/hbplus). It is not needed to run the design engine (which only reads the trained checkpoint).
• Let the install finish uninterrupted — a killed uv pip install can leave the venv half-written (package metadata present, module files missing). If imports fail oddly, repair in place with uv pip install --python .venv/bin/python --reinstall -e ./foundry -r requirements-extra.txt.

Assign a protonation state to every His/Asp/Glu in a structure — the labels the Potts model is trained on and the design engine consumes. This runs the transformation pipeline prepare_potts_input(..., extended_vocab="v6") — the same code path the training data and _build_context use: it strips hydrogens, runs HBPLUS, applies the FLAML labeller, and attaches a per-residue protonation_label token (-P protonated · -S neutral His · -D deprotonated acid · -A ambiguous).

HBPLUS_PATH=/path/to/hbplus python labeller/label_pdb.py     # -> labeller/outputs/protonation_labels.csv

import numpy as np
from mpnn.potts_inference import prepare_potts_input

out = prepare_potts_input("inference/examples/pdl1_seed_binder.pdb", extended_vocab="v6")
ca  = out["atom_array"][out["atom_array"].atom_name == "CA"]     # one CA per residue, token order
labels = ca.get_annotation("protonation_label")                  # per-residue token: HIS-S / ASP-D / GLU-P / …

chain  res_id res_name token
    A      32      HIS  HIS-S     # neutral at rest
    A      57      GLU  GLU-D     # deprotonated
    B      52      HIS  HIS-S
    …                             # 21 titratable residues, all neutral/deprotonated

Note the read-out: the apo seed binder carries no strongly-protonated residue at rest — which is exactly why design (below) pins HIS-P/ASP-P/GLU-P centres deliberately rather than reading them off the input. The pipeline emits the discrete token (the model-input form); for the raw labeller probabilities (p_protonated, sd) call mpnn.transforms.ev6.EV6Predictor directly — the labeller prepare_potts_input wraps.

PottsMPNNPHEngine (in the mpnn package at inference_engines/potts_mpnn_ph.py) places protonated centres and redesigns their neighbourhood with Potts-head block descent — the exact optimiser used in our internal design campaigns.

python inference/design_ph.py       # -> inference/outputs/ (see below)
# interactively:  jupyter lab inference/design_ph.ipynb   (pick the "ProtonPottsMPNN (.venv)" kernel)

from mpnn.inference_engines.potts_mpnn_ph import PottsMPNNPHEngine, PHDesignCriteria

engine = PottsMPNNPHEngine(checkpoint_path=CKPT, extended_vocab="v6")   # 30-token v6 model
crit = PHDesignCriteria(
    method="block_descent", backend="potts",          # the internal-campaign optimiser
    combined_lambda=0.3,                               # Eq (6): O = (1−λ)·zscore(H_stab) + λ·zscore(Σ sel)
    center_types=["HIS-P", "ASP-P", "GLU-P"],          # composition to place …
    placement_by="scan_potts",                         # … placement chooses the positions
    dep_map={"HIS-P": ["HIS-S"], "ASP-P": ["ASP-D"], "GLU-P": ["GLU-D"]},  # v6 has no HID/HIE
    block_size=3, temperature=0.05, neighbour_k=16, max_mutations=20,
    record_trajectory=True,
)
design_set = engine.run_ph_redesign(atom_array=aa, binder_chain="A", criteria_list=[crit], seed=0)

The notebook opens up the internals: placement (which state goes where, and how many centres — acids to the core, HIS-P to the surface) and the block-descent trajectory (stability + selectivity vs. step). _build_context featurises through prepare_potts_input (the same transform pipeline the labeller/training use) — the engine reads a path or an AtomArray.

Many designs → the Pareto front. run_ph_redesign takes a list of criteria, so N designs is just a combined_lambda sweep from 0 (pure stability) to 1 (pure selectivity), fanned across a CPU fork pool (n_jobs). The notebook runs N_DESIGNS of them and plots each in (stability, selectivity) space with the Pareto front marked (pareto_front.png). Set N_DESIGNS = 20 for a denser front.

Fold the Pareto designs. It then picks N_FOLD designs off the Pareto front and folds each with the packaged RF3 engine (fold_rf3.py, from_target templating: the target chain is templated, the binder is folded from its designed sequence), scoring charge clashes + pH-sensitive H-bonds at the pinned centres. RF3 code ships here, but the weights (~3 GB) do not — set RF3_CKPT=/abs/rf3_*.ckpt and run on a GPU (with the RF3 atom-embedding cache) to fold. This path was exercised end-to-end (input build → checkpoint load → RF3 forward → a 2-chain binder+target .cif) with an internal checkpoint; on a GPU node with the embedding cache it produces a physical fold. Without RF3 the notebook still runs: it exports the selected designs (pareto_fold_manifest.json) ready to fold elsewhere and scores a shipped real RF3 fold as the demo.

Every design is saved with its protonation states. Outputs in inference/outputs/:

Point it at your own backbone by editing PDB / BINDER_CHAIN (or inference/examples/example_meta.json). The checkpoint's extended_vocab must be "v6" or the 30-token weight load fails.

Benchmark scripts derive the package root from their location (override with PROTON_ROOT=/abs/path). The model-quality benchmarks (PKAD, stability) compute from raw structures; the design benchmarks (binding, within-backbone) read shipped parquets (regenerating them needs the Boltz-2 / RF3 oracles).

This project is released under the MIT License — see LICENSE. It covers the Proton-PottsMPNN code authored here (labeller/, inference/, scoring/, benchmarks/, training/, checkpoints/, the docs, and the pH-design additions to the mpnn package). The bundled foundry/ is a verbatim copy of IPD's rc-foundry and keeps its own BSD 3-Clause License (foundry/LICENSE.md, © 2025 Institute for Protein Design, University of Washington).

If you use this in academic work, please cite the manuscript "pH-sensitive binder design with Proton-PottsMPNN" (Jacobsen et al., 2026).