# graylab/igfold architecture

> Architecture diagram of the GitHub repository graylab/igfold, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/graylab/igfold
- Repository: https://github.com/graylab/igfold

## Overview

##### Project Type and Purpose
- IgFold is a Python deep-learning library and command-line tool for fast, accurate antibody and nanobody structure prediction.
- It provides a reusable “runner” interface (IgFoldRunner) that orchestrates: sequence embedding, structure prediction via graph-transformer modules, optional refinement (PyRosetta or OpenMM), renumbering (AbNumber), and PDB output.

##### High-Level Components
a. IgFoldRunner (igfold/IgFoldRunner.py)
- Orchestrates the end-to-end pipeline: takes input sequences, calls the model, triggers refinement and renumbering, writes PDB.
b. Core Model (igfold/model)
- IgFold (GraphTransformer-based) pipeline:
– AntiBERTy embedding (igfold/utils/embed.py)
– GraphTransformer module (GraphTransformer.py)
– IPA attention blocks (IPABlock.py, IPATransformer.py)
– Triangle updates (TriangleGraphTransformer.py, TriangleMultiplicativeModule.py)
– Final structure head in IgFold.py
c. Refinement Modules (igfold/refine)
- PyRosetta backend (pyrosetta_ref.py)
- OpenMM backend (openmm_ref.py)
– Pluggable: Runner picks one based on environment and flags.
d. Supporting Utilities (igfold/utils)
- Sequence parsing, coordinate transforms, PDB I/O, visualization, renumbering interface, metrics.
e. Training Utilities (igfold/training)
- Data loaders and helper functions for model development—not part of the inference pipeline.

##### External Dependencies and Data Sources
- Deep-learning framework: PyTorch
- Pretrained language model: AntiBERTy
- Refinement engines: PyRosetta or OpenMM (with pdbfixer)
- Renumbering: AbNumber
- Optional: Colab notebook and large antibody sequence archives (OAS, Jaffe2022)

##### Data Flow and Interactions
1) Input: Antibody chain sequences (H and L or single chain)
2) Embedding: AntiBERTy → per-residue features
3) Graph Construction: build residue graph and pair features
4) Iterative Structure Prediction: GraphTransformer → IPA → Triangle modules → coordinate head
5) Output: initial 3D coordinates
6) Optional Refinement: PyRosetta or OpenMM → energy minimization → improved geometry
7) Renumbering: Chothia scheme via AbNumber
8) Final Output: PDB file with predicted B-factors (RMSD estimates) in B-column

##### Architectural Patterns and Design Principles
- Modular Pipeline: distinct stages (embed → predict → refine → renum)
- Pluggable Backends: refinement step selects implementation by availability
- Separation of Concerns: model code under igfold/model, orchestration in Runner, I/O and utilities decoupled
- Reusable Components: graph and attention blocks can be extended or replaced

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestration
    subgraph "Orchestration"
        Runner["IgFoldRunner"]:::orchestration
    end

    %% Embedding Stage
    subgraph "Embedding Stage"
        Embedding["AntiBERTy Embedding"]:::core
    end

    %% Core Model Pipeline
    subgraph "Model Pipeline"
        GraphTransformer["GraphTransformer"]:::core
        IPABlock["IPABlock"]:::core
        IPATransformer["IPATransformer"]:::core
        TriangleGT["TriangleGraphTransformer"]:::core
        TriangleMul["TriangleMultiplicativeModule"]:::core
        IgFold["IgFold"]:::core
    end

    %% Refinement Backends
    subgraph "Refinement Backends"
        pyro["PyRosetta Backend"]:::refine
        openmm["OpenMM Backend"]:::refine
    end

    %% Utilities
    subgraph "Utilities"
        fasta["Sequence Parsing"]:::utils
        coords["Coordinate Transforms"]:::utils
        tensor["Tensor & Array"]:::utils
        geometry["Geometric Utils"]:::utils
        transforms["Transform Utils"]:::utils
        pdbio["PDB I/O"]:::utils
        visualize["Visualization"]:::utils
        abnumber["Renumbering (AbNumber)"]:::utils
        metrics["Antibody Metrics"]:::utils
        general["General Utils"]:::utils
        folding["Folding Helpers"]:::utils
        constants["Constants"]:::utils
    end

    %% External Dependencies
    subgraph "External Dependencies"
        pytorch["PyTorch"]:::external
        antiberty["AntiBERTy"]:::external
        pyrosetta_dep["PyRosetta"]:::external
        openmm_dep["OpenMM"]:::external
        abnumber_ext["AbNumber"]:::external
    end

    %% Data Flow
    InputSeqs["Input Sequences"] -->|sequences| Runner
    Runner -->|sequences| Embedding
    Embedding -->|embeddings| GraphTransformer
    GraphTransformer -->|features| IPABlock
    IPABlock -->|attention| IPATransformer
    IPATransformer -->|pair updates| TriangleGT
    TriangleGT -->|triangle updates| TriangleMul
    TriangleMul -->|refined pairs| IgFold
    IgFold -->|initial 3D coords| InitialCoords["Initial Coordinates"]
    InitialCoords -.->|optional| pyro
    InitialCoords -.->|optional| openmm
    pyro -->|refined coords| Refined["Refined Coordinates"]
    openmm -->|refined coords| Refined
    Refined -->|coords| abnumber
    abnumber -->|renumbered coords| FinalPDB["PDB File Output"]:::database

    %% Utilities usage
    Runner -.-> fasta
    Runner -.-> coords
    Runner -.-> pdbio
    Runner -.-> folding
    Embedding -.-> antiferty
    Embedding -.-> pytorch
    GraphTransformer -.-> pytorch
    IPABlock -.-> pytorch
    IPATransformer -.-> pytorch
    TriangleGT -.-> pytorch
    TriangleMul -.-> pytorch
    IgFold -.-> pytorch
    Refined -.-> pyrosetta_dep
    Refined -.-> openmm_dep
    abnumber -.-> abnumber_ext

    %% Click Events
    click Runner "https://github.com/graylab/igfold/blob/main/igfold/IgFoldRunner.py"
    click Embedding "https://github.com/graylab/igfold/blob/main/igfold/utils/embed.py"
    click IgFold "https://github.com/graylab/igfold/blob/main/igfold/model/IgFold.py"
    click GraphTransformer "https://github.com/graylab/igfold/blob/main/igfold/model/components/GraphTransformer.py"
    click IPABlock "https://github.com/graylab/igfold/blob/main/igfold/model/components/IPABlock.py"
    click IPATransformer "https://github.com/graylab/igfold/blob/main/igfold/model/components/IPATransformer.py"
    click TriangleGT "https://github.com/graylab/igfold/blob/main/igfold/model/components/TriangleGraphTransformer.py"
    click TriangleMul "https://github.com/graylab/igfold/blob/main/igfold/model/components/TriangleMultiplicativeModule.py"
    click pyro "https://github.com/graylab/igfold/blob/main/igfold/refine/pyrosetta_ref.py"
    click openmm "https://github.com/graylab/igfold/blob/main/igfold/refine/openmm_ref.py"
    click fasta "https://github.com/graylab/igfold/blob/main/igfold/utils/fasta.py"
    click coords "https://github.com/graylab/igfold/blob/main/igfold/utils/coordinates.py"
    click tensor "https://github.com/graylab/igfold/blob/main/igfold/utils/tensor.py"
    click geometry "https://github.com/graylab/igfold/blob/main/igfold/utils/geometry.py"
    click transforms "https://github.com/graylab/igfold/blob/main/igfold/utils/transforms.py"
    click pdbio "https://github.com/graylab/igfold/blob/main/igfold/utils/pdb.py"
    click visualize "https://github.com/graylab/igfold/blob/main/igfold/utils/visualize.py"
    click abnumber "https://github.com/graylab/igfold/blob/main/igfold/utils/abnumber_.py"
    click metrics "https://github.com/graylab/igfold/blob/main/igfold/utils/ab_metrics.py"
    click general "https://github.com/graylab/igfold/blob/main/igfold/utils/general.py"
    click folding "https://github.com/graylab/igfold/blob/main/igfold/utils/folding.py"
    click constants "https://github.com/graylab/igfold/blob/main/igfold/utils/constants.py"

    %% Styles
    classDef orchestration fill:#9f6,stroke:#333,stroke-width:1px
    classDef core fill:#6cf,stroke:#333,stroke-width:1px
    classDef refine fill:#f96,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef utils fill:#ccc,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
    classDef external fill:#c9f,stroke:#333,stroke-width:1px
    classDef database fill:#fcf,stroke:#333,stroke-width:1px,shape:cylinder
```
