# yuchuantian/dic architecture

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

- Interactive diagram: https://gitdiagram.com/yuchuantian/dic
- Repository: https://github.com/yuchuantian/dic

## Overview

##### Project Type and Purpose
- Type: Research-code repository implementing “DiC: Rethinking Conv3x3 Designs in Diffusion Models” in PyTorch.
- Purpose: Train, sample, and evaluate ConvUNet-based diffusion models (DiC) on image datasets or pre-computed VAE features.

##### Main System Components
A. Data Sources
- Raw ImageNet Dataset (folders train/, val/)
- Precomputed VAE Features (imagenet_feature/)
- External Model Hubs (HuggingFace, ModelScope) for VAE download
B. Core Code Modules
1. Model Definitions
- dic_models.py (ConvUNet architecture)
- models.py (additional network definitions)
2. Diffusion Engine (diffusion/)
- diffusion_utils.py (sampling loops, noise schedules)
- gaussian_diffusion.py (forward/backward diffusion math)
- respace.py (timestep rescaling)
- timestep_sampler.py (noise scheduling strategies)
3. Utilities
- utils/parser_setter.py (CLI argument parsing)
- utils/fastdit_kit.py (data loaders, VAE feature handling)
C. Orchestration Scripts
- Training
- train.py (fp32, torchrun)
- train_accelerate.py (fp16, accelerate)
- Sampling
- sample_ddp.py (distributed sampling)
- Evaluation
- evaluator.py (metrics on generated samples)
- Download Helper
- download.py (automate VAE / dataset pulls)
D. External Services & Artifacts
- HuggingFace / ModelScope (dataset and VAE hosting)
- Output Artifacts: model checkpoints, sampled images, evaluation logs

##### Relationships & Data Flow
1. Data Ingestion
- Optionally: Raw Images → VAE Encoder → Feature Cache
2. Training Pipeline
- CLI Script (train.py or train_accelerate.py)
↓
- Parser (parser_setter)
↓
- Model Instantiation (dic_models.py + diffusion modules)
↓
- Diffusion Process (gaussian_diffusion, timestep_sampler)
↓
- Optimizer / Backprop
↓
- Checkpoint Writer
3. Sampling Pipeline
- CLI Script (sample_ddp.py)
↓
- Load Checkpoint → Diffusion Engine → Generated Images
4. Evaluation Pipeline
- evaluator.py reads checkpoints & generated images → computes metrics
5. Download Utility
- download.py orchestrates pulls from HuggingFace/ModelScope

##### Architectural Patterns & Principles
- Modular separation: Data I/O, Model definition, Diffusion logic, Orchestration.
- Reusable components: diffusion/ folder encapsulates all scheduler/math.
- CLI-driven entrypoints for training, sampling, evaluation.
- Distributed/disaggregated execution via torch.distributed / accelerate.

##### Final Checklist
– Have you separated all 4 major layers (Data, Core Modules, Orchestrators, External)?
– Are all data flows directional and unambiguous?
– Is each code folder/file represented by a logical block?
– Did you highlight the VAE feature path vs. raw image path?

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Sources Layer
    subgraph "Data Sources" 
        direction TB
        RawImageNet[(Raw ImageNet Dataset)]:::data
        VAEFeatures[(Precomputed VAE Features)]:::data
    end

    %% External Services Layer
    subgraph "External Services"
        direction TB
        HF["HuggingFace"]:::external
        MS["ModelScope"]:::external
    end

    %% Core Code Modules Layer
    subgraph "Core Modules"
        direction TB
        DicModels["ConvUNet Model Definitions"]:::core
        ModelsPy["Additional Network Definitions"]:::core
        subgraph "Diffusion Engine"
            direction TB
            DiffusionDir["diffusion/"]:::core
            DiffUtils["Sampling Loops & Noise Schedules"]:::core
            GaussDiff["Forward/Backward Diffusion Math"]:::core
            Respace["Timestep Rescaling Utilities"]:::core
            TimestepSampler["Noise Scheduling Strategies"]:::core
        end
        Parser["CLI Argument Parser"]:::core
        FastDiT["Data Loader & VAE Feature Handling"]:::core
    end

    %% Orchestration Scripts Layer
    subgraph "Orchestration Scripts"
        direction TB
        TrainFP32("train.py"):::script
        TrainFP16("train_accelerate.py"):::script
        SampleDDP("sample_ddp.py"):::script
        Evaluator("evaluator.py"):::script
        DownloadUtil("download.py"):::script
    end

    %% Data Flows
    RawImageNet -->|"loads raw images"| FastDiT
    VAEFeatures -->|"loads features"| FastDiT
    HF -->|"downloads VAE/dataset"| DownloadUtil
    MS -->|"downloads VAE/dataset"| DownloadUtil
    DownloadUtil -->|"writes raw data & features"| RawImageNet
    DownloadUtil -->|"writes raw data & features"| VAEFeatures

    FastDiT -->|"provides data"| TrainFP32
    FastDiT -->|"provides data"| TrainFP16

    %% Training Pipeline Invocation
    TrainFP32 -.->|invokes| Parser
    TrainFP16 -.->|invokes| Parser
    Parser -.->|sets up| DicModels
    Parser -.->|sets up| ModelsPy
    Parser -.->|sets up| DiffUtils
    Parser -.->|sets up| GaussDiff
    Parser -.->|sets up| Respace
    Parser -.->|sets up| TimestepSampler

    %% Sampling Pipeline
    SampleDDP -.->|invokes| GaussDiff
    SampleDDP -.->|invokes| TimestepSampler
    SampleDDP -->|"loads checkpoint & generates images"| VAEFeatures

    %% Evaluation Pipeline
    Evaluator -.->|reads checkpoints & images| VAEFeatures
    Evaluator -->|"computes metrics"| RawImageNet

    %% Click Events
    click DicModels "https://github.com/yuchuantian/dic/blob/main/dic_models.py"
    click ModelsPy "https://github.com/yuchuantian/dic/blob/main/models.py"
    click DiffusionDir "https://github.com/yuchuantian/dic/tree/main/diffusion/"
    click DiffUtils "https://github.com/yuchuantian/dic/blob/main/diffusion/diffusion_utils.py"
    click GaussDiff "https://github.com/yuchuantian/dic/blob/main/diffusion/gaussian_diffusion.py"
    click Respace "https://github.com/yuchuantian/dic/blob/main/diffusion/respace.py"
    click TimestepSampler "https://github.com/yuchuantian/dic/blob/main/diffusion/timestep_sampler.py"
    click Parser "https://github.com/yuchuantian/dic/blob/main/utils/parser_setter.py"
    click FastDiT "https://github.com/yuchuantian/dic/blob/main/utils/fastdit_kit.py"
    click TrainFP32 "https://github.com/yuchuantian/dic/blob/main/train.py"
    click TrainFP16 "https://github.com/yuchuantian/dic/blob/main/train_accelerate.py"
    click SampleDDP "https://github.com/yuchuantian/dic/blob/main/sample_ddp.py"
    click Evaluator "https://github.com/yuchuantian/dic/blob/main/evaluator.py"
    click DownloadUtil "https://github.com/yuchuantian/dic/blob/main/download.py"

    %% Styles
    classDef data fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef core fill:#c8e6c9,stroke:#43a047,color:#1b5e20
    classDef script fill:#ffe0b2,stroke:#fb8c00,color:#e65100
    classDef external fill:#e1bee7,stroke:#8e24aa,color:#4a148c
```
