# sail-sg/gdpo architecture

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

## Overview

##### Project type and purpose
- This is a research-oriented machine-learning framework (“Graph Diffusion Policy Optimization”) for graph generation tasks. It implements graph diffusion models optimized via reinforcement learning (GDPO), supporting arbitrary objectives (e.g., molecular docking scores). It provides pipelines for data preparation, model definition, RL training (PPO), generation, evaluation, and analysis.

##### File structure
Top-level directories and responsibilities:
- analysis: post-hoc analysis and visualization tools (Python + ORCA C++ bindings).
- configs: all experiment, dataset, model, and training hyperparameters (YAML) organized by subfolders.
- dataset: PyTorch/Lightning DataModule wrappers for various graph datasets (ZINC, MOSES, Planar, SBM, toy, protein docking).
- diffusion: core diffusion model logic (noise schedules, layers, distributions, extra feature support).
- model: neural nets (transformers, attention, diffusion-discrete, InfoMax modules, etc.).
- metrics: computation of training and graph/molecular evaluation metrics.
- scorer: external scoring interfaces (docking via QVina, SA score, receptor files, RDKit utilities).
Other files:
- main_train / main_ppo / main_generate / process.py: entry points for training, RL fine-tuning, generation, data processing.
- run_*.sh: convenience scripts for common experiments.
- environment.yml, requirements.txt: dependency specifications (Conda, pip).

##### Extract architectural insights from README
- Uses Hydra-style config overrides via CLI (bare “+experiment=…”).
- Supports multi-seed parallel runs.
- Builds on PyTorch Lightning for checkpointing and resume functionality.
- Requires external tools: RDKit, ORCA for quantum or molecular analysis, QVina for docking.

1. Configuration Manager (YAML + Hydra)
2. Data Pipeline
- Raw dataset sources (./dataset folder, downloads)
- Dataset loaders (dataset/*)
3. Model Components
- Diffusion model (diffusion/*)
- Neural network modules (model/*)
4. Reinforcement Learning Engine
- PPO trainer (main_ppo.py, PyTorch Lightning)
- Policy gradient wrapper (analysis/dist_helper.py)
5. Scoring & Reward Module
- Molecular scorer (scorer/*)
- ORCA integration (analysis/orca)
6. Evaluation & Metrics
- Generation pipeline (main_generate.py)
- Metrics calculators (metrics/*)
- Visualization & analysis (analysis/visualization.py)
7. Execution & Orchestration
- Shell scripts (run_*.sh)
- Process manager (process.py)
8. External Dependencies
- RDKit, QVina, ORCA, Conda environment

- Configuration Manager → Data Pipeline, Model Components, RL Engine (feeds hyperparameters)
- Data Pipeline → RL Engine (batches of graphs)
- RL Engine → Model Components (forward + backward passes)
- Model Components → Scoring Module (generated graphs → reward signals)
- Scoring Module → RL Engine (reinforcement signals)
- RL Engine → Checkpoint storage (outputs/)
- Evaluation & Metrics ← Model Components + Scoring Module + Data Pipeline (test mode)
- Visualization ← Evaluation & Metrics

c. Architectural patterns & principles
- Modular separation of concerns: data, model, training, scoring, analysis.
- Config-driven experiments (Hydra style): decouples code from hyperparameters.
- Plugin architecture for datasets, models, and scorers.
- Use of PyTorch Lightning for standardized training loops and checkpointing.
- Interoperability with C++ (ORCA) and CLI tools (QVina).

d. Key technologies & frameworks
- Python 3.x, PyTorch, PyTorch Lightning
- Hydra/YAML for configs
- RDKit for molecular graphs
- QVina / docking for reward computation
- ORCA (C++) for quantum calculations
- Conda for environment management

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Configuration Manager
    subgraph "Configuration Manager"
        CM["Configuration Manager"]:::config
    end

    %% Data Pipeline
    subgraph "Data Pipeline"
        DS["Dataset Store"]:::data
        AD["abstract_dataset.py"]:::data
        LD["lightningdata.py"]:::data
        MD["moses_dataset.py"]:::data
        PD["ppo_dataset.py"]:::data
        ZD["zinc_dataset.py"]:::data
        DU["utils.py"]:::data
    end

    %% Model Components
    subgraph "Model Components"
        subgraph "Diffusion Core"
            NS["noise_schedule.py"]:::model
            DI["distributions.py"]:::model
            DL["layers.py"]:::model
            EF["extra_features.py"]:::model
            EFM["extra_features_molecular.py"]:::model
            DUF["diffusion_utils.py"]:::model
        end
        subgraph "Neural Modules"
            TM["transformer_model.py"]:::model
            AT["attention.py"]:::model
            DD["diffusion_discrete.py"]:::model
            IM["infomax.py"]:::model
            IOM["info_model.py"]:::model
            LN["layers.py"]:::model
        end
    end

    %% Reinforcement Learning Engine
    subgraph "RL Engine"
        PPO["main_ppo.py"]:::training
        PG["dist_helper.py"]:::training
    end

    %% Scoring & Reward Module
    subgraph "Scoring & Reward"
        SC["scorer.py"]:::scoring
        DO["docking.py"]:::scoring
        VD["vinadock.py"]:::scoring
        SA["sa_scorer.py"]:::scoring
        REC["receptors/"]:::scoring
    end

    %% ORCA Integration
    subgraph "ORCA Integration"
        OC["orca.cpp"]:::external
        OH["orca.h"]:::external
        OB["orca (binary)"]:::external
    end

    %% Evaluation & Metrics
    subgraph "Evaluation & Metrics"
        GEN["main_generate.py"]:::data
        TMET["train_metrics.py"]:::data
        AMET["abstract_metrics.py"]:::data
        MMET["molecular_metrics.py"]:::data
        MMDIS["molecular_metrics_discrete.py"]:::data
    end

    %% Visualization & Analysis
    subgraph "Visualization & Analysis"
        VIZ["visualization.py"]:::data
        GR["graphrewards.py"]:::data
        RF["rdkit_functions.py"]:::data
        SU["spectre_utils.py"]:::data
    end

    %% Execution & Orchestration
    subgraph "Execution & Orchestration"
        PM["process.py"]:::orchestration
        RS["run_*.sh"]:::orchestration
        ES["environment.yml / requirements.txt"]:::orchestration
    end

    %% Checkpoints
    CK["Checkpoints"]:::store

    %% External Dependencies
    subgraph "External Dependencies"
        RD["RDKit"]:::external
        QV["QVina"]:::external
        OCli["ORCA"]:::external
    end

    %% Connections
    CM --> AD
    CM --> NS
    CM --> TM
    CM --> PPO

    AD --> PPO
    LD --> PPO
    MD --> PPO
    PD --> PPO
    ZD --> PPO
    DU --> PPO

    PPO --> NS
    PPO --> DI
    PPO --> DL
    PPO --> EF
    PPO --> EFM
    PPO --> DUF
    PPO --> TM
    PPO --> AT
    PPO --> DD
    PPO --> IM
    PPO --> IOM
    PPO --> LN

    TM --> SC
    AT --> SC
    DD --> SC
    IM --> SC
    IOM --> SC
    LN --> SC

    SC --> PPO

    PPO --> CK

    AD --> GEN
    NS --> GEN
    TM --> GEN
    SC --> GEN

    GEN --> TMET
    GEN --> AMET
    GEN --> MMET
    GEN --> MMDIS

    TMET --> VIZ
    AMET --> VIZ
    MMET --> VIZ
    MMDIS --> VIZ

    PG --> PPO

    PM --> PPO
    PM --> GEN
    RS --> PPO
    RS --> GEN

    RD --> SC
    RD --> RF
    QV --> VD
    OCli --> OC
    OCli --> OH
    OCli --> OB
    OC --> SC

    %% Click Events
    click CM "https://github.com/sail-sg/gdpo/tree/main/configs/"
    click AD "https://github.com/sail-sg/gdpo/blob/main/dataset/abstract_dataset.py"
    click LD "https://github.com/sail-sg/gdpo/blob/main/dataset/lightningdata.py"
    click MD "https://github.com/sail-sg/gdpo/blob/main/dataset/moses_dataset.py"
    click PD "https://github.com/sail-sg/gdpo/blob/main/dataset/ppo_dataset.py"
    click ZD "https://github.com/sail-sg/gdpo/blob/main/dataset/zinc_dataset.py"
    click DU "https://github.com/sail-sg/gdpo/blob/main/dataset/utils.py"
    click NS "https://github.com/sail-sg/gdpo/blob/main/diffusion/noise_schedule.py"
    click DI "https://github.com/sail-sg/gdpo/blob/main/diffusion/distributions.py"
    click DL "https://github.com/sail-sg/gdpo/blob/main/diffusion/layers.py"
    click EF "https://github.com/sail-sg/gdpo/blob/main/diffusion/extra_features.py"
    click EFM "https://github.com/sail-sg/gdpo/blob/main/diffusion/extra_features_molecular.py"
    click DUF "https://github.com/sail-sg/gdpo/blob/main/diffusion/diffusion_utils.py"
    click TM "https://github.com/sail-sg/gdpo/blob/main/model/transformer_model.py"
    click AT "https://github.com/sail-sg/gdpo/blob/main/model/attention.py"
    click DD "https://github.com/sail-sg/gdpo/blob/main/model/diffusion_discrete.py"
    click IM "https://github.com/sail-sg/gdpo/blob/main/model/infomax.py"
    click IOM "https://github.com/sail-sg/gdpo/blob/main/model/info_model.py"
    click LN "https://github.com/sail-sg/gdpo/blob/main/model/layers.py"
    click PPO "https://github.com/sail-sg/gdpo/blob/main/main_ppo.py"
    click PG "https://github.com/sail-sg/gdpo/blob/main/analysis/dist_helper.py"
    click SC "https://github.com/sail-sg/gdpo/blob/main/scorer/scorer.py"
    click DO "https://github.com/sail-sg/gdpo/blob/main/scorer/docking.py"
    click VD "https://github.com/sail-sg/gdpo/blob/main/scorer/vinadock.py"
    click SA "https://github.com/sail-sg/gdpo/blob/main/scorer/sa_scorer.py"
    click REC "https://github.com/sail-sg/gdpo/tree/main/scorer/receptors/"
    click OC "https://github.com/sail-sg/gdpo/blob/main/analysis/orca/orca.cpp"
    click OH "https://github.com/sail-sg/gdpo/blob/main/analysis/orca/orca.h"
    click OB "https://github.com/sail-sg/gdpo/tree/main/analysis/orca/orca"
    click GEN "https://github.com/sail-sg/gdpo/blob/main/main_generate.py"
    click TMET "https://github.com/sail-sg/gdpo/blob/main/metrics/train_metrics.py"
    click AMET "https://github.com/sail-sg/gdpo/blob/main/metrics/abstract_metrics.py"
    click MMET "https://github.com/sail-sg/gdpo/blob/main/metrics/molecular_metrics.py"
    click MMDIS "https://github.com/sail-sg/gdpo/blob/main/metrics/molecular_metrics_discrete.py"
    click VIZ "https://github.com/sail-sg/gdpo/blob/main/analysis/visualization.py"
    click GR "https://github.com/sail-sg/gdpo/blob/main/analysis/graphrewards.py"
    click RF "https://github.com/sail-sg/gdpo/blob/main/analysis/rdkit_functions.py"
    click SU "https://github.com/sail-sg/gdpo/blob/main/analysis/spectre_utils.py"
    click PM "https://github.com/sail-sg/gdpo/blob/main/process.py"
    click RS "https://github.com/sail-sg/gdpo/blob/main/run_*.sh"
    click ES "https://github.com/sail-sg/gdpo/blob/main/environment.yml"
    click ES "https://github.com/sail-sg/gdpo/blob/main/requirements.txt"

    %% Styles
    classDef data fill:#DAE8FC,stroke:#6C8EBF,color:#0B4173
    classDef model fill:#D5E8D4,stroke:#82B366,color:#274E13
    classDef training fill:#E1D5E7,stroke:#9673A6,color:#442C50
    classDef scoring fill:#FFE6CC,stroke:#D79B00,color:#7F6000
    classDef config fill:#F8CECC,stroke:#B85450,color:#5A1D1D
    classDef orchestration fill:#F2F2F2,stroke:#999999,color:#333333
    classDef external fill:#E0E0E0,stroke:#888888,color:#333333
    classDef store fill:#D0CECE,stroke:#8A8A8A,color:#333333
```
