# ugonfor/dgq architecture

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

- Interactive diagram: https://gitdiagram.com/ugonfor/dgq
- Repository: https://github.com/ugonfor/dgq

## Overview

##### Project Type and Purpose
- This is a research‐codebase and CLI tool for “Distribution‐Aware Group Quantization (DGQ)” of large text‐to‐image diffusion models (Stable Diffusion v1.4 & SDXL‐turbo).
- It integrates with Hugging Face’s diffusers library to perform:
- Weight‐only quantization (4/8 bits)
- Activation quantization (6/8 bits)
- Merging quantized weights+activations
- Running inference on the fully‐quantized model
- Users invoke shell scripts or Python entrypoints to orchestrate each phase.

##### File‐Structure Analysis
- Top-level:
- environment.yaml, setup.py, Makefile – environment & build
- scripts/*.sh – bash wrappers for each quantization/inference step
- src/*.py – Python modules: calibration, quantization, inference, utilities
- quant/*.py – core quantization routines (weight, activation, group routines)
- results/*.py – post‐processing (merge checkpoints)
- linklink/ – helpers for distributed execution & logging
- diffusers/ & diffusers_rewrite/ – submodule containing the HuggingFace library and a small rewrite for runtime calls
- Patterns:
- “scripts → src → quant → results” sequence for workflow
- Modular separation: quantization logic (quant/), orchestration (scripts/), I/O & merging (results/), external library (diffusers/)

##### README Insights
- Describes a four‐stage pipeline:
1. Weight quantization
2. Activation quantization
3. Merge the two quantized checkpoints
4. Inference with the merged checkpoint
- Lists external dependencies: PyTorch/CUDA, HuggingFace diffusers, conda environment

##### Diagramming Recommendations
- Actor (stick‐figure) for the User
- Rounded rectangles for Scripts & CLI entrypoints
- Rectangles for Python modules (quant, src, results)
- Orchestration (scripts & linklink) in blue
- Quantization logic (quant/) in green
- I/O & merge (results/) in orange
- Inference & model loading (src/ + diffusers_rewrite) in purple
- Storage in gray
User → Script → WeightQuant → Storage → ActQuant → Storage → Merge → Storage → Inference → Output
- Orchestration lane (scripts, linklink)
- Compute lane (quant, inference)
- Storage lane (checkpoints)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actor
    User(["User / CLI"]):::actor

    %% Orchestration Layer
    subgraph Orchestration
        direction TB
        QW_sh(["quantize_weight.sh"]):::orchestration
        QA_sh(["quantize_act.sh"]):::orchestration
        GEN_SD(["gen4eval_SD.sh"]):::orchestration
        GEN_SDXL(["gen4eval_SDXL.sh"]):::orchestration
        DH(["dist_helper.py"]):::orchestration
        LH(["log_helper.py"]):::orchestration
    end

    %% Compute Layer
    subgraph "Quantization Logic" 
        direction TB
        QModel(["quant_model.py"]):::quant
        Calib(["calibration.py"]):::quant
        CalibGQ(["calibration_group_quantization.py"]):::quant
        AR(["adaptive_rounding.py"]):::quant
        QLayer(["quant_layer.py"]):::quant
        QLayerText(["quant_layer_text.py"]):::quant
        QBlock(["quant_block.py"]):::quant
        Uti(["utils.py"]):::compute
        LoadUtil(["load_qmodel_util.py"]):::compute
    end

    %% Merge & Post-Processing Layer
    subgraph "Results & Merge"
        direction TB
        Merge(["merge.py"]):::results
        CheckW(["check_weight.py"]):::results
        Clean(["clean.py"]):::results
    end

    %% Inference Layer
    subgraph "Inference & Model Loading"
        direction TB
        InfPy(["inference_qmodel.py"]):::inference
        SDRewrite(["sd.py"]):::inference
        SDXLRewrite(["sdxl.py"]):::inference
    end

    %% External & Storage
    subgraph External
        direction TB
        Diffusers(["HuggingFace Diffusers"]):::external
    end

    Storage[("Checkpoint Storage")]:::storage
    Output(["Generated Images"]):::output

    %% Data Flow
    User --> QW_sh
    QW_sh --> DH
    QW_sh --> LH
    QW_sh --> QW_py["quantize_weight.py"]:::orchestration
    QW_py --> QModel
    QW_py --> Calib
    QW_py --> CalibGQ
    QW_py --> AR
    QW_py --> Uti
    QW_py -->|"writes .pth_weight_only"| Storage

    User --> QA_sh
    QA_sh --> DH
    QA_sh --> LH
    QA_sh --> QA_py["quantize_act.py"]:::orchestration
    QA_py --> QLayer
    QA_py --> QLayerText
    QA_py --> QBlock
    QA_py --> LoadUtil
    QA_py -->|"reads .pth_weight_only"| Storage
    QA_py -->|"writes .pth_activation"| Storage

    User --> Merge
    Merge -->|"reads .pth_weight_only & .pth_activation"| Storage
    Merge -->|"writes .pth_merged"| Storage

    User --> GEN_SD
    User --> GEN_SDXL
    GEN_SD --> DH
    GEN_SD --> LH
    GEN_SD --> InfPy
    GEN_SDXL --> DH
    GEN_SDXL --> LH
    GEN_SDXL --> InfPy

    InfPy -->|"loads .pth_merged"| Storage
    InfPy --> SDRewrite
    InfPy --> SDXLRewrite
    SDRewrite --> Diffusers
    SDXLRewrite --> Diffusers
    InfPy -->|"generates images"| Output

    %% Click Events
    click QW_sh "https://github.com/ugonfor/dgq/blob/main/scripts/quantize_weight.sh"
    click QA_sh "https://github.com/ugonfor/dgq/blob/main/scripts/quantize_act.sh"
    click GEN_SD "https://github.com/ugonfor/dgq/blob/main/scripts/gen4eval_SD.sh"
    click GEN_SDXL "https://github.com/ugonfor/dgq/blob/main/scripts/gen4eval_SDXL.sh"
    click QModel "https://github.com/ugonfor/dgq/blob/main/quant/quant_model.py"
    click Calib "https://github.com/ugonfor/dgq/blob/main/quant/calibration.py"
    click CalibGQ "https://github.com/ugonfor/dgq/blob/main/quant/calibration_group_quantization.py"
    click AR "https://github.com/ugonfor/dgq/blob/main/quant/adaptive_rounding.py"
    click QLayer "https://github.com/ugonfor/dgq/blob/main/quant/quant_layer.py"
    click QLayerText "https://github.com/ugonfor/dgq/blob/main/quant/quant_layer_text.py"
    click QBlock "https://github.com/ugonfor/dgq/blob/main/quant/quant_block.py"
    click Merge "https://github.com/ugonfor/dgq/blob/main/results/merge.py"
    click InfPy "https://github.com/ugonfor/dgq/blob/main/src/inference_qmodel.py"
    click SDRewrite "https://github.com/ugonfor/dgq/blob/main/diffusers_rewrite/sd.py"
    click SDXLRewrite "https://github.com/ugonfor/dgq/blob/main/diffusers_rewrite/sdxl.py"
    click QW_py "https://github.com/ugonfor/dgq/blob/main/src/quantize_weight.py"
    click QA_py "https://github.com/ugonfor/dgq/blob/main/src/quantize_act.py"
    click Uti "https://github.com/ugonfor/dgq/blob/main/src/utils.py"
    click LoadUtil "https://github.com/ugonfor/dgq/blob/main/quant/load_qmodel_util.py"
    click DH "https://github.com/ugonfor/dgq/blob/main/linklink/dist_helper.py"
    click LH "https://github.com/ugonfor/dgq/blob/main/linklink/log_helper.py"
    click Diffusers "https://github.com/ugonfor/dgq/tree/main/diffusers/"

    %% Styles
    classDef actor fill:#FFD580,stroke:#333,stroke-width:1px;
    classDef orchestration fill:#AED6F1,stroke:#1F618D,stroke-width:1px;
    classDef quant fill:#ABEBC6,stroke:#196F3D,stroke-width:1px;
    classDef compute fill:#D6EAF8,stroke:#1B4F72,stroke-width:1px;
    classDef results fill:#F9E79F,stroke:#B9770E,stroke-width:1px;
    classDef inference fill:#D2B4DE,stroke:#6C3483,stroke-width:1px;
    classDef external fill:#A3E4D7,stroke:#117A65,stroke-width:1px;
    classDef storage fill:#E5E7E9,stroke:#566573,stroke-width:1px;
    classDef output fill:#F5B7B1,stroke:#943126,stroke-width:1px;
```
