An assumption-explicit budget model for optically-trunked cryogenic quantum control — and where it stops working.
Software-first prototype of an Optical Packet Trunk + Cryogenic Waveform Router: a binary control protocol, a discrete-event simulator, a compiler, and — the part that matters — a power and bandwidth model that is able to return infeasible, and does.
Pure Python 3.10+. Zero third-party dependencies. Apache-2.0.
No hardware was measured. There is no qubit state, no fidelity, and no
cryogenic measurement anywhere in this repository. Every figure below is either
emitted by this project's own encoder and simulator, or derived analytically
from constants that are individually tagged measured, literature, vendor
or assumption. A result computed from an assumption is a consequence of that
assumption, not a fact about a cryostat.
The architecture is not novel, and this repository says so before it says
anything else. US 12,079,690 B2 (Rigetti, priority 2019, granted 2024) already
claims the optical transmission line, network-packet framing, WDM onto a single
fibre, and an in-cryostat controller. That is the whole of the "core
architecture". docs/prior-art-and-datasheets.md records the prior-art pass
with per-figure [FETCHED] / [SNIPPET] provenance labels.
What is contributed here is the part the patent does not contain: an open budget model with a visible assumption ledger, and two falsifiable disagreements it produced.
There is a more capable open tool, and you should probably start with it. QIsim (ISCA 2023, MIT) models the 4 K control interface at device level — gate error, timing, workloads, CMOS and SFQ, technology nodes 45 through 7 nm, and a photonic link. A serious cryogenic control study should begin there. What this repository offers instead is the protocol and wire-overhead layer QIsim's README does not describe, and a model that runs on the standard library alone — QIsim's stack needs Design Compiler Ultra, a commercial EDA licence. Different goods; §2.1 of the paper states the delta in full, including what we could not check.
| Result | Value |
|---|---|
| Scaling limit, realistic assumptions, 1.5 W 4 K stage | 17 qubits |
| Scaling limit, every assumption stacked favourably | 1959 qubits |
| Binding constraint | 4 K cooling, in every scenario tested |
| Dominant power term at scale | SerDes data movement, not waveform synthesis |
RUN_BATCH worth on the optimistic limit |
3.0x (260 → 783 qubits) |
| Room-temperature line reduction at 1024 qubits | 36x (not the 192x an assumed fibre count gives) |
Three of those are worth stating plainly:
Cooling binds everywhere. Not the optical link, not the feedthrough count, at no size tested. Optical link capacity is inert — the trunk is never the bottleneck the architecture is usually motivated by.
Batching is a wire-format change worth 3x. RUN_BATCH packs up to 8191
8-byte operation records into one packet. No hardware assumption is touched;
SerDes power scales with bits moved, so moving fewer bits is directly a power
win. The gain saturates at 80.2x versus raw streaming, bounded by the op-record
size.
Sizing the trunk honestly costs 5x of the headline. The original model assumed two fibres regardless of qubit count, which made its reduction factor an assumption restated as arithmetic. Deriving the fibre count from the real packet rate needed to sustain a 1 µs surface-code cycle drops 192x to 36x.
Published work (Liu & Huang, arXiv:2606.10114) keeps waveform memory at room temperature, arguing it is the lower-power choice. This model caches at 4 K and wins at every size tested — 278.6 mW against 1167.2 mW at 256 qubits.
The deciding constant is 4 K SRAM power per KB, which nobody publishes on its own. So the result is reported as a break-even against a measured upper bound, not as a verdict: a 32 KB SRAM in a 14 nm FinFET AWG operating at 4 K bounds it at ≤ 0.5 mW/KB, and the break-even sits at 0.918 mW/KB. The verdict survives real silicon by about 1.8x — not the 18x it appears to survive by when measured against this project's own assumed value.
That correction is the kind of thing this repository exists to make visible.
No installation, no dependencies, no virtualenv.
git clone https://github.com/abuzaro21/ColdLink-Q.git
cd ColdLink-Q
python examples/run_benchmarks.pyThat one command regenerates every phase artifact, evaluates the six MVP
pass/fail criteria, generates the claims table, renders the HTML report, and
audits docs/paper-draft.md cell by cell against freshly computed values.
It exits non-zero on any disagreement.
Then open runs/report/index.html.
python -m unittest discover tests # 258 testsEvery number in the paper draft is a hand transcription of a generated file, and a transcription goes stale silently. That had already happened here: the README once claimed a realistic limit of 10 qubits when the model said 17.
So benchmarks.py parses the paper's own Markdown tables and compares every
numeric cell against a freshly computed value. Tables are located by header
signature rather than section number, so renumbering cannot silently disable a
check, and a check that cannot find its table reports MISSING and fails
rather than contributing zero.
tests/test_benchmarks.py corrupts the paper five ways on purpose — a wrong
number, a deleted table, a renamed circuit — and asserts the audit notices.
A checker that has never been watched failing proves nothing.
The honest limit: this proves the paper matches the model, not that the model matches reality. A green run means no transcription drift. The constants are still what they are.
| Phase | Module | What it does |
|---|---|---|
| 1 | protocol.py |
OPQCP binary packets: CRC32C, truncated HMAC-SHA256, replay window, late-packet validation, RUN_BATCH multi-operation packet |
| 2 | simulator.py |
Deterministic discrete-event kernel — warm controller → optical link → 4 K router |
| 3 | thermal.py |
Line inventory and passive-conduction proxy, baseline vs proposed |
| 3b | budget.py |
Link bandwidth and 4 K active-power budgets — the two models that can return feasible = false |
| 4 | waveform.py |
4 K router resources: generator capacity, guard bands, detuning-dependent crosstalk, finite macro cache |
| 5 | readout.py |
IQ discrimination, drift, and a bounded calibration loop (see the boundary below) |
| 6 | compiler.py |
Gate list → layered schedule → macro cache → packets, executed on the real simulator and checked against intent |
| 8 | faults.py |
Fault-injection sweep across six axes, plus the config-driven scenarios A-D |
| 8 | benchmarks.py |
One-command regeneration plus the cell-by-cell paper audit |
| 7 | report.py |
Static self-contained HTML report, including the views that were not built |
| 9 | docs/paper-draft.md |
The write-up, machine-audited against the code |
Six fault axes are swept from a healthy control point until a stated criterion fails. Five seeds per point; a point passes only if every seed passes.
| Axis | Breaks at |
|---|---|
| Optical jitter | 80 ticks |
| Packet error rate | 1% |
| Router ingress queue | below 168 in flight |
| Crosstalk coupling | 3.5x the Phase 4 matrix |
| Readout drift rate | 1.5x |
| Readout SNR | 0.6x separation |
A breaking point is reported only where the axis is monotone; an axis that never
failed reports None, never the end of its range. Two of these numbers are
properties of the workload rather than the architecture, and the paper says
which. faults.py's own guards caught two bugs that looked exactly like
results — see §8.5.
readout.py contains no quantum measurement. It models two labelled
Gaussian clouds, a nearest-centroid rule, and what happens when they move. No
qubit state, no resonator, no dispersive shift, no back-action. Every geometry
constant is tagged assumption. Its fidelities are properties of an assumed
geometry in arbitrary units, never predicted hardware readout fidelities.
Its Monte Carlo is cross-checked against a closed form computed from math.erfc
with no sampling in it, because a simulator that samples from the wrong
distribution and then measures the wrong distribution agrees with itself
perfectly. Its calibration loop fails in four of six scenarios by construction —
a loop that always reports recovery measures nothing.
report.py renders, it does not compute. Doc 07 specifies eight views; the
page lists which are built, partial, or not built, because a report that
silently omits what it could not produce is indistinguishable from one where
nothing was expected.
python examples/example_packets.py # packet encoding
python examples/run_phase2_demo.py # event simulator
python examples/run_phase3_routing_thermal.py # line/thermal proxy
python examples/run_phase3b_budgets.py # the budgets that can fail
python examples/run_phase4_waveform_router.py # router conflicts
python examples/run_phase5_readout.py # readout + calibration
python examples/run_phase6_compiler.py # compiler, end to end
python examples/run_phase8_faults.py # fault sweep: where it breaks
python examples/run_phase7_report.py # HTML report
python examples/run_benchmarks.py # everything + the auditArtifacts land in runs/<phase>/.
The repository is built to be argued with, and the two ways of doing it are not equally valuable.
Challenge an assumption. Every constant carries a provenance tag. Open
runs/phase3b_budgets/budget_metrics.json and read assumption_provenance —
anything tagged assumption is engineering judgement with no source behind it,
and macro_cache_bytes_per_qubit, fixed_control_mw, thermal_margin,
max_fibers and lanes_per_fiber are all still in that category. Changing one
and re-running tells you whether it decides anything. The sensitivity analysis
already reports which ones do.
Contribute a measurement. The most valuable single contribution to this
project is a real 4 K SRAM power figure isolated from surrounding logic. It
decides the cache-placement disagreement above and no published source contains
it. See .github/ISSUE_TEMPLATE/measurement_contribution.yml.
CONTRIBUTING.md has the rest.
coldlink-q/
LICENSE NOTICE CONTRIBUTING.md CITATION.cff CHANGELOG.md
docs/
paper-draft.md the write-up, machine-audited
protocol.md OPQCP wire format
prior-art-and-datasheets.md the prior-art pass, with provenance labels
schema/opqcp-packet.schema.json
configs/ scenarios A-D, actually executed
src/coldlinkq/ 10 modules, no dependencies
tests/ 258 tests
examples/ one runnable script per phase
runs/ generated artifacts (committed, so a reader
can check the paper without running anything)
Apache License 2.0. Copyright 2026 Ibrahem Marwani. See LICENSE and NOTICE.
Apache-2.0 rather than MIT for the explicit patent grant (Section 3), its defensive-termination clause, and Section 4(b)'s change-marking requirement — which fits a project whose value is claim provenance: a fork that alters a constant has to record that it modified files.
Section 3 grants patent rights held by contributors to this work. It cannot
grant rights under patents held by anyone else. This repository models an
architecture covered by granted third-party patents, notably US 12,079,690 B2
(Rigetti). Using this software confers no right to practise those. NOTICE says
so explicitly.
Nothing here is legal advice.