# xilinx/brevitas architecture

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

- Interactive diagram: https://gitdiagram.com/xilinx/brevitas
- Repository: https://github.com/xilinx/brevitas

## Overview

##### Project type and purpose
- Brevitas is an open-source Python library (built on PyTorch) for neural network quantization.
- It provides both PTQ (post-training quantization) and QAT (quantization-aware training) workflows, plus export to ONNX/QONNX and example pipelines.

##### Main high-level components
a. Core Quantization API
– `brevitas.core` (bit-width, function wrappers, quant, scaling, stats, utils)
– `brevitas.quant` (quantization algorithms, solvers)
– `brevitas.quant_tensor` (QuantTensor classes & handlers)
b. PyTorch Integration
– `brevitas.nn` (Quantized layer modules)
– `brevitas.fx` (FX tracer & value tracer)
– `brevitas.proxy` (parameter/runtime proxies)
c. Graph & Compiler
– `brevitas.graph` (graph transforms: quantize, equalize, calibrate, etc.)
– `brevitas.compiler` (overall orchestration)
d. Export Subsystem
– `brevitas.export.*`
- ONNX / QONNX export managers & handlers
- Torch export (QCDQ)
- Inference export
e. Examples & User Flows
– `brevitas_examples` (ImageNet PTQ, LLM quant, speech, diffusion, etc.)
f. External Dependencies
– PyTorch, ONNX, numpy, SciPy, third-party quant libs (QONNX), hardware backends (TVM, FINN)
g. CI / Docs
– `.github/workflows`, `docs/`, `docsrc/`

##### Component relationships & interactions
1. User code (examples or custom scripts) instantiates `brevitas.nn.Quant*` layers → these layers wrap native PyTorch modules.
2. Internally, `Quant*` layers use `brevitas.proxy` to wrap parameters/activations as `QuantTensor`.
3. On forward pass, `QuantTensor` interacts with `brevitas.core.function_wrapper` and quant routines in `brevitas.core.quant`.
4. For FX-based workflows, `brevitas.fx` tracer inspects the layer graph → feeds into `brevitas.graph` transforms (quantize, equalize, calibrate).
5. After calibration/QAT, `brevitas.export` uses handlers/managers to produce ONNX/QONNX or Torch+QCDQ modules.
6. Exported models run in inference engines or hardware accelerators (e.g., TVM, FINN).
7. Examples drive and demonstrate these flows.

##### Architectural patterns & principles
- Modular layering: core logic ←→ integration layer ←→ export
- Dependency injection & handler registries (common/handler) for extensibility
- FX-based graph rewrites for quant transforms
- Proxy/Tensor wrapper pattern separating quant logic from PyTorch internals

##### Detailed breaking-down of components (sample decomposition)

[User Scripts / Examples] → [Integration Layer (nn, proxy, quant_tensor)] → [Core Quant API] ↔ [FX & Graph Passes] → [Export Subsystem] → [External Runtime / Hardware]

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Examples Layer
    subgraph "Examples & User Flows"
        direction TB
        Examples["📄 User Scripts / Examples"]:::gray
    end

    %% Integration Layer
    subgraph "Integration Layer" 
        direction TB
        NN["Quantized Layers (brevitas.nn)"]:::green
        Proxy["Parameter/Runtime Proxies (brevitas.proxy)"]:::green
        QT["QuantTensor (brevitas.quant_tensor)"]:::green
    end

    %% Core Quant API
    subgraph "Core Quant API"
        direction TB
        Core["Core Modules (brevitas.core)"]:::blue
        QuantAlgo["Quantization Algorithms (brevitas.quant)"]:::blue
    end

    %% FX & Graph
    subgraph "FX & Graph Passes"
        direction TB
        FX["FX Tracer & ValueTracer (brevitas.fx)"]:::orange
        Graph["Graph Transforms (brevitas.graph)"]:::orange
        Compiler["Compiler Orchestration (brevitas/compiler.py)"]:::orange
    end

    %% Export Subsystem
    subgraph "Export Subsystem"
        direction TB
        Common["Common Handlers (brevitas/export/common)"]:::purple
        Inference["Inference Manager (brevitas/export/inference)"]:::purple
        ONNX["ONNX/QONNX Export (brevitas/export/onnx)"]:::purple
        TorchQ["Torch QCDQ Export (brevitas/export/torch)"]:::purple
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        PyTorch[(PyTorch)]:::external
        ONNXRT[(ONNX Runtime)]:::external
        HW[(TVM / FINN)]:::external
        NumLib[(numpy, SciPy, QONNX)]:::external
    end

    %% CI & Docs
    subgraph "CI & Documentation"
        direction TB
        CI["Workflows (.github/workflows)"]:::gray
        Docs["Documentation (docs/, docsrc/)"]:::gray
    end

    %% Flow Connections
    Examples -->|"instantiate Quantized Layers"| NN
    NN -->|"wrap with Proxy"| Proxy
    Proxy -->|"produce"| QT
    QT -->|"calls quant routines"| Core
    Core -->|"uses algorithms"| QuantAlgo
    NN -->|"FX trace"| FX
    Proxy --> FX
    QT --> FX
    FX -->|"graph transform"| Graph
    Graph -->|"orchestrate"| Compiler
    Compiler -->|"invokes export subsystems"| Common
    Common --> Inference
    Common --> ONNX
    Common --> TorchQ
    ONNX -->|"runs on"| ONNXRT
    TorchQ -->|"runs on"| PyTorch
    ONNXRT --> HW
    PyTorch --> HW
    Examples -.-> CI
    Examples -.-> Docs

    %% Click Events
    click Core "https://github.com/xilinx/brevitas/tree/master/src/brevitas/core"
    click QuantAlgo "https://github.com/xilinx/brevitas/tree/master/src/brevitas/quant"
    click QT "https://github.com/xilinx/brevitas/tree/master/src/brevitas/quant_tensor"
    click NN "https://github.com/xilinx/brevitas/tree/master/src/brevitas/nn"
    click FX "https://github.com/xilinx/brevitas/tree/master/src/brevitas/fx"
    click Proxy "https://github.com/xilinx/brevitas/tree/master/src/brevitas/proxy"
    click Graph "https://github.com/xilinx/brevitas/tree/master/src/brevitas/graph"
    click Compiler "https://github.com/xilinx/brevitas/blob/master/src/brevitas/compiler.py"
    click Common "https://github.com/xilinx/brevitas/tree/master/src/brevitas/export/common"
    click Inference "https://github.com/xilinx/brevitas/tree/master/src/brevitas/export/inference"
    click ONNX "https://github.com/xilinx/brevitas/tree/master/src/brevitas/export/onnx"
    click TorchQ "https://github.com/xilinx/brevitas/tree/master/src/brevitas/export/torch"
    click Examples "https://github.com/xilinx/brevitas/tree/master/src/brevitas_examples"
    click CI "https://github.com/xilinx/brevitas/tree/master/.github/workflows"
    click Docs "https://github.com/xilinx/brevitas/tree/master/docs/"

    %% Styles
    classDef blue fill:#D0E8FF,stroke:#0066CC,color:#003366
    classDef green fill:#DFF2D8,stroke:#4AA02C,color:#2C662D
    classDef orange fill:#FFE5B4,stroke:#CC8400,color:#663C00
    classDef purple fill:#E6D0FF,stroke:#8000CC,color:#4B0066
    classDef gray fill:#F2F2F2,stroke:#999999,color:#333333
    classDef external fill:#FFFFFF,stroke:#000000,stroke-dasharray: 5 5,color:#000000
```
