# christian-creator/protonpottsmpnn architecture

> Architecture diagram of the GitHub repository christian-creator/protonpottsmpnn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/christian-creator/protonpottsmpnn
- Repository: https://github.com/christian-creator/protonpottsmpnn

## Overview

This repository supports pH-sensitive binder design with Proton-PottsMPNN: structures are protonation-labelled, featurized into the model’s explicit protonation-token vocabulary, and used to design sequences around pinned protonated centres. The principal workflow runs block-descent redesign, explores stability/selectivity trade-offs, then optionally folds and scores selected designs. Training and structure-labeling are supporting branches; RF3 folding requires external checkpoint weights. The graph follows documented workflows and indexed source references; unsampled implementation details are not inferred.

Main entry points: [`labeller/label_pdb.py`](https://github.com/christian-creator/protonpottsmpnn/blob/main/labeller/label_pdb.py) (PDB labeling), [`inference/design_ph.py`](https://github.com/christian-creator/protonpottsmpnn/blob/main/inference/design_ph.py) (Design workflow), [`foundry/models/mpnn/src/mpnn/potts_inference.py`](https://github.com/christian-creator/protonpottsmpnn/blob/main/foundry/models/mpnn/src/mpnn/potts_inference.py) (Potts featurization), [`inference/fold_rf3.py`](https://github.com/christian-creator/protonpottsmpnn/blob/main/inference/fold_rf3.py) (RF3 folding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_label["Protonation labeling"]
  node_label_cli["PDB labeling<br/>[label_pdb.py]"]
  node_his_features["His features"]
  node_acid_features["Acid features"]
end

subgraph group_model["PottsMPNN core"]
  node_input_prep["Potts featurization<br/>[potts_inference.py]"]
  node_token_vocab["Protonation tokens<br/>[token_encodings.py]"]
  node_graph_features["Graph embeddings"]
  node_potts_model["Potts model<br/>[pottsmpnn.py]"]
  node_training["Model training<br/>[pottsmpnn.py]"]
end

subgraph group_design["pH design"]
  node_ph_engine["pH design engine<br/>[potts_mpnn_ph.py]"]
  node_placement["Centre placement"]
  node_design_run["Design workflow<br/>[design_ph.py]"]
  node_pareto["Pareto selection<br/>[design_ph.py]"]
end

subgraph group_validation["Fold and scoring"]
  node_rf3_fold["RF3 folding<br/>[fold_rf3.py]"]
  node_charge_score["Charge clashes"]
  node_fold_score["Fold annotation<br/>[annotate_folds.py]"]
end

node_researcher(("Designer"))
node_structure["Input structure"]
node_hbplus{{"HBPLUS"}}
node_rf3_weights[("RF3 checkpoint")]

node_researcher -->|"labels structures"| node_label_cli
node_structure -->|"provides PDB"| node_label_cli
node_label_cli -->|"uses geometry"| node_hbplus
node_label_cli -.->|"labels histidines"| node_his_features
node_label_cli -.->|"labels acids"| node_acid_features
node_researcher -->|"requests designs"| node_design_run
node_structure -->|"provides backbone"| node_design_run
node_design_run -->|"runs redesign"| node_ph_engine
node_design_run -->|"scans centres"| node_placement
node_ph_engine -->|"builds context"| node_input_prep
node_input_prep -->|"encodes tokens"| node_token_vocab
node_input_prep -->|"featurizes structure"| node_graph_features
node_input_prep -->|"runs forward"| node_potts_model
node_ph_engine -->|"optimizes Potts energy"| node_potts_model
node_design_run -->|"selects trade-offs"| node_pareto
node_pareto -->|"folds designs"| node_rf3_fold
node_rf3_fold -->|"loads checkpoint"| node_rf3_weights
node_rf3_fold -->|"scores clashes"| node_charge_score
node_rf3_fold -->|"annotates folds"| node_fold_score
node_label_cli -->|"supplies labels"| node_training
node_training -.->|"trains model"| node_potts_model

click node_label_cli "https://github.com/christian-creator/protonpottsmpnn/blob/main/labeller/label_pdb.py"
click node_his_features "https://github.com/christian-creator/protonpottsmpnn/blob/main/labeller/03_his_rich_features.py"
click node_acid_features "https://github.com/christian-creator/protonpottsmpnn/blob/main/labeller/04_acid_rich_features.py"
click node_input_prep "https://github.com/christian-creator/protonpottsmpnn/blob/main/foundry/models/mpnn/src/mpnn/potts_inference.py"
click node_token_vocab "https://github.com/christian-creator/protonpottsmpnn/blob/main/foundry/models/mpnn/src/mpnn/transforms/feature_aggregation/token_encodings.py"
click node_graph_features "https://github.com/christian-creator/protonpottsmpnn/blob/main/foundry/models/mpnn/src/mpnn/model/layers/graph_embeddings.py"
click node_potts_model "https://github.com/christian-creator/protonpottsmpnn/blob/main/foundry/models/mpnn/src/mpnn/model/pottsmpnn.py"
click node_ph_engine "https://github.com/christian-creator/protonpottsmpnn/blob/main/foundry/models/mpnn/src/mpnn/inference_engines/potts_mpnn_ph.py"
click node_placement "https://github.com/christian-creator/protonpottsmpnn/blob/main/inference/design_placement_scan.py"
click node_design_run "https://github.com/christian-creator/protonpottsmpnn/blob/main/inference/design_ph.py"
click node_pareto "https://github.com/christian-creator/protonpottsmpnn/blob/main/inference/design_ph.py"
click node_rf3_fold "https://github.com/christian-creator/protonpottsmpnn/blob/main/inference/fold_rf3.py"
click node_charge_score "https://github.com/christian-creator/protonpottsmpnn/blob/main/scoring/annotate_charge_clash.py"
click node_fold_score "https://github.com/christian-creator/protonpottsmpnn/blob/main/scoring/annotate_folds.py"
click node_training "https://github.com/christian-creator/protonpottsmpnn/blob/main/foundry/models/mpnn/src/mpnn/trainers/pottsmpnn.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_label_cli,node_his_features,node_acid_features toneBlue
class node_input_prep,node_token_vocab,node_graph_features,node_potts_model,node_training,node_rf3_weights toneAmber
class node_ph_engine,node_placement,node_design_run,node_pareto toneMint
class node_rf3_fold,node_charge_score,node_fold_score toneRose
class node_researcher,node_structure,node_hbplus toneIndigo
```

## Components

### Protonation labeling

- [PDB labeling](https://github.com/christian-creator/protonpottsmpnn/blob/main/labeller/label_pdb.py): `labeller/label_pdb.py`
- [His features](https://github.com/christian-creator/protonpottsmpnn/blob/main/labeller/03_his_rich_features.py): `labeller/03_his_rich_features.py`
- [Acid features](https://github.com/christian-creator/protonpottsmpnn/blob/main/labeller/04_acid_rich_features.py): `labeller/04_acid_rich_features.py`

### PottsMPNN core

- [Potts featurization](https://github.com/christian-creator/protonpottsmpnn/blob/main/foundry/models/mpnn/src/mpnn/potts_inference.py): `foundry/models/mpnn/src/mpnn/potts_inference.py`
- [Protonation tokens](https://github.com/christian-creator/protonpottsmpnn/blob/main/foundry/models/mpnn/src/mpnn/transforms/feature_aggregation/token_encodings.py): `foundry/models/mpnn/src/mpnn/transforms/feature_aggregation/token_encodings.py`
- [Graph embeddings](https://github.com/christian-creator/protonpottsmpnn/blob/main/foundry/models/mpnn/src/mpnn/model/layers/graph_embeddings.py): `foundry/models/mpnn/src/mpnn/model/layers/graph_embeddings.py`
- [Potts model](https://github.com/christian-creator/protonpottsmpnn/blob/main/foundry/models/mpnn/src/mpnn/model/pottsmpnn.py): `foundry/models/mpnn/src/mpnn/model/pottsmpnn.py`
- [Model training](https://github.com/christian-creator/protonpottsmpnn/blob/main/foundry/models/mpnn/src/mpnn/trainers/pottsmpnn.py): `foundry/models/mpnn/src/mpnn/trainers/pottsmpnn.py`

### pH design

- [pH design engine](https://github.com/christian-creator/protonpottsmpnn/blob/main/foundry/models/mpnn/src/mpnn/inference_engines/potts_mpnn_ph.py): `foundry/models/mpnn/src/mpnn/inference_engines/potts_mpnn_ph.py`
- [Centre placement](https://github.com/christian-creator/protonpottsmpnn/blob/main/inference/design_placement_scan.py): `inference/design_placement_scan.py`
- [Design workflow](https://github.com/christian-creator/protonpottsmpnn/blob/main/inference/design_ph.py): `inference/design_ph.py`
- [Pareto selection](https://github.com/christian-creator/protonpottsmpnn/blob/main/inference/design_ph.py): `inference/design_ph.py`

### Fold and scoring

- [RF3 folding](https://github.com/christian-creator/protonpottsmpnn/blob/main/inference/fold_rf3.py): `inference/fold_rf3.py`
- [Charge clashes](https://github.com/christian-creator/protonpottsmpnn/blob/main/scoring/annotate_charge_clash.py): `scoring/annotate_charge_clash.py`
- [Fold annotation](https://github.com/christian-creator/protonpottsmpnn/blob/main/scoring/annotate_folds.py): `scoring/annotate_folds.py`

### Other components

- **Designer**
- **Input structure**
- **HBPLUS**
- **RF3 checkpoint**

## Connections

- Designer → PDB labeling: labels structures (evidence: `README.md`)
- Input structure → PDB labeling: provides PDB (evidence: `README.md`)
- PDB labeling → HBPLUS: uses geometry (evidence: `README.md`)
- PDB labeling → His features: labels histidines
- PDB labeling → Acid features: labels acids
- Designer → Design workflow: requests designs (evidence: `README.md`)
- Input structure → Design workflow: provides backbone (evidence: `README.md`)
- Design workflow → pH design engine: runs redesign (evidence: `inference/design_ph.py`)
- Design workflow → Centre placement: scans centres (evidence: `inference/design_ph.py`)
- pH design engine → Potts featurization: builds context (evidence: `foundry/models/mpnn/src/mpnn/inference_engines/potts_mpnn_ph.py`)
- Potts featurization → Protonation tokens: encodes tokens (evidence: `foundry/models/mpnn/src/mpnn/potts_inference.py`)
- Potts featurization → Graph embeddings: featurizes structure (evidence: `foundry/models/mpnn/src/mpnn/potts_inference.py`)
- Potts featurization → Potts model: runs forward (evidence: `foundry/models/mpnn/src/mpnn/potts_inference.py`)
- pH design engine → Potts model: optimizes Potts energy (evidence: `foundry/models/mpnn/src/mpnn/inference_engines/potts_mpnn_ph.py`)
- Design workflow → Pareto selection: selects trade-offs (evidence: `README.md`)
- Pareto selection → RF3 folding: folds designs (evidence: `README.md`)
- RF3 folding → RF3 checkpoint: loads checkpoint (evidence: `README.md`)
- RF3 folding → Charge clashes: scores clashes (evidence: `inference/design_ph.py`)
- RF3 folding → Fold annotation: annotates folds (evidence: `inference/design_ph.py`)
- PDB labeling → Model training: supplies labels (evidence: `README.md`)
- Model training → Potts model: trains model
