# calad0i/hgq architecture

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

- Interactive diagram: https://gitdiagram.com/calad0i/hgq
- Repository: https://github.com/calad0i/hgq

## Overview

##### Main Components

a) Core Components:
- Quantization Engine (src/HGQ/quantizer)
- Binary Operations Module (src/HGQ/bops)
- Neural Network Layers (src/HGQ/layers)
- Proxy System (src/HGQ/proxy)
- Utility Functions (src/HGQ/utils)

b) External Interfaces:
- TensorFlow Integration
- hls4ml Integration
- QKeras Integration

**Top Level (User Interface)**

- Training Pipeline
- Quantization-Aware Training
- Bitwidth Optimization

- Core Components
- Quantizer Module
- Layer Implementations
- Binary Operations
- Proxy System

- External Integration Layer
- TensorFlow Backend
- hls4ml Export
- QKeras Plugin

##### Key Elements to Highlight

a) Data Flow:

- Blue: Core quantization components
- Green: Neural network layers
- Orange: External interfaces
- Purple: Resource estimation components
- Gray: Utility and support functions

##### Component Details

**Quantizer Module**
- Fixed Point Quantizer
- Precision Derivation
- Unary LUT

**Layer Implementation**
- Base Layers
- Conv Layers
- Dense Layers
- Experimental Layers (Attention)

**Proxy System**
- Conversion Logic
- QKeras Plugin
- Precision Derivation

##### Key Interactions to Emphasize

- Training flow from input to quantized model
- Resource estimation feedback loop
- Conversion path to hls4ml
- Integration points with existing frameworks

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph User_Interface
        UI[User Interface]:::interface
    end

    subgraph Training_Pipeline
        QAT[Quantization-Aware Training]:::training
        BO[Bitwidth Optimization]:::training
    end

    subgraph Core_Components
        QM[Quantizer Module]:::core
        LI[Layer Implementations]:::core
        BOPS[Binary Operations]:::core
        PS[Proxy System]:::core
    end

    subgraph Layer_Details
        BL[Base Layers]:::layer
        CL[Conv Layers]:::layer
        DL[Dense Layers]:::layer
        EL[Experimental Layers]:::layer
    end

    subgraph Quantizer_Components
        FPQ[Fixed Point Quantizer]:::quantizer
        PD[Precision Derivation]:::quantizer
        UL[Unary LUT]:::quantizer
    end

    subgraph Proxy_Components
        CL_P[Conversion Logic]:::proxy
        QK_P[QKeras Plugin]:::proxy
        PD_P[Precision Derivation]:::proxy
    end

    subgraph External_Integration
        TF[TensorFlow Backend]:::external
        HLS[hls4ml Export]:::external
        QK[QKeras Integration]:::external
    end

    UI --> QAT
    QAT --> BO
    BO --> QM
    QM --> LI
    LI --> BOPS
    BOPS -.-> BO
    PS --> External_Integration

    LI --> BL
    LI --> CL
    LI --> DL
    LI --> EL

    QM --> FPQ
    QM --> PD
    QM --> UL

    PS --> CL_P
    PS --> QK_P
    PS --> PD_P

    %% Click events for component mapping
    click QM "https://github.com/calad0i/HGQ/blob/master/src/HGQ/quantizer/quantizer.py"
    click BOPS "https://github.com/calad0i/HGQ/blob/master/src/HGQ/bops/bops.py"
    click LI "https://github.com/calad0i/HGQ/tree/master/src/HGQ/layers/"
    click BL "https://github.com/calad0i/HGQ/blob/master/src/HGQ/layers/base.py"
    click CL "https://github.com/calad0i/HGQ/blob/master/src/HGQ/layers/conv.py"
    click DL "https://github.com/calad0i/HGQ/blob/master/src/HGQ/layers/dense.py"
    click EL "https://github.com/calad0i/HGQ/blob/master/src/HGQ/layers/experimental/attn.py"
    click PS "https://github.com/calad0i/HGQ/tree/master/src/HGQ/proxy/"
    click CL_P "https://github.com/calad0i/HGQ/blob/master/src/HGQ/proxy/convert.py"
    click QK_P "https://github.com/calad0i/HGQ/blob/master/src/HGQ/proxy/plugins/qkeras.py"
    click PD_P "https://github.com/calad0i/HGQ/blob/master/src/HGQ/proxy/precision_derivation.py"
    click FPQ "https://github.com/calad0i/HGQ/blob/master/src/HGQ/proxy/fixed_point_quantizer.py"
    click UL "https://github.com/calad0i/HGQ/blob/master/src/HGQ/proxy/unary_lut.py"
    click QK "https://github.com/calad0i/HGQ/blob/master/examples/qkeras.ipynb"

    %% Styling
    classDef interface fill:#f9f,stroke:#333
    classDef training fill:#afd,stroke:#333
    classDef core fill:#9cf,stroke:#333
    classDef layer fill:#6c6,stroke:#333
    classDef quantizer fill:#69f,stroke:#333
    classDef proxy fill:#f96,stroke:#333
    classDef external fill:#fc9,stroke:#333

    %% Legend
    subgraph Legend
        L1[User Interface]:::interface
        L2[Training Components]:::training
        L3[Core Components]:::core
        L4[Layer Components]:::layer
        L5[Quantizer Components]:::quantizer
        L6[Proxy Components]:::proxy
        L7[External Integration]:::external
    end
```
