# zeysun/antibmpnn architecture

> Architecture diagram of the GitHub repository zeysun/antibmpnn, 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/zeysun/antibmpnn
- Repository: https://github.com/zeysun/antibmpnn

## Overview

AntiBMPNN is an antibody-sequence design system built around structure-conditioned ProteinMPNN. The main workflow takes an antibody variable-region PDB and design settings, generates candidate sequences, then parses and clusters the results for review and downstream structural validation. Helper scripts prepare optional design constraints; a separate training path builds and trains antibody models. The run script’s import of the model utilities and the training script’s model/data dependencies are supported by the source index. Some helper-script and example-script wiring is not shown, so those links are omitted or marked unverified.

Main entry points: [`Running_AntiBMPNN_run.py`](https://github.com/zeysun/antibmpnn/blob/main/Running_AntiBMPNN_run.py) (Design runner), [`helper_scripts/parse_multiple_chains.py`](https://github.com/zeysun/antibmpnn/blob/main/helper_scripts/parse_multiple_chains.py) (Parsed structure), [`training/Training.py`](https://github.com/zeysun/antibmpnn/blob/main/training/Training.py) (Training workflow), [`helper_scripts/make_fixed_positions_dict.py`](https://github.com/zeysun/antibmpnn/blob/main/helper_scripts/make_fixed_positions_dict.py) (Position constraints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_design["Sequence design"]
  node_runner["Design runner"]
  node_mpnn["ProteinMPNN utilities"]
  node_parsed["Parsed structure"]
end

subgraph group_constraints["Design constraints"]
  node_fixedchains["Chain selection"]
  node_fixedpos["Position constraints"]
  node_tiedpos["Tied positions"]
  node_posneg["Positive/negative ties"]
  node_biasaa["Amino-acid bias<br/>[make_bias_AA.py]"]
  node_biasres["Residue bias"]
  node_pssm["PSSM constraints"]
  node_omit["Amino-acid omissions<br/>[make_omit_AA.py]"]
  node_pssmdict["PSSM conversion<br/>[make_pssm_dict.py]"]
end

subgraph group_review["Result review"]
  node_fasta["Designed sequences"]
  node_parser["Sequence analysis"]
end

subgraph group_training["Model training"]
  node_trainer["Training workflow<br/>[Training.py]"]
  node_trainutils["Training data utilities<br/>[utils_Antibody.py]"]
  node_trainmodel["Antibody model"]
end

node_user(("Designer"))
node_pdb["Antibody PDB"]
node_alphafold["AlphaFold3"]

node_user -->|"runs design"| node_runner
node_pdb -->|"supplies structure"| node_runner
node_runner -->|"imports utilities"| node_mpnn
node_runner -->|"writes sequences"| node_fasta
node_fasta -->|"parses and clusters"| node_parser
node_parser -->|"informs validation"| node_alphafold
node_pdb -.->|"parses chains"| node_parsed
node_parsed -.->|"supplies positions"| node_fixedpos
node_parsed -.->|"supplies positions"| node_tiedpos
node_parsed -.->|"supplies positions"| node_posneg
node_fixedchains -.->|"configures chains"| node_runner
node_fixedpos -.->|"configures positions"| node_runner
node_tiedpos -.->|"configures ties"| node_runner
node_posneg -.->|"configures ties"| node_runner
node_biasaa -.->|"configures bias"| node_runner
node_biasres -.->|"configures bias"| node_runner
node_pssm -.->|"configures PSSM"| node_runner
node_omit -.->|"configures omissions"| node_runner
node_pssmdict -.->|"prepares PSSM"| node_runner
node_trainer -->|"uses data utilities"| node_trainutils
node_trainer -->|"constructs model"| node_trainmodel
node_trainmodel -->|"returns model"| node_trainer

click node_runner "https://github.com/zeysun/antibmpnn/blob/main/Running_AntiBMPNN_run.py"
click node_mpnn "https://github.com/zeysun/antibmpnn/blob/main/protein_mpnn_utils.py"
click node_parsed "https://github.com/zeysun/antibmpnn/blob/main/helper_scripts/parse_multiple_chains.py"
click node_fixedchains "https://github.com/zeysun/antibmpnn/blob/main/helper_scripts/assign_fixed_chains.py"
click node_fixedpos "https://github.com/zeysun/antibmpnn/blob/main/helper_scripts/make_fixed_positions_dict.py"
click node_tiedpos "https://github.com/zeysun/antibmpnn/blob/main/helper_scripts/make_tied_positions_dict.py"
click node_posneg "https://github.com/zeysun/antibmpnn/blob/main/helper_scripts/make_pos_neg_tied_positions_dict.py"
click node_biasaa "https://github.com/zeysun/antibmpnn/blob/main/helper_scripts/make_bias_AA.py"
click node_biasres "https://github.com/zeysun/antibmpnn/blob/main/helper_scripts/make_bias_per_res_dict.py"
click node_pssm "https://github.com/zeysun/antibmpnn/blob/main/helper_scripts/make_pssm_input_dict.py"
click node_omit "https://github.com/zeysun/antibmpnn/blob/main/helper_scripts/other_tools/make_omit_AA.py"
click node_pssmdict "https://github.com/zeysun/antibmpnn/blob/main/helper_scripts/other_tools/make_pssm_dict.py"
click node_parser "https://github.com/zeysun/antibmpnn/blob/main/helper_scripts/parsing_design_result.py"
click node_trainer "https://github.com/zeysun/antibmpnn/blob/main/training/Training.py"
click node_trainutils "https://github.com/zeysun/antibmpnn/blob/main/training/utils_Antibody.py"
click node_trainmodel "https://github.com/zeysun/antibmpnn/blob/main/training/model_utils_Antibody.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_runner,node_mpnn,node_parsed toneBlue
class node_fixedchains,node_fixedpos,node_tiedpos,node_posneg,node_biasaa,node_biasres,node_pssm,node_omit,node_pssmdict toneAmber
class node_fasta,node_parser toneMint
class node_trainer,node_trainutils,node_trainmodel toneRose
class node_user,node_pdb,node_alphafold toneIndigo
```

## Components

### Sequence design

- [Design runner](https://github.com/zeysun/antibmpnn/blob/main/Running_AntiBMPNN_run.py): `Running_AntiBMPNN_run.py`
- [ProteinMPNN utilities](https://github.com/zeysun/antibmpnn/blob/main/protein_mpnn_utils.py): `protein_mpnn_utils.py`
- [Parsed structure](https://github.com/zeysun/antibmpnn/blob/main/helper_scripts/parse_multiple_chains.py): `helper_scripts/parse_multiple_chains.py`

### Design constraints

- [Chain selection](https://github.com/zeysun/antibmpnn/blob/main/helper_scripts/assign_fixed_chains.py): `helper_scripts/assign_fixed_chains.py`
- [Position constraints](https://github.com/zeysun/antibmpnn/blob/main/helper_scripts/make_fixed_positions_dict.py): `helper_scripts/make_fixed_positions_dict.py`
- [Tied positions](https://github.com/zeysun/antibmpnn/blob/main/helper_scripts/make_tied_positions_dict.py): `helper_scripts/make_tied_positions_dict.py`
- [Positive/negative ties](https://github.com/zeysun/antibmpnn/blob/main/helper_scripts/make_pos_neg_tied_positions_dict.py): `helper_scripts/make_pos_neg_tied_positions_dict.py`
- [Amino-acid bias](https://github.com/zeysun/antibmpnn/blob/main/helper_scripts/make_bias_AA.py): `helper_scripts/make_bias_AA.py`
- [Residue bias](https://github.com/zeysun/antibmpnn/blob/main/helper_scripts/make_bias_per_res_dict.py): `helper_scripts/make_bias_per_res_dict.py`
- [PSSM constraints](https://github.com/zeysun/antibmpnn/blob/main/helper_scripts/make_pssm_input_dict.py): `helper_scripts/make_pssm_input_dict.py`
- [Amino-acid omissions](https://github.com/zeysun/antibmpnn/blob/main/helper_scripts/other_tools/make_omit_AA.py): `helper_scripts/other_tools/make_omit_AA.py`
- [PSSM conversion](https://github.com/zeysun/antibmpnn/blob/main/helper_scripts/other_tools/make_pssm_dict.py): `helper_scripts/other_tools/make_pssm_dict.py`

### Result review

- **Designed sequences**
- [Sequence analysis](https://github.com/zeysun/antibmpnn/blob/main/helper_scripts/parsing_design_result.py): `helper_scripts/parsing_design_result.py`

### Model training

- [Training workflow](https://github.com/zeysun/antibmpnn/blob/main/training/Training.py): `training/Training.py`
- [Training data utilities](https://github.com/zeysun/antibmpnn/blob/main/training/utils_Antibody.py): `training/utils_Antibody.py`
- [Antibody model](https://github.com/zeysun/antibmpnn/blob/main/training/model_utils_Antibody.py): `training/model_utils_Antibody.py`

### Other components

- **Designer**
- **Antibody PDB**
- **AlphaFold3**

## Connections

- Designer → Design runner: runs design (evidence: `README.md`)
- Antibody PDB → Design runner: supplies structure (evidence: `README.md`)
- Design runner → ProteinMPNN utilities: imports utilities (evidence: `Running_AntiBMPNN_run.py`)
- Design runner → Designed sequences: writes sequences (evidence: `README.md`)
- Designed sequences → Sequence analysis: parses and clusters (evidence: `README.md`)
- Sequence analysis → AlphaFold3: informs validation (evidence: `README.md`)
- Antibody PDB → Parsed structure: parses chains
- Parsed structure → Position constraints: supplies positions
- Parsed structure → Tied positions: supplies positions
- Parsed structure → Positive/negative ties: supplies positions
- Chain selection → Design runner: configures chains
- Position constraints → Design runner: configures positions
- Tied positions → Design runner: configures ties
- Positive/negative ties → Design runner: configures ties
- Amino-acid bias → Design runner: configures bias
- Residue bias → Design runner: configures bias
- PSSM constraints → Design runner: configures PSSM
- Amino-acid omissions → Design runner: configures omissions
- PSSM conversion → Design runner: prepares PSSM
- Training workflow → Training data utilities: uses data utilities (evidence: `training/Training.py`)
- Training workflow → Antibody model: constructs model (evidence: `training/Training.py`)
- Antibody model → Training workflow: returns model (evidence: `training/Training.py`)
