qnetbench¶

A benchmark suite and workload-characterization framework for quantum-network applications — the SPEC/TPC/YCSB equivalent for the quantum internet.

Every scheduler, router and API paper in this field is evaluated on a workload its own authors built, almost always QKD plus one bespoke toy, so no two results are comparable. qnetbench fixes the substrate rather than the schedulers: a curated set of protocols written once against a portable API, run unchanged on three simulator backends, emitting a versioned trace that any third-party tool can consume.

pip install qnetbench
qnetbench run qkd

What is in the box¶

Layer	What you get
27 core protocols	QKD variants, BQC, distributed gates, distillation, GHZ multipartite protocols, repeater chains, DQC — one per distinct demand class
66-entry catalog	the core plus generated distributed-circuit instances; unbounded via the circuit generator
3 backends	`reference` (pure Python, always available), `sequence` (SeQUeNCe), `netsquid` (NetSquid)
4 arbitration modes	the backend's `native` scheduling, or `fifo` / `fidelity_first` / `edf` applied identically everywhere
Characterization	a measured demand signature per application: burstiness, classical coupling, deadline-criticality, fidelity and staleness curves
A versioned trace	JSONL with a JSON Schema, plus a checksummed reference corpus

That is 66 × 3 × 4 = 792 predefined runnable configurations before the circuit generator, which is unbounded.

The result the suite exists for¶

Run several tenants against one oversubscribed link and the best scheduling policy flips depending on what the workload is made of:

$ qnetbench contention
policy              deadline_heavy    fidelity_heavy
----------------------------------------------------
fifo                       0.800             0.867
fidelity_first             0.800             0.933*
edf                        0.817*            0.900
winner                         edf    fidelity_first

EDF wins on deadline-heavy traffic and loses on fidelity-heavy traffic; fidelity_first does the opposite. A paper that evaluated on either workload alone would have crowned one policy and been wrong about the other. See Contention.

Where to go next¶

New here — Install, then the Quickstart.
Running experiments — the command line and run_once.
Understanding the output — metrics and traces.
Your own circuits — Load any distributed circuit.
Extending the suite — add an application or a backend.
Every symbol — the API reference, generated from the source docstrings.

Design commitments¶

These are load-bearing, and everything else follows from them:

An application never imports a simulator. It talks to the portable API shim in qnetbench.api only. If the shim leaks simulator concepts, comparability dies.
Demand is declarative. Every request for entanglement carries a Demand contract — minimum fidelity, latency budget, deadline, staleness tolerance, priority. Schedulers read contracts; metrics score violations of them.
Everything observable is a trace. Metrics are computed from the JSONL, never inline, so a third party reproduces our numbers without importing our code.
Two independent backends or it does not count. Cross-backend equivalence is a tested deliverable, not an aspiration.
Runs are deterministic in their seed. (app, seed, backend, topology) reproduces byte for byte.