# rsqm/diffusemnist architecture

> Architecture diagram of the GitHub repository rsqm/diffusemnist, 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/rsqm/diffusemnist
- Repository: https://github.com/rsqm/diffusemnist

## Overview

##### Project Type and Purpose
- This is a machine-learning pipeline project implementing a Denoising Diffusion Probabilistic Model (DDPM) with a U-Net backbone for image generation on the MNIST dataset.
- It provides two parallel workflows: one CUDA-enabled (fast training/inference) and one CUDA-disabled (slower CPU-only training but workable inference).

##### File Structure Analysis
- Top level: two main directories
- CUDA-Enabled-Diffusion-Training&Inference
- CUDA-Disabled-Diffusion-Training&Inference
- Each directory contains:
- train.py (training loop)
- inference.py (generating images from noise)
- main.py (CLI entry point)
- models/ (U-Net implementation, diffusion scheduler, sinusoidal embeddings)
- utils/ (dataset loader, checkpoint manager, display, scheduler helpers, random seed)
- models/data/MNIST/raw (raw MNIST files)
- Root README outlines features, dependencies, and high-level architecture.

##### Key Components
a. Data Ingestion
- Raw MNIST images → Dataset util → DataLoader
b. Diffusion Scheduler
- Defines forward noising and reverse denoising schedules
c. Time Embedding Generator
- Sinusoidal embeddings for each time step
d. U-Net Denoiser
- Encoder/Decoder blocks, residual connections, optional attention
e. Training Loop
- Sample data → add noise via scheduler → model predicts noise → compute loss → optimizer update → checkpoint
f. Checkpoint Manager
- Save/load model weights and optimizer state
g. Inference Loop
- Start from random Gaussian noise → iterative denoising via scheduler & U-Net → output images
h. /Visualization
- Plot intermediate denoising steps and final images
i. Hardware Layer
- CUDA-enabled GPU vs CPU fallback

##### Relationships and Interaction Flows
- DataLoader feeds batches into the Training Loop.
- Training Loop calls Diffusion Scheduler to add noise and to retrieve the corresponding time embeddings.
- U-Net consumes noisy images + time embeddings to predict noise residuals.
- Loss computation updates model through PyTorch optimizer.
- Checkpoint Manager persists model/optimizer state.
- Inference Loop uses the same Scheduler and U-Net in reverse mode starting from pure noise.
- Util renders images at each denoising step.
- All core operations are dispatched to GPU when CUDA is enabled, or CPU otherwise.

##### Architectural Patterns and Design Principles
- Modular separation: distinct packages for models, utilities, data, training, and inference.
- Pipeline pattern: sequential flow (ingest → noise → denoise → update).
- Dependency inversion: high-level training/inference scripts depend on abstracted utils and model APIs.
- Single responsibility: each module (scheduler, dataset, display, checkpoint) has one clear purpose.

##### Relevant Technologies and Frameworks
- Python 3.x, PyTorch for tensor operations and model definition.
- torchvision, numpy, einops for data manipulation.
- tqdm for progress bars, matplotlib for visualization.
- CUDA toolkit integration in the “enabled” variant.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Hardware Layer"
        GPU["CUDA-Enabled-Diffusion-Training&Inference"]:::hardware
        CPU["CUDA-Disabled-Diffusion-Training&Inference"]:::hardware
    end

    subgraph "CUDA Enabled Workflow"
        direction TB
        EDataloader["DataLoader & Dataset"]:::data
        EnTrain["TrainingLoop"]:::workflow
        EScheduler["DiffusionScheduler\n(forward diffusion & reverse denoising)"]:::model
        ETimeEmb["TimeEmbeddingGenerator"]:::model
        EUNet["UNet Denoiser\n(encoder, decoder, residual, attention)"]:::model
        ECheckpoint["CheckpointManager"]:::util
        EnInfer["InferenceLoop"]:::workflow
        EDisplay["Display/Visualization"]:::util
    end

    subgraph "CUDA Disabled Workflow"
        direction TB
        CDataloader["DataLoader & Dataset"]:::data
        CTrain["TrainingLoop"]:::workflow
        CScheduler["DiffusionScheduler\n(forward diffusion & reverse denoising)"]:::model
        CTimeEmb["TimeEmbeddingGenerator"]:::model
        CUNet["UNet Denoiser\n(encoder, decoder, residual, attention)"]:::model
        CCheckpoint["CheckpointManager"]:::util
        CInfer["InferenceLoop"]:::workflow
        CDisplay["Display/Visualization"]:::util
    end

    GPU --> EnTrain
    GPU --> EnInfer
    CPU --> CTrain
    CPU --> CInfer

    EDataloader -->|images| EnTrain
    EnTrain -->|add noise| EScheduler
    EScheduler -->|noisy images| EUNet
    ETimeEmb -->|embeddings| EUNet
    EUNet -->|predicted noise| EnTrain
    EnTrain -->|update & gradients| EUNet
    EnTrain -->|save/load| ECheckpoint
    ECheckpoint -->|load weights| EnInfer

    EnInfer -->|random noise| EScheduler
    EScheduler -->|input| EUNet
    ETimeEmb -->|embeddings| EUNet
    EUNet -->|denoised images| EScheduler
    EScheduler -->|intermediate steps| EDisplay
    EDisplay -->|visuals| EDisplay

    CDataloader -->|images| CTrain
    CTrain -->|add noise| CScheduler
    CScheduler -->|noisy images| CUNet
    CTimeEmb -->|embeddings| CUNet
    CUNet -->|predicted noise| CTrain
    CTrain -->|update & gradients| CUNet
    CTrain -->|save/load| CCheckpoint
    CCheckpoint -->|load weights| CInfer

    CInfer -->|random noise| CScheduler
    CScheduler -->|input| CUNet
    CTimeEmb -->|embeddings| CUNet
    CUNet -->|denoised images| CScheduler
    CScheduler -->|intermediate steps| CDisplay
    CDisplay -->|visuals| CDisplay

    click EDataloader "https://github.com/rsqm/diffusemnist/blob/main/CUDA-Enabled-Diffusion-Training&Inference/utils/dataset.py"
    click EScheduler "https://github.com/rsqm/diffusemnist/blob/main/CUDA-Enabled-Diffusion-Training&Inference/models/diffusion_scheduler.py"
    click ETimeEmb "https://github.com/rsqm/diffusemnist/blob/main/CUDA-Enabled-Diffusion-Training&Inference/models/sinusoidal_embeddings.py"
    click EUNet "https://github.com/rsqm/diffusemnist/blob/main/CUDA-Enabled-Diffusion-Training&Inference/models/unet.py"
    click EnTrain "https://github.com/rsqm/diffusemnist/blob/main/CUDA-Enabled-Diffusion-Training&Inference/train.py"
    click EnInfer "https://github.com/rsqm/diffusemnist/blob/main/CUDA-Enabled-Diffusion-Training&Inference/inference.py"
    click GPU "https://github.com/rsqm/diffusemnist/tree/main/CUDA-Enabled-Diffusion-Training&Inference/"
    click ECheckpoint "https://github.com/rsqm/diffusemnist/blob/main/CUDA-Enabled-Diffusion-Training&Inference/utils/checkpoint.py"
    click EDisplay "https://github.com/rsqm/diffusemnist/blob/main/CUDA-Enabled-Diffusion-Training&Inference/utils/display.py"

    click CDataloader "https://github.com/rsqm/diffusemnist/blob/main/CUDA-Disabled-Diffusion-Training&Inference/utils/dataset.py"
    click CScheduler "https://github.com/rsqm/diffusemnist/blob/main/CUDA-Disabled-Diffusion-Training&Inference/models/diffusion_scheduler.py"
    click CTimeEmb "https://github.com/rsqm/diffusemnist/blob/main/CUDA-Disabled-Diffusion-Training&Inference/models/sinusoidal_embeddings.py"
    click CUNet "https://github.com/rsqm/diffusemnist/blob/main/CUDA-Disabled-Diffusion-Training&Inference/models/unet.py"
    click CTrain "https://github.com/rsqm/diffusemnist/blob/main/CUDA-Disabled-Diffusion-Training&Inference/train.py"
    click CInfer "https://github.com/rsqm/diffusemnist/blob/main/CUDA-Disabled-Diffusion-Training&Inference/inference.py"
    click CPU "https://github.com/rsqm/diffusemnist/tree/main/CUDA-Disabled-Diffusion-Training&Inference/"
    click CCheckpoint "https://github.com/rsqm/diffusemnist/blob/main/CUDA-Disabled-Diffusion-Training&Inference/utils/checkpoint.py"
    click CDisplay "https://github.com/rsqm/diffusemnist/blob/main/CUDA-Disabled-Diffusion-Training&Inference/utils/display.py"

    classDef data fill:#D0E8FF,stroke:#84C1FF
    classDef model fill:#DFFFD6,stroke:#A2E38B
    classDef workflow fill:#FFE8B2,stroke:#FFCF6E
    classDef util fill:#F3DFFD,stroke:#D5A1D9
    classDef hardware fill:#E0E0E0,stroke:#B0B0B0,stroke-dasharray: 5 5
```
