# usnistgov/mqns architecture

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

- Interactive diagram: https://gitdiagram.com/usnistgov/mqns
- Repository: https://github.com/usnistgov/mqns

## Overview

MQNS is a discrete-event simulator for comparing quantum-entanglement routing strategies. A user configures a network, traffic, and simulation; the network is built and routes are computed, then forwarding models entanglement generation, swapping, and optional purification while tracking qubits and memory. The simulator schedules events and supports monitoring. The README documents major forwarding and link-model capabilities; the source index and excerpts support the core implementation links, but do not expose every runtime dispatch, so uncertain links are omitted.

Main entry points: [`mqns/network/fw/controller.py`](https://github.com/usnistgov/mqns/blob/main/mqns/network/fw/controller.py) (Routing controller), [`mqns/network/protocol/link_layer.py`](https://github.com/usnistgov/mqns/blob/main/mqns/network/protocol/link_layer.py) (Entanglement link layer), [`mqns/network/network/network.py`](https://github.com/usnistgov/mqns/blob/main/mqns/network/network/network.py) (Network and requests), [`mqns/network/builder.py`](https://github.com/usnistgov/mqns/blob/main/mqns/network/builder.py) (Network builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Scenario Setup"]
  node_builder["Network builder<br/>[builder.py]"]
  node_topology["Network topology"]
  node_network["Network and requests<br/>[network.py]"]
  node_traffic["Traffic generation"]
end

subgraph group_routing["Routing and Forwarding"]
  node_controller["Proactive controller<br/>[controller.py]"]
  node_routecontrol["Routing controller<br/>[controller.py]"]
  node_routecompute["Route computation<br/>[routing.py]"]
  node_algorithms["Path algorithms"]
  node_forwarding["Forwarding strategies<br/>[forwarder.py]"]
  node_swap["Swap sequences<br/>[swap_sequence.py]"]
  node_multiplex["Qubit multiplexing"]
end

subgraph group_quantum["Quantum Resources"]
  node_linklayer["Entanglement link layer<br/>[link_layer.py]"]
  node_linkarch["Link architectures<br/>[link_arch.py]"]
  node_memory[("Quantum memory<br/>[memory.py]")]
  node_qubit["Qubit and state models"]
  node_entanglement["Entanglement models<br/>[entanglement.py]"]
  node_noise["Noise models"]
end

subgraph group_runtime["Simulation Runtime"]
  node_simulator["Event simulator<br/>[simulator.py]"]
  node_events["Events and time<br/>[event.py]"]
  node_monitor["Simulation monitor<br/>[monitor.py]"]
end

node_user(("Simulation user"))

node_user -->|"configures"| node_builder
node_builder -->|"constructs"| node_topology
node_builder -->|"builds"| node_network
node_user -->|"defines"| node_traffic
node_traffic -->|"creates requests"| node_network
node_network -->|"provides routes"| node_routecontrol
node_routecontrol -->|"builds routes"| node_network
node_routecontrol -->|"computes paths"| node_routecompute
node_routecompute -->|"queries paths"| node_algorithms
node_routecontrol -->|"installs paths"| node_forwarding
node_controller -->|"dispatches commands"| node_routecontrol
node_controller -->|"configures allocation"| node_multiplex
node_forwarding -->|"uses sequences"| node_swap
node_forwarding -.->|"initiates distribution"| node_linklayer
node_linklayer -->|"models link generation"| node_linkarch
node_linklayer -->|"reserves qubits"| node_memory
node_memory -.->|"stores"| node_qubit
node_linklayer -->|"generates pairs"| node_entanglement
node_entanglement -->|"applies error models"| node_noise
node_entanglement -->|"uses states"| node_qubit
node_user -->|"runs simulation"| node_simulator
node_simulator -->|"schedules events"| node_events
node_simulator -->|"notifies watchers"| node_monitor

click node_builder "https://github.com/usnistgov/mqns/blob/main/mqns/network/builder.py"
click node_topology "https://github.com/usnistgov/mqns/tree/main/mqns/network/topology"
click node_network "https://github.com/usnistgov/mqns/blob/main/mqns/network/network/network.py"
click node_traffic "https://github.com/usnistgov/mqns/tree/main/mqns/network/network"
click node_controller "https://github.com/usnistgov/mqns/blob/main/mqns/network/proactive/controller.py"
click node_routecontrol "https://github.com/usnistgov/mqns/blob/main/mqns/network/fw/controller.py"
click node_routecompute "https://github.com/usnistgov/mqns/blob/main/mqns/network/fw/routing.py"
click node_algorithms "https://github.com/usnistgov/mqns/tree/main/mqns/network/route"
click node_forwarding "https://github.com/usnistgov/mqns/blob/main/mqns/network/fw/forwarder.py"
click node_swap "https://github.com/usnistgov/mqns/blob/main/mqns/network/fw/swap_sequence.py"
click node_multiplex "https://github.com/usnistgov/mqns/tree/main/mqns/network/proactive"
click node_linklayer "https://github.com/usnistgov/mqns/blob/main/mqns/network/protocol/link_layer.py"
click node_linkarch "https://github.com/usnistgov/mqns/blob/main/mqns/entity/qchannel/link_arch.py"
click node_memory "https://github.com/usnistgov/mqns/blob/main/mqns/entity/memory/memory.py"
click node_qubit "https://github.com/usnistgov/mqns/tree/main/mqns/models/qubit"
click node_entanglement "https://github.com/usnistgov/mqns/blob/main/mqns/models/epr/entanglement.py"
click node_noise "https://github.com/usnistgov/mqns/tree/main/mqns/models/error"
click node_simulator "https://github.com/usnistgov/mqns/blob/main/mqns/simulator/simulator.py"
click node_events "https://github.com/usnistgov/mqns/blob/main/mqns/simulator/event.py"
click node_monitor "https://github.com/usnistgov/mqns/blob/main/mqns/entity/monitor/monitor.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_builder,node_topology,node_network,node_traffic,node_user toneBlue
class node_controller,node_routecontrol,node_routecompute,node_algorithms,node_forwarding,node_swap,node_multiplex toneAmber
class node_linklayer,node_linkarch,node_memory,node_qubit,node_entanglement,node_noise toneMint
class node_simulator,node_events,node_monitor toneRose
```

## Components

### Scenario Setup

- [Network builder](https://github.com/usnistgov/mqns/blob/main/mqns/network/builder.py): `mqns/network/builder.py`
- [Network topology](https://github.com/usnistgov/mqns/tree/main/mqns/network/topology): `mqns/network/topology`
- [Network and requests](https://github.com/usnistgov/mqns/blob/main/mqns/network/network/network.py): `mqns/network/network/network.py`
- [Traffic generation](https://github.com/usnistgov/mqns/tree/main/mqns/network/network): `mqns/network/network`

### Routing and Forwarding

- [Proactive controller](https://github.com/usnistgov/mqns/blob/main/mqns/network/proactive/controller.py): `mqns/network/proactive/controller.py`
- [Routing controller](https://github.com/usnistgov/mqns/blob/main/mqns/network/fw/controller.py): `mqns/network/fw/controller.py`
- [Route computation](https://github.com/usnistgov/mqns/blob/main/mqns/network/fw/routing.py): `mqns/network/fw/routing.py`
- [Path algorithms](https://github.com/usnistgov/mqns/tree/main/mqns/network/route): `mqns/network/route`
- [Forwarding strategies](https://github.com/usnistgov/mqns/blob/main/mqns/network/fw/forwarder.py): `mqns/network/fw/forwarder.py`
- [Swap sequences](https://github.com/usnistgov/mqns/blob/main/mqns/network/fw/swap_sequence.py): `mqns/network/fw/swap_sequence.py`
- [Qubit multiplexing](https://github.com/usnistgov/mqns/tree/main/mqns/network/proactive): `mqns/network/proactive`

### Quantum Resources

- [Entanglement link layer](https://github.com/usnistgov/mqns/blob/main/mqns/network/protocol/link_layer.py): `mqns/network/protocol/link_layer.py`
- [Link architectures](https://github.com/usnistgov/mqns/blob/main/mqns/entity/qchannel/link_arch.py): `mqns/entity/qchannel/link_arch.py`
- [Quantum memory](https://github.com/usnistgov/mqns/blob/main/mqns/entity/memory/memory.py): `mqns/entity/memory/memory.py`
- [Qubit and state models](https://github.com/usnistgov/mqns/tree/main/mqns/models/qubit): `mqns/models/qubit`
- [Entanglement models](https://github.com/usnistgov/mqns/blob/main/mqns/models/epr/entanglement.py): `mqns/models/epr/entanglement.py`
- [Noise models](https://github.com/usnistgov/mqns/tree/main/mqns/models/error): `mqns/models/error`

### Simulation Runtime

- [Event simulator](https://github.com/usnistgov/mqns/blob/main/mqns/simulator/simulator.py): `mqns/simulator/simulator.py`
- [Events and time](https://github.com/usnistgov/mqns/blob/main/mqns/simulator/event.py): `mqns/simulator/event.py`
- [Simulation monitor](https://github.com/usnistgov/mqns/blob/main/mqns/entity/monitor/monitor.py): `mqns/entity/monitor/monitor.py`

### Other components

- **Simulation user**

## Connections

- Simulation user → Network builder: configures (evidence: `mqns/network/builder.py`)
- Network builder → Network topology: constructs (evidence: `mqns/network/builder.py`)
- Network builder → Network and requests: builds (evidence: `mqns/network/builder.py`)
- Simulation user → Traffic generation: defines
- Traffic generation → Network and requests: creates requests (evidence: `mqns/network/network/__init__.py`)
- Network and requests → Routing controller: provides routes (evidence: `mqns/network/fw/controller.py`)
- Routing controller → Network and requests: builds routes (evidence: `mqns/network/fw/controller.py`)
- Routing controller → Route computation: computes paths (evidence: `mqns/network/fw/controller.py`)
- Route computation → Path algorithms: queries paths (evidence: `mqns/network/fw/routing.py`)
- Routing controller → Forwarding strategies: installs paths (evidence: `mqns/network/fw/controller.py`)
- Proactive controller → Routing controller: dispatches commands (evidence: `mqns/network/proactive/controller.py`)
- Proactive controller → Qubit multiplexing: configures allocation (evidence: `mqns/network/proactive/controller.py`)
- Forwarding strategies → Swap sequences: uses sequences
- Forwarding strategies → Entanglement link layer: initiates distribution
- Entanglement link layer → Link architectures: models link generation (evidence: `mqns/network/protocol/link_layer.py`)
- Entanglement link layer → Quantum memory: reserves qubits (evidence: `mqns/network/protocol/link_layer.py`)
- Quantum memory → Qubit and state models: stores (evidence: `mqns/entity/memory/memory.py`)
- Entanglement link layer → Entanglement models: generates pairs (evidence: `mqns/network/protocol/link_layer.py`)
- Entanglement models → Noise models: applies error models (evidence: `mqns/models/epr/entanglement.py`)
- Entanglement models → Qubit and state models: uses states (evidence: `mqns/models/epr/entanglement.py`)
- Simulation user → Event simulator: runs simulation
- Event simulator → Events and time: schedules events (evidence: `mqns/simulator/simulator.py`)
- Event simulator → Simulation monitor: notifies watchers (evidence: `mqns/simulator/simulator.py`)
