# igashov/difflinker architecture

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

- Interactive diagram: https://gitdiagram.com/igashov/difflinker
- Repository: https://github.com/igashov/difflinker

## Overview

##### Project Type and Purpose
- DiffLinker is an open-source ML tool for 3D-conditional molecular linker design.
- It implements an equivariant diffusion model (EDM) and a size-prediction GNN, orchestrated with PyTorch Lightning.
- It provides data preparation pipelines, model training, inference (generation), and evaluation scripts.

##### High-Level Architectural Components
a. Data Layer
- case_studies/ : example fragment–protein datasets
- data/ : raw data pipelines (CASF, GEOM, pockets, ZINC)
- configs/ : YAML configs driving training/inference parameters
b. Preprocessing & Dataset
- data/** scripts → clean, fragment, generate conformers, split datasets → output `.pt` files
- src/datasets.py → PyTorch Dataset/DataModule definitions
- src/delinker_utils/ → utility functions (fragmentation, scoring, RDKit/OpenBabel wrappers)
c. Model Core
- src/edm.py → diffusion model implementation
- src/egnn.py → equivariant GNN layers
- src/linker_size_lightning.py & src/lightning.py → LightningModules for diffusion & size prediction
- src/delinker.py → high-level model wrapper combining EDM + EGNN
- src/molecule_builder.py → reconstructs 3D molecules from model output
d. Training & Validation
- train_difflinker.py → trains diffusion model using configs/*.yml
- train_size_gnn.py → trains GNN for linker size prediction
- environment.yml → reproducible conda environment
- logs/, models/ directories for checkpoints & TensorBoard/WandB logs
e. Inference & Sampling
- generate.py, generate_with_pocket.py, generate_with_protein.py → entry points for linker generation
- sample.py, sample_trajectories.py → batch sampling & trajectory saving
- run_obabel.py, reformat_data_obabel.py → OpenBabel calls for format conversions
f. Evaluation & Metrics
- compute_metrics.py → computes metrics (recovery, validity, novelty, etc.)
- resources/ → ground-truth references & evaluation CSVs

##### Relationships & Data Flow
- Raw data → data/ preprocessing scripts → saved `.pt` datasets
→ src/datasets.py wraps them into DataLoader
→ train scripts feed DataLoader into LightningModules → model checkpoints
- Inference scripts load checkpoints + config → call model wrapper → generate 3D coordinates → molecule_builder
→ optional OpenBabel reformat → saved output files
- Evaluation scripts consume generated samples + ground-truth → compute metrics

##### Architectural Patterns & Design Principles
- Modular separation: data preparation, model definition, training logic, inference, evaluation
- Config-driven workflows: all hyperparameters & file paths in YAML or CLI args
- Reusable utilities: src/delinker_utils houses shared functions (fragmentation, scoring)
- PyTorch Lightning organizes training/validation loops and checkpointing
- Clear I/O contracts: each script reads from defined folders (`datasets/`, `models/`, `samples/`)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        case_studies[(case_studies/)]:::datastore
        raw_data[(data/)]:::datastore
        configs[(configs/)]:::datastore
    end

    %% Preprocessing & Dataset
    subgraph "Preprocessing & Dataset"
        direction TB
        CASF["CASF Preparation\\n(data/casf/prepare.py)"]:::script
        GEOM1["Generate Conformers\\n(data/geom/generate_geom_conformers.py)"]:::script
        GEOM2["Multi-frag Generation\\n(data/geom/generate_geom_multifrag.py)"]:::script
        GEOM3["Prepare GEOM Dataset\\n(data/geom/prepare_geom_dataset.py)"]:::script
        GEOM4["Train/Test Split\\n(data/geom/train_test_split.py)"]:::script
        POCK1["Clean & Split Pocket\\n(data/pocket/clean_and_split.py)"]:::script
        POCK2["Filter & Split Pocket\\n(data/pocket/filter_and_train_test_split.py)"]:::script
        POCK3["Frag & Conformers\\n(data/pocket/generate_fragmentation_and_conformers.py)"]:::script
        POCK4["Prepare Pocket Dataset\\n(data/pocket/prepare_dataset.py)"]:::script
        ZINC1["Unique SMILES\\n(data/zinc/create_unique_smiles.py)"]:::script
        ZINC2["Filter & Merge\\n(data/zinc/filter_and_merge.py)"]:::script
        ZINC3["Prepare Dataset\\n(data/zinc/prepare_dataset.py)"]:::script
        ZINC4["Prepare Parallel\\n(data/zinc/prepare_dataset_parallel.py)"]:::script
        ZINC5["Prepare Sequential\\n(data/zinc/prepare_dataset_sequential.py)"]:::script
        ZINC6["Prepare Val/Test\\n(data/zinc/prepare_val_test.py)"]:::script
        ZINC7["RDKit Parallel\\n(data/zinc/rdkit_conf_parallel.py)"]:::script
        DSET["Dataset & DataModule\\n(src/datasets.py)"]:::module
        UTIL["Delinker Utils\\n(src/delinker_utils/)"]:::module
    end

    %% Model Core
    subgraph "Model Core"
        direction TB
        EDM["DiffusionModel\\n(src/edm.py)"]:::module
        EGNN["EGNN Layers\\n(src/egnn.py)"]:::module
        LIGHT["Diffusion LightningModule\\n(src/lightning.py)"]:::module
        SIZE_LM["Size LightningModule\\n(src/linker_size_lightning.py)"]:::module
        LINKER_WRP["Model Wrapper\\n(src/delinker.py)"]:::module
        SIZE_GNN["LinkerSize GNN\\n(src/linker_size.py)"]:::module
        BUILDER["Molecule Builder\\n(src/molecule_builder.py)"]:::module
        NOISE["Noise Utils\\n(src/noise.py)"]:::module
        UTILS["Core Utils\\n(src/utils.py)"]:::module
    end

    %% Training & Validation
    subgraph "Training & Validation"
        direction TB
        TRAIN_DIFF["Train Diffusion\\n(train_difflinker.py)"]:::script
        TRAIN_SIZE["Train Size GNN\\n(train_size_gnn.py)"]:::script
        ENV["Conda Env\\n(environment.yml)"]:::script
        CHECKPTS[(models/)]:::datastore
        LOGS[(logs/)]:::datastore
    end

    %% Inference & Sampling
    subgraph "Inference & Sampling"
        direction TB
        GEN1["Generate\\n(generate.py)"]:::script
        GEN2["Gen with Pocket\\n(generate_with_pocket.py)"]:::script
        GEN3["Gen with Protein\\n(generate_with_protein.py)"]:::script
        SAMPLE["Sample Batch\\n(sample.py)"]:::script
        TRAJ["Sample Trajectories\\n(sample_trajectories.py)"]:::script
        OBABEL1["Run OpenBabel\\n(run_obabel.py)"]:::script
        OBABEL2["Reformat OBabel Data\\n(reformat_data_obabel.py)"]:::script
        SAMPLES[(samples/)]:::datastore
    end

    %% Evaluation & Metrics
    subgraph "Evaluation & Metrics"
        direction TB
        METRICS["Compute Metrics\\n(compute_metrics.py)"]:::script
        RESOURCES[(resources/)]:::datastore
    end

    %% External Tools
    subgraph "External Tools"
        direction TB
        PL["PyTorch Lightning"]:::external
        RD["RDKit"]:::external
        OB["OpenBabel"]:::external
    end

    %% Data Flow Connections
    case_studies --> CASF
    raw_data --> CASF
    case_studies --> GEOM1
    raw_data --> GEOM1
    raw_data --> POCK1
    raw_data --> ZINC1
    configs --> TRAIN_DIFF
    configs --> TRAIN_SIZE
    configs --> GEN1

    CASF --> DSET
    GEOM1 --> DSET
    GEOM2 --> DSET
    GEOM3 --> DSET
    GEOM4 --> DSET
    POCK1 --> DSET
    POCK2 --> DSET
    POCK3 --> DSET
    POCK4 --> DSET
    ZINC1 --> DSET
    ZINC2 --> DSET
    ZINC3 --> DSET
    ZINC4 --> DSET
    ZINC5 --> DSET
    ZINC6 --> DSET
    ZINC7 --> DSET

    DSET --> EDM
    UTIL --> EDM
    EDM --> LIGHT
    EGNN --> LIGHT
    LIGHT --> LINKER_WRP
    SIZE_LM --> LINKER_WRP
    LINKER_WRP --> BUILDER
    BUILDER --> SAMPLES
    NOISE --> EDM
    UTILS --> LIGHT

    LINKER_WRP --> TRAIN_DIFF
    LIGHT --> TRAIN_DIFF
    LINKER_WRP --> TRAIN_SIZE
    SIZE_GNN --> TRAIN_SIZE
    TRAIN_DIFF --> CHECKPTS
    TRAIN_DIFF --> LOGS
    TRAIN_SIZE --> CHECKPTS
    TRAIN_SIZE --> LOGS

    CHECKPTS --> GEN1
    GEN1 --> BUILDER
    GEN2 --> BUILDER
    GEN3 --> BUILDER
    SAMPLE --> SAMPLES
    TRAJ --> SAMPLES
    OBABEL1 --> OBABEL2
    OBABEL2 --> SAMPLES

    SAMPLES --> METRICS
    RESOURCES --> METRICS

    %% External deps usage
    PL --> TRAIN_DIFF
    PL --> TRAIN_SIZE
    PL --> GEN1
    PL --> GEN2
    PL --> GEN3
    RD --> CASF
    RD --> GEOM1
    RD --> POCK3
    OB --> OBABEL1
    OB --> OBABEL2

    %% Click Events
    click case_studies "https://github.com/igashov/difflinker/tree/main/case_studies/"
    click raw_data "https://github.com/igashov/difflinker/tree/main/data/"
    click configs "https://github.com/igashov/difflinker/tree/main/configs/"
    click CASF "https://github.com/igashov/difflinker/blob/main/data/casf/prepare.py"
    click GEOM1 "https://github.com/igashov/difflinker/blob/main/data/geom/generate_geom_conformers.py"
    click GEOM2 "https://github.com/igashov/difflinker/blob/main/data/geom/generate_geom_multifrag.py"
    click GEOM3 "https://github.com/igashov/difflinker/blob/main/data/geom/prepare_geom_dataset.py"
    click GEOM4 "https://github.com/igashov/difflinker/blob/main/data/geom/train_test_split.py"
    click POCK1 "https://github.com/igashov/difflinker/blob/main/data/pocket/clean_and_split.py"
    click POCK2 "https://github.com/igashov/difflinker/blob/main/data/pocket/filter_and_train_test_split.py"
    click POCK3 "https://github.com/igashov/difflinker/blob/main/data/pocket/generate_fragmentation_and_conformers.py"
    click POCK4 "https://github.com/igashov/difflinker/blob/main/data/pocket/prepare_dataset.py"
    click ZINC1 "https://github.com/igashov/difflinker/blob/main/data/zinc/create_unique_smiles.py"
    click ZINC2 "https://github.com/igashov/difflinker/blob/main/data/zinc/filter_and_merge.py"
    click ZINC3 "https://github.com/igashov/difflinker/blob/main/data/zinc/prepare_dataset.py"
    click ZINC4 "https://github.com/igashov/difflinker/blob/main/data/zinc/prepare_dataset_parallel.py"
    click ZINC5 "https://github.com/igashov/difflinker/blob/main/data/zinc/prepare_dataset_sequential.py"
    click ZINC6 "https://github.com/igashov/difflinker/blob/main/data/zinc/prepare_val_test.py"
    click ZINC7 "https://github.com/igashov/difflinker/blob/main/data/zinc/rdkit_conf_parallel.py"
    click DSET "https://github.com/igashov/difflinker/blob/main/src/datasets.py"
    click UTIL "https://github.com/igashov/difflinker/tree/main/src/delinker_utils/"
    click EDM "https://github.com/igashov/difflinker/blob/main/src/edm.py"
    click EGNN "https://github.com/igashov/difflinker/blob/main/src/egnn.py"
    click LIGHT "https://github.com/igashov/difflinker/blob/main/src/lightning.py"
    click SIZE_LM "https://github.com/igashov/difflinker/blob/main/src/linker_size_lightning.py"
    click LINKER_WRP "https://github.com/igashov/difflinker/blob/main/src/delinker.py"
    click SIZE_GNN "https://github.com/igashov/difflinker/blob/main/src/linker_size.py"
    click BUILDER "https://github.com/igashov/difflinker/blob/main/src/molecule_builder.py"
    click NOISE "https://github.com/igashov/difflinker/blob/main/src/noise.py"
    click UTILS "https://github.com/igashov/difflinker/blob/main/src/utils.py"
    click TRAIN_DIFF "https://github.com/igashov/difflinker/blob/main/train_difflinker.py"
    click TRAIN_SIZE "https://github.com/igashov/difflinker/blob/main/train_size_gnn.py"
    click ENV "https://github.com/igashov/difflinker/blob/main/environment.yml"
    click GEN1 "https://github.com/igashov/difflinker/blob/main/generate.py"
    click GEN2 "https://github.com/igashov/difflinker/blob/main/generate_with_pocket.py"
    click GEN3 "https://github.com/igashov/difflinker/blob/main/generate_with_protein.py"
    click SAMPLE "https://github.com/igashov/difflinker/blob/main/sample.py"
    click TRAJ "https://github.com/igashov/difflinker/blob/main/sample_trajectories.py"
    click OBABEL1 "https://github.com/igashov/difflinker/blob/main/run_obabel.py"
    click OBABEL2 "https://github.com/igashov/difflinker/blob/main/reformat_data_obabel.py"
    click METRICS "https://github.com/igashov/difflinker/blob/main/compute_metrics.py"
    click RESOURCES "https://github.com/igashov/difflinker/tree/main/resources/"

    %% Styles
    classDef datastore fill:#BBDEFB,stroke:#0D47A1,stroke-width:1px
    classDef script fill:#C8E6C9,stroke:#1B5E20,stroke-width:1px
    classDef module fill:#FFF9C4,stroke:#F57F17,stroke-width:1px
    classDef external fill:#EEEEEE,stroke:#424242,stroke-width:1px,stroke-dasharray: 2 2
```
