# jmtomczak/intro_dgm architecture

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

- Interactive diagram: https://gitdiagram.com/jmtomczak/intro_dgm
- Repository: https://github.com/jmtomczak/intro_dgm

## Overview

##### Project type and purpose
- This is not a traditional full-stack application, but an **educational example suite** for deep generative modeling supporting the book “Deep Generative Modeling.”
- Each top-level folder (e.g., `mog`, `arms`, `flows`, `vaes`, etc.) contains a self-contained Jupyter notebook that implements and demonstrates a specific class of generative models.

##### File structure
- Top-level directories:
- `mog` – Mixture of Gaussians examples
- `arms` – Autoregressive Models (with `molecules/` data assets)
- `flows` – Flow-based models (RealNVP, IDF)
- `vaes` – Variational Autoencoders (standard, hierarchical, priors)
- `ddgms` – Diffusion-based models
- `sbgms` – Score-based / flow-matching models
- `hybrid_modeling`, `ebms`, `gans`, `neural_compression`, `llms` – other model families
- Within each directory: a single Jupyter notebook `.ipynb`.
- `arms/molecules/` contains `.npy` files used as toy datasets.
- Root `README.md` lists dependencies & describes each example.

##### Extract key insights from the README
- **Dependencies**: PyTorch, NumPy, Matplotlib, scikit-learn, pytorch-model-summary, Jupyter
- **Purpose**: concisely introduce each model type in an easy‐to‐run format
- No monolithic codebase—rather, many small “modules” (notebooks) that each follow a similar pattern.

a. Main components
- **External Libraries & Tools** (PyTorch, NumPy, scikit-learn, Matplotlib, Jupyter)
- **Core Model Families** (MOG, ARM, Flow, VAE, DDGM, SBGM, EBM, GAN, Hybrid, Neural Compression, LLM)
- **Data Assets** (e.g., `.npy` files under `arms/molecules`)
- **Jupyter Interface** (the notebooks themselves)
- **Visualization & Reporting** (plots generated by Matplotlib)
b. Relationships & interactions
- Notebooks import **External Libraries** → load **Data Assets** → define & train **Models** → produce **Plots/Results**
- Each model-family notebook is independent but follows the same “pipeline” pattern.
c. Architectural patterns & design principles
- **Modular separation**: each folder = isolated example
- **Pipeline flow**: Data → Model definition → Training loop → Evaluation → Visualization
- **Reproducibility**: versioned dependencies, simple toy datasets
d. Key technologies/frameworks
- PyTorch for model definition & training
- NumPy for data handling
- Jupyter as the primary execution environment
- Matplotlib & scikit-learn for visualization & metrics

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Libraries & Tools"
        README["README.md"]:::external
        PT["PyTorch"]:::external
        NP["NumPy"]:::external
        SK["scikit-learn"]:::external
        MPL["Matplotlib"]:::external
        JUP["Jupyter"]:::external
    end

    subgraph "Data Assets"
        A1["alphabet.npy"]:::data
        A2["alphabet_dict.npy"]:::data
        A3["alphabet_dict_reverse.npy"]:::data
        A4["tox21_smiles_tokenized.npy"]:::data
    end

    subgraph "Educational Example Suite"
        subgraph "Mixture of Gaussians (MOG)"
            MOG["mog_example.ipynb"]:::pipeline
        end
        subgraph "Autoregressive Models (ARM)"
            ARM1["arm_example.ipynb"]:::pipeline
            ARM2["transformer_example.ipynb"]:::pipeline
        end
        subgraph "Flow-based Models"
            F1["realnvp_example.ipynb"]:::pipeline
            F2["idf_example.ipynb"]:::pipeline
        end
        subgraph "Variational Autoencoders (VAE)"
            V1["vae_example.ipynb"]:::pipeline
            V2["vae_hierarchical_example.ipynb"]:::pipeline
            V3["vae_priors_example.ipynb"]:::pipeline
        end
        subgraph "Diffusion-based Models (DDGM)"
            DDM["ddgm_example.ipynb"]:::pipeline
        end
        subgraph "Score-based & Flow-Matching Models (SBGM)"
            S1["fm_example.ipynb"]:::pipeline
            S2["sbgm_example.ipynb"]:::pipeline
            S3["sm_example.ipynb"]:::pipeline
        end
        subgraph "Energy-Based Models (EBM)"
            EBM["ebm_example.ipynb"]:::pipeline
        end
        subgraph "Generative Adversarial Networks (GAN)"
            GAN["gans_example.ipynb"]:::pipeline
        end
        subgraph "Hybrid Modeling"
            HYB["hybrid_example.ipynb"]:::pipeline
        end
        subgraph "Neural Compression"
            NC["neural_compression_example.ipynb"]:::pipeline
        end
        subgraph "Large Language Models (LLM)"
            LLM["teenygpt_example.ipynb"]:::pipeline
        end
    end

    OUTPUT["Plots/Results"]:::output

    %% Connections from README to libraries
    README --> PT
    README --> NP
    README --> SK
    README --> MPL
    README --> JUP

    %% MOG pipeline
    PT -->|imports| MOG
    NP -->|imports| MOG
    MPL -->|visualizes| MOG
    JUP -->|executes| MOG
    MOG -->|produces| OUTPUT

    %% ARM pipelines
    PT -->|imports| ARM1
    NP -->|imports| ARM1
    JUP -->|executes| ARM1
    PT -->|imports| ARM2
    NP -->|imports| ARM2
    JUP -->|executes| ARM2
    A1 -->|loads| ARM1
    A2 -->|loads| ARM1
    A3 -->|loads| ARM1
    A4 -->|loads| ARM1
    ARM1 -->|produces| OUTPUT
    ARM2 -->|produces| OUTPUT

    %% Flow pipelines
    PT -->|imports| F1
    NP -->|imports| F1
    JUP -->|executes| F1
    PT -->|imports| F2
    NP -->|imports| F2
    JUP -->|executes| F2
    F1 -->|produces| OUTPUT
    F2 -->|produces| OUTPUT

    %% VAE pipelines
    PT -->|imports| V1
    NP -->|imports| V1
    JUP -->|executes| V1
    PT -->|imports| V2
    NP -->|imports| V2
    JUP -->|executes| V2
    PT -->|imports| V3
    NP -->|imports| V3
    JUP -->|executes| V3
    V1 -->|produces| OUTPUT
    V2 -->|produces| OUTPUT
    V3 -->|produces| OUTPUT

    %% DDGM pipeline
    PT -->|imports| DDM
    NP -->|imports| DDM
    JUP -->|executes| DDM
    DDM -->|produces| OUTPUT

    %% SBGM pipelines
    PT -->|imports| S1
    NP -->|imports| S1
    JUP -->|executes| S1
    PT -->|imports| S2
    NP -->|imports| S2
    JUP -->|executes| S2
    PT -->|imports| S3
    NP -->|imports| S3
    JUP -->|executes| S3
    S1 -->|produces| OUTPUT
    S2 -->|produces| OUTPUT
    S3 -->|produces| OUTPUT

    %% EBM pipeline
    PT -->|imports| EBM
    NP -->|imports| EBM
    JUP -->|executes| EBM
    EBM -->|produces| OUTPUT

    %% GAN pipeline
    PT -->|imports| GAN
    NP -->|imports| GAN
    JUP -->|executes| GAN
    GAN -->|produces| OUTPUT

    %% Hybrid pipeline
    PT -->|imports| HYB
    NP -->|imports| HYB
    JUP -->|executes| HYB
    HYB -->|produces| OUTPUT

    %% Neural Compression pipeline
    PT -->|imports| NC
    NP -->|imports| NC
    JUP -->|executes| NC
    NC -->|produces| OUTPUT

    %% LLM pipeline
    PT -->|imports| LLM
    NP -->|imports| LLM
    JUP -->|executes| LLM
    LLM -->|produces| OUTPUT

    %% Click Events
    click README "https://github.com/jmtomczak/intro_dgm/blob/main/README.md"
    click MOG "https://github.com/jmtomczak/intro_dgm/blob/main/mog/mog_example.ipynb"
    click ARM1 "https://github.com/jmtomczak/intro_dgm/blob/main/arms/arm_example.ipynb"
    click ARM2 "https://github.com/jmtomczak/intro_dgm/blob/main/arms/transformer_example.ipynb"
    click A1 "https://github.com/jmtomczak/intro_dgm/blob/main/arms/molecules/alphabet.npy"
    click A2 "https://github.com/jmtomczak/intro_dgm/blob/main/arms/molecules/alphabet_dict.npy"
    click A3 "https://github.com/jmtomczak/intro_dgm/blob/main/arms/molecules/alphabet_dict_reverse.npy"
    click A4 "https://github.com/jmtomczak/intro_dgm/blob/main/arms/molecules/tox21_smiles_tokenized.npy"
    click F1 "https://github.com/jmtomczak/intro_dgm/blob/main/flows/realnvp_example.ipynb"
    click F2 "https://github.com/jmtomczak/intro_dgm/blob/main/flows/idf_example.ipynb"
    click V1 "https://github.com/jmtomczak/intro_dgm/blob/main/vaes/vae_example.ipynb"
    click V2 "https://github.com/jmtomczak/intro_dgm/blob/main/vaes/vae_hierarchical_example.ipynb"
    click V3 "https://github.com/jmtomczak/intro_dgm/blob/main/vaes/vae_priors_example.ipynb"
    click DDM "https://github.com/jmtomczak/intro_dgm/blob/main/ddgms/ddgm_example.ipynb"
    click S1 "https://github.com/jmtomczak/intro_dgm/blob/main/sbgms/fm_example.ipynb"
    click S2 "https://github.com/jmtomczak/intro_dgm/blob/main/sbgms/sbgm_example.ipynb"
    click S3 "https://github.com/jmtomczak/intro_dgm/blob/main/sbgms/sm_example.ipynb"
    click EBM "https://github.com/jmtomczak/intro_dgm/blob/main/ebms/ebm_example.ipynb"
    click GAN "https://github.com/jmtomczak/intro_dgm/blob/main/gans/gans_example.ipynb"
    click HYB "https://github.com/jmtomczak/intro_dgm/blob/main/hybrid_modeling/hybrid_example.ipynb"
    click NC "https://github.com/jmtomczak/intro_dgm/blob/main/neural_compression/neural_compression_example.ipynb"
    click LLM "https://github.com/jmtomczak/intro_dgm/blob/main/llms/teenygpt_example.ipynb"

    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef data fill:#bbf,stroke:#333,stroke-width:1px
    classDef pipeline fill:#bfb,stroke:#333,stroke-width:1px
    classDef output fill:#ffb,stroke:#333,stroke-width:1px
```
