How rsqm/diffusemnist works
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.