# aifoundry-org/mhaq architecture

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

- Interactive diagram: https://gitdiagram.com/aifoundry-org/mhaq
- Repository: https://github.com/aifoundry-org/mhaq

## Overview

##### Project Type and Purpose
- This is an open‐source, Python-based quantization framework (“MHAQ”) built on PyTorch Lightning.
- It provides a modular environment for defining, integrating, and benchmarking custom quantization methods on vision (and other) models.
- Key use cases: model composition, quantization (QAT), training, logging, and visualization.

##### High-Level File Structure Analysis
– Top-level directories:
- config: YAML files defining quantization and training pipelines
- data: placeholder and pre-trained model files
- scripts: CLI or example scripts to launch specific quant workflows
- src: main framework code, subdivided by function (aux, callbacks, config loader, data, loggers, models, quantization, training)
- tests: performance tests for quant implementations
– Entry points: scripts/rniq_q_config.py, scripts/training/resnet_train.py
– Config/schema: src/config/config_loader.py + config_schema.py
– Training orchestration: src/training/trainer.py (wraps PyTorch Lightning Trainer)
– Quantization engine: src/quantization/quantizer.py delegates to different backends (rniq, dummy)
– Callbacks & loggers: src/callbacks/*.py and src/loggers/*.py for experiment control and metric tracking

##### Insights from README
- Framework leverages PyTorch Lightning for distributed training, checkpoints, metrics.
- Workflow: load YAML config → compose model → wrap in Quantizer → prepare datamodule → training fit → evaluate.
- Customization points: add new quant methods under src/quantization, extend callbacks, inject new data pipelines under src/data.

a. Main Components
1. User (CLI/API)
2. Config Loader
3. Model Composer
4. Quantizer (pluggable backends: RNIQ, Dummy)
5. Data Module (vision pipelines, e.g., CIFAR, ImageNet, DALI variants)
6. Trainer (PyTorch Lightning wrapper)
7. Callbacks & Loggers (early stopping, LR scheduler, WandB, visualizations)
8. Persistence (saved weights/models under data/models)
9. Tests & Scripts (validation and benchmarking in tests/ and scripts/)

b. Relationships & Data Flow
- User invokes a script → config loader reads YAML → config object
- Composer uses config → builds base model architecture
- Quantizer takes base model + config → produces quantized model (in-place or copy)
- Data Module reads config → sets up dataset transforms, loaders
- Trainer receives quantized model & data module → runs fit()
- During fit: callbacks adjust LR, temperature, noise ratio; loggers send metrics to console/WandB
- On complete: trainer checkpoints model → saved to data/models
- Tests import quantizer/trainer to run perf benchmarks

c. Architectural Patterns & Principles
- Modular plugin architecture (strategy pattern for quant backends, data pipelines, callbacks)
- Single responsibility: each subpackage (aux, quantization, data, models) focuses on a concern
- Inversion of control via central config object injected into all components
- Layered design: CLI → Configuration → Composition → Quantization → Training → Persistence

d. Key Technologies & Frameworks
- Python 3.x, PyTorch, PyTorch Lightning
- YAML for configs
- DALI (for high-performance data loading)
- WandB (external logging service)
- Standard Python packaging, pytest for tests

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User / CLI Layer
    subgraph "User / CLI Scripts"
        direction TB
        CLI_RNIQ["rniq_q_config.py"]:::user
        CLI_DummyCfg["dummy_q_config.py"]:::user
        CLI_DummyManual["dummy_q_manual.py"]:::user
        CLI_RNIQVis["rniq_q_config_vis.py"]:::user
        CLI_ResNet["resnet_train.py"]:::user
    end

    %% Configuration Layer
    subgraph "Configuration"
        direction TB
        ConfigLoader["Config Loader"]:::core
        ConfigSchema["Config Schema"]:::core
    end

    %% Composition Layer
    subgraph "Model Composition"
        direction TB
        Composer["Model Composer"]:::core
        VisionModule["Vision Module"]:::core
    end

    %% Quantization Layer
    subgraph "Quantization Engine"
        direction TB
        Quantizer["Quantizer (Engine)"]:::core
        subgraph "Quantization Backends"
            direction TB
            DummyBackend["Dummy Backend"]:::plugin
            RNIQBackend["RNIQ Backend"]:::plugin
        end
    end

    %% Data Layer
    subgraph "Data Module"
        direction TB
        DataComposer["Data Module Composer"]:::core
        subgraph "Vision Pipelines"
            direction TB
            CIFAR["cifar10.py"]:::core
            ImageNet["imagenet.py"]:::core
        end
        GenData["CIFAR Gen"]:::core
    end

    %% Training Layer
    subgraph "Training"
        direction TB
        Trainer["Trainer"]:::core
        subgraph "Callbacks"
            direction TB
            EarlyStop["Early Stopping"]:::core
            LRRevert["LR Loss Revert"]:::core
            NoiseAdjust["Noise Ratio Adjust"]:::core
            TempAdjust["Temperature Adjust"]:::core
            BWVis["BW Visualization"]:::core
            ViolinVis["Violin Visualization"]:::core
        end
        subgraph "Loggers"
            direction TB
            DefaultLog["Default Logger"]:::core
            WandBLog["WandB Logger"]:::ext
        end
    end

    %% Persistence
    Persistence["Model Persistence (data/models)"]:::persist

    %% Testing Layer
    Tests["Performance Tests"]:::core

    %% Connections
    CLI_RNIQ -->|"loads config"| ConfigLoader
    CLI_DummyCfg -->|"loads config"| ConfigLoader
    CLI_DummyManual -->|"loads config"| ConfigLoader
    CLI_RNIQVis -->|"loads config"| ConfigLoader
    CLI_ResNet -->|"loads config"| ConfigLoader

    ConfigLoader -->|"produces Config object"| Composer
    ConfigLoader -->|"produces Config object"| DataComposer

    Composer -->|"builds base model"| Quantizer
    VisionModule --> Quantizer

    Quantizer -->|"quantized model"| Trainer
    DummyBackend --> Quantizer
    RNIQBackend --> Quantizer

    DataComposer -->|"DataLoader"| Trainer
    CIFAR --> DataComposer
    ImageNet --> DataComposer
    GenData --> DataComposer

    Trainer -->|"fits model"| EarlyStop
    Trainer -->|"fits model"| LRRevert
    Trainer -->|"fits model"| NoiseAdjust
    Trainer -->|"fits model"| TempAdjust
    Trainer -->|"fits model"| BWVis
    Trainer -->|"fits model"| ViolinVis
    Trainer -->|"logs metrics"| DefaultLog
    Trainer -->|"logs metrics"| WandBLog

    Trainer -->|"checkpoints"| Persistence
    Tests -->|"imports"| Quantizer
    Tests -->|"imports"| Trainer

    %% Click Events
    click ConfigLoader "https://github.com/aifoundry-org/mhaq/blob/master/src/config/config_loader.py"
    click ConfigSchema "https://github.com/aifoundry-org/mhaq/blob/master/src/config/config_schema.py"
    click Composer "https://github.com/aifoundry-org/mhaq/blob/master/src/models/compose/composer.py"
    click VisionModule "https://github.com/aifoundry-org/mhaq/blob/master/src/models/compose/vision/vision_cls_module.py"
    click Quantizer "https://github.com/aifoundry-org/mhaq/blob/master/src/quantization/quantizer.py"
    click DummyBackend "https://github.com/aifoundry-org/mhaq/tree/master/src/quantization/dummy/"
    click RNIQBackend "https://github.com/aifoundry-org/mhaq/tree/master/src/quantization/rniq/"
    click DataComposer "https://github.com/aifoundry-org/mhaq/blob/master/src/data/compose/composer.py"
    click CIFAR "https://github.com/aifoundry-org/mhaq/blob/master/src/data/compose/vision/cifar10.py"
    click ImageNet "https://github.com/aifoundry-org/mhaq/blob/master/src/data/compose/vision/imagenet.py"
    click GenData "https://github.com/aifoundry-org/mhaq/blob/master/src/data/gen/cifar_gen_from_labels.py"
    click Trainer "https://github.com/aifoundry-org/mhaq/blob/master/src/training/trainer.py"
    click EarlyStop "https://github.com/aifoundry-org/mhaq/blob/master/src/callbacks/early_stopping.py"
    click LRRevert "https://github.com/aifoundry-org/mhaq/blob/master/src/callbacks/lr_loss_revert.py"
    click NoiseAdjust "https://github.com/aifoundry-org/mhaq/blob/master/src/callbacks/noise_ratio_adjust.py"
    click TempAdjust "https://github.com/aifoundry-org/mhaq/blob/master/src/callbacks/temperature_adjust.py"
    click BWVis "https://github.com/aifoundry-org/mhaq/blob/master/src/callbacks/bw_vis.py"
    click ViolinVis "https://github.com/aifoundry-org/mhaq/blob/master/src/callbacks/violin_vis.py"
    click DefaultLog "https://github.com/aifoundry-org/mhaq/blob/master/src/loggers/default_logger.py"
    click WandBLog "https://github.com/aifoundry-org/mhaq/blob/master/src/loggers/wandb_logger.py"
    click Persistence "https://github.com/aifoundry-org/mhaq/tree/master/data/models/"
    click CLI_RNIQ "https://github.com/aifoundry-org/mhaq/blob/master/scripts/rniq_q_config.py"
    click CLI_DummyCfg "https://github.com/aifoundry-org/mhaq/blob/master/scripts/dummy_q_config.py"
    click CLI_DummyManual "https://github.com/aifoundry-org/mhaq/blob/master/scripts/dummy_q_manual.py"
    click CLI_RNIQVis "https://github.com/aifoundry-org/mhaq/blob/master/scripts/rniq_q_config_vis.py"
    click CLI_ResNet "https://github.com/aifoundry-org/mhaq/blob/master/scripts/training/resnet_train.py"
    click Tests "https://github.com/aifoundry-org/mhaq/blob/master/tests/quant_implementatoin_perf.py"

    %% Styles
    classDef user fill:#ccffcc,stroke:#333,stroke-width:1px;
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef ext fill:#ffd699,stroke:#333,stroke-width:1px;
    classDef persist fill:#dddddd,stroke:#333,stroke-width:1px;
    classDef plugin fill:#e0b3ff,stroke:#333,stroke-width:1px;
```
