# novwaul/sr3 architecture

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

- Interactive diagram: https://gitdiagram.com/novwaul/sr3
- Repository: https://github.com/novwaul/sr3

## Overview

##### Project type and purpose
- This is a research-oriented Python project implementing the SR3 super-resolution diffusion model (4× upsampling) from “Image Super-Resolution via Iterative Refinement” (arXiv:2104.07636).
- It provides data loading, UNet-based diffusion training, sampling routines, and evaluation metrics.

##### File structure
Top-level files:
- main.py  — CLI entrypoint for training or testing
- train.py  — high-level training loop
- diffusion.py — defines forward/backward diffusion processes
- data.py  — dataset loading, augmentation, batching
- metrics.py — IS/FID/PSNR/SSIM computation
- utils.py  — helper functions (logging, checkpoint I/O, config parsing)
- LICENSE, README.md

UNet/
- model.py — definition of the SR3 UNet architecture with attention and group-norm tweaks

##### README for additional insights
- Specifies PyTorch-style hyperparameter settings and CLI flags in main.py
- Describes architectural differences vs. vanilla DDPM (attention at two depths, group-norm groups=8, embedding scale change, gamma sampling)
- Outlines train/test commands and sample/metric evaluation

a. Components:
1. User CLI (main.py)
2. Data Pipeline (data.py)
3. Diffusion Module (diffusion.py)
4. Model Component (UNet/model.py)
5. Training Loop (train.py)
6. Sampling Loop (main.py + diffusion.py + UNet)
7. Metrics & Logging (metrics.py + utils.py)
8. Checkpoint & Config Management (utils.py)

b. Relationships & Data Flow:
- CLI reads config → invokes Training or Testing
- Data Pipeline → produces (LR, HR) batches → feeds Diffusion Module
- Diffusion Module calls UNet at each time step to predict noise or denoised output
- Training Loop updates UNet weights via optimizer & schedules (lr, β schedule)
- Checkpoints saved/loaded via Utils
- Sampling Loop uses learned UNet + reverse diffusion to generate SR images
- Metrics Module computes FID/IS/PSNR/SSIM on outputs → logs via Utils

c. Architectural patterns & principles:
- Modular separation of concerns: data / model / diffusion logic / training / metrics
- Explicit scheduling components (learning rate, beta, gamma)
- Pluggable UNet architecture for easy experimentation

d. Key technologies & frameworks:
- Python 3.x
- PyTorch (tensors, nn.Module, DataLoader, optim)
- NumPy, PIL/OpenCV (data augmentation)
- Logging (TensorBoard or custom via utils)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    CLI["User CLI\n(main.py)"]:::cli

    %% Data Layer
    Data["Data Pipeline\n(data.py)"]:::data

    %% Model & Diffusion Layer
    subgraph "Model & Diffusion"
        UNet["SR3 UNet\n(UNet/model.py)"]:::model
        Diffusion["Diffusion Module\n(diffusion.py)"]:::model
    end

    %% Training Loop
    Trainer["Training Loop\n(train.py)"]:::loop

    %% Sampling Loop
    Sampler["Sampling Loop"]:::loop

    %% Evaluation & Utilities
    Metrics["Metrics & Logging\n(metrics.py + utils.py)"]:::util
    Checkpoint["Checkpoint & Config\n(utils.py)"]:::util

    %% External Dependencies
    PyTorch((PyTorch)):::external
    Disk[(Disk I/O)]:::external

    %% Connections
    CLI -->|"parse config"| Trainer
    CLI -->|"parse config"| Sampler

    Data -->|"(LR, HR) batch"| Diffusion
    Diffusion -->|"noisy image"| UNet
    UNet -->|"noise prediction"| Diffusion
    Diffusion -->|"loss tensor"| Trainer
    Trainer -->|"gradient update"| UNet

    Trainer -->|"save/load"| Checkpoint
    Sampler -->|"save samples"| Disk

    Sampler -->|"start reverse diffusion"| Diffusion
    Diffusion -->|"SR sample"| Sampler
    Sampler -->|"generated samples"| Metrics

    Trainer -->|"training metrics"| Metrics

    Metrics -->|"log outputs"| Checkpoint

    %% External
    Trainer --> PyTorch
    Data --> PyTorch
    UNet --> PyTorch

    %% Click Events
    click CLI "https://github.com/novwaul/sr3/blob/main/main.py"
    click Data "https://github.com/novwaul/sr3/blob/main/data.py"
    click Diffusion "https://github.com/novwaul/sr3/blob/main/diffusion.py"
    click UNet "https://github.com/novwaul/sr3/blob/main/UNet/model.py"
    click Trainer "https://github.com/novwaul/sr3/blob/main/train.py"
    click Metrics "https://github.com/novwaul/sr3/blob/main/metrics.py"
    click Checkpoint "https://github.com/novwaul/sr3/blob/main/utils.py"

    %% Styles
    classDef data fill:#add8e6,stroke:#000,color:#000
    classDef model fill:#98fb98,stroke:#000,color:#000
    classDef loop fill:#ffa500,stroke:#000,color:#000
    classDef util fill:#d3d3d3,stroke:#000,color:#000
    classDef cli fill:#cce5ff,stroke:#000,color:#000
    classDef external fill:#f0f0f0,stroke:#000,color:#000
```
