# sequence-toolbox/sequence architecture

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

- Interactive diagram: https://gitdiagram.com/sequence-toolbox/sequence
- Repository: https://github.com/sequence-toolbox/sequence

## Overview

SeQUeNCe is a discrete-event quantum-network simulator. A user configures a topology and application; nodes combine simulated hardware and protocol stacks, while the timeline schedules events that drive communication and quantum-state changes. Entanglement generation, swapping, purification, teleportation, resource allocation, routing/reservations, and QKD are distinct product capabilities. The graph follows documented and indexed references; unsampled subsystems are included at their directory paths, with only supported relationships shown.

Main entry points: [`sequence/topology/node.py`](https://github.com/sequence-toolbox/sequence/blob/master/sequence/topology/node.py) (Network nodes), [`sequence/kernel/timeline.py`](https://github.com/sequence-toolbox/sequence/blob/master/sequence/kernel/timeline.py) (Event timeline), [`sequence/app`](https://github.com/sequence-toolbox/sequence/tree/master/sequence/app) (Applications), [`sequence/entanglement_management/generation`](https://github.com/sequence-toolbox/sequence/tree/master/sequence/entanglement_management/generation) (Entanglement generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Simulation Kernel"]
  node_timeline["Event timeline<br/>[timeline.py]"]
  node_events["Event scheduling<br/>[event.py]"]
  node_process["Process dispatch<br/>[process.py]"]
  node_quantum["Quantum state manager"]
end

subgraph group_network["Topology &amp; Network"]
  node_topology["Topology builders"]
  node_node["Network nodes<br/>[node.py]"]
  node_network_manager["Network manager<br/>[network_manager.py]"]
  node_routing["Network routing"]
  node_reservation["Reservation handling<br/>[reservation.py]"]
end

subgraph group_hardware["Quantum Hardware"]
  node_hardware["Optical hardware"]
  node_memory["Quantum memories<br/>[memory.py]"]
end

subgraph group_entanglement["Entanglement Protocols"]
  node_ent_protocol["Entanglement protocol base"]
  node_generation["Entanglement generation"]
  node_swapping["Entanglement swapping"]
  node_purification["Entanglement purification"]
end

subgraph group_services["Applications &amp; Services"]
  node_resource["Resource manager"]
  node_memory_manager["Memory tracking<br/>[memory_manager.py]"]
  node_application["Applications"]
  node_teleportation["Teleportation<br/>[teleportation.py]"]
  node_qkd["Quantum key distribution"]
  node_metrics["Simulation metrics"]
end

node_user(("Network user"))

node_user -->|"configures"| node_topology
node_user -->|"runs"| node_application
node_topology -->|"creates"| node_node
node_node -->|"registers entities"| node_timeline
node_timeline -->|"executes"| node_events
node_events -->|"dispatches"| node_process
node_timeline -->|"creates"| node_quantum
node_node -->|"assembles"| node_hardware
node_node -->|"assembles"| node_memory
node_generation -->|"uses"| node_memory
node_generation -->|"coordinates"| node_node
node_generation -->|"extends"| node_ent_protocol
node_swapping -->|"extends"| node_ent_protocol
node_swapping -->|"uses"| node_memory
node_resource -->|"creates"| node_memory_manager
node_resource -->|"reads"| node_reservation
node_resource -->|"sends messages"| node_node
node_network_manager -->|"uses"| node_routing
node_network_manager -->|"uses"| node_reservation
node_application -->|"uses"| node_node
node_application -->|"requests"| node_reservation
node_application -->|"checks"| node_memory_manager
node_teleportation -->|"communicates"| node_node
node_qkd -->|"runs on"| node_node
node_timeline -->|"records"| node_metrics

click node_topology "https://github.com/sequence-toolbox/sequence/tree/master/sequence/topology"
click node_node "https://github.com/sequence-toolbox/sequence/blob/master/sequence/topology/node.py"
click node_timeline "https://github.com/sequence-toolbox/sequence/blob/master/sequence/kernel/timeline.py"
click node_events "https://github.com/sequence-toolbox/sequence/blob/master/sequence/kernel/event.py"
click node_process "https://github.com/sequence-toolbox/sequence/blob/master/sequence/kernel/process.py"
click node_quantum "https://github.com/sequence-toolbox/sequence/tree/master/sequence/kernel/quantum_manager"
click node_hardware "https://github.com/sequence-toolbox/sequence/tree/master/sequence/components"
click node_memory "https://github.com/sequence-toolbox/sequence/blob/master/sequence/components/memory.py"
click node_ent_protocol "https://github.com/sequence-toolbox/sequence/blob/master/sequence/entanglement_management/entanglement_protocol.py"
click node_generation "https://github.com/sequence-toolbox/sequence/tree/master/sequence/entanglement_management/generation"
click node_swapping "https://github.com/sequence-toolbox/sequence/tree/master/sequence/entanglement_management/swapping"
click node_purification "https://github.com/sequence-toolbox/sequence/tree/master/sequence/entanglement_management/purification"
click node_resource "https://github.com/sequence-toolbox/sequence/blob/master/sequence/resource_management/resource_manager.py"
click node_memory_manager "https://github.com/sequence-toolbox/sequence/blob/master/sequence/resource_management/memory_manager.py"
click node_network_manager "https://github.com/sequence-toolbox/sequence/blob/master/sequence/network_management/network_manager.py"
click node_routing "https://github.com/sequence-toolbox/sequence/tree/master/sequence/network_management/routing"
click node_reservation "https://github.com/sequence-toolbox/sequence/blob/master/sequence/network_management/reservation.py"
click node_application "https://github.com/sequence-toolbox/sequence/tree/master/sequence/app"
click node_teleportation "https://github.com/sequence-toolbox/sequence/blob/master/sequence/entanglement_management/teleportation.py"
click node_qkd "https://github.com/sequence-toolbox/sequence/tree/master/sequence/qkd"
click node_metrics "https://github.com/sequence-toolbox/sequence/tree/master/sequence/utils/metrics"

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_timeline,node_events,node_process,node_quantum,node_user toneBlue
class node_topology,node_node,node_network_manager,node_routing,node_reservation toneAmber
class node_hardware,node_memory toneMint
class node_ent_protocol,node_generation,node_swapping,node_purification toneRose
class node_resource,node_memory_manager,node_application,node_teleportation,node_qkd,node_metrics toneIndigo
```

## Components

### Simulation Kernel

- [Event timeline](https://github.com/sequence-toolbox/sequence/blob/master/sequence/kernel/timeline.py): `sequence/kernel/timeline.py`
- [Event scheduling](https://github.com/sequence-toolbox/sequence/blob/master/sequence/kernel/event.py): `sequence/kernel/event.py`
- [Process dispatch](https://github.com/sequence-toolbox/sequence/blob/master/sequence/kernel/process.py): `sequence/kernel/process.py`
- [Quantum state manager](https://github.com/sequence-toolbox/sequence/tree/master/sequence/kernel/quantum_manager): `sequence/kernel/quantum_manager`

### Topology & Network

- [Topology builders](https://github.com/sequence-toolbox/sequence/tree/master/sequence/topology): `sequence/topology`
- [Network nodes](https://github.com/sequence-toolbox/sequence/blob/master/sequence/topology/node.py): `sequence/topology/node.py`
- [Network manager](https://github.com/sequence-toolbox/sequence/blob/master/sequence/network_management/network_manager.py): `sequence/network_management/network_manager.py`
- [Network routing](https://github.com/sequence-toolbox/sequence/tree/master/sequence/network_management/routing): `sequence/network_management/routing`
- [Reservation handling](https://github.com/sequence-toolbox/sequence/blob/master/sequence/network_management/reservation.py): `sequence/network_management/reservation.py`

### Quantum Hardware

- [Optical hardware](https://github.com/sequence-toolbox/sequence/tree/master/sequence/components): `sequence/components`
- [Quantum memories](https://github.com/sequence-toolbox/sequence/blob/master/sequence/components/memory.py): `sequence/components/memory.py`

### Entanglement Protocols

- [Entanglement protocol base](https://github.com/sequence-toolbox/sequence/blob/master/sequence/entanglement_management/entanglement_protocol.py): `sequence/entanglement_management/entanglement_protocol.py`
- [Entanglement generation](https://github.com/sequence-toolbox/sequence/tree/master/sequence/entanglement_management/generation): `sequence/entanglement_management/generation`
- [Entanglement swapping](https://github.com/sequence-toolbox/sequence/tree/master/sequence/entanglement_management/swapping): `sequence/entanglement_management/swapping`
- [Entanglement purification](https://github.com/sequence-toolbox/sequence/tree/master/sequence/entanglement_management/purification): `sequence/entanglement_management/purification`

### Applications & Services

- [Resource manager](https://github.com/sequence-toolbox/sequence/blob/master/sequence/resource_management/resource_manager.py): `sequence/resource_management/resource_manager.py`
- [Memory tracking](https://github.com/sequence-toolbox/sequence/blob/master/sequence/resource_management/memory_manager.py): `sequence/resource_management/memory_manager.py`
- [Applications](https://github.com/sequence-toolbox/sequence/tree/master/sequence/app): `sequence/app`
- [Teleportation](https://github.com/sequence-toolbox/sequence/blob/master/sequence/entanglement_management/teleportation.py): `sequence/entanglement_management/teleportation.py`
- [Quantum key distribution](https://github.com/sequence-toolbox/sequence/tree/master/sequence/qkd): `sequence/qkd`
- [Simulation metrics](https://github.com/sequence-toolbox/sequence/tree/master/sequence/utils/metrics): `sequence/utils/metrics`

### Other components

- **Network user**

## Connections

- Network user → Topology builders: configures (evidence: `README.md`)
- Network user → Applications: runs (evidence: `README.md`)
- Topology builders → Network nodes: creates (evidence: `sequence/topology/router_net_topo.py`)
- Network nodes → Event timeline: registers entities (evidence: `sequence/topology/node.py`)
- Event timeline → Event scheduling: executes (evidence: `sequence/kernel/timeline.py`)
- Event scheduling → Process dispatch: dispatches (evidence: `sequence/kernel/event.py`)
- Event timeline → Quantum state manager: creates (evidence: `sequence/kernel/timeline.py`)
- Network nodes → Optical hardware: assembles (evidence: `sequence/topology/node.py`)
- Network nodes → Quantum memories: assembles (evidence: `sequence/topology/node.py`)
- Entanglement generation → Quantum memories: uses (evidence: `sequence/entanglement_management/generation/single_heralded.py`)
- Entanglement generation → Network nodes: coordinates (evidence: `sequence/entanglement_management/generation/single_heralded.py`)
- Entanglement generation → Entanglement protocol base: extends
- Entanglement swapping → Entanglement protocol base: extends (evidence: `sequence/entanglement_management/swapping/swapping_base.py`)
- Entanglement swapping → Quantum memories: uses (evidence: `sequence/entanglement_management/swapping/swapping_base.py`)
- Resource manager → Memory tracking: creates (evidence: `sequence/resource_management/resource_manager.py`)
- Resource manager → Reservation handling: reads (evidence: `sequence/resource_management/resource_manager.py`)
- Resource manager → Network nodes: sends messages (evidence: `sequence/resource_management/resource_manager.py`)
- Network manager → Network routing: uses (evidence: `sequence/network_management/network_manager.py`)
- Network manager → Reservation handling: uses (evidence: `sequence/network_management/network_manager.py`)
- Applications → Network nodes: uses (evidence: `sequence/app/app.py`)
- Applications → Reservation handling: requests (evidence: `sequence/app/app.py`)
- Applications → Memory tracking: checks (evidence: `sequence/app/app.py`)
- Teleportation → Network nodes: communicates (evidence: `sequence/entanglement_management/teleportation.py`)
- Quantum key distribution → Network nodes: runs on (evidence: `sequence/qkd/BB84.py`)
- Event timeline → Simulation metrics: records (evidence: `sequence/kernel/timeline.py`)