# limuloo/pydiff architecture

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

- Interactive diagram: https://gitdiagram.com/limuloo/pydiff
- Repository: https://github.com/limuloo/pydiff

## Overview

##### Project Type and Purpose
- This is a research‐oriented machine‐learning framework for “low‐light image enhancement” using Pyramid Diffusion Models (PyDiff).
- It builds on a foundational image‐restoration library (“BasicSR‐light”) and adds a diffusion‐based enhancement pipeline.

##### High-Level File-Structure Analysis
Top-level directories:
- BasicSR-light/ – core image‐restoration library
– archs/: network building blocks (EDSR, RRDB, StyleGAN2, SwinIR, etc.)
– data/: dataset definitions, samplers, degradations, transforms
– losses/, metrics/: loss functions & evaluation metrics (PSNR, SSIM, FID, LPIPS…)
– models/: base and task‐specific model classes
– ops/: custom CUDA/C++ operations (deformable conv, fused activations, upfirdn2d)
– scripts/: data‐prep, model conversion, metric calculators, training/inference wrappers
– train.py, test.py: entry points for training and evaluation
- PyDiff/ – new diffusion model layers & orchestration
– archs/: diffusion U‐Net, Pyramid diffusion architectures
– data/: LOL dataset loader
– models/: PyDiffModel class wrapping diffusion process
– train.py: distributed training launcher
– options/: config YAMLs for train/infer (v1, v2, v3, infer)
- dataset/, pretrained_models/: placeholders for input data and weights
- images/: figures (e.g., framework.png)

##### Key Points from README
- Two workflows: training (single/multi‐GPU distributed) and inference.
- Relies on two pipelined modules: BasicSR-light for infrastructure + PyDiff for diffusion.

##### Main Components
a. Configuration layer
- YAML files under BasicSR-light/options and PyDiff/options
- Hyperparameters, dataset paths, model settings
b. Data layer
- Raw “LOLdataset” folder → data‐preparation scripts (BasicSR-light/scripts/data_preparation + any custom PyDiff scripts)
- Data loader modules (BasicSR-light/basicsr/data & PyDiff/pydiff/data) apply samplers & transforms
c. Core library (BasicSR-light)
- Neural‐network primitives (archs/) + model wrappers (models/)
- Loss functions (losses/) & metrics (metrics/)
- Custom ops loaded as Python extensions (ops/)
d. Diffusion module (PyDiff)
- PyDiffModel orchestrates multi‐scale diffusion steps using U-Net variants (pydiff/archs/)
- Schedules and noise‐removal routines
e. Training pipeline
- pydiff/train.py (torch.distributed) → GPU cluster
- Interacts with BasicSR’s optimizer & scheduler utilities
- Checkpoints saved to pretrained_models/
f. Inference pipeline
- BasicSR-light/inference/*.py and pydiff/train.py -opt options/infer.yaml
- Generates enhanced images → evaluation metrics / visual outputs
g. Evaluation & Metrics
- Batch metric calculators in BasicSR-light/scripts/metrics
- Logging utilities record PSNR, SSIM, FID, LPIPS

##### Relationships & Data-Flow
- From Checkpoint + Config → Inference Script → Enhanced Output → Metric Calculator → Log/Report
- External dependencies: PyTorch/CUDA toolkits, distributed‐launcher, file‐system mounts for dataset & weights

##### Architectural Patterns & Design Principles
- Modular layering: separation of general restoration tools (BasicSR) vs. research innovation (PyDiff)
- Extension pattern: custom CUDA ops wrapped as Python modules
- Pipeline pattern: clearly delineated data‐prep → data‐load → model → training/inference
- Configurable workflow via YAML: supports reproducibility & experiment management

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Configuration Layer
    subgraph "Configuration Layer"
        direction TB
        Config_BSR["BasicSR-light YAML configs"]:::infra
        Config_PyDiff["PyDiff YAML configs"]:::research
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DataPrep_BSR["BasicSR-light data prep scripts"]:::infra
        DataLoader_BSR["BasicSR-light data loaders/transforms"]:::infra
        DataLoader_PyDiff["PyDiff LOL dataset loader"]:::research
        DatasetMount["Dataset mount point"]:::external
    end

    %% Core Library
    subgraph "Core Library (BasicSR-light)"
        direction TB
        Primitives["Network primitives (archs/)"]:::infra
        Models_BSR["Base & task-specific models"]:::infra
        Losses["Loss functions"]:::infra
        Metrics_Core["Evaluation metrics"]:::infra
        Ops["Custom CUDA/C++ ops"]:::infra
    end

    %% Diffusion Module
    subgraph "Diffusion Module (PyDiff)"
        direction TB
        Arch_ddpm["ddpm_arch.py"]:::research
        Arch_gc["gc_arch.py"]:::research
        Arch_sr3["sr3unet_arch.py"]:::research
        PyDiffModel["PyDiffModel orchestration"]:::research
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        direction TB
        PyDiff_Train["PyDiff distributed training launcher"]:::research
        BSR_Train["BasicSR-light training entrypoint"]:::infra
        GPUCluster["GPU cluster"]:::external
        CheckpointMount["Checkpoint weights directory"]:::external
    end

    %% Inference Pipeline
    subgraph "Inference Pipeline"
        direction TB
        BSR_Infer["BasicSR-light inference scripts"]:::infra
        PyDiff_InferCfg["PyDiff inference config usage"]:::research
        EnhancedOutput["Enhanced images output"]:::external
    end

    %% Evaluation & Metrics
    subgraph "Evaluation & Metrics"
        direction TB
        MetricScripts["Batch metric calculators (scripts)"]:::infra
        Metrics_CoreImpl["Core metric implementations"]:::infra
        LogReport["Log/Report"]:::external
    end

    %% Data & Control Flow
    Config_BSR -->|provides configs| DataPrep_BSR
    Config_PyDiff -->|provides configs| DataLoader_PyDiff
    DataPrep_BSR -->|prepares data| DataLoader_BSR
    DatasetMount -->|raw data| DataPrep_BSR
    DataLoader_BSR -->|loads data| Primitives
    DataLoader_PyDiff -->|loads data| Primitives
    Primitives -->|builds model| Models_BSR
    Models_BSR -->|model instantiation| PyDiffModel
    Arch_ddpm --> PyDiffModel
    Arch_gc --> PyDiffModel
    Arch_sr3 --> PyDiffModel

    PyDiffModel -->|start training| PyDiff_Train
    BSR_Train -->|uses optimizer/scheduler| PyDiff_Train
    PyDiff_Train --> GPUCluster
    PyDiff_Train --> CheckpointMount

    CheckpointMount -->|load weights| BSR_Infer
    PyDiff_InferCfg -->|configures| BSR_Infer
    BSR_Infer --> EnhancedOutput
    EnhancedOutput --> MetricScripts
    EnhancedOutput --> Metrics_CoreImpl
    MetricScripts --> LogReport
    Metrics_CoreImpl --> LogReport

    %% Click Events
    click Config_BSR "https://github.com/limuloo/pydiff/tree/main/BasicSR-light/options/"
    click Config_PyDiff "https://github.com/limuloo/pydiff/blob/main/PyDiff/options/infer.yaml"
    click Config_PyDiff "https://github.com/limuloo/pydiff/blob/main/PyDiff/options/train_v1.yaml"
    click Config_PyDiff "https://github.com/limuloo/pydiff/blob/main/PyDiff/options/train_v2.yaml"
    click Config_PyDiff "https://github.com/limuloo/pydiff/blob/main/PyDiff/options/train_v3.yaml"
    click DataPrep_BSR "https://github.com/limuloo/pydiff/tree/main/BasicSR-light/scripts/data_preparation/"
    click DataLoader_BSR "https://github.com/limuloo/pydiff/tree/main/BasicSR-light/basicsr/data/"
    click DataLoader_PyDiff "https://github.com/limuloo/pydiff/blob/main/PyDiff/pydiff/data/lol_dataset.py"
    click Primitives "https://github.com/limuloo/pydiff/tree/main/BasicSR-light/basicsr/archs/"
    click Models_BSR "https://github.com/limuloo/pydiff/tree/main/BasicSR-light/basicsr/models/"
    click Losses "https://github.com/limuloo/pydiff/tree/main/BasicSR-light/basicsr/losses/"
    click Metrics_Core "https://github.com/limuloo/pydiff/tree/main/BasicSR-light/basicsr/metrics/"
    click Ops "https://github.com/limuloo/pydiff/tree/main/BasicSR-light/basicsr/ops/"
    click Arch_ddpm "https://github.com/limuloo/pydiff/blob/main/PyDiff/pydiff/archs/ddpm_arch.py"
    click Arch_gc "https://github.com/limuloo/pydiff/blob/main/PyDiff/pydiff/archs/gc_arch.py"
    click Arch_sr3 "https://github.com/limuloo/pydiff/blob/main/PyDiff/pydiff/archs/sr3unet_arch.py"
    click PyDiffModel "https://github.com/limuloo/pydiff/blob/main/PyDiff/pydiff/models/pydiff_model.py"
    click PyDiff_Train "https://github.com/limuloo/pydiff/blob/main/PyDiff/pydiff/train.py"
    click BSR_Train "https://github.com/limuloo/pydiff/blob/main/BasicSR-light/basicsr/train.py"
    click BSR_Infer "https://github.com/limuloo/pydiff/blob/main/BasicSR-light/inference/inference_*.py"
    click MetricScripts "https://github.com/limuloo/pydiff/tree/main/BasicSR-light/scripts/metrics/"
    click Metrics_CoreImpl "https://github.com/limuloo/pydiff/tree/main/BasicSR-light/basicsr/metrics/"

    %% Styles
    classDef infra fill:#D0E6FF,stroke:#4B8BBE,color:#000
    classDef research fill:#D0FFD6,stroke:#3C8F3C,color:#000
    classDef external fill:#FFE2B3,stroke:#FF8C00,color:#000
```
