# prasanthrayudu313/cxl-kv-simulation architecture

> Architecture diagram of the GitHub repository prasanthrayudu313/cxl-kv-simulation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prasanthrayudu313/cxl-kv-simulation
- Repository: https://github.com/prasanthrayudu313/cxl-kv-simulation

## Overview

CXL KV-Cache Simulator models LLM request handling and KV placement across GPU HBM and shared CXL memory. Its principal workflow generates requests, admits them under a placement policy, simulates prefill/decode (or split prefill/decode), and records performance and memory metrics. Workload variants, compression, cost modeling, and experiment runners support research comparisons; the dashboard is a separate in-browser visualization. Connections for unsampled modules are limited to documented capabilities and SOURCE INDEX references.

Main entry points: [`core/engine.py`](https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/core/engine.py) (Coupled Engine), [`experiments/run_all_new.py`](https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/experiments/run_all_new.py) (Experiment Suites), [`core/disaggregated_engine.py`](https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/core/disaggregated_engine.py) (Disaggregated Engine), [`config.py`](https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/config.py) (Hardware Config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Simulation Runtime"]
  node_runner["Simulation Runner<br/>[run_simulation.py]"]
  node_engine["Coupled Engine<br/>[engine.py]"]
  node_disagg["Disaggregated Engine"]
  node_models["Request &amp; Metrics<br/>[models.py]"]
  node_config["Hardware Config<br/>[config.py]"]
end

subgraph group_memory["KV Placement"]
  node_placement["Placement Policies<br/>[placement.py]"]
end

subgraph group_workloads["Workload Inputs"]
  node_synthetic["Synthetic Workload<br/>[generator.py]"]
  node_sharegpt["ShareGPT Workload<br/>[sharegpt.py]"]
  node_multiturn["Multi-turn Workload<br/>[multiturn.py]"]
end

subgraph group_research["Research Evaluation"]
  node_experiments["Experiment Suites<br/>[run_all_new.py]"]
  node_extended["Extended Experiments<br/>[run_extended.py]"]
  node_plots["Result Plotting<br/>[plot_results.py]"]
  node_compression["KV Compression<br/>[compression.py]"]
  node_accuracy["Compression Accuracy"]
  node_cost["Cost Model<br/>[cost_model.py]"]
end

subgraph group_ui["Visualization"]
  node_dashboard["Browser Dashboard<br/>[index.html]"]
end

node_operator(("Researcher"))

node_operator -->|"runs"| node_runner
node_runner -->|"creates"| node_engine
node_engine -->|"generates requests"| node_synthetic
node_engine -->|"admits and evicts"| node_placement
node_engine -->|"tracks request state"| node_models
node_engine -->|"uses parameters"| node_config
node_disagg -->|"generates requests"| node_synthetic
node_disagg -->|"admits requests"| node_placement
node_disagg -->|"tracks request state"| node_models
node_disagg -->|"uses parameters"| node_config
node_synthetic -->|"creates requests"| node_models
node_synthetic -->|"reads distributions"| node_config
node_sharegpt -->|"creates requests"| node_models
node_multiturn -->|"reads workload settings"| node_config
node_experiments -->|"runs comparisons"| node_engine
node_experiments -->|"compares architectures"| node_disagg
node_experiments -->|"sweeps compression"| node_compression
node_experiments -->|"uses cost model"| node_cost
node_experiments -->|"runs sessions"| node_multiturn
node_experiments -->|"compares policies"| node_placement
node_extended -->|"runs calibrated traces"| node_sharegpt
node_extended -->|"runs sessions"| node_multiturn
node_extended -->|"runs simulations"| node_engine
node_accuracy -.->|"evaluates accuracy"| node_compression
node_operator -->|"opens"| node_dashboard
node_dashboard -->|"aligns constants"| node_config
node_operator -->|"plots results"| node_plots

click node_runner "https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/run_simulation.py"
click node_engine "https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/core/engine.py"
click node_disagg "https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/core/disaggregated_engine.py"
click node_models "https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/core/models.py"
click node_config "https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/config.py"
click node_placement "https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/policies/placement.py"
click node_synthetic "https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/workload/generator.py"
click node_sharegpt "https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/workload/sharegpt.py"
click node_multiturn "https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/workload/multiturn.py"
click node_experiments "https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/experiments/run_all_new.py"
click node_extended "https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/experiments/run_extended.py"
click node_plots "https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/experiments/plot_results.py"
click node_compression "https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/core/compression.py"
click node_accuracy "https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/core/compression_accuracy.py"
click node_cost "https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/core/cost_model.py"
click node_dashboard "https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/dashboard/index.html"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runner,node_engine,node_disagg,node_models,node_config toneBlue
class node_placement toneAmber
class node_synthetic,node_sharegpt,node_multiturn toneMint
class node_experiments,node_extended,node_plots,node_compression,node_accuracy,node_cost toneRose
class node_dashboard,node_operator toneIndigo
```

## Components

### Simulation Runtime

- [Simulation Runner](https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/run_simulation.py): `run_simulation.py`
- [Coupled Engine](https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/core/engine.py): `core/engine.py`
- [Disaggregated Engine](https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/core/disaggregated_engine.py): `core/disaggregated_engine.py`
- [Request & Metrics](https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/core/models.py): `core/models.py`
- [Hardware Config](https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/config.py): `config.py`

### KV Placement

- [Placement Policies](https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/policies/placement.py): `policies/placement.py`

### Workload Inputs

- [Synthetic Workload](https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/workload/generator.py): `workload/generator.py`
- [ShareGPT Workload](https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/workload/sharegpt.py): `workload/sharegpt.py`
- [Multi-turn Workload](https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/workload/multiturn.py): `workload/multiturn.py`

### Research Evaluation

- [Experiment Suites](https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/experiments/run_all_new.py): `experiments/run_all_new.py`
- [Extended Experiments](https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/experiments/run_extended.py): `experiments/run_extended.py`
- [Result Plotting](https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/experiments/plot_results.py): `experiments/plot_results.py`
- [KV Compression](https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/core/compression.py): `core/compression.py`
- [Compression Accuracy](https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/core/compression_accuracy.py): `core/compression_accuracy.py`
- [Cost Model](https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/core/cost_model.py): `core/cost_model.py`

### Visualization

- [Browser Dashboard](https://github.com/prasanthrayudu313/cxl-kv-simulation/blob/main/dashboard/index.html): `dashboard/index.html`

### Other components

- **Researcher**

## Connections

- Researcher → Simulation Runner: runs (evidence: `README.md`)
- Simulation Runner → Coupled Engine: creates (evidence: `run_simulation.py`)
- Coupled Engine → Synthetic Workload: generates requests (evidence: `core/engine.py`)
- Coupled Engine → Placement Policies: admits and evicts (evidence: `core/engine.py`)
- Coupled Engine → Request & Metrics: tracks request state (evidence: `core/engine.py`)
- Coupled Engine → Hardware Config: uses parameters (evidence: `core/engine.py`)
- Disaggregated Engine → Synthetic Workload: generates requests (evidence: `core/disaggregated_engine.py`)
- Disaggregated Engine → Placement Policies: admits requests (evidence: `core/disaggregated_engine.py`)
- Disaggregated Engine → Request & Metrics: tracks request state (evidence: `core/disaggregated_engine.py`)
- Disaggregated Engine → Hardware Config: uses parameters (evidence: `core/disaggregated_engine.py`)
- Synthetic Workload → Request & Metrics: creates requests (evidence: `workload/generator.py`)
- Synthetic Workload → Hardware Config: reads distributions (evidence: `workload/generator.py`)
- ShareGPT Workload → Request & Metrics: creates requests (evidence: `workload/sharegpt.py`)
- Multi-turn Workload → Hardware Config: reads workload settings (evidence: `workload/multiturn.py`)
- Experiment Suites → Coupled Engine: runs comparisons (evidence: `experiments/run_all_new.py`)
- Experiment Suites → Disaggregated Engine: compares architectures (evidence: `experiments/run_all_new.py`)
- Experiment Suites → KV Compression: sweeps compression (evidence: `experiments/run_all_new.py`)
- Experiment Suites → Cost Model: uses cost model (evidence: `experiments/run_all_new.py`)
- Experiment Suites → Multi-turn Workload: runs sessions (evidence: `experiments/run_all_new.py`)
- Experiment Suites → Placement Policies: compares policies (evidence: `experiments/run_all_new.py`)
- Extended Experiments → ShareGPT Workload: runs calibrated traces (evidence: `experiments/run_extended.py`)
- Extended Experiments → Multi-turn Workload: runs sessions (evidence: `experiments/run_extended.py`)
- Extended Experiments → Coupled Engine: runs simulations (evidence: `experiments/run_extended.py`)
- Compression Accuracy → KV Compression: evaluates accuracy
- Researcher → Browser Dashboard: opens (evidence: `README.md`)
- Browser Dashboard → Hardware Config: aligns constants (evidence: `README.md`)
- Researcher → Result Plotting: plots results (evidence: `README.md`)