quantinuum

name	quantinuum
description	Build and run Guppy/Selene quantum circuits on Quantinuum stacks; healthcare/hackathon triage kernels (QUBO, biomarker features)
version	1.1.0
metadata	{"hermes":{"tags":["quantum","guppy","selene","pytket","quantinuum","healthcare","hackathon"],"category":"research","requires_toolsets":["terminal"]}}

Quantinuum (Guppy + Selene)

Write real quantum circuits in Python with @guppy, compile them, and execute shots on the Selene emulator; optionally compile the same circuit offline with TKET for an independent check.

When to Use

Load this skill when the task mentions Guppy, Selene, Quantinuum (H1/H2/Helios/Sol/Apollo), pytket/TKET, QPDE, QSP/QSVT, Shor / modular exponentiation, SWAP tests, Steane codes, quantum TDA / Laplacian moments, Floquet dynamics, tomographic equivalence, shot sweeps, noise/ZNE mitigation on a quantum kernel, or any healthcare/hackathon use case that maps clinical triage onto quantum circuits (delayed discharge, biomarker risk stratification, EndoTrack-style referral QUBOs — see references/healthcare-endometriosis.md).

Setup

python3 -V                                   # must be >= 3.12
pip install "guppylang>=1.0"                 # Selene ships inside guppylang
pip install pytket pytket-quantinuum         # optional TKET lane (offline, no credentials, no HQCs)

Guppy v1.0 is a breaking release (output replaces result, measure(q).read(), emulator builder). Touching any pre-v1 code? Read references/guppy-v1-migration.md first.

Procedure

1. Model first, circuit second. Write the classical Hamiltonian / oracle / matrix in NumPy and check it against the source paper before any @guppy code exists.
2. Write the kernel in a real .py file (never a REPL/exec/notebook cell — Guppy reads source with inspect.getsource). Parameterize by generating a temp module; see references/driver-pattern.md.
3. Smoke-test small: 1–2 qubits, 64 shots, ideal error model. Confirm the distribution is what the classical model predicts before scaling.
4. Verify semantics with a dense-matrix oracle (global-phase-free: ||a − (⟨a,b⟩/|⟨a,b⟩|)·b|| ≤ 1e-9) whenever you claim a rewrite or gate-count reduction.
5. Run the sweep resumably: one JSON file per row under _cache_<name>/, then loop while [ $(ls cache | wc -l) -lt N ]; do timeout 580 python -m ...; done. See references/sweep-runner.md.
6. Add noise last: depolarizing/leakage ladder, then Richardson ZNE. Vendor-realistic H2 parameters are in references/selene-runtime.md.
7. Report from committed JSON, not from a live process — the results file is the artifact.

Navigation

Task	Read
Gates, qubits, angles, measurement, controlled phase	references/guppy-language.md
SWAP test, Toffoli, CSWAP, amplitude encoding, QFT readout, feed-forward	references/circuit-patterns.md
Guppy v1 migration: renames, emulator builder, compatibility shim	references/guppy-v1-migration.md
Parameterized circuits, angle hygiene, temp-module import	references/driver-pattern.md
Sweeps as first-class objects + resumable per-row cache	references/sweep-runner.md
QSP/QSVT kernel + NumPy phase finder	references/qsp-qsvt.md
Controlled pow_const_mod for small-N Shor	references/shor-modexp.md
Quantum Phase Difference Estimation + ethylene benchmark	references/qpde.md
ADAPT-GQE generative circuit synthesis	references/adapt-gqe.md
[[7,1,3]] Steane code, RGT gadget, partial-FT cadence	references/encoded-circuits.md
Quantum-TDA Laplacian moments	references/laplacian-moments-tda.md
Cross-platform validation (PEC + ZNE, IBM ↔ Quantinuum)	references/cross-platform-validation.md
TKET/pytket offline compile lane, native rebase, equivalence oracle	references/pytket.md
Hardware roadmap (Helios → Sol → Apollo → Lumos)	references/hardware-roadmap.md
Compile + run shots, mid-circuit measurement, noise models	references/selene-runtime.md
Tomographic equivalence proofs (18-cell 1q, 324-cell 2q)	references/tomographic-equivalence.md
Composing a variational ansatz with a Clifford canonicaliser	references/rewriter-composition.md
Nadarasa v0.4.2 reference stack (QPDE, noise+ZNE, TDA, Floquet)	references/nadarasa-v042-stack.md

Pitfalls

1. @guppy functions must live in a real .py file on disk — REPL / exec() / notebook cells fail under inspect.getsource.

2. angle(x) is in HALFTURNS, not radians. angle(0.5) = π/2 (S gate). For radians θ use angle(θ / math.pi). Any source formula containing an explicit π: divide the π out first (t = π/16 → angle(1/16)).

3. Tomographic-equivalence threshold = 4·√(0.5/shots). The textbook 3σ·√(p(1−p)/n) form gives false FAILs near p = 0 or p = 1.

4. No coherent / T1–T2 noise model ships with Selene — only IdealErrorModel, DepolarizingErrorModel, SimpleLeakageErrorModel.

5. Long sweeps must be resumable. One timeout otherwise wipes the whole run.

6. Guppy v1 breaks every pre-v1 driver: result(...) → output(...), measure(q) → measure(q).read(), and build(compiled).run_shots(...) → the emulator builder (program.emulator(n_qubits=N).with_shots(S).with_simulator(Quest())...run()). Pass the @guppy program object, never program.compile(). Pin OptimizationLevel.Classical for gate-count benchmarks — v1 optimises on compile.

7. Gate every count claim on a unitary-equivalence oracle. An optimiser that changes semantics looks like the best optimiser in the table.

8. TKET drops idle wires — add_blank_wires before comparing or sampling, or the TVD reads 1.0. Native ops (PhasedX, Rz, ZZPhase, ZZMax) are halfturns on both sides, so compiled circuits round-trip onto Selene with no angle conversion.

9. Only Clifford segments may go through a rule-(N/M/P) canonicaliser. Split at rotation boundaries; verify Ry(θ)/Rz(θ) cores with the dense oracle. CNOT · Rz(2θ) · CNOT is , not a Givens rotation.

Running as a team

When the work is split across profiles (orchestrator / runner / analyst / scribe), keep the boundaries hard:

• Long sweeps go to a runner profile that only executes and reports artefact paths. It does not interpret, fit, or claim.
• The per-row JSON cache is the hand-off artefact between runner and analyst — never a chat summary of the numbers. If it isn't in _cache_<name>/ or a committed dump, it didn't happen.
• No claim crosses a profile boundary without its verification evidence attached: the shot count and 4*sqrt(0.5/shots) verdict for a probability comparison, the 1e-9 unitary-oracle result for a gate-count reduction, the artefact path for anything else.
• The writer cannot introduce a number that is not already in an artefact.
• One process per profile. Share memory through an MCP memory server, not a shared profile.

Verification

python3 scripts/qtda_template.py

Prints a SWAP-test fidelity in [0, 1] for two amplitude-encoded states. If it errors on measure(...) or result(...), the installed guppylang is pre-v1 — reinstall guppylang>=1.0.