# microsoft/graphormer architecture

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

- Interactive diagram: https://gitdiagram.com/microsoft/graphormer
- Repository: https://github.com/microsoft/graphormer

## Overview

##### Main Components
- Core Library (Graphormer):
– This component includes fundamental modules (e.g., criterions, data handling, models, modules/multihead attention, training tasks, pretrain utilities, and evaluation scripts). It is used as the backbone for all subprojects.
– Highlight supporting functionalities that integrate with external frameworks (e.g., fairseq, PyG, DGL, and OGB).
- Subproject Variants (Distributional Graphormer):
– Catalyst-Adsorption: Contains specialized scripts, models, and training procedures specifically tailored for modeling catalyst adsorption phenomena.
– Property-Guided: Another branch that contains bespoke models (such as m3gnet utilities) and task definitions for material property prediction.
– Protein–Ligand: Focused on tasks like protein–ligand interactions with dedicated evaluation, preprocessing (using environment files, sample pdb scripts), and diffusion models.
– Protein: A branch that appears oriented toward general protein modeling, with a separate data provider and a suite of model definitions.
- Auxiliary Components:
– Examples: Scripted examples and custom dataset handlers for demonstrating how to set up experiments.
– Documentation and CI/CD: GitHub workflows, docs (readthedocs, tutorials, guides), and installation scripts (like install.sh) that manage deployment and user onboarding.

##### Out Relationships and Interactions
- Within the Core Library, delineate subdivisions such as:
– Data Management: Handling datasets (algos, collators, dataset loaders, and wrappers).
– Model Components: The structure of graphormer layers, 3D modules, multihead attention, encoder layers, etc.
– Training and Tasks: Custom training scripts, pre-training processes, and criterions (loss functions).

##### Architectural Patterns and Design Principles
- Modularity: The repository is clearly structured in modular components—with separate directories for data, models, modules, and tasks—which makes it easier to extend for different molecular modeling tasks.
- Reusability & Extensibility: The core library is designed to be adapted for multiple domain-specific projects.
- Separation of Concerns: Division between core functionalities (model definitions, utility functions) and task-specific logic (specific training scripts, data pipelines for each subproject).

##### Relevant Technologies
- Deep Learning and Pre-training: The modules and models that implement transformer-based architectures adapted for graph data.
- External Libraries and Frameworks: Support for fairseq, PyG (PyTorch Geometric), DGL (Deep Graph Library), and OGB.
- Scripting and Lifecycle Management: Shell scripts (install.sh, train.sh) for installation and training, plus CI/CD configs from GitHub workflows that ensure consistent builds and tests.

##### Elements
– Graphormer Core (with submodules: Data, Models, Modules, Tasks, Utils)
– Catalyst-Adsorption extension
– Property-Guided extension
– Protein–Ligand extension
– Protein extension
– External Framework Integrations (fairseq, PyG, DGL, OGB)
– Data flow (from dataset processing, through model layers, to evaluation)
– Dependency flows (from core library components to specialized subprojects)
– Core components vs. task-specific components
– External integrations vs. internal modules
- Optionally, include deployment/CI components (GitHub Actions, installation scripts) on the periphery if relevant.

##### Final Assembly
– Start with a high-level view with the “Graphormer Core” at the center.
– Link external libraries and examples to the relevant core modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Integrations"
        ES["fairseq Integration"]:::external
        EPyG["PyG Datasets"]:::external
        EDGL["DGL Datasets"]:::external
        EOGB["OGB Datasets"]:::external
    end

    subgraph "Core Engine"
        GC_Main["Graphormer Core"]:::core
        GC_Criterions["Criterions"]:::core
        GC_Data["Data Handling"]:::core
        GC_Models["Models"]:::core
        GC_Modules["Modules"]:::core
        GC_Pretrain["Pretrain Utilities"]:::core
        GC_Tasks["Training & Tasks"]:::core
        GC_Utils["Utilities"]:::core
    end

    subgraph "Specialized Extensions"
        subgraph "Catalyst-Adsorption Extension"
            CA_Main["Catalyst-Adsorption Core"]:::extension
            CA_Script["Install Scripts"]:::extension
            CA_Train["Training Script"]:::extension
        end
        subgraph "Property-Guided Extension"
            PG_Main["Property-Guided Core"]:::extension
            PG_Script["Install Scripts"]:::extension
        end
        subgraph "Protein–Ligand Extension"
            PL_Main["Protein–Ligand Core"]:::extension
            PL_Script["Install Script"]:::extension
            PL_Env["Environment Config"]:::extension
            PL_Eval["Evaluation & Examples"]:::extension
        end
        subgraph "Protein Extension"
            P_Common["Protein Common"]:::extension
            P_Data["Data Provider"]:::extension
            P_Model["Protein Models"]:::extension
            P_Run["Inference Script"]:::extension
        end
    end

    subgraph "Auxiliary Components"
        EX["Examples"]:::auxiliary
        DOC["Docs & CI/CD"]:::auxiliary
    end

    %% External Integrations to Core
    ES -->|"integrates"| GC_Main
    EPyG -->|"data"| GC_Data
    EDGL -->|"data"| GC_Data
    EOGB -->|"data"| GC_Data

    %% Core Engine internal breakdown
    GC_Main --> GC_Criterions
    GC_Main --> GC_Data
    GC_Main --> GC_Models
    GC_Main --> GC_Modules
    GC_Main --> GC_Pretrain
    GC_Main --> GC_Tasks
    GC_Main --> GC_Utils

    %% Core to Specialized Extensions
    GC_Main -->|"extends"| CA_Main
    GC_Main -->|"extends"| PG_Main
    GC_Main -->|"extends"| PL_Main
    GC_Main -->|"extends"| P_Common

    %% Catalyst-Adsorption internal flow
    CA_Main --> CA_Script
    CA_Script --> CA_Train

    %% Protein–Ligand internal flow
    PL_Main --> PL_Script
    PL_Main --> PL_Env
    PL_Main --> PL_Eval

    %% Protein Extension internal flow
    P_Common --> P_Data
    P_Common --> P_Model
    P_Common --> P_Run

    %% Auxiliary to Core connections
    EX -->|"demonstrates"| GC_Main
    DOC -->|"supports"| GC_Main

    %% Click Events for Core Engine Components
    click GC_Main "https://github.com/microsoft/graphormer/blob/main/graphormer/__init__.py"
    click GC_Criterions "https://github.com/microsoft/graphormer/tree/main/graphormer/criterions/"
    click GC_Data "https://github.com/microsoft/graphormer/tree/main/graphormer/data/"
    click GC_Models "https://github.com/microsoft/graphormer/tree/main/graphormer/models/"
    click GC_Modules "https://github.com/microsoft/graphormer/tree/main/graphormer/modules/"
    click GC_Pretrain "https://github.com/microsoft/graphormer/tree/main/graphormer/pretrain/"
    click GC_Tasks "https://github.com/microsoft/graphormer/tree/main/graphormer/tasks/"
    click GC_Utils "https://github.com/microsoft/graphormer/tree/main/graphormer/utils/"

    %% Click Events for Catalyst-Adsorption Extension
    click CA_Main "https://github.com/microsoft/graphormer/tree/main/distributional_graphormer/catalyst-adsorption/graphormer/"
    click CA_Script "https://github.com/microsoft/graphormer/blob/main/distributional_graphormer/catalyst-adsorption/install.sh"
    click CA_Train "https://github.com/microsoft/graphormer/blob/main/scripts/train.sh"

    %% Click Events for Property-Guided Extension
    click PG_Main "https://github.com/microsoft/graphormer/tree/main/distributional_graphormer/property-guided/graphormer/"
    click PG_Script "https://github.com/microsoft/graphormer/blob/main/distributional_graphormer/property-guided/install.sh"

    %% Click Events for Protein–Ligand Extension
    click PL_Main "https://github.com/microsoft/graphormer/tree/main/distributional_graphormer/protein-ligand/src/graphormer/"
    click PL_Script "https://github.com/microsoft/graphormer/blob/main/distributional_graphormer/protein-ligand/src/install.sh"
    click PL_Env "https://github.com/microsoft/graphormer/blob/main/distributional_graphormer/protein-ligand/src/env.yml"
    click PL_Eval "https://github.com/microsoft/graphormer/tree/main/distributional_graphormer/protein-ligand/src/evaluation"

    %% Click Events for Protein Extension
    click P_Common "https://github.com/microsoft/graphormer/tree/main/distributional_graphormer/protein/common/"
    click P_Data "https://github.com/microsoft/graphormer/tree/main/distributional_graphormer/protein/data_provider/"
    click P_Model "https://github.com/microsoft/graphormer/tree/main/distributional_graphormer/protein/model/"
    click P_Run "https://github.com/microsoft/graphormer/blob/main/distributional_graphormer/protein/run_inference.py"

    %% Click Events for External Integrations
    click ES "https://github.com/microsoft/graphormer/tree/main/fairseq"
    click EPyG "https://github.com/microsoft/graphormer/tree/main/graphormer/data/pyg_datasets/"
    click EDGL "https://github.com/microsoft/graphormer/tree/main/graphormer/data/dgl_datasets/"
    click EOGB "https://github.com/microsoft/graphormer/tree/main/graphormer/data/ogb_datasets/"

    %% Click Events for Auxiliary Components
    click EX "https://github.com/microsoft/graphormer/tree/main/examples/"
    click DOC "https://github.com/microsoft/graphormer/tree/main/.github/workflows/"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef extension fill:#ABEBC6,stroke:#196F3D,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef auxiliary fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
```
