# abolfazlbyte/llmcompass_mod architecture

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

- Interactive diagram: https://gitdiagram.com/abolfazlbyte/llmcompass_mod
- Repository: https://github.com/abolfazlbyte/llmcompass_mod

## Overview

##### Project type and purpose
- From the README and file tree, this is an open-source hardware-software co-design and simulation framework (“LLMCompass”) for evaluating large language model (LLM) inference hardware.
- It exposes a modular pipeline to explore design spaces (configs → models → metrics → visualization).

##### File structure
- Top-level directories:
- configs: JSON definitions of hardware templates and experiment scenarios
- hardware_model: Python classes for device, system, compute/memory/io modules, interconnect
- software_model: operator kernels (matmul, layernorm, gelu, transformer, etc.) and communication primitives
- cost_model: performance/area/supply-chain estimation routines
- systolic_array_model: LUT files for array sizes mapping to cycle counts or bandwidth
- design_space_exploration: orchestration entry point (dse.py)
- docs, Dockerfile, environment.yml, utils.py, README.md
- Patterns:
- Pipeline style: config loader → model instantiation → simulation → cost estimation → result output
- Clean separation: hardware vs. software vs. cost vs. exploration logic

##### README for additional insights
- The user guide (docs/run.md) describes how to run simulations for each figure/experiment.
- Dependencies: Python 3.9, scalesim, PyTorch, matplotlib, seaborn, scipy.
- Dockerfile for reproducibility.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration
    subgraph "Configuration"
        CM["Configuration Manager"]:::data
    end

    %% Exploration
    DSE["Design Space Explorer"]:::core

    %% Hardware Model Subsystem
    subgraph "Hardware Model"
        HM_Device["Device"] 
        HM_System["System"]
        HM_Compute["Compute Module"]
        HM_Memory["Memory Module"]
        HM_IO["IO Module"] 
        HM_Interconnect["Interconnect"]
        HM_Arch["Arch Template"]
    end

    %% Software Model Subsystem
    subgraph "Software Model"
        SM_Operators["Operator Kernels"]
        SM_Comm["Communication Primitives"]
    end

    %% Cost Model Subsystem
    subgraph "Cost Model"
        CM_Core["Core Estimation Routines"]
        CM_Area["Area Estimation"]
        CM_Supply["Supply Chain Integration"]
        CM_Examples["Examples/Helpers"]
    end

    %% Systolic Array Model
    SAM["Systolic Array LUTs"]:::data

    %% Results & Visualization
    Results["Results & Visualization"]:::io

    %% Deployment & Environment
    Deploy["Deployment & Environment"]:::io
    Docs["Documentation & Run Instructions"]:::io
    Utils["Utility Scripts"]:::io

    %% External Dependencies
    subgraph "External Dependencies"
        Ext_ScaleSim["scalesim"]:::external
        Ext_PyTorch["PyTorch"]:::external
        Ext_Plot["Matplotlib/Seaborn/SciPy"]:::external
    end

    %% Data Flows
    CM -->|loads configs| DSE
    DSE -->|orchestrates| HM_Device
    DSE -->|orchestrates| SM_Operators
    SM_Operators -->|invoke patterns| HM_Compute
    HM_Compute -->|lookup cycles| SAM
    HM_System --> SAM
    HM_Device -->|components| HM_System
    HM_Compute -->|component| HM_System
    HM_Memory -->|component| HM_System
    HM_IO -->|component| HM_System
    HM_Interconnect -->|component| HM_System
    DSE -->|collects metrics| CM_Core
    HM_System --> CM_Core
    SM_Operators --> CM_Core
    CM_Area --> CM_Core
    CM_Supply --> CM_Core
    CM_Core --> CM_Examples
    DSE -->|forwards to| Results

    %% Deployment & Docs
    Deploy --> DSE
    Docs --> DSE
    Utils --> DSE

    %% External integrations
    Ext_ScaleSim --> HM_Device
    Ext_PyTorch --> SM_Operators
    Ext_Plot --> Results

    %% Styling
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef data fill:#98FB98,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef io fill:#FFE4B5,stroke:#000,stroke-width:1px

    %% Click Events
    click CM "https://github.com/abolfazlbyte/llmcompass_mod/tree/main/configs/"
    click DSE "https://github.com/abolfazlbyte/llmcompass_mod/blob/main/design_space_exploration/dse.py"
    click HM_Device "https://github.com/abolfazlbyte/llmcompass_mod/blob/main/hardware_model/device.py"
    click HM_System "https://github.com/abolfazlbyte/llmcompass_mod/blob/main/hardware_model/system.py"
    click HM_Compute "https://github.com/abolfazlbyte/llmcompass_mod/blob/main/hardware_model/compute_module.py"
    click HM_Memory "https://github.com/abolfazlbyte/llmcompass_mod/blob/main/hardware_model/memory_module.py"
    click HM_IO "https://github.com/abolfazlbyte/llmcompass_mod/blob/main/hardware_model/io_module.py"
    click HM_Interconnect "https://github.com/abolfazlbyte/llmcompass_mod/blob/main/hardware_model/interconnect.py"
    click HM_Arch "https://github.com/abolfazlbyte/llmcompass_mod/blob/main/hardware_model/arch_template.py"
    click SM_Operators "https://github.com/abolfazlbyte/llmcompass_mod/blob/main/software_model/operators.py"
    click SM_Comm "https://github.com/abolfazlbyte/llmcompass_mod/blob/main/software_model/communication_primitives.py"
    click SM_Operators "https://github.com/abolfazlbyte/llmcompass_mod/blob/main/software_model/matmul.py"
    click SM_Operators "https://github.com/abolfazlbyte/llmcompass_mod/blob/main/software_model/layernorm.py"
    click SM_Operators "https://github.com/abolfazlbyte/llmcompass_mod/blob/main/software_model/gelu.py"
    click SM_Operators "https://github.com/abolfazlbyte/llmcompass_mod/blob/main/software_model/softmax.py"
    click SM_Operators "https://github.com/abolfazlbyte/llmcompass_mod/blob/main/software_model/transformer.py"
    click SM_Comm "https://github.com/abolfazlbyte/llmcompass_mod/blob/main/software_model/utils.py"
    click CM_Core "https://github.com/abolfazlbyte/llmcompass_mod/blob/main/cost_model/cost_model.py"
    click CM_Area "https://github.com/abolfazlbyte/llmcompass_mod/blob/main/cost_model/regfile_area.py"
    click CM_Supply "https://github.com/abolfazlbyte/llmcompass_mod/tree/main/cost_model/supply_chain/"
    click CM_Examples "https://github.com/abolfazlbyte/llmcompass_mod/blob/main/cost_model/cost_examples.py"
    click SAM "https://github.com/abolfazlbyte/llmcompass_mod/tree/main/systolic_array_model/"
    click Deploy "https://github.com/abolfazlbyte/llmcompass_mod/tree/main/Dockerfile"
    click Deploy "https://github.com/abolfazlbyte/llmcompass_mod/blob/main/environment.yml"
    click Docs "https://github.com/abolfazlbyte/llmcompass_mod/blob/main/README.md"
    click Docs "https://github.com/abolfazlbyte/llmcompass_mod/blob/main/docs/run.md"
    click Utils "https://github.com/abolfazlbyte/llmcompass_mod/blob/main/utils.py"
```
