# nicola-decao/molgan architecture

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

- Interactive diagram: https://gitdiagram.com/nicola-decao/molgan
- Repository: https://github.com/nicola-decao/molgan

## Overview

##### Main Components
a. External Dependencies (outside your codebase)
- TensorFlow, RDKit, NumPy, scikit-learn (defined in environment.yml and README).
b. Data Layer
- data/download_dataset.sh
- utils/sparse_molecular_dataset.py (converts raw files into graph tensors).
c. Model Layer
- models/gan.py (Generator & Discriminator classes)
- models/vae.py (Encoder & Decoder classes)
d. Optimizer/Training Layer
- optimizers/gan.py (GAN-specific loss, gradient updates, WGAN variant, RL reward)
- optimizers/vae.py (VAE-specific ELBO loss)
- utils/trainer.py (high-level training loop orchestrator)
e. Utility Layer
- utils/layers.py (graph convolutional layers, MLPs)
- utils/molecular_metrics.py (validity, uniqueness, novelty calculators)
- utils/progress_bar.py (CLI progress reporting)
- utils/utils.py (misc helpers)
f. Entry Point
- example.py (demonstrates how to wire Data → Model → Optimizer → Trainer → Metrics)

##### Relationships & Data Flow
- The user runs example.py, which:
1. Executes download_dataset.sh (optional)
2. Invokes sparse_molecular_dataset to load and preprocess graphs
3. Instantiates a MolGAN model (GAN or VAE) from models/
4. Instantiates the corresponding Optimizer from optimizers/
5. Passes model, optimizer, and dataset into utils/trainer.Trainer
6. Trainer uses utils/layers to build TF graph, runs training loop, calls utils/molecular_metrics after each epoch
7. Outputs trained model checkpoints and metric logs to disk

##### Architectural Patterns & Principles
- Layered architecture: clear separation of concerns (Data → Model → Optimizer → Trainer → Utilities).
- Dependency Injection: example.py selects implementations and injects into Trainer.
- Modular extensibility: adding a new model or optimizer is as simple as implementing the same abstract interface.
- Functional data pipeline: raw files → sparse graphs → TensorFlow tensors.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Dependencies"
        EX["TensorFlow, RDKit, NumPy, scikit-learn"]:::external
    end

    EP["example.py: Entry Point"]:::code

    subgraph "Data Layer"
        DScript["data/download_dataset.sh: Download Dataset"]:::code
        DProc["utils/sparse_molecular_dataset.py: Preprocessing"]:::code
    end

    subgraph "Model Layer"
        ML_GAN["models/gan.py: Generator & Discriminator"]:::code
        ML_VAE["models/vae.py: Encoder & Decoder"]:::code
    end

    subgraph "Optimizer Layer"
        OPT_GAN["optimizers/gan.py: GAN Loss & Updates"]:::code
        OPT_VAE["optimizers/vae.py: VAE ELBO Loss"]:::code
    end

    TRAINER["utils/trainer.py: Training Orchestrator"]:::code

    subgraph "Utility Layer"
        UTIL_LAYERS["utils/layers.py: Graph Conv & MLP"]:::code
        UTIL_METRICS["utils/molecular_metrics.py: Metrics"]:::code
        UTIL_PROGRESS["utils/progress_bar.py: Progress Reporting"]:::code
        UTIL_UTILS["utils/utils.py: Helpers"]:::code
    end

    OUTPUTS["Model Checkpoints & Logs"]:::outputs

    EP -->|"runs"| DScript
    EP -->|"invokes"| DProc
    DProc -->|"GraphDataset"| ML_GAN
    DProc -->|"GraphDataset"| ML_VAE
    ML_GAN -->|"model params"| OPT_GAN
    ML_VAE -->|"model params"| OPT_VAE
    OPT_GAN --> TRAINER
    OPT_VAE --> TRAINER
    TRAINER -->|"builds graph"| UTIL_LAYERS
    TRAINER -->|"calls metrics"| UTIL_METRICS
    TRAINER -->|"updates progress"| UTIL_PROGRESS
    TRAINER --> UTIL_UTILS
    TRAINER -->|"outputs"| OUTPUTS
    UTIL_METRICS --> EX

    click EP "https://github.com/nicola-decao/molgan/blob/master/example.py"
    click DScript "https://github.com/nicola-decao/molgan/blob/master/data/download_dataset.sh"
    click DProc "https://github.com/nicola-decao/molgan/blob/master/utils/sparse_molecular_dataset.py"
    click ML_GAN "https://github.com/nicola-decao/molgan/blob/master/models/gan.py"
    click ML_VAE "https://github.com/nicola-decao/molgan/blob/master/models/vae.py"
    click OPT_GAN "https://github.com/nicola-decao/molgan/blob/master/optimizers/gan.py"
    click OPT_VAE "https://github.com/nicola-decao/molgan/blob/master/optimizers/vae.py"
    click TRAINER "https://github.com/nicola-decao/molgan/blob/master/utils/trainer.py"
    click UTIL_LAYERS "https://github.com/nicola-decao/molgan/blob/master/utils/layers.py"
    click UTIL_METRICS "https://github.com/nicola-decao/molgan/blob/master/utils/molecular_metrics.py"
    click UTIL_PROGRESS "https://github.com/nicola-decao/molgan/blob/master/utils/progress_bar.py"
    click UTIL_UTILS "https://github.com/nicola-decao/molgan/blob/master/utils/utils.py"

    classDef code fill:#E8F1F2,stroke:#333,stroke-width:1px
    classDef external fill:#FDF6E3,stroke:#333,stroke-width:1px
    classDef outputs fill:#E8FFE1,stroke:#333,stroke-width:1px
```
