Pythonic quantum-classical programming language. Contribute to CQCL/guppylang development by creating an account on GitHub.

Version 2 of the TKET quantum compiler. Contribute to CQCL/tket2 development by creating an account on GitHub.

The author, Kristian Koci, describes his experience developing three practical developer tools for Quantinuum's guppy/HUGR quantum computing stack. These tools - qshelf, Estimand, and qmatchpoint - were built with a focus on correctness and verification rather than as simple demonstrations. The development process revealed six significant bugs in the ecosystem: four in guppylang itself and two in Google's Qualtran library. The bugs included issues with unitary calculations, type handling, and discrepancies in resource estimation formulas. For instance, qshelf uncovered problems with quantum algorithm implementations, while Estimand identified errors in the resource estimation models that required verification against the original research papers. The author emphasizes that treating correctness as a primary concern, rather than an afterthought, led to these discoveries. This approach involved verifying every claim through actual compilation and mathematical reference checks, not just relying on documentation. The tools themselves serve specific purposes: qshelf provides a verified registry of quantum algorithms, Estimand estimates physical resource requirements for quantum circuits, and qmatchpoint integrates quantum error correction decoding. The author notes that these findings highlight the importance of rigorous verification in quantum computing development, even in mature libraries. The work demonstrates how a disciplined approach to correctness can uncover real issues that might otherwise go unnoticed in the development process. The author has made the tools available in repositories for others to use and has documented the findings for transparency.

# I built three tools for Quantinuum's guppy/HUGR stack. Along the way I found six real bugs. I've been working with guppylang — Quantinuum's Python-embedded quantum programming language, compiling to HUGR, running on their Selene simulator and trapped-ion hardware. It's a young ecosystem, and I wanted to build things that were actually useful, not just demos. That meant treating correctness as the whole point, not an afterthought — every formula cited to its source, every claim about compiler behavior verified by actually compiling code and inspecting the output, not assumed from docs. That discipline turned out to matter more than expected. Building three fairly ordinary developer tools surfaced six real, confirmed bugs — four in guppylang itself, two in Google's Qualtran (a widely-used quantum resource-estimation library) — none of which I was looking for going in. ## The three tools **qshelf** — a tested package registry of quantum algorithm implementations for guppylang/HUGR (QFT, Grover, QAOA, VQE-H2), each verified against an independent mathematical reference (exact linear algebra, `scipy.linalg.expm`, exact diagonalization), not just "it ran without crashing." **Estimand** — a fault-tolerant resource estimator for guppy/HUGR programs. Given a compiled guppy circuit, it estimates physical qubit count, runtime, and error probability under a surface-code scheme. It's an adapter, not a resource-estimation engine — it extracts a gate-count summary from real guppy control flow (conditionals, nested loops, cross-function calls, even `CallIndirect`) and feeds it to Qualtran's already-published cost models. Verified end-to-end against unmodified QFT and Grover implementations. **qmatchpoint** — wires PyMatching (an established, peer-reviewed decoder) to the syndrome bits a guppy QEC circuit produces, since nothing in the guppylang/HUGR/Selene stack currently does decoding. ## The bugs Building qshelf against real algorithm math found four guppylang issues: a wrong unitary from `iqft` compiled standalone vs. combined with `qft`, a wrong unitary from multi-controlled Z (later fixed upstream), a rejected generic array-length type, and a rejected `numpy.ndarray` closure (reclassified as a feature request). The more interesting ones came from Estimand. Its whole job is turning guppy programs into gate counts, then trusting Qualtran's surface-code math to do the rest — so I went and checked that math against the actual cited papers (Beverland et al. 2022, Litinski 2019 x2), rather than trusting the citation. Two real discrepancies turned up: * `CompactDataBlock`'s tile-count formula was missing an additive constant from its own cited paper (`arxiv.org/abs/1808.02892`, Fig. 9) — confirmed by a maintainer, and by the time I got around to fixing it, main had already drifted to a _different_ wrong version of the same formula. PR here, awaiting review. * `make_beverland_et_al()`'s magic-state factory error model silently used Beverland's threshold constant instead of Litinski's own, inside a component that's otherwise a faithful reimplementation of Litinski's paper. Turned into a longer, still-open discussion about whether the whole preset should more faithfully reproduce Beverland's actual architecture choices (data block, factory grid-search) rather than borrowing Litinski's defaults. None of this was the goal going in. It's just what happens when "does this actually match what it claims to implement" is a mandatory question, not an optional one, and I think that's a more useful takeaway than any of the three tools individually — verification discipline finds real things, even (especially) in mature, widely-used libraries. Repos linked above if any of it's useful, and happy to talk through any of the decisions behind them.