# minahilraza/brevitas_fixed_point architecture

> Architecture diagram of the GitHub repository minahilraza/brevitas_fixed_point, 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/minahilraza/brevitas_fixed_point
- Repository: https://github.com/minahilraza/brevitas_fixed_point

## Overview

##### Project Type and Purpose
- This is an open-source training toolkit for fixed-point quantized deep learning classification models (Lenet, Alexnet, VGG) built on PyTorch and Brevitas.
- Its primary function is to launch training/evaluation runs from the command line, manage checkpoints, and leverage Brevitas quantization modules.

##### File Structure Analysis
- Top-level: README.md, training_scripts/
- training_scripts/
- run.py – CLI entrypoint and orchestration script
- models/ – network definitions (Lenet, Alexnet, VGG) using Brevitas
- checkpoint/ – stored .pth files for pretrained weights

##### Key Insights from README
- External dependencies: PyTorch (≥1.1.0), Brevitas
- Usage: `python run.py --network <ModelName> --dataset <Dataset> [--resume] [--evaluate]`
- Supports training & evaluation on MNIST and CIFAR10, with weight and activation quantization

a. Main Components
- User/CLI Layer
- run.py (Orchestrator)
- Data Loader (PyTorch datasets: MNIST, CIFAR10)
- Model Definitions (Brevitas‐wrapped network modules)
- Training Engine (Loss, Optimizer, Backpropagation loop)
- Checkpoint Manager (save/load .pth files)
- External Libraries (PyTorch, Brevitas)
b. Relationships & Interactions
- The user issues a CLI command → run.py parses arguments →
- Data Loader loads batches →
- Model Definition is instantiated (with fixed-point quantization layers) →
- Training Engine consumes batches + model → forward/backward →
- Checkpoint Manager writes weights →
- Optional resume/evaluate hooks feed back into the engine
- All core operations call into PyTorch and Brevitas APIs
c. Architectural Patterns
- Modular separation: orchestration (run.py) vs. model definitions vs. data handling
- Plugin‐style extensibility: new models or datasets can be added under models/ or by extending run.py
- Checkpoint abstraction to decouple training logic from storage
d. Key Technologies
- PyTorch: tensor ops, nn.Module, DataLoader, optim
- Brevitas: QuantTensor, QuantConv, QuantLinear
- Python CLI parsing (argparse) in run.py

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and CLI
    User(("User")):::external
    CLI["CLI Parser & Orchestrator"]:::orchestration

    %% Data
    Data["Data Loader\n(PyTorch Datasets)"]:::data

    %% Models
    subgraph "Model Definitions (Brevitas)" 
        Lenet["Lenet"]:::model
        Alexnet["Alexnet"]:::model
        VGG["VGG"]:::model
    end

    %% Training Engine
    Trainer["Training Engine"]:::orchestration
    subgraph "Training Steps"
        Loss["Loss Computation"]:::orchestration
        Optimizer["Optimizer Step"]:::orchestration
        Backprop["Backpropagation"]:::orchestration
    end

    %% Checkpointing
    CheckpointMgr["Checkpoint Manager"]:::storage
    Checkpoints["Pretrained Checkpoints\n(ckpt*.pth)"]:::storage

    %% External Libraries
    External["PyTorch & Brevitas APIs"]:::external

    %% Documentation
    Readme["README.md"]:::external

    %% Connections
    User -->|"launch CLI"| CLI
    CLI -->|"parse args"| Data
    CLI -->|"instantiate model"| Lenet
    CLI -->|"instantiate model"| Alexnet
    CLI -->|"instantiate model"| VGG
    Data -->|"load batches"| Trainer
    Lenet -->|"model instance"| Trainer
    Alexnet -->|"model instance"| Trainer
    VGG -->|"model instance"| Trainer
    Trainer --> Loss
    Loss --> Optimizer
    Optimizer --> Backprop
    Backprop --> Trainer
    Trainer -->|"save/load weights"| CheckpointMgr
    CheckpointMgr --> Checkpoints
    Trainer -->|"calls"| External
    Lenet -->|"uses"| External
    Alexnet -->|"uses"| External
    VGG -->|"uses"| External
    CLI -->|"see docs"| Readme

    %% Click Events
    click CLI "https://github.com/minahilraza/brevitas_fixed_point/blob/master/training_scripts/run.py"
    click Lenet "https://github.com/minahilraza/brevitas_fixed_point/blob/master/training_scripts/models/lenet.py"
    click Alexnet "https://github.com/minahilraza/brevitas_fixed_point/blob/master/training_scripts/models/alexnet.py"
    click VGG "https://github.com/minahilraza/brevitas_fixed_point/blob/master/training_scripts/models/vgg.py"
    click CheckpointMgr "https://github.com/minahilraza/brevitas_fixed_point/tree/master/training_scripts/checkpoint/"
    click Readme "https://github.com/minahilraza/brevitas_fixed_point/blob/master/README.md"

    %% Styles
    classDef orchestration fill:#AED6F1,stroke:#217DBB,color:#000;
    classDef data fill:#A9DFBF,stroke:#229954,color:#000;
    classDef model fill:#F5B041,stroke:#B9770E,color:#000;
    classDef storage fill:#D5DBDB,stroke:#808B96,color:#000;
    classDef external fill:#F9E79F,stroke:#B7950B,color:#000;
```
