# joennlae/halutmatmul architecture

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

- Interactive diagram: https://gitdiagram.com/joennlae/halutmatmul
- Repository: https://github.com/joennlae/halutmatmul

## Overview

##### Project type and purpose
- This is a heterogeneous accelerator project (“Stella Nera”) combining:
- An algorithmic/software stack (Python library “halutmatmul,” training scripts, model definitions, tests, example) that implements the Maddness‐based approximate matrix multiplication method.
- A hardware stack (SystemVerilog RTL, verification suites, OpenROAD synthesis & P&R flows, post‐layout simulation) realizing the accelerator in silicon.
- Purpose: provide both a software reference and a fully open‐source hardware implementation of a multiplier‐free DNN matmul accelerator.

##### File structure
- Top‐level directories:
- src/python – the Python package, subdivided into:
– concepts: unit tests and algorithmic building blocks
– halutmatmul: core library, CUDA functions, learning & inference code
– models: PyTorch models (ResNet variants, tiny nets)
– training: training scripts, presets, quantization routines
– test: pytest suites for algorithmic validation
– example.py – a stand‑alone usage demo
- hardware – the accelerator RTL and build flows:
– rtl – SystemVerilog modules (halut_encoder, halut_decoder, halut_matmul, support units)
– target – various flows:
- dv – Python testbenches & DV scripts
- open‑frontend, open‑synth‑and‑pnr – OpenROAD flow configurations & Makefiles
- post‑layout‑simulation – Sim scripts for extracted netlists
- scaling – helper scripts to adapt hardware width & units
– util – scripts for docs/table generation
– Dockerfile & Makefile for local builds
- config files: environment_*.yml for conda, pyproject.toml, GitHub workflows for CI.

##### Key insights from README
- Two pillars:
a) Algorithmic (Maddness) – offline training, LUT/threshold generation, numpy/CUDA/PyTorch-based inference.
b) Hardware (OpenROAD) – from RTL to GDS with fully open toolchain, including DV and post-layout simulation.
- Emphasis on code/CI badges for Python testing, type checking, ML validation (ResNet9), RTL linting, DV, synthesis+PNR.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Environment & CI
    subgraph "Environment & CI"
        CI_CondaCPU["environment_cpu.yml"]:::env
        CI_CondaGPU["environment_gpu.yml"]:::env
        CI_CondaHW["hardware/environment_hw.yml"]:::env
        CI_PyProj["pyproject.toml"]:::env
        CI_Workflows["GitHub Actions Workflows"]:::env
    end

    %% Software Stack
    subgraph "Software Stack"
        direction TB
        subgraph "Data & Model Layer"
            D["Data & Model Layer"]:::software
        end
        subgraph "HalutMatmul Library"
            direction TB
            H1["__init__.py"]:::software
            H2["functions.py"]:::software
            H3["halutmatmul.py"]:::software
            H4["learn.py"]:::software
            H5["maddness.py"]:::software
            H6["maddness_multisplit.py"]:::software
            H7["model.py"]:::software
            H8["modules.py"]:::software
            H9["cuda/functions.py"]:::software
        end
        subgraph "Example & Test Harness"
            direction TB
            E1["example.py"]:::software
            E2["concepts/"]:::software
            E3["test/"]:::software
        end
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        direction TB
        T1["train.py"]:::software
        T2["train_quantization.py"]:::software
        T3["presets.py"]:::software
        T4["utils_train.py"]:::software
        T5["timm_model.py"]:::software
    end

    %% Hardware Stack
    subgraph "Hardware Stack"
        direction TB
        subgraph "RTL Modules"
            R1["halut_encoder.sv"]:::hardware
            R2["halut_decoder.sv"]:::hardware
            R3["halut_matmul.sv"]:::hardware
            R4["halut_pkg.sv"]:::hardware
        end
        subgraph "Verification Environment (DV)"
            DV["hardware/target/dv/"]:::hardware
        end
        subgraph "Synthesis & P&R Flow"
            S1["open-frontend"]:::hardware
            S2["open-synth-and-pnr"]:::hardware
            S3["Makefile"]:::hardware
            S4["Dockerfile"]:::hardware
        end
        subgraph "Post-Layout Simulation"
            PLS["post-layout-simulation/"]:::hardware
        end
    end

    %% LUTs
    LUT["LUTs & Thresholds"]:::software

    %% Relationships
    T1 -->|generates| LUT
    T2 -->|generates| LUT
    T3 -->|generates| LUT
    T4 -->|generates| LUT
    T5 -->|generates| LUT
    LUT -->|used by| H3
    LUT -->|parameterizes| R1
    H3 -- test --> E3
    E2 -- test blocks --> H1
    DV -- tests --> R1
    DV -- tests --> R2
    DV -- tests --> R3
    DV -- tests --> R4
    R1 -->|synth & P&R| S2
    R2 -->|synth & P&R| S2
    R3 -->|synth & P&R| S2
    R4 -->|synth & P&R| S2
    S2 -->|produces netlist| PLS
    %% CI triggers all
    CI_CondaCPU --> CI_Workflows
    CI_CondaGPU --> CI_Workflows
    CI_CondaHW --> CI_Workflows
    CI_PyProj --> CI_Workflows
    D --> CI_Workflows
    H1 --> CI_Workflows
    R1 --> CI_Workflows

    %% Click events
    click D "https://github.com/joennlae/halutmatmul/tree/master/src/python/models"
    click T1 "https://github.com/joennlae/halutmatmul/blob/master/src/python/training/train.py"
    click T2 "https://github.com/joennlae/halutmatmul/blob/master/src/python/training/train_quantization.py"
    click T3 "https://github.com/joennlae/halutmatmul/blob/master/src/python/training/presets.py"
    click T4 "https://github.com/joennlae/halutmatmul/blob/master/src/python/training/utils_train.py"
    click T5 "https://github.com/joennlae/halutmatmul/blob/master/src/python/training/timm_model.py"
    click H1 "https://github.com/joennlae/halutmatmul/blob/master/src/python/halutmatmul/__init__.py"
    click H2 "https://github.com/joennlae/halutmatmul/blob/master/src/python/halutmatmul/functions.py"
    click H3 "https://github.com/joennlae/halutmatmul/blob/master/src/python/halutmatmul/halutmatmul.py"
    click H4 "https://github.com/joennlae/halutmatmul/blob/master/src/python/halutmatmul/learn.py"
    click H5 "https://github.com/joennlae/halutmatmul/blob/master/src/python/halutmatmul/maddness.py"
    click H6 "https://github.com/joennlae/halutmatmul/blob/master/src/python/halutmatmul/maddness_multisplit.py"
    click H7 "https://github.com/joennlae/halutmatmul/blob/master/src/python/halutmatmul/model.py"
    click H8 "https://github.com/joennlae/halutmatmul/blob/master/src/python/halutmatmul/modules.py"
    click H9 "https://github.com/joennlae/halutmatmul/blob/master/src/python/halutmatmul/cuda/functions.py"
    click E1 "https://github.com/joennlae/halutmatmul/blob/master/src/python/example.py"
    click E2 "https://github.com/joennlae/halutmatmul/tree/master/src/python/concepts"
    click E3 "https://github.com/joennlae/halutmatmul/tree/master/src/python/test"
    click R1 "https://github.com/joennlae/halutmatmul/blob/master/hardware/rtl/halut_encoder.sv"
    click R2 "https://github.com/joennlae/halutmatmul/blob/master/hardware/rtl/halut_decoder.sv"
    click R3 "https://github.com/joennlae/halutmatmul/blob/master/hardware/rtl/halut_matmul.sv"
    click R4 "https://github.com/joennlae/halutmatmul/blob/master/hardware/rtl/halut_pkg.sv"
    click DV "https://github.com/joennlae/halutmatmul/tree/master/hardware/target/dv"
    click S1 "https://github.com/joennlae/halutmatmul/tree/master/hardware/target/open-frontend"
    click S2 "https://github.com/joennlae/halutmatmul/tree/master/hardware/target/open-synth-and-pnr"
    click S3 "https://github.com/joennlae/halutmatmul/tree/master/hardware/Makefile"
    click S4 "https://github.com/joennlae/halutmatmul/tree/master/hardware/Dockerfile"
    click PLS "https://github.com/joennlae/halutmatmul/tree/master/hardware/target/post-layout-simulation"
    click CI_CondaCPU "https://github.com/joennlae/halutmatmul/blob/master/environment_cpu.yml"
    click CI_CondaGPU "https://github.com/joennlae/halutmatmul/blob/master/environment_gpu.yml"
    click CI_CondaHW "https://github.com/joennlae/halutmatmul/blob/master/hardware/environment_hw.yml"
    click CI_PyProj "https://github.com/joennlae/halutmatmul/blob/master/pyproject.toml"
    click CI_Workflows "https://github.com/joennlae/halutmatmul/blob/master/.github/workflows/python_testing.yaml"

    %% Styles
    classDef software fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef hardware fill:#98FB98,stroke:#333,stroke-width:1px
    classDef env fill:#D3D3D3,stroke:#333,stroke-width:1px
```
