# kiaghods/butterfly_matrix_kernel architecture

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

- Interactive diagram: https://gitdiagram.com/kiaghods/butterfly_matrix_kernel
- Repository: https://github.com/kiaghods/butterfly_matrix_kernel

## Overview

Step 1: Identify Project Type and Purpose
- This is an open-source, high-performance numerical library/tool focused on butterfly matrix multiplication and related FFT kernels on NVIDIA GPUs.
- It provides Triton GPU kernels, a PyTorch nn.Module wrapper, reference implementations, and a full suite of testing, profiling, benchmarking and optimization scripts.

Step 2: Analyze File Structure
Top-level components:
##### Core computation
- triton_kernel.py         – main butterfly GPU kernel
- triton_fft_kernel.py     – discrete FFT using butterfly kernels
- reference_impl.py        – pure‐PyTorch reference for correctness
##### Python module interface
- butterfly_module.py      – PyTorch nn.Module wrapper (ButterflyLayer)
##### Testing
- unittests/               – pytest unit tests (correctness, numwarp tuning)
- testing/                 – standalone correctness harness
##### Profiling
- profiling/torch_profiler.py   – PyTorch profiler integration
- profiling/memory_profiler.py  – memory usage profiling
- profiling/visualization.py    – SQLite-based Nsight Systems visualization
##### Benchmarking
- benchmarking/performance_bench.py – performance comparison script
##### Optimization
- optimization/numwarp_tuning.py  – warp‐count tuning
- optimization/fused_kernel.py    – L=8 fused stage kernel
- optimization/pipelined_kernel.py– pipelined stage kernel
##### Automation scripts
- scripts/run_profiling.py
- scripts/run_benchmarks.py
##### Results & artifacts
- results/                     – stored profiles, benchmarks, plots, optimization data

Step 3: README Insights
- The README clearly describes each component’s role, usage examples, and the optimization strategies (kernel fusion, pipelining, num_warps).
- It details the FFT implementation as a special use-case of butterfly matmul.

1. User/API Layer
– ButterflyLayer (PyTorch nn.Module)
– FFT wrapper
2. Core GPU Engines
– Triton butterfly kernel
– Triton FFT butterfly stage kernel
3. Reference Implementation
– PyTorch‐only matmul in reference_impl.py
4. Testing Suite
– pytest (unittests/)
– correctness_harness (testing/)
5. Profiling Tools
– TorchProfiler integration
– MemoryProfiler
– Nsight Systems → visualization
6. Benchmarking Suite
– performance_bench.py
7. Optimization Scripts
– numwarp tuning
– pipelining kernel
– fused kernel (L=8)
8. Automation & CI Scripts
– run_profiling.py
– run_benchmarks.py
9. Results Storage
– results/profiles, benchmarks, plots, optimization outputs

– User/API Layer → Core GPU Engines (runtime calls)
– Core GPU Engines ↔ Reference Implementation (correctness validation)
– Testing Suite → API Layer & Core Engines (executes both)
– Profiling Tools ⟶ Core Engines & API Layer (collect metrics)
– Benchmarking Suite ⟶ Core Engines & Reference Impl (performance comparison)
– Optimization Scripts ⟶ Core Engines (generate and test variants)
– Automation Scripts orchestrate Testing, Profiling, Benchmarking
– Results Storage ← all tools (profiling, benchmarking, optimization)

c. Architectural Patterns & Principles
– Layered design: API wrapper, core compute, utilities
– Separation of concerns: computation vs. testing vs. profiling vs. benchmarking
– Data flow: from input tensors → kernels → outputs, then into testing/profiling/benchmarking tools

d. Key Technologies & Frameworks
– Triton (GPU kernels)
– PyTorch (tensor ops, autograd, nn.Module)
– pytest (unit tests)
– Nsight Systems / PyTorch profiler / memory_profiler
– Python scripting for orchestration

- **core functionality**: GPU kernels and how they integrate with PyTorch.
- **extensibility points**: reference vs. optimized kernels, custom tuning scripts.
- **integration**: how profiling and benchmarking plug into the workflow.

Step 6: Diagramming Guidelines
- Use clear, descriptive labels on each node (e.g., “Triton Butterfly Kernel”, “ButterflyLayer nn.Module”).
- Green for core compute engines
- Blue for orchestration/scripts
- Orange for testing/profiling/benchmarking
- Gray for results storage
- Rectangles for code modules
- Parallelograms for user/API interfaces

Step 7: Detailed Capture of Essential Architectural Elements
- Layer (API, compute, validation, instrumentation, storage) is represented.
- Interactions with brief notes (e.g., “compare performance”, “validate output”).
- If space permits, include version or dependencies (e.g., “requires CUDA compute capability ≥7.0”, “Python 3.10+”).

## Diagram (Mermaid)

```mermaid
graph TB
    %% API Layer
    ButterflyLayer[/"ButterflyLayer nn.Module"/]:::api
    FFTWrapper[/"FFT Wrapper"/]:::api

    %% Core Compute
    subgraph "Core GPU Engines"
        direction TB
        TritonButterfly["Triton Butterfly Kernel"]:::coreCompute
        TritonFFT["Triton FFT Butterfly Kernel"]:::coreCompute
    end

    %% Reference Implementation
    ReferenceImpl["Reference Implementation"]:::coreCompute

    %% Testing Suite
    subgraph "Testing Suite"
        direction TB
        UnitTests["pytest (unittests/)"]:::testProfile
        CorrectnessHarness["Correctness Harness"]:::testProfile
    end

    %% Profiling Tools
    subgraph "Profiling Tools"
        direction TB
        TorchProfiler["Torch Profiler Integration"]:::testProfile
        MemoryProfiler["Memory Profiler"]:::testProfile
        NsightVis["Nsight Systems Visualization"]:::testProfile
    end

    %% Benchmarking
    BenchmarkSuite["Benchmarking Suite"]:::testProfile

    %% Optimization Scripts
    subgraph "Optimization Scripts"
        direction TB
        NumwarpTuning["Numwarp Tuning"]:::coreCompute
        FusedKernel["Fused Kernel (L=8)"]:::coreCompute
        PipelinedKernel["Pipelined Kernel"]:::coreCompute
    end

    %% Automation Scripts
    subgraph "Automation & CI Scripts"
        direction TB
        RunProfiling["Run Profiling Script"]:::orchestration
        RunBenchmarks["Run Benchmarks Script"]:::orchestration
    end

    %% Results Storage
    Results["Results Storage"]:::storage

    %% Data/Control Flow (black)
    ButterflyLayer -->|calls| TritonButterfly
    ButterflyLayer -->|calls| TritonFFT
    FFTWrapper -->|wraps| TritonFFT
    TritonButterfly <-->|validate| ReferenceImpl
    UnitTests -->|tests| ButterflyLayer
    UnitTests -->|tests| TritonButterfly
    UnitTests -->|tests| TritonFFT
    CorrectnessHarness -->|harness| ButterflyLayer
    CorrectnessHarness -->|harness| TritonFFT
    TorchProfiler -->|profiles| TritonButterfly
    TorchProfiler -->|profiles| ButterflyLayer
    MemoryProfiler -->|profiles| TritonButterfly
    NsightVis -->|visualize| TritonButterfly
    BenchmarkSuite -->|benchmarks| TritonButterfly
    BenchmarkSuite -->|benchmarks| ReferenceImpl
    NumwarpTuning -->|tunes| TritonButterfly
    FusedKernel -->|optimizes| TritonButterfly
    PipelinedKernel -->|optimizes| TritonButterfly

    %% Orchestration (blue arrows)
    RunProfiling -.->|orchestrates| UnitTests
    RunProfiling -.->|orchestrates| TorchProfiler
    RunProfiling -.->|orchestrates| MemoryProfiler
    RunProfiling -.->|orchestrates| NsightVis
    RunBenchmarks -.->|orchestrates| BenchmarkSuite
    RunBenchmarks -.->|orchestrates| UnitTests

    %% Results storage (all tools)
    TorchProfiler -->|outputs| Results
    MemoryProfiler -->|outputs| Results
    NsightVis -->|outputs| Results
    BenchmarkSuite -->|outputs| Results
    NumwarpTuning -->|outputs| Results
    FusedKernel -->|outputs| Results
    PipelinedKernel -->|outputs| Results
    UnitTests -->|logs| Results
    CorrectnessHarness -->|logs| Results

    %% Click Events
    click TritonButterfly "https://github.com/kiaghods/butterfly_matrix_kernel/blob/master/triton_kernel.py"
    click TritonFFT "https://github.com/kiaghods/butterfly_matrix_kernel/blob/master/triton_fft_kernel.py"
    click ReferenceImpl "https://github.com/kiaghods/butterfly_matrix_kernel/blob/master/reference_impl.py"
    click ButterflyLayer "https://github.com/kiaghods/butterfly_matrix_kernel/blob/master/butterfly_module.py"
    click UnitTests "https://github.com/kiaghods/butterfly_matrix_kernel/tree/master/unittests/"
    click CorrectnessHarness "https://github.com/kiaghods/butterfly_matrix_kernel/blob/master/testing/correctness_harness.py"
    click TorchProfiler "https://github.com/kiaghods/butterfly_matrix_kernel/blob/master/profiling/torch_profiler.py"
    click MemoryProfiler "https://github.com/kiaghods/butterfly_matrix_kernel/blob/master/profiling/memory_profiler.py"
    click NsightVis "https://github.com/kiaghods/butterfly_matrix_kernel/blob/master/profiling/visualization.py"
    click BenchmarkSuite "https://github.com/kiaghods/butterfly_matrix_kernel/blob/master/benchmarking/performance_bench.py"
    click NumwarpTuning "https://github.com/kiaghods/butterfly_matrix_kernel/blob/master/optimization/numwarp_tuning.py"
    click FusedKernel "https://github.com/kiaghods/butterfly_matrix_kernel/blob/master/optimization/fused_kernel.py"
    click PipelinedKernel "https://github.com/kiaghods/butterfly_matrix_kernel/blob/master/optimization/pipelined_kernel.py"
    click RunProfiling "https://github.com/kiaghods/butterfly_matrix_kernel/blob/master/scripts/run_profiling.py"
    click RunBenchmarks "https://github.com/kiaghods/butterfly_matrix_kernel/blob/master/scripts/run_benchmarks.py"
    click Results "https://github.com/kiaghods/butterfly_matrix_kernel/tree/master/results/"

    %% Styles
    classDef coreCompute fill:#a2d5a1,stroke:#333,stroke-width:1px
    classDef orchestration fill:#add8e6,stroke:#333,stroke-width:1px
    classDef testProfile fill:#f4a261,stroke:#333,stroke-width:1px
    classDef storage fill:#c0c0c0,stroke:#333,stroke-width:1px
    classDef api fill:#ffe4b5,stroke:#333,stroke-width:1px shape:parallelogram
```
