# jerryyann/dpi architecture

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

- Interactive diagram: https://gitdiagram.com/jerryyann/dpi
- Repository: https://github.com/jerryyann/dpi

## Overview

##### Project type and purpose
- This is a research‐style Python codebase implementing a face super‐resolution pipeline based on diffusion models (as presented in the “Diffusion Models Beat GANs on Image Synthesis” paper).
- It provides two main workflows:
a. Training a Conditional Residual Transformer (CRT) via “image_train.py.”
b. Generating (sampling) high‐resolution faces via “sr_sample.py.”

##### File structure
- Top‐level “scripts/” folder holds the two entry‐point scripts:
- image_train.py – launches distributed training
- sr_sample.py – launches distributed sampling
- The “guided_diffusion/” package contains core modules:
- datasets.py, image_datasets.py, test_datasets.py – data loading & preprocessing
- gaussian_diffusion.py, unet.py, losses.py, nn.py – model definitions and loss functions
- train_util.py, script_util.py – training/sampling orchestration
- resample.py, respace.py – timestep scheduling utilities
- dist_util.py, fp16_util.py – distributed & mixed‐precision support
- logger.py – centralized logging
- Top‐level helper scripts: evaluation.py, face_re.py, evaluation utilities in my_utils.py, face_re.py
- setup.py defines packaging/install; weights/ (external) holds pre‐trained checkpoints.

##### README for additional insights
- Confirms two main operations: downloading a pre‐trained diffusion model checkpoint and running sampling or training via Torch’s distributed launch.

##### Elements
- CLI Scripts, Orchestration, Data, Model, Utilities, Storage, External Services
- Blue for CLI/orchestration
- Green for Data/Model
- Orange for Utilities
- Gray for Storage/External

##### High‐detail capture
- Within Data, subdivide into “Image Datasets” vs. “Test Datasets.”
- Within Utilities, show “DistributedUtil,” “FP16Util,” “Resample/Respace,” and “Logger.”
- Dual workflows:
- Training: CLI → Orchestration → Data → Model → Loss → Optimizer → Checkpoint
- Sampling: CLI → Orchestration → Model (reverse diffusion) → Output Images

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        TrainScript["image_train.py"]:::cli
        SampleScript["sr_sample.py"]:::cli
        EvalScript["evaluation.py"]:::cli
        FaceREScript["face_re.py"]:::cli
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        ScriptUtil["script_util.py"]:::orchestration
        TrainUtil["train_util.py"]:::orchestration
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Datasets["datasets.py"]:::data
        ImageDatasets["image_datasets.py"]:::data
        TestDatasets["test_datasets.py"]:::data
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        GaussianDiffusion["gaussian_diffusion.py"]:::model
        UNet["unet.py"]:::model
        Losses["losses.py"]:::model
        NN["nn.py"]:::model
    end

    %% Utility Layer
    subgraph "Utility Layer"
        direction TB
        DistUtil["dist_util.py"]:::util
        FP16Util["fp16_util.py"]:::util
        Resample["resample.py"]:::util
        Respace["respace.py"]:::util
        Logger["logger.py"]:::util
    end

    %% Helper Utilities
    MyUtils["my_utils.py"]:::helper

    %% Packaging & Storage Configuration
    Setup["setup.py"]:::storage

    %% Storage Layer
    subgraph "Storage Layer"
        direction TB
        WeightsFolder["weights/ (checkpoints)"]:::storage
        Outputs["Output Images"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        TorchDist["PyTorch Distributed Launch"]:::external
        GPUCluster["GPU Cluster Scheduler"]:::external
    end

    %% Connections
    TrainScript -->|invokes| ScriptUtil
    SampleScript -->|invokes| ScriptUtil
    EvalScript -->|invokes| ScriptUtil
    FaceREScript -->|invokes| ScriptUtil

    ScriptUtil -->|uses| Datasets
    ScriptUtil -->|uses| ImageDatasets
    ScriptUtil -->|uses| TestDatasets
    ScriptUtil -->|coordinates| TrainUtil

    TrainUtil -->|loads| GaussianDiffusion
    TrainUtil -->|loads| UNet
    TrainUtil -->|computes| Losses
    TrainUtil -->|handles| NN

    TrainUtil -->|utilizes| DistUtil
    TrainUtil -->|utilizes| FP16Util
    TrainUtil -->|utilizes| Resample
    TrainUtil -->|utilizes| Respace
    TrainUtil -->|logs via| Logger

    ScriptUtil -->|loads checkpoint| WeightsFolder
    TrainUtil -->|saves checkpoint| WeightsFolder
    ScriptUtil -->|writes outputs| Outputs

    ScriptUtil -->|launch through| TorchDist
    TorchDist -->|schedules on| GPUCluster

    %% Helper & Setup
    TrainScript -->|may call| MyUtils
    SampleScript -->|may call| MyUtils
    EvalScript -->|may call| MyUtils
    FaceREScript -->|may call| MyUtils
    Setup -->|configures package| ScriptsConfig[/"Project Configuration"/]:::storage

    %% Click Events
    click TrainScript "https://github.com/jerryyann/dpi/blob/master/scripts/image_train.py"
    click SampleScript "https://github.com/jerryyann/dpi/blob/master/scripts/sr_sample.py"
    click EvalScript "https://github.com/jerryyann/dpi/blob/master/evaluation.py"
    click FaceREScript "https://github.com/jerryyann/dpi/blob/master/face_re.py"
    click ScriptUtil "https://github.com/jerryyann/dpi/blob/master/guided_diffusion/script_util.py"
    click TrainUtil "https://github.com/jerryyann/dpi/blob/master/guided_diffusion/train_util.py"
    click Datasets "https://github.com/jerryyann/dpi/blob/master/guided_diffusion/datasets.py"
    click ImageDatasets "https://github.com/jerryyann/dpi/blob/master/guided_diffusion/image_datasets.py"
    click TestDatasets "https://github.com/jerryyann/dpi/blob/master/guided_diffusion/test_datasets.py"
    click GaussianDiffusion "https://github.com/jerryyann/dpi/blob/master/guided_diffusion/gaussian_diffusion.py"
    click UNet "https://github.com/jerryyann/dpi/blob/master/guided_diffusion/unet.py"
    click Losses "https://github.com/jerryyann/dpi/blob/master/guided_diffusion/losses.py"
    click NN "https://github.com/jerryyann/dpi/blob/master/guided_diffusion/nn.py"
    click DistUtil "https://github.com/jerryyann/dpi/blob/master/guided_diffusion/dist_util.py"
    click FP16Util "https://github.com/jerryyann/dpi/blob/master/guided_diffusion/fp16_util.py"
    click Resample "https://github.com/jerryyann/dpi/blob/master/guided_diffusion/resample.py"
    click Respace "https://github.com/jerryyann/dpi/blob/master/guided_diffusion/respace.py"
    click Logger "https://github.com/jerryyann/dpi/blob/master/guided_diffusion/logger.py"
    click MyUtils "https://github.com/jerryyann/dpi/blob/master/my_utils.py"
    click Setup "https://github.com/jerryyann/dpi/blob/master/setup.py"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef orchestration fill:#99ccff,stroke:#0066cc,color:#000;
    classDef data fill:#ccffcc,stroke:#33cc33,color:#000;
    classDef model fill:#66ff66,stroke:#009900,color:#000;
    classDef util fill:#ffdd99,stroke:#ff9933,color:#000;
    classDef helper fill:#ffebcc,stroke:#ff9900,color:#000;
    classDef storage fill:#e0e0e0,stroke:#999999,color:#000;
    classDef external fill:#f2f2f2,stroke:#b3b3b3,color:#000;
```
