# zartbot/shallowsim architecture

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

- Interactive diagram: https://gitdiagram.com/zartbot/shallowsim
- Repository: https://github.com/zartbot/shallowsim

## Overview

##### Project Type and Purpose
- ShallowSim is a simulation tool designed to analyze the inference performance of the DeepSeek-V3/R1 model. It benchmarks different model architectures on various GPU architectures and studies interconnect bus requirements in scale-up and scale-out scenarios.
- The README confirms its dual focus: simulation of model inference performance and analysis of architectural design, while the file tree shows a mix of Python scripts and Jupyter notebooks that drive analysis and visualization.

##### Main Components to Highlight
a. Simulation Engine (Core Module)
- Module File: “shallowsim.py”
b. Configuration & Model Parameters
- Files/Objects: ModelArgs, Config (as initialized in the notebooks)
- Role: Defines the simulation parameters and model-specific settings required to run performance tests.
c. GPU Information and Device Data Handler
- File: “device/gpu_info.csv”
- Role: Acts as an input data source. A component responsible for reading GPU details and providing this information to the simulation engine.
d. Data Analysis and Charting Components
- Files: Jupyter notebooks (e.g., decode.ipynb, prefill.ipynb, model_arch.ipynb) and produced CSV files (e.g., perf_vs_seq_len.csv, perf_vs_n_layers.csv, perf_vs_n_active_experts.csv)
- Role: Notebooks orchestrate simulation runs, data aggregation, result extraction, and plotting of performance metrics (with figures stored in the “figures” directory).
e. Experiment Management
- Files: The various notebooks serve as orchestrators for different simulation aspects (e.g., sequence length analysis, GPU-specific stats).
- Role: They calibrate the simulation by setting parameters (like EP counts, BatchSize, seq_len) and scheduling performance evaluations.

##### Relationships and Interactions
- The simulation process starts by reading the GPU details (from “device/gpu_info.csv”) via a dedicated function (get_gpu_info), which ensures that the simulation uses accurate hardware profiles.
- The ModelArgs and Config classes (or objects) prepare the simulation settings which are then passed into the simulation engine function (decode_time_with_ep_list).
- The final outputs include CSV files for further analysis and figures (performance plots stored under “figures”) that help evaluate the impact of model configurations and GPU interconnect characteristics.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Different components handle configuration (ModelArgs/Config), simulation (shallowsim.py functions), data ingestion (gpu_info.csv), and analysis/visualization (Jupyter notebooks and plotting functions).
- Pipeline/Data Flow: The architecture represents a pipeline—from initial configuration and data ingestion to simulation, result aggregation, and visualization.
- Reusability & Extensibility: With distinct modules doing specific jobs, the design encourages future extension (e.g., adding additional simulation parameters or new visualization techniques) without overhauling the entire system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Layer"
        A["Configuration Module"]:::config
        B["GPU Info Handler"]:::datasource
    end

    %% Core Simulation Engine
    subgraph "Core Simulation"
        C["Simulation Engine (shallowsim.py)"]:::simulation
    end

    %% Experiment Management (Jupyter Notebooks)
    subgraph "Experiment Management"
        D1["decode.ipynb"]:::notebooks
        D2["decode_ep_analysis.ipynb"]:::notebooks
        D3["prefill.ipynb"]:::notebooks
        D4["model_arch.ipynb"]:::notebooks
    end

    %% Data Aggregation & Processing
    subgraph "Data Aggregation"
        F["Data Aggregation & Processing"]:::notebooks
    end

    %% Visualization & Reporting
    subgraph "Visualization & Reporting"
        E1["perf_vs_seq_len.csv"]:::output
        E2["perf_vs_n_layers.csv"]:::output
        E3["perf_vs_n_active_experts.csv"]:::output
        E4["Figures"]:::output
    end

    %% Connections
    A --> C
    B --> C
    C --> D1
    C --> D2
    C --> D3
    C --> D4
    D1 --> F
    D2 --> F
    D3 --> F
    D4 --> F
    F --> E1
    F --> E2
    F --> E3
    F --> E4

    %% Click Events
    click B "https://github.com/zartbot/shallowsim/blob/main/device/gpu_info.csv"
    click C "https://github.com/zartbot/shallowsim/blob/main/shallowsim.py"
    click D1 "https://github.com/zartbot/shallowsim/blob/main/decode.ipynb"
    click D2 "https://github.com/zartbot/shallowsim/blob/main/decode_ep_analysis.ipynb"
    click D3 "https://github.com/zartbot/shallowsim/blob/main/prefill.ipynb"
    click D4 "https://github.com/zartbot/shallowsim/blob/main/model_arch.ipynb"
    click E1 "https://github.com/zartbot/shallowsim/blob/main/perf_vs_seq_len.csv"
    click E2 "https://github.com/zartbot/shallowsim/blob/main/perf_vs_n_layers.csv"
    click E3 "https://github.com/zartbot/shallowsim/blob/main/perf_vs_n_active_experts.csv"
    click E4 "https://github.com/zartbot/shallowsim/tree/main/figures/"

    %% Styles
    classDef config fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef datasource fill:#D5F5E3,stroke:#28B463,stroke-width:2px;
    classDef simulation fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef notebooks fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
    classDef output fill:#D6EAF8,stroke:#2874A6,stroke-width:2px;
```
