# marieoestreich/drugdiff architecture

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

- Interactive diagram: https://gitdiagram.com/marieoestreich/drugdiff
- Repository: https://github.com/marieoestreich/drugdiff

## Overview

##### Project type and purpose
- DrugDiff is a research‑oriented machine‑learning pipeline for de novo molecular generation. It implements a latent diffusion model (DDPM) augmented with predictor‑based guidance to steer generation toward desired molecular properties.

##### File structure
- Top level:
- data/ – raw and preprocessed datasets (ZINC‑250k, GuacaMol) and symbol/mapping pickles.
- src/ – core library code:
· src/models/ – model definitions (VAE, DDPM variants, predictor guidance).
· src/utils/ – helper functions (SMILES scoring, fingerprinting, I/O).
- scripts/ – CLI entry points for training the affinity predictor and for molecule generation under three modes (unconditional, single‑property, multi‑property).
- notebooks/ – Jupyter notebooks demonstrating evaluation workflows for each generation mode.
- README.md – project overview, usage instructions, architectural figure reference.

##### README for additional insights
- Confirms the three generation modes (unconditional, single‑property, multi‑property).
- Instructs where to place pretrained checkpoints (/model/).

##### Final recommendations
- Keep the layout left‑to‑right: data on the left, training in the middle, inference & evaluation on the right.
- Don’t omit any of the three generation modes—each is a distinct flow that uses the same core diffusion engine with different predictor interactions.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Sources
    subgraph "Data Sources"
        DZINC["ZINC-250k Dataset"]:::datastore
        DGUAC["GuacaMol Dataset"]:::datastore
    end

    %% Data Processing & Utilities
    subgraph "Data Processing & Utilities"
        UTIL1["src/utils/util.py"]:::code
        UTIL2["src/utils/diff_utils.py"]:::code
        UTIL3["src/utils/sascorer.py"]:::code
        UTIL4["src/utils/fpscores.pkl.gz"]:::datastore
        PREP["Preprocessed Pickles"]:::datastore
    end

    %% Predictor Module
    subgraph "Predictor Module"
        PRED_TRAIN["scripts/train_predictor_target_affinity.py"]:::compute
        EVAL_LOGIC["src/models/components/evaluation.py"]:::code
        PRED_CHK["Predictor Checkpoint"]:::datastore
    end

    %% Latent Diffusion Model
    subgraph "Latent Diffusion Model"
        VAE["src/models/components/vae.py"]:::code
        DENSE_DDPM["src/models/components/denseddpm.py"]:::code
        CORE_DDPM["src/models/ddpm.py"]:::code
        GUACA_DDPM["src/models/ddpm_guacamol.py"]:::code
        DIFF_CHK["Diffusion Checkpoint"]:::datastore
    end

    %% Generation Engines
    subgraph "Generation Engines"
        GEN_UN["scripts/generate_without_guidance.py"]:::compute
        GEN_SINGLE["scripts/generate_with_single_property_guidance.py"]:::compute
        GEN_MULTI["scripts/generate_with_multi_property_guidance.py"]:::compute
        GEN_SMILES["Generated SMILES"]:::datastore
    end

    %% Evaluation & Visualization
    subgraph "Evaluation & Visualization"
        EVAL_NO["notebooks/evaluation_without_guidance.ipynb"]:::compute
        EVAL_SINGLE["notebooks/evaluation_with_single_property_guidance.ipynb"]:::compute
        EVAL_MULTI["notebooks/evaluation_with_multi_property_guidance.ipynb"]:::compute
        EVAL_PRED["notebooks/eval_predictor_target_affinity.ipynb"]:::compute
    end

    %% Data Flow
    DZINC -->|"raw SMILES"| UTIL1
    DGUAC -->|"raw SMILES"| UTIL1
    UTIL1 -->|"tokens,fingerprints"| UTIL2
    UTIL2 -->|"scored SMILES"| UTIL3
    UTIL3 -->|"score data"| PREP
    PREP -->|"training data"| PRED_TRAIN
    PREP -->|"training data"| VAE
    PREP -->|"training data"| CORE_DDPM
    PREP -->|"training data"| GUACA_DDPM
    PRED_TRAIN -->|"predictor weights"| PRED_CHK
    VAE -->|"feature maps"| DIFF_CHK
    CORE_DDPM -->|"model weights"| DIFF_CHK
    GUACA_DDPM -->|"model weights"| DIFF_CHK

    %% Generation Flows
    DIFF_CHK -->|"diffusion model"| GEN_UN
    DIFF_CHK -->|"diffusion model"| GEN_SINGLE
    DIFF_CHK -->|"diffusion model"| GEN_MULTI
    PRED_CHK -->|"guidance scores"| GEN_SINGLE
    PRED_CHK -->|"guidance scores"| GEN_MULTI
    GEN_UN -->|"generated SMILES"| GEN_SMILES
    GEN_SINGLE -->|"generated SMILES"| GEN_SMILES
    GEN_MULTI -->|"generated SMILES"| GEN_SMILES

    %% Evaluation Flows
    GEN_SMILES -->|"SMILES"| EVAL_NO
    GEN_SMILES -->|"SMILES"| EVAL_SINGLE
    GEN_SMILES -->|"SMILES"| EVAL_MULTI
    PRED_CHK -->|"predictor weights"| EVAL_PRED

    %% Click Events
    click DZINC "https://github.com/marieoestreich/drugdiff/tree/main/data/zinc250k/"
    click DGUAC "https://github.com/marieoestreich/drugdiff/tree/main/data/guacamol/"
    click UTIL1 "https://github.com/marieoestreich/drugdiff/blob/main/src/utils/util.py"
    click UTIL2 "https://github.com/marieoestreich/drugdiff/blob/main/src/utils/diff_utils.py"
    click UTIL3 "https://github.com/marieoestreich/drugdiff/blob/main/src/utils/sascorer.py"
    click UTIL4 "https://github.com/marieoestreich/drugdiff/blob/main/src/utils/fpscores.pkl.gz"
    click PRED_TRAIN "https://github.com/marieoestreich/drugdiff/blob/main/scripts/train_predictor_target_affinity.py"
    click EVAL_LOGIC "https://github.com/marieoestreich/drugdiff/blob/main/src/models/components/evaluation.py"
    click VAE "https://github.com/marieoestreich/drugdiff/blob/main/src/models/components/vae.py"
    click DENSE_DDPM "https://github.com/marieoestreich/drugdiff/blob/main/src/models/components/denseddpm.py"
    click CORE_DDPM "https://github.com/marieoestreich/drugdiff/blob/main/src/models/ddpm.py"
    click GUACA_DDPM "https://github.com/marieoestreich/drugdiff/blob/main/src/models/ddpm_guacamol.py"
    click GEN_UN "https://github.com/marieoestreich/drugdiff/blob/main/scripts/generate_without_guidance.py"
    click GEN_SINGLE "https://github.com/marieoestreich/drugdiff/blob/main/scripts/generate_with_single_property_guidance.py"
    click GEN_MULTI "https://github.com/marieoestreich/drugdiff/blob/main/scripts/generate_with_multi_property_guidance.py"
    click EVAL_NO "https://github.com/marieoestreich/drugdiff/blob/main/notebooks/evaluation_without_guidance.ipynb"
    click EVAL_SINGLE "https://github.com/marieoestreich/drugdiff/blob/main/notebooks/evaluation_with_single_property_guidance.ipynb"
    click EVAL_MULTI "https://github.com/marieoestreich/drugdiff/blob/main/notebooks/evaluation_with_multi_property_guidance.ipynb"
    click EVAL_PRED "https://github.com/marieoestreich/drugdiff/blob/main/notebooks/eval_predictor_target_affinity.ipynb"

    %% Styles
    classDef code fill:#D0E6FF,stroke:#000;
    classDef datastore fill:#D4F4DD,stroke:#000;
    classDef compute fill:#FFE2A3,stroke:#000;
    classDef external fill:#E0E0E0,stroke:#000;
```
