# wangyuyue/simpyssd architecture

> Architecture diagram of the GitHub repository wangyuyue/simpyssd, 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/wangyuyue/simpyssd
- Repository: https://github.com/wangyuyue/simpyssd

## Overview

SimpySSD models BeaconGNN workloads executing with in-storage graph sampling on configurable SSD, system, and accelerator designs. The principal workflow starts in the experiment runner: it selects a workload and configurations, builds a graph and sampled subgraphs, runs GNN requests through an event-driven SSD/system model, then collects and plots latency, utilization, speedup, and energy results. The graph preserves documented experiment and analysis stages; implementation links are limited to relationships visible in excerpts or the SOURCE INDEX.

Main entry points: [`src/main.py`](https://github.com/wangyuyue/simpyssd/blob/dev/src/main.py) (Experiment Runner), [`src/system.py`](https://github.com/wangyuyue/simpyssd/blob/dev/src/system.py) (System Model), [`src/accel_config.py`](https://github.com/wangyuyue/simpyssd/blob/dev/src/accel_config.py) (Accelerator Configuration), [`src/gnn.py`](https://github.com/wangyuyue/simpyssd/blob/dev/src/gnn.py) (GNN Execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workload["Workload Modeling"]
  node_runner["Experiment Runner<br/>[main.py]"]
  node_graph["Graph Workloads<br/>[graph.py]"]
  node_subgraph["Subgraph Sampling<br/>[subgraph.py]"]
  node_gnn["GNN Execution<br/>[gnn.py]"]
  node_topology["Accelerator Topology<br/>[gnn_topology.py]"]
end

subgraph group_simulation["Device Simulation"]
  node_engine["Event Engine<br/>[sim.py]"]
  node_ssd["SSD Model<br/>[ssd_estimate.py]"]
  node_system["System Model<br/>[system.py]"]
  node_dram["DRAM Model<br/>[dram.py]"]
  node_pcie["PCIe Model<br/>[pcie.py]"]
  node_accelerator["Accelerator Model<br/>[nn_accel.py]"]
end

subgraph group_configuration["Design Configuration"]
  node_ssdconfig["SSD Configuration<br/>[ssd_config.py]"]
  node_systemconfig["System Configuration<br/>[system_config.py]"]
  node_accelconfig["Accelerator Configuration<br/>[accel_config.py]"]
  node_ssdprofiles["SSD Profiles"]
  node_systemprofiles["System Profiles"]
  node_accelprofiles["Accelerator Profiles"]
end

subgraph group_analysis["Results Analysis"]
  node_stats["Simulation Statistics<br/>[sys_stat.py]"]
  node_energy["Energy Estimation<br/>[energy_estimate.py]"]
  node_latency["Latency Analysis<br/>[dataframe.py]"]
  node_dump["Result Export<br/>[dump.py]"]
  node_plot["Result Plotting<br/>[plot.py]"]
  node_series["Series Processing<br/>[series_process.py]"]
end

node_user(("Experiment User"))
node_external_scalesim["Scale-Sim Tool"]

node_user -->|"starts experiments"| node_runner
node_runner -->|"builds workload"| node_graph
node_runner -->|"samples subgraphs"| node_subgraph
node_runner -->|"runs workload"| node_gnn
node_gnn -->|"queries graph"| node_graph
node_gnn -->|"issues commands"| node_ssd
node_runner -->|"creates system"| node_system
node_system -->|"instantiates SSD"| node_ssd
node_system -->|"uses PCIe"| node_pcie
node_system -->|"uses accelerator"| node_accelerator
node_system -->|"uses DRAM"| node_dram
node_ssd -->|"schedules events"| node_engine
node_runner -->|"executes events"| node_engine
node_runner -->|"loads profile"| node_ssdconfig
node_runner -->|"selects profile"| node_systemconfig
node_runner -->|"sets accelerator"| node_accelconfig
node_ssdconfig -.->|"reads settings"| node_ssdprofiles
node_systemconfig -->|"reads settings"| node_systemprofiles
node_accelconfig -->|"reads settings"| node_accelprofiles
node_accelconfig -->|"builds topology"| node_topology
node_accelconfig -->|"simulates compute"| node_external_scalesim
node_runner -->|"records statistics"| node_stats
node_runner -->|"computes energy"| node_energy
node_runner -->|"exports results"| node_dump
node_runner -->|"plots results"| node_plot
node_dump -->|"builds dataframes"| node_latency
node_plot -->|"processes series"| node_series
node_plot -->|"plots dataframes"| node_latency
node_energy -->|"uses SSD settings"| node_ssdconfig
node_energy -->|"uses system settings"| node_systemconfig

click node_runner "https://github.com/wangyuyue/simpyssd/blob/dev/src/main.py"
click node_graph "https://github.com/wangyuyue/simpyssd/blob/dev/src/graph.py"
click node_subgraph "https://github.com/wangyuyue/simpyssd/blob/dev/src/subgraph.py"
click node_gnn "https://github.com/wangyuyue/simpyssd/blob/dev/src/gnn.py"
click node_topology "https://github.com/wangyuyue/simpyssd/blob/dev/src/gnn_topology.py"
click node_engine "https://github.com/wangyuyue/simpyssd/blob/dev/src/sim.py"
click node_ssd "https://github.com/wangyuyue/simpyssd/blob/dev/src/ssd_estimate.py"
click node_system "https://github.com/wangyuyue/simpyssd/blob/dev/src/system.py"
click node_dram "https://github.com/wangyuyue/simpyssd/blob/dev/src/dram.py"
click node_pcie "https://github.com/wangyuyue/simpyssd/blob/dev/src/pcie.py"
click node_accelerator "https://github.com/wangyuyue/simpyssd/blob/dev/src/nn_accel.py"
click node_ssdconfig "https://github.com/wangyuyue/simpyssd/blob/dev/src/ssd_config.py"
click node_systemconfig "https://github.com/wangyuyue/simpyssd/blob/dev/src/system_config.py"
click node_accelconfig "https://github.com/wangyuyue/simpyssd/blob/dev/src/accel_config.py"
click node_ssdprofiles "https://github.com/wangyuyue/simpyssd/tree/dev/configs/ssd"
click node_systemprofiles "https://github.com/wangyuyue/simpyssd/tree/dev/configs/system"
click node_accelprofiles "https://github.com/wangyuyue/simpyssd/tree/dev/configs/accelerator"
click node_stats "https://github.com/wangyuyue/simpyssd/blob/dev/src/ssd_statistics/sys_stat.py"
click node_energy "https://github.com/wangyuyue/simpyssd/blob/dev/src/ssd_statistics/energy_estimate.py"
click node_latency "https://github.com/wangyuyue/simpyssd/blob/dev/src/ssd_statistics/dataframe.py"
click node_dump "https://github.com/wangyuyue/simpyssd/blob/dev/src/ssd_statistics/dump.py"
click node_plot "https://github.com/wangyuyue/simpyssd/blob/dev/src/ssd_statistics/plot.py"
click node_series "https://github.com/wangyuyue/simpyssd/blob/dev/src/ssd_statistics/series_process.py"

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_graph,node_subgraph,node_gnn,node_topology,node_user toneBlue
class node_engine,node_ssd,node_system,node_dram,node_pcie,node_accelerator toneAmber
class node_ssdconfig,node_systemconfig,node_accelconfig,node_ssdprofiles,node_systemprofiles,node_accelprofiles toneMint
class node_stats,node_energy,node_latency,node_dump,node_plot,node_series toneRose
class node_external_scalesim toneIndigo
```

## Components

### Workload Modeling

- [Experiment Runner](https://github.com/wangyuyue/simpyssd/blob/dev/src/main.py): `src/main.py`
- [Graph Workloads](https://github.com/wangyuyue/simpyssd/blob/dev/src/graph.py): `src/graph.py`
- [Subgraph Sampling](https://github.com/wangyuyue/simpyssd/blob/dev/src/subgraph.py): `src/subgraph.py`
- [GNN Execution](https://github.com/wangyuyue/simpyssd/blob/dev/src/gnn.py): `src/gnn.py`
- [Accelerator Topology](https://github.com/wangyuyue/simpyssd/blob/dev/src/gnn_topology.py): `src/gnn_topology.py`

### Device Simulation

- [Event Engine](https://github.com/wangyuyue/simpyssd/blob/dev/src/sim.py): `src/sim.py`
- [SSD Model](https://github.com/wangyuyue/simpyssd/blob/dev/src/ssd_estimate.py): `src/ssd_estimate.py`
- [System Model](https://github.com/wangyuyue/simpyssd/blob/dev/src/system.py): `src/system.py`
- [DRAM Model](https://github.com/wangyuyue/simpyssd/blob/dev/src/dram.py): `src/dram.py`
- [PCIe Model](https://github.com/wangyuyue/simpyssd/blob/dev/src/pcie.py): `src/pcie.py`
- [Accelerator Model](https://github.com/wangyuyue/simpyssd/blob/dev/src/nn_accel.py): `src/nn_accel.py`

### Design Configuration

- [SSD Configuration](https://github.com/wangyuyue/simpyssd/blob/dev/src/ssd_config.py): `src/ssd_config.py`
- [System Configuration](https://github.com/wangyuyue/simpyssd/blob/dev/src/system_config.py): `src/system_config.py`
- [Accelerator Configuration](https://github.com/wangyuyue/simpyssd/blob/dev/src/accel_config.py): `src/accel_config.py`
- [SSD Profiles](https://github.com/wangyuyue/simpyssd/tree/dev/configs/ssd): `configs/ssd`
- [System Profiles](https://github.com/wangyuyue/simpyssd/tree/dev/configs/system): `configs/system`
- [Accelerator Profiles](https://github.com/wangyuyue/simpyssd/tree/dev/configs/accelerator): `configs/accelerator`

### Results Analysis

- [Simulation Statistics](https://github.com/wangyuyue/simpyssd/blob/dev/src/ssd_statistics/sys_stat.py): `src/ssd_statistics/sys_stat.py`
- [Energy Estimation](https://github.com/wangyuyue/simpyssd/blob/dev/src/ssd_statistics/energy_estimate.py): `src/ssd_statistics/energy_estimate.py`
- [Latency Analysis](https://github.com/wangyuyue/simpyssd/blob/dev/src/ssd_statistics/dataframe.py): `src/ssd_statistics/dataframe.py`
- [Result Export](https://github.com/wangyuyue/simpyssd/blob/dev/src/ssd_statistics/dump.py): `src/ssd_statistics/dump.py`
- [Result Plotting](https://github.com/wangyuyue/simpyssd/blob/dev/src/ssd_statistics/plot.py): `src/ssd_statistics/plot.py`
- [Series Processing](https://github.com/wangyuyue/simpyssd/blob/dev/src/ssd_statistics/series_process.py): `src/ssd_statistics/series_process.py`

### Other components

- **Experiment User**
- **Scale-Sim Tool**

## Connections

- Experiment User → Experiment Runner: starts experiments (evidence: `README.md`)
- Experiment Runner → Graph Workloads: builds workload (evidence: `src/main.py`)
- Experiment Runner → Subgraph Sampling: samples subgraphs (evidence: `src/main.py`)
- Experiment Runner → GNN Execution: runs workload (evidence: `src/main.py`)
- GNN Execution → Graph Workloads: queries graph (evidence: `src/gnn.py`)
- GNN Execution → SSD Model: issues commands (evidence: `src/gnn.py`)
- Experiment Runner → System Model: creates system (evidence: `src/main.py`)
- System Model → SSD Model: instantiates SSD (evidence: `src/system.py`)
- System Model → PCIe Model: uses PCIe (evidence: `src/system.py`)
- System Model → Accelerator Model: uses accelerator (evidence: `src/system.py`)
- System Model → DRAM Model: uses DRAM (evidence: `src/system.py`)
- SSD Model → Event Engine: schedules events (evidence: `src/ssd_estimate.py`)
- Experiment Runner → Event Engine: executes events (evidence: `src/main.py`)
- Experiment Runner → SSD Configuration: loads profile (evidence: `src/main.py`)
- Experiment Runner → System Configuration: selects profile (evidence: `src/main.py`)
- Experiment Runner → Accelerator Configuration: sets accelerator (evidence: `src/main.py`)
- SSD Configuration → SSD Profiles: reads settings (evidence: `src/ssd_config.py`)
- System Configuration → System Profiles: reads settings (evidence: `src/system_config.py`)
- Accelerator Configuration → Accelerator Profiles: reads settings
- Accelerator Configuration → Accelerator Topology: builds topology (evidence: `src/accel_config.py`)
- Accelerator Configuration → Scale-Sim Tool: simulates compute (evidence: `src/accel_config.py`)
- Experiment Runner → Simulation Statistics: records statistics (evidence: `src/main.py`)
- Experiment Runner → Energy Estimation: computes energy (evidence: `src/main.py`)
- Experiment Runner → Result Export: exports results (evidence: `src/main.py`)
- Experiment Runner → Result Plotting: plots results (evidence: `src/main.py`)
- Result Export → Latency Analysis: builds dataframes (evidence: `src/ssd_statistics/dump.py`)
- Result Plotting → Series Processing: processes series (evidence: `src/ssd_statistics/plot.py`)
- Result Plotting → Latency Analysis: plots dataframes (evidence: `src/ssd_statistics/plot.py`)
- Energy Estimation → SSD Configuration: uses SSD settings (evidence: `src/ssd_statistics/energy_estimate.py`)
- Energy Estimation → System Configuration: uses system settings (evidence: `src/ssd_statistics/energy_estimate.py`)