Engineering

Decisions, and what they cost

This page lists the tradeoffs that shaped the site: the problem, the call, what it cost, and where you can check it. One entry records a false claim I found and removed while writing it.

decision 01

Write the physics from scratch in TypeScript

problem: The browser needed a statevector simulator, a density-matrix simulator, a variational optimizer and error mitigation. No maintained JavaScript port of Qiskit exists, and shipping a Python service for every interaction would make every demo a network call.
the call: A small, readable engine (complex linear algebra, gates, CNOT, Kraus channels, parameter-shift VQE, Richardson-extrapolated ZNE) written against the textbook, with the H₂ Hamiltonian coefficients taken from O'Malley et al. 2016 and checked against exact diagonalization.
the cost: Every primitive had to be tested against known results (Bell-pair purity ½, VQE within chemical accuracy, ZNE beating the raw noisy point), a test suite that now runs in CI. The upside is the site's core promise: nothing renders that didn't compute, and the engine is small enough to read.
check it: tests/physics.test.mjs ↗

decision 02

Readable objects for teaching, typed arrays for scale

problem: One complex-number object per amplitude is clear to read and fine for 2-5 qubit games, but 2ⁿ objects hit a wall around 14 qubits.
the call: Keep the readable engine for every game, and add a second Float64Array kernel (split re/im, in-place gates) for the scaling benchmark, cross-checked against the readable engine on random circuits to 1e-10.
the cost: Two engines to keep in agreement, enforced by a test. The benchmark on the arcade runs both live on the visitor's machine, which shows the 2ⁿ wall instead of describing it.
check it: Engine Scaling Benchmark

decision 03

Exact density matrices for noise

problem: Noise could be modeled by sampling Pauli errors (cheap, noisy numbers) or by evolving the full density matrix under a depolarizing channel (exact, 4ⁿ memory).
the call: Exact density matrices everywhere noise appears, the ZNE panel, the Decoherence Dial, the Circuit Lab, so purity and coherence are exact values.
the cost: It caps noisy circuits at five qubits in the browser. For a teaching site that is the right trade: a visitor turning a noise slider sees a smooth, exact curve rather than Monte-Carlo jitter.
check it: Circuit Lab, noise panel

decision 04

Parameter-shift gradients for the VQE

problem: Finite differences are simpler but introduce a step-size error; the parameter-shift rule gives the exact gradient for rotation gates.
the call: Parameter-shift. The convergence curve on the VQE suite is therefore an exact gradient descent, and the final energy matches full diagonalization to the precision shown.
the cost: Two energy evaluations per parameter per step instead of one, irrelevant at two qubits, and the correctness is worth more than the speed.
check it: docs: Hamiltonian and ansatz

decision 05

A Python transpiler service, and a false keyword removed

problem: OpenQASM → Amazon Braket IR needs Qiskit's parser and the Braket provider; that stack is Python and far too heavy for edge functions.
the call: A FastAPI service (Python, Qiskit, qiskit-braket-provider) with a labeled mock on the site when the service is down: the mock's Braket IR carries mock: true, and its circuit metrics are still computed from the real QASM. While writing this page I found an SEO keyword claiming a 'Rust quantum compiler pass' on two pages. There is no Rust in the project, so I removed the keyword.
the cost: A second deployment to keep alive, and the site has to say so when it isn't. The real-hardware lane lives in the same service so the whole 'leaves the browser' path is one codebase.
check it: docs: transpiler pipeline

decision 06

Evidence-integrity CI

problem: Research claims drift: a status changes in one file and not another, a number gets retyped, a source link rots.
the call: The research record lives in two representations (a portable evidence.json and typed TypeScript the site renders) and a validator cross-checks them on every push. IDs, statuses, source URLs. The Field section gets the same treatment plus a hype-phrase blocklist and rules like 'roadmaps must be tagged projection' and 'preprints must be tagged preprint'.
the cost: Adding a claim means touching two files and satisfying a test. That friction is deliberate.
check it: scripts/validate-research.mjs ↗

decision 07

What the pet is allowed to say

problem: A talking companion is a temptation to invent: it could easily 'explain' physics it hasn't computed.
the call: QPet can only say three kinds of things: lines about real routes and sections, lines about its own emotional state machine, and narration of real engine events with the numbers read from the event payload. No language model. Its collapses are Born-rule samples.
the cost: It is less impressive than a chatbot would be. A pet that invents a Hamiltonian would break the site's one rule, so that is the trade.
check it: lib/quantum/events.ts, the documented boundary ↗

decision 08

What CI caught that a laptop never would

problem: Two real defects shipped past local testing: while roaming, the pet's body ignored pointer events so a real mouse click could never poke it (programmatic clicks had masked this); and the phone menu's close-on-route-change effect fired on mount, racing a fast tap on slow devices.
the call: A headed Playwright job in CI on every push, real pointer events, real hydration timing, phone viewports at 375/390/428 px.
the cost: Roughly three extra minutes per CI run and one flaky-timing lesson (never run e2e concurrently with next build, they share .next). Both bugs were found by the job, not by me.
check it: e2e/ on GitHub ↗

decision 09

Deployment: the known wart

problem: Pushing to GitHub runs CI but does not deploy: the Vercel project has no Git integration, so production updates are manual CLI deploys.
the call: Documented here. Every deploy in the history was a deliberate CLI action after a green CI run; the fix is a one-minute dashboard change that requires the owner's account.
the cost: A person sits between 'green' and 'live'. That is stated here instead of pretending the pipeline is automatic.
check it: README. Deploy ↗

The builder page says who made these calls. The paper is what they led to.