# gcorso/diffdock architecture

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

- Interactive diagram: https://gitdiagram.com/gcorso/diffdock
- Repository: https://github.com/gcorso/diffdock

## Overview

##### Project Type and Purpose
- DiffDock is an open-source, research‐grade machine learning tool for molecular docking.
- It provides both training and inference pipelines for a diffusion‐based docking model (original & “L”), plus a simple web UI.
- Key use cases: model training (`train.py`), evaluation (`evaluate.py`), batch & single‐complex inference (`inference.py`), GUI application (`app/main.py`).

##### File-Structure Analysis
Top-level directories and files:
- app/                ← Web UI (Gradio)
- confidence/         ← Confidence‐score model and data processing
- data/               ← Raw & processed datasets, train/val/test splits
- datasets/           ← Dataset builders & ESM embedding preprocessing
- examples/           ← Sample PDB/SDF inputs for inference
- models/             ← Neural network definitions (AA, CG, layers)
- spyrmsd/            ← Integrated RMSD library (graph algorithms, IO)
- utils/              ← Helper functions (geometry, sampling, I/O, logging)
- train.py / evaluate.py / inference.py ← Entrypoints
- Dockerfile, environment.yml ← Deployment & environment specs

##### README Insights
- Describes deployment options: Conda env vs Docker.
- Highlights external dependencies: ESM‐based protein embeddings, RDKit/OBabel, GPU (CUDA).
- Specifies two modes: CLI batch inference & GUI.

##### Main Components and Their Interactions
A. Data Layer
1. Raw inputs: PDB files, SDF/MOL2 ligands, SMILES strings
2. Preprocessing:
– ESM embedding preparation (datasets/esm_embedding_preparation.py → FASTA → ESM2 → embeddings pt)
– Data splits & caching in data/
– RMSD calculations via spyrmsd
B. Model Layer
1. Neural nets (models/): coarse‐grained (CG) & all-atom (AA) diffusion models
2. Tensor layers & custom SO(3)/SE(3) operations (models/tensor_layers.py)
3. Confidence head (confidence/confidence_train.py)
C. Training & Evaluation
1. train.py: orchestrates data loading (datasets/, data/), model instantiation, optimizer, training loop (utils/training.py), logging (utils/logging_utils.py)
2. evaluate.py: uses saved checkpoints + default_inference_args.yaml to benchmark on splits
D. Inference & Application
1. inference.py: CLI entrypoint for batch & single‐complex docking
2. app/main.py + mol_viewer.py + run_utils.py: Gradio‐based GUI, molecule visualization
E. Deployment & Environment
1. Conda (environment.yml)
2. Docker: top‐level Dockerfile + app/Dockerfile for building reproducible containers

##### Architectural Patterns & Design Principles
- Modular design: clear separation of data ingestion, model definition, training, inference, and UI.
- Layered architecture:
- Data layer → Model layer → Application layer → Presentation layer
- Extensibility:
- “datasets/” can be extended to new sources; “models/” can host new architectures; “app/” can be swapped for other UIs.
- Dependency‐injection via config files (default_inference_args.yaml).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Data Layer
    subgraph "Data Layer"
        RawFiles["Raw Inputs (PDB, SDF, SMILES)"]:::data
        subgraph "Preprocessing"
            ESMPrep["ESM2 Embedder"]:::compute
            ESM2PT["ESM ➔ PT"]:::compute
            Sidechain["Sidechain ESM ➔ PT"]:::compute
            Conformer["Conformer Matching"]:::compute
            MOAD["MOAD Builder"]:::compute
            PDBBind["PDBBind Builder"]:::compute
            ProcessMols["Process Molecules"]:::compute
            DataLoaderPrep["Data Loader Prep"]:::compute
            Loader["Loader"]:::compute
            RMSDCalc["RMSD Calculator"]:::compute
        end
        DataStore["Processed Data Storage"]:::data
    end

    %% Model Layer
    subgraph "Model Layer"
        CGModel["Coarse-Grained Model"]:::compute
        AAModel["All-Atom Model"]:::compute
        OldCG["Old CG Model"]:::compute
        OldAA["Old AA Model"]:::compute
        Layers["Layers"]:::compute
        TensorLayers["Tensor Layers"]:::compute
        subgraph "Confidence Module"
            ConfTrain["Confidence Training"]:::compute
            ConfDataProc["Confidence Dataset"]:::compute
        end
    end

    %% Training & Evaluation
    subgraph "Training & Evaluation"
        Train["train.py"]:::compute
        Eval["evaluate.py"]:::compute
    end

    %% Inference & UI
    subgraph "Inference & UI"
        Infer["inference.py"]:::compute
        subgraph "GUI Application"
            AppMain["Gradio UI"]:::ui
            MolViewer["Molecule Viewer"]:::ui
            RunUtils["Run Utils"]:::ui
            Requirements["Requirements"]:::ui
            AppDocker["App Dockerfile"]:::infra
        end
        User["User"]:::external
    end

    %% Deployment & Environment
    subgraph "Deployment"
        DockerRoot["Docker"]:::infra
        Conda["Conda (env)"]:::infra
        GPU["GPU (CUDA)"]:::infra
        EnvYML["Environment YML"]:::infra
    end

    %% Connections
    RawFiles -->|input| ESMPrep
    RawFiles -->|input| RMSDCalc
    ESMPrep --> ESM2PT
    ESM2PT --> Sidechain
    Sidechain --> Conformer
    Conformer --> MOAD
    MOAD --> PDBBind
    PDBBind --> ProcessMols
    ProcessMols --> DataLoaderPrep
    DataLoaderPrep --> Loader
    Loader --> DataStore
    RMSDCalc --> DataStore

    DataStore --> Train
    CGModel --> Train
    AAModel --> Train
    ConfTrain --> Train
    ConfDataProc --> Train

    Train --> CGModel
    Train --> AAModel
    Train --> ConfTrain

    DataStore --> Eval
    CGModel --> Eval
    AAModel --> Eval
    ConfTrain --> Eval

    DataStore --> Infer
    CGModel --> Infer
    AAModel --> Infer
    ConfTrain --> Infer

    Infer --> AppMain
    AppMain --> MolViewer
    AppMain --> RunUtils
    AppMain --> User
    User --> AppMain

    DockerRoot --> Train
    DockerRoot --> Eval
    DockerRoot --> Infer
    DockerRoot --> AppMain

    Conda --> Train
    Conda --> Eval
    Conda --> Infer
    Conda --> AppMain

    GPU --> Train
    GPU --> Eval
    GPU --> Infer

    %% Click Events
    click AppMain "https://github.com/gcorso/diffdock/blob/main/app/main.py"
    click MolViewer "https://github.com/gcorso/diffdock/blob/main/app/mol_viewer.py"
    click RunUtils "https://github.com/gcorso/diffdock/blob/main/app/run_utils.py"
    click Requirements "https://github.com/gcorso/diffdock/blob/main/app/requirements.txt"
    click AppDocker "https://github.com/gcorso/diffdock/tree/main/app/Dockerfile"

    click ConfTrain "https://github.com/gcorso/diffdock/blob/main/confidence/confidence_train.py"
    click ConfDataProc "https://github.com/gcorso/diffdock/blob/main/confidence/dataset.py"

    click RawFiles "https://github.com/gcorso/diffdock/tree/main/data/"

    click ESMPrep "https://github.com/gcorso/diffdock/blob/main/datasets/esm_embedding_preparation.py"
    click ESM2PT "https://github.com/gcorso/diffdock/blob/main/datasets/esm_embeddings_to_pt.py"
    click Sidechain "https://github.com/gcorso/diffdock/blob/main/datasets/sidechain_esm_embeddings_to_pt.py"
    click Conformer "https://github.com/gcorso/diffdock/blob/main/datasets/conformer_matching.py"
    click MOAD "https://github.com/gcorso/diffdock/blob/main/datasets/moad.py"
    click PDBBind "https://github.com/gcorso/diffdock/blob/main/datasets/pdbbind.py"
    click ProcessMols "https://github.com/gcorso/diffdock/blob/main/datasets/process_mols.py"
    click DataLoaderPrep "https://github.com/gcorso/diffdock/blob/main/datasets/dataloader.py"
    click Loader "https://github.com/gcorso/diffdock/blob/main/datasets/loader.py"

    click RMSDCalc "https://github.com/gcorso/diffdock/tree/main/spyrmsd/"

    click CGModel "https://github.com/gcorso/diffdock/blob/main/models/cg_model.py"
    click AAModel "https://github.com/gcorso/diffdock/blob/main/models/aa_model.py"
    click OldCG "https://github.com/gcorso/diffdock/blob/main/models/old_cg_model.py"
    click OldAA "https://github.com/gcorso/diffdock/blob/main/models/old_aa_model.py"
    click Layers "https://github.com/gcorso/diffdock/blob/main/models/layers.py"
    click TensorLayers "https://github.com/gcorso/diffdock/blob/main/models/tensor_layers.py"

    click Train "https://github.com/gcorso/diffdock/blob/main/train.py"
    click EnvYML "https://github.com/gcorso/diffdock/blob/main/default_inference_args.yaml"
    click Eval "https://github.com/gcorso/diffdock/blob/main/evaluate.py"
    click Infer "https://github.com/gcorso/diffdock/blob/main/inference.py"
    click DockerRoot "https://github.com/gcorso/diffdock/tree/main/Dockerfile"
    click Conda "https://github.com/gcorso/diffdock/blob/main/environment.yml"

    %% Styles
    classDef data fill:#E0F7FA,stroke:#0288D1;
    classDef compute fill:#E8F5E9,stroke:#388E3C;
    classDef ui fill:#FFF9C4,stroke:#FBC02D;
    classDef infra fill:#ECEFF1,stroke:#90A4AE;
    classDef external fill:#FFCCBC,stroke:#D84315;
```
