# a4bio/pifold architecture

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

- Interactive diagram: https://gitdiagram.com/a4bio/pifold
- Repository: https://github.com/a4bio/pifold

## Overview

##### Project type and purpose
- PiFold is an open-source research tool (Python library + CLI) for protein inverse folding (“given a 3D protein backbone, predict a sequence that will fold into it”).
- It’s not a web or full-stack app, but a scientific/ML pipeline with components for data loading, feature construction, GNN-based modeling, training, evaluation, and fixed-backbone design.

##### File structure
- Top level:
- main.py & parser.py – CLI entry point and argument parsing
- API/ – data‐loading, featurization, recording, utility routines
- methods/ – core model definitions (PiGNN layers), training scheduler, ProDesign legacy code
- utils/ – orchestration helpers (experiment setup, logging, simulation design)
- assets/ – paper PDF and framework/result screenshots
- example/ – sample input PDB file
- Look for patterns:
- API handles “I/O → feature → batch” pipeline
- methods encapsulate “model architecture → forward pass → loss”
- main.py glues API + methods + utils into end-to-end runs
- parser.py isolates CLI interface from implementation

##### README for additional insights
- Describes high-level framework: input (protein structure) → residue featurizer (virtual atoms + learned features) → PiGNN layers (node/edge/global contexts) → one-shot sequence decoder → evaluation on CATH, TS50, TS500.
- Mentions ablations, benchmarking, fixed backbone design use-case.

1. CLI Layer
– main.py & parser.py (argument parsing, run modes: train / design / benchmark)
2. Data Layer (API)
– Dataset loaders: CATH, TS datasets (cath_dataset.py, ts_dataset.py)
– Dataloaders (dataloader.py, dataloader_gtrans.py)
– Featurizer (featurizer.py)
– Recorder & utils (recorder.py, utils.py)
3. Model Layer (methods)
– BaseMethod abstraction (base_method.py)
– PiGNN modules (prodesign_module.py, prodesign_model.py)
– Optim scheduler & training loop (optim_scheduler.py, utils.py)
4. Utility Layer (utils)
– Experiment orchestration & logging (main_utils.py)
– Simulation/design‐specific helpers (simdesign_utils.py)
5. External Dependencies & Data
– PyTorch / TorchGeometric (implied)
– CATH, TS50/TS500 datasets
– Example PDB files
– CLI → Parser → Experiment config
– CLI uses API.DataLayer to load and batch data
– API.Featurizer → emits graph representations to ModelLayer
– ModelLayer (PiGNN) → outputs logits/sequence predictions
– OptimScheduler → updates ModelLayer parameters
– Recorder & Utils capture metrics, save checkpoints
– CLI triggers evaluation on held-out TS datasets; fixed-backbone design path reads a PDB, runs forward only
c. Architectural patterns & design principles:
– Layered architecture (CLI / Data / Model / Utils)
– Modular design: clear separation of concerns (I/O vs. computation vs. orchestration)
– Abstract base class (BaseMethod) for easy swapping or extending methods
– One-shot generation pattern (non-autoregressive inference)
d. Key technologies & libraries:
– Python 3.x
– PyTorch (+ TorchGeometric for GNN layers)
– NumPy, SciPy for feature ops
– Click or argparse for CLI (parser.py)
– Standard ML tooling (logging, checkpointing)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        MAIN(("main.py")):::cli
        PARSER(("parser.py")):::cli
    end

    %% Data Layer
    subgraph "Data Layer (API)"
        direction TB
        CATH_DS[/"cath_dataset.py"/]:::data
        TS_DS[/"ts_dataset.py"/]:::data
        DATALOADER[/"dataloader.py"/]:::data
        DATALOADER_G[/"dataloader_gtrans.py"/]:::data
        FEAT["featurizer.py"]:::data
        RECORDER["recorder.py"]:::data
        APIUTILS["utils.py"]:::data
    end

    %% Model Layer
    subgraph "Model Layer (Methods)"
        direction TB
        BASE["base_method.py"]:::model
        MODULE["prodesign_module.py"]:::model
        MODEL["prodesign_model.py"]:::model
        SCHED["optim_scheduler.py"]:::model
        MUTILS["utils.py"]:::model
    end

    %% Utility Layer
    subgraph "Utility Layer"
        direction TB
        MU["main_utils.py"]:::utils
        SU["simdesign_utils.py"]:::utils
    end

    %% Example Input
    subgraph "Example Input Data"
        direction TB
        PDB(("1o91.pdb1.gz")):::external
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        TORCH(("PyTorch / TorchGeometric")):::external
        DATASETS(("CATH, TS50/TS500")):::external
    end

    %% Connections
    MAIN -->|uses| PARSER
    MAIN -->|configures| MU
    MAIN -->|loads data| CATH_DS
    MAIN -->|loads data| TS_DS
    MAIN -->|calls| DATALOADER
    MAIN -->|calls| DATALOADER_G
    DATALOADER -->|calls| FEAT
    DATALOADER_G -->|calls| FEAT
    FEAT -->|produces graph| MODULE
    MODULE -->|forward pass| MODEL
    MODEL -->|outputs logits| MAIN
    MODEL -->|parameters| SCHED
    SCHED -->|updates| MODEL
    MAIN -->|records| RECORDER
    RECORDER -->|logs| SU
    MAIN -->|uses| MU
    MAIN -->|design mode| PDB
    TORCH -->|library| MODULE
    DATASETS -->|source| CATH_DS
    DATASETS -->|source| TS_DS

    %% Click Events
    click MAIN "https://github.com/a4bio/pifold/blob/main/main.py"
    click PARSER "https://github.com/a4bio/pifold/blob/main/parser.py"
    click CATH_DS "https://github.com/a4bio/pifold/blob/main/API/cath_dataset.py"
    click TS_DS "https://github.com/a4bio/pifold/blob/main/API/ts_dataset.py"
    click DATALOADER "https://github.com/a4bio/pifold/blob/main/API/dataloader.py"
    click DATALOADER_G "https://github.com/a4bio/pifold/blob/main/API/dataloader_gtrans.py"
    click FEAT "https://github.com/a4bio/pifold/blob/main/API/featurizer.py"
    click RECORDER "https://github.com/a4bio/pifold/blob/main/API/recorder.py"
    click APIUTILS "https://github.com/a4bio/pifold/blob/main/API/utils.py"
    click BASE "https://github.com/a4bio/pifold/blob/main/methods/base_method.py"
    click MODULE "https://github.com/a4bio/pifold/blob/main/methods/prodesign_module.py"
    click MODEL "https://github.com/a4bio/pifold/blob/main/methods/prodesign_model.py"
    click SCHED "https://github.com/a4bio/pifold/blob/main/methods/optim_scheduler.py"
    click MUTILS "https://github.com/a4bio/pifold/blob/main/methods/utils.py"
    click MU "https://github.com/a4bio/pifold/blob/main/utils/main_utils.py"
    click SU "https://github.com/a4bio/pifold/blob/main/utils/simdesign_utils.py"
    click PDB "https://github.com/a4bio/pifold/blob/main/example/1o91.pdb1.gz"
    click TORCH "https://github.com/a4bio/pifold/blob/main/ReadMe.md"
    click DATASETS "https://github.com/a4bio/pifold/blob/main/assets/PiFold_arxiv.pdf"

    %% Styles
    classDef cli fill:#D0E7FF,stroke:#0366D6;
    classDef data fill:#E6F4EA,stroke:#28A745;
    classDef model fill:#FFE5D0,stroke:#D9822B;
    classDef utils fill:#F0F0F0,stroke:#6A737D;
    classDef external fill:#F0E6FF,stroke:#6F42C1;
```
