# ultraethernet/uet-htsim architecture

> Architecture diagram of the GitHub repository ultraethernet/uet-htsim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ultraethernet/uet-htsim
- Repository: https://github.com/ultraethernet/uet-htsim

## Overview

HTSIM is a discrete-event network simulator focused on evaluating congestion-control transports across configurable datacenter topologies and traffic scenarios. A typical run configures a transport-specific executable, builds topology and traffic inputs, then simulates packet delivery and records results. The graph preserves the documented scenario and analysis capability, as well as the event, packet, queue, and link layers. Edges cite README or source-index evidence; some runtime wiring is not established by the excerpts, so it is omitted.

Main entry points: [`htsim/sim/datacenter/main_uec.cpp`](https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/datacenter/main_uec.cpp) (UEC runner), [`htsim/sim/datacenter/main_ndp.cpp`](https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/datacenter/main_ndp.cpp) (NDP runner), [`htsim/sim/queue.h`](https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/queue.h) (Packet queues), [`htsim/sim/datacenter/dragon_fly_topology.cpp`](https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/datacenter/dragon_fly_topology.cpp) (Dragonfly topology)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_run["Simulation runs"]
  node_ndp_main["NDP runner<br/>[main_ndp.cpp]"]
  node_uec_main["UEC runner<br/>[main_uec.cpp]"]
  node_main_config["Run configuration<br/>[config.h]"]
end

subgraph group_scenario["Topology and traffic"]
  node_traffic["Traffic matrices"]
  node_topology_api["Topology interface<br/>[topology.h]"]
  node_fat_topology["Fat-tree topology"]
  node_dragon_topology["Dragonfly topology"]
  node_fat_switch["Fat-tree switch"]
end

subgraph group_transport["Transport protocols"]
  node_ndp["NDP transport<br/>[ndp.cpp]"]
  node_uec["UEC transport<br/>[uec.cpp]"]
end

subgraph group_runtime["Simulation runtime"]
  node_packet_network["Packets and routes<br/>[network.h]"]
  node_eventlist["Event scheduler<br/>[eventlist.h]"]
  node_queues["Packet queues<br/>[queue.h]"]
  node_composite_queue["Composite queues<br/>[compositequeue.h]"]
  node_pipe["Link delay<br/>[pipe.h]"]
  node_switch["Switch ports<br/>[switch.h]"]
  node_circular_buffer["Circular buffer<br/>[circular_buffer.h]"]
end

subgraph group_results["Logging and analysis"]
  node_logfile["Run log<br/>[logfile.h]"]
  node_loggers["Metrics loggers<br/>[loggers.h]"]
  node_analysis["Result analysis"]
end

node_user(("Simulation user"))

node_user -->|"configures run"| node_ndp_main
node_user -->|"configures run"| node_uec_main
node_ndp_main -->|"reads settings"| node_main_config
node_uec_main -->|"reads settings"| node_main_config
node_ndp_main -->|"loads flows"| node_traffic
node_uec_main -->|"loads flows"| node_traffic
node_ndp_main -->|"configures topology"| node_fat_topology
node_uec_main -->|"configures topology"| node_fat_topology
node_ndp_main -->|"runs transport"| node_ndp
node_uec_main -->|"runs transport"| node_uec
node_ndp_main -->|"schedules events"| node_eventlist
node_uec_main -->|"schedules events"| node_eventlist
node_ndp_main -->|"creates output"| node_logfile
node_uec_main -->|"creates output"| node_logfile
node_uec_main -->|"configures metrics"| node_loggers
node_fat_topology -->|"implements"| node_topology_api
node_dragon_topology -->|"implements"| node_topology_api
node_fat_topology -->|"creates switches"| node_fat_switch
node_dragon_topology -->|"allocates queues"| node_queues
node_dragon_topology -->|"creates links"| node_pipe
node_dragon_topology -->|"registers queue metrics"| node_loggers
node_ndp -->|"uses packet routes"| node_packet_network
node_ndp -->|"interacts with queues"| node_queues
node_uec -->|"buffers state"| node_circular_buffer
node_composite_queue -->|"extends queue"| node_queues
node_queues -->|"buffers packets"| node_circular_buffer
node_switch -->|"groups ports"| node_queues
node_logfile -->|"uses event timing"| node_eventlist
node_analysis -->|"summarizes results"| node_user

click node_ndp_main "https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/datacenter/main_ndp.cpp"
click node_uec_main "https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/datacenter/main_uec.cpp"
click node_main_config "https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/config.h"
click node_traffic "https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/datacenter/connection_matrix.cpp"
click node_topology_api "https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/datacenter/topology.h"
click node_fat_topology "https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/datacenter/fat_tree_topology.cpp"
click node_dragon_topology "https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/datacenter/dragon_fly_topology.cpp"
click node_fat_switch "https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/datacenter/fat_tree_switch.cpp"
click node_ndp "https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/ndp.cpp"
click node_uec "https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/uec.cpp"
click node_packet_network "https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/network.h"
click node_eventlist "https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/eventlist.h"
click node_queues "https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/queue.h"
click node_composite_queue "https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/compositequeue.h"
click node_pipe "https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/pipe.h"
click node_switch "https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/switch.h"
click node_circular_buffer "https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/circular_buffer.h"
click node_logfile "https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/logfile.h"
click node_loggers "https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/loggers.h"
click node_analysis "https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/datacenter/validation/analysis_and_plotting.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_ndp_main,node_uec_main,node_main_config,node_user toneBlue
class node_traffic,node_topology_api,node_fat_topology,node_dragon_topology,node_fat_switch toneAmber
class node_ndp,node_uec toneMint
class node_packet_network,node_eventlist,node_queues,node_composite_queue,node_pipe,node_switch,node_circular_buffer toneRose
class node_logfile,node_loggers,node_analysis toneIndigo
```

## Components

### Simulation runs

- [NDP runner](https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/datacenter/main_ndp.cpp): `htsim/sim/datacenter/main_ndp.cpp`
- [UEC runner](https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/datacenter/main_uec.cpp): `htsim/sim/datacenter/main_uec.cpp`
- [Run configuration](https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/config.h): `htsim/sim/config.h`

### Topology and traffic

- [Traffic matrices](https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/datacenter/connection_matrix.cpp): `htsim/sim/datacenter/connection_matrix.cpp`
- [Topology interface](https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/datacenter/topology.h): `htsim/sim/datacenter/topology.h`
- [Fat-tree topology](https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/datacenter/fat_tree_topology.cpp): `htsim/sim/datacenter/fat_tree_topology.cpp`
- [Dragonfly topology](https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/datacenter/dragon_fly_topology.cpp): `htsim/sim/datacenter/dragon_fly_topology.cpp`
- [Fat-tree switch](https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/datacenter/fat_tree_switch.cpp): `htsim/sim/datacenter/fat_tree_switch.cpp`

### Transport protocols

- [NDP transport](https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/ndp.cpp): `htsim/sim/ndp.cpp`
- [UEC transport](https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/uec.cpp): `htsim/sim/uec.cpp`

### Simulation runtime

- [Packets and routes](https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/network.h): `htsim/sim/network.h`
- [Event scheduler](https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/eventlist.h): `htsim/sim/eventlist.h`
- [Packet queues](https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/queue.h): `htsim/sim/queue.h`
- [Composite queues](https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/compositequeue.h): `htsim/sim/compositequeue.h`
- [Link delay](https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/pipe.h): `htsim/sim/pipe.h`
- [Switch ports](https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/switch.h): `htsim/sim/switch.h`
- [Circular buffer](https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/circular_buffer.h): `htsim/sim/circular_buffer.h`

### Logging and analysis

- [Run log](https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/logfile.h): `htsim/sim/logfile.h`
- [Metrics loggers](https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/loggers.h): `htsim/sim/loggers.h`
- [Result analysis](https://github.com/ultraethernet/uet-htsim/blob/main/htsim/sim/datacenter/validation/analysis_and_plotting.py): `htsim/sim/datacenter/validation/analysis_and_plotting.py`

### Other components

- **Simulation user**

## Connections

- Simulation user → NDP runner: configures run
- Simulation user → UEC runner: configures run
- NDP runner → Run configuration: reads settings (evidence: `htsim/sim/datacenter/main_ndp.cpp`)
- UEC runner → Run configuration: reads settings (evidence: `htsim/sim/datacenter/main_uec.cpp`)
- NDP runner → Traffic matrices: loads flows (evidence: `htsim/sim/datacenter/main_ndp.cpp`)
- UEC runner → Traffic matrices: loads flows (evidence: `htsim/sim/datacenter/main_uec.cpp`)
- NDP runner → Fat-tree topology: configures topology (evidence: `htsim/sim/datacenter/main_ndp.cpp`)
- UEC runner → Fat-tree topology: configures topology (evidence: `htsim/sim/datacenter/main_uec.cpp`)
- NDP runner → NDP transport: runs transport (evidence: `htsim/sim/datacenter/main_ndp.cpp`)
- UEC runner → UEC transport: runs transport (evidence: `htsim/sim/datacenter/main_uec.cpp`)
- NDP runner → Event scheduler: schedules events (evidence: `htsim/sim/datacenter/main_ndp.cpp`)
- UEC runner → Event scheduler: schedules events (evidence: `htsim/sim/datacenter/main_uec.cpp`)
- NDP runner → Run log: creates output (evidence: `htsim/sim/datacenter/main_ndp.cpp`)
- UEC runner → Run log: creates output (evidence: `htsim/sim/datacenter/main_uec.cpp`)
- UEC runner → Metrics loggers: configures metrics (evidence: `htsim/sim/datacenter/main_uec.cpp`)
- Fat-tree topology → Topology interface: implements (evidence: `htsim/sim/datacenter/fat_tree_topology.cpp`)
- Dragonfly topology → Topology interface: implements
- Fat-tree topology → Fat-tree switch: creates switches (evidence: `htsim/sim/datacenter/fat_tree_topology.cpp`)
- Dragonfly topology → Packet queues: allocates queues (evidence: `htsim/sim/datacenter/dragon_fly_topology.cpp`)
- Dragonfly topology → Link delay: creates links (evidence: `htsim/sim/datacenter/dragon_fly_topology.cpp`)
- Dragonfly topology → Metrics loggers: registers queue metrics (evidence: `htsim/sim/datacenter/dragon_fly_topology.cpp`)
- NDP transport → Packets and routes: uses packet routes (evidence: `htsim/sim/ndp.cpp`)
- NDP transport → Packet queues: interacts with queues (evidence: `htsim/sim/ndp.cpp`)
- UEC transport → Circular buffer: buffers state (evidence: `htsim/sim/uec.cpp`)
- Composite queues → Packet queues: extends queue (evidence: `htsim/sim/compositequeue.h`)
- Packet queues → Circular buffer: buffers packets (evidence: `htsim/sim/queue.h`)
- Switch ports → Packet queues: groups ports (evidence: `htsim/sim/switch.h`)
- Run log → Event scheduler: uses event timing (evidence: `htsim/sim/logfile.h`)
- Result analysis → Simulation user: summarizes results
