open-standards/wai/quantum-studio/README.md

Quantum Studio

An editor for OpenQASM programs, with three places to run them:

• this browser, through the quantum job service's engine compiled to WebAssembly, in a worker;
• this computer, through the same engine built natively, in the desktop app;
• the job service, over HTTP.

In the desktop app, your hardware is a fourth: one of your own providers (wai-quantum providers add), its estimate asked for first and a dialog shown before a run that is not free, the credential held by the app and never by the page. In a browser tab the switch only says that such runs go through the desktop app or the command line (wai-quantum run --provider NAME), since a browser tab must not hold a provider's credential.

Every place returns the same job: the request, the method and why it was chosen, the result, and its receipt. Every run asks for its verdict, and the result shows the level the engine checked to as a badge, with its statement, sealed by the receipt; a result from a host that gives none, and a refused run, have theirs worked out on this device, and say they are not sealed. The Studio shows them the same way and checks every receipt on the machine it runs on. The same request with the same seed gives the same counts in each place.

The editor:

• highlights OpenQASM;

• completes the standard gates and the program's own registers;

• marks the engine's diagnostics on their lines;

• draws the circuit and shows the plan as you type.

• lets you edit the circuit by its drawing (below);

• reads the circuit to a screen reader in the engine's words, and saves the drawing as SVG or LaTeX.

Ctrl+Enter (⌘+Enter on macOS) runs the program, and Escape cancels a run. The program and the history of runs are kept on the device. "Copy link" puts the program in a URL fragment, which no server sees.

The course

Course opens the circuits course (wai-quantum/course/): 21 lessons from a first circuit to a resource estimate, the same course wai-quantum learn runs. A lesson is a short text and an exercise:

• Load the starter puts the exercise's starter program in the editor; your draft stays in Versions.
• Check runs the program in the editor against the exercise with the engine (in this browser, or natively on the desktop): the verdict of each case with its badge, each rule (the gates allowed, gate counts, the T count, the critique's smells, the estimate's counts) with ✓ or ✗, and passed or not yet.
• What went wrong? says what the reader's diagnostics, the verdict and the critique found, in your language, with the engine's own words beside them.
• Hint gives the lesson's hints one at a time, with the engine's pointer toward where to look.
• Ask the assistant for a hint, with a model connected, asks it for one hint and tells it not to write the program; a program in its answer that passes the exercise is held back, and code is not shown.

None of these shows the solution. Progress (which lessons passed, how many checks and hints) is kept only in this browser, and the pane says so. Quantum, reconsidered, the course on interference and learning, is linked beside it.

Languages

The interface's words are data: locales/<locale>/<area>.json, one file for each part of the interface, English the source and Simplified Chinese beside it (locales/index.js gathers them). The Studio follows the browser's language until you pick one with the switch in the header; your choice is kept in this browser. A host may pin one with data-lang on the mount element. The engine's own messages (a verdict's statement, a diagnostic) stay as the engine writes them. The Chinese words are a machine-assisted translation, marked so in each file and in the footer, to be reviewed by a fluent reader. node test/locales.test.mjs holds every locale to every key, with the same placeholders.

Step through

"Step through", under the circuit, runs the program one gate, measurement or reset at a time on the engine's debugger, in this browser (or natively on the desktop). It steps on a method where every number is exact for it: the bit-exact state vector when every angle is a dyadic multiple of 2π, else double precision, and under the job's noise the density matrix, beside the noiseless state on the same path. Up to 16 qubits are stepped, or 8 under noise; a wider program is refused with the reason.

• The slider and the buttons beside it move forward and back. Going back runs the program again from a state the engine saved, so a step seen twice is the same bits, and its digest says so. The next step is named with its line, and a gate is marked on the diagram.
• Qubits: each qubit's phase disk (its fill the probability of reading 1, its hand the phase about Z, its ring the purity) and its Bloch sphere, a plain drawing seen from one side, with the engine's numbers under them. The entanglement across the first half of the qubits is given beside them.
• Amplitudes: each basis state's amplitude, probability and phase, the most probable first, each with a disk whose area is the probability and whose hand is the phase. For a mixed state, the probabilities.
• Reduced state: the density matrix of the qubits you tick, each entry's size shaded, with its purity and entropy.
• Against the noiseless state: under noise, each probability of the noisy state beside the noiseless one's, and the fidelity between them.
• Branches: every outcome of every measurement in the middle of the program, as a tree, each with its probability and its weight: exact fractions for a noiseless Clifford program. Each leaf gives the distribution of the final measurements on it. Choosing a branch puts the path on it; with none chosen, each measurement takes the likelier outcome.

Every number shown is the engine's; the drawings only place them.

Editing by the drawing

Above the diagram is a palette of gates. Drag one onto a wire, or choose it and then click a place: it goes on that wire (a two-qubit gate on that wire and the next), before the gates drawn to the right of the drop. Drag a drawn gate up or down to put it on other wires, or left or right to move it among the others. From the keyboard, Tab to a gate: ↑ and ↓ move it between wires, ← and → before the gate before it or after the gate after it, and Delete removes it ("Delete gate" does too).

The engine makes each edit in the program's own text, through its syntax tree, so the program keeps its names, its layout and its comments. The editor records it as your edit, as if you had typed it. A gate that one statement does not make alone (one gate of a broadcast over a register, of a gate the program defines, or of a loop) cannot be moved or deleted from the drawing: the Studio names the line to change. A generator's circuit depends on its inputs, so it is edited in its text.

The circuit in words, and as a file

The diagram's description, which a screen reader reads, is the engine's account of the circuit: its qubits and bits, then each column, each gate with its role on each qubit, each measurement with its bit, and each condition as the legend writes it. "SVG" saves the drawing as the engine writes it, a standalone image that follows the colour of the text it is placed in, and "LaTeX" saves it as one picture in plain TikZ that needs only \usepackage{tikz}.

Device

Under Device, a device target: one of the built-in targets (synthetic, in the shapes of published formats), one imported here (Import… reads a calibration or target snapshot in any format the engine reads, kept in this browser), or, in the desktop app, one kept with wai-quantum targets import. The coupling map is drawn with each pair coloured by its two-qubit error and each qubit by its readout error, one-qubit error or T1. The colours are five bins of one hue, by quantile of the device's own values; the poorest pairs are drawn thicker, every mark gives its numbers on hover, and As a table lists them. With a device chosen, a run is compiled to its gates, placed on the qubits and routes most likely to succeed, and simulated under its noise; the noise fields wait, since the noise is the device's own. The layout the plan chose is drawn on the map before the run. The result's Device block names the target and its hash (in the receipt), the placement and its expected success beside the fewest swaps', the noise, and how far the counts are from the ideal ones. It is a model of the device, and it says so. On the service, a built-in target goes by name and any other as its document.

Generators

The editor reads a program with the engine's own reader, the one every surface uses: the whole of OpenQASM 3.1, each problem marked on its line with the reader's code ([Q103]); engine_diagnostic_codes() gives each code's meaning.

A program that declares integer inputs (input uint n;) is a generator: its for loops and its ifs on integers write out one circuit for each value. The Studio shows a field for each input under the editor and reads the program at those values. The lint and the critique read the generator itself, so a problem or a smell keeps the generator's own line. The diagram, the plan, a run (here or on the service), the lens and the alternatives take the circuit it writes out. The values are kept in this browser, by name.

The Workbench

The Workbench searches a family of circuits for its cheapest members, and the engine judges every proposal. The program in the editor is the reference. The specification says:

• what each member must do: prepare the same state from |0…0⟩, or be the same circuit;
• the sizes to check at (n = 3, 5, 8);
• the gates allowed, and whether a gate may join any pair or only neighbours on a line;
• the cost, as weights on the critique's measures summed over the sizes;
• the two measures the map plots.

"Start" checks the reference at every size and seeds an archive with it. The archive keeps the cheapest verified generator in each cell of the map. Three proposers write into it, and each is named on what it found:

• the reader: "Submit the editor's program";
• the built-in, blind search: "Search ×100", seeded edits of what the archive holds. It is the baseline an idea has to beat;
• the model, when one is connected: "Ask the model ×3". It is told the specification and shown the cheapest found, with the costs the engine measured.

A proposal is verified only when it reads, keeps the rules and passes the check at every size. Each kept entry is sealed with this browser's key (the desktop app's, in the app). Clicking a point shows its cost, how it was checked, its seal and where it came from; "Open in editor" puts it in the editor. The archive is kept in this browser and comes back with the page. "Download" saves the specification and its archive side by side (NAME.json and NAME.archive.json), so wai-quantum discover verify NAME.json checks every seal. In the desktop app a search also counts its seconds and the joules its process spent.

Rewrites

"Rewrites", under the circuit, lists every rewrite the program admits that keeps its meaning: gates that cancel, rotations that merge, a gate between two Hadamards that becomes its conjugate, a gate carried past what it commutes with, two gates that trade places. The engine checks each one on the qubits it touches. Pointing at a rewrite marks its gates on the diagram; "Take" offers it as the engine's proposal, reviewed like any other, and the list follows the program as it changes. In Alternatives, a candidate that is the same circuit as the draft says how the draft becomes it, as a chain of checked rewrites.

Compiling

"Compile", under the circuit, takes the program through the engine's passes, each checked where it acts, to Clifford+T within the budget ε (or to the standard gates, nothing approximated), at level 0, 1 or 2. Each pass is a row: the gates, CNOTs, T gates and rotations before and after, and its check (proof, exact, or approximate with its distance). The line above says how far the output is from the program, up to a global phase, the budget and how it was shared among the rotations, the whole output's distance measured against the program on dense unitaries (up to 8 qubits), and whether the certificate, sealed with this browser's key (the desktop app's, in the app), verifies here. The circuit after the last pass is drawn under the table; choosing a pass draws the circuit after that one. "Use" offers the compiled program as the engine's proposal, reviewed like any other. A compile is marked stale once the program changes. The passes, the levels and how to read ε are on the compiler page.

"Estimate", under the compile lens, says what a fault-tolerant machine would need to run the program, on the physical qubit chosen and within the error budget given (the probability the run may fail). It gives the program's logical counts first: its logical qubits (with the ancillas a gate under several controls takes), measurements, T gates, Toffolis and rotations, the T gates in the rotations' synthesised words, and the T depth and total depth; then each rotation's share of the budget and how many T gates its word took, and the code model the distance is chosen by (on a gate-based qubit, fitted to the engine's own exact-matching or union-find decoder, or the planar model's assumed one). The estimate is the headline: physical qubits, T factories and the share of qubits they take, runtime and code distance. The frontier plots every estimate no other beats on both physical qubits and runtime, runtime across and qubits up on log scales, and lists them in a table; pointing at a point, or focusing it, reads it out. Every estimate is sealed with this browser's key (the desktop app's, in the app) in the resource-estimate receipt family, and the line under the table says whether the seals verify and whether the request re-run here gives every figure. An estimate is marked stale once the program changes. Every number and what it assumes is on the estimate page.

Error correction

"Error correction", a closed section under the result, opens on a code chosen from a list: the rotated surface code, the triangular colour code, the toric code, the Steane code, and two bivariate-bicycle codes. Its lattice is drawn with each check and qubit, and its distance certificate stated under it: in each sector, the least weight of a logical found, and every lighter support ruled out by an exhaustive search; "Show witness" rings a logical of that weight on the lattice. Clicking a qubit (or Enter on it) flips it, and its syndrome lights the checks it violates; "Decode" corrects the syndrome with the decoder chosen, draws the correction, and says whether the residual is a product of stabilizers (the logical state unharmed) or a logical error. Under "Threshold", "Measure" samples logical failure rates at distances 3, 5 and 7 over three physical rates and plots them on log scales, each point with its failures, shots and standard error. Every answer is sealed with this browser's key (the desktop app's, in the app) and checked here. What each decoder guarantees is on the error-correction page.

With noise set, "Mitigate", in the Noise section, mitigates the run's expectation values (zero-noise extrapolation, error amplification or cancellation from a learned noise model, Clifford data regression, virtual distillation, or readout inversion). The result shows each value raw and mitigated with its error bar, beside the ideal one the simulation knows, with the method's bias and error-bar assumptions and the circuits and shots it took.

What is new, and Found

The engine says what is new in a program: the known construction it is, found again; a known result reached by a different route; or how far it is from the nearest program it was compared with. The known constructions are GHZ by a chain, by doubling and by fan-out, the uniform superposition and the quantum Fourier transform. The distance is structural, from 0 (built alike) to 1 (nothing shared), and it is the engine's, not a search of the literature.

• Alternatives: each card says what is new in it, against the known constructions and the draft. A card that reaches a known result by a different route is marked.
• The Workbench: each kept generator is named for what it is, and its entry shows it with the measures it beats the reference on that the cost does not weigh. A candidate that breaks only one rule of the specification (a gate, or the line) and would be verified without it is an aberration. It is never kept: the log says what it would cost, and "Try without that rule" loosens the specification, for a new archive under it.
• Found keeps what is worth a second look: a different route to a known result, an aberration, a verified entry far from everything it was compared with. Each can be opened in the editor, saved with a note, or dismissed. Its count says how many were flagged and how many saved. It is kept in this browser.

Your own way

Under Versions, "Your own way" says whether your versions are converging on the model's proposals: how far your latest is built from them, and how much of the program is the model's. "Explore on my own for a while" pauses the model while you work:

• the assistant only asks questions, and does not offer its programs;
• Alternatives' Explore and the Workbench's "Ask the model" wait;
• the versions you make are noted as made on your own, and the line sets their distance from the proposals beside the rest.

"End" lets the model propose again. The mode is kept in this browser.

Study

The Study pane lets you take part in a study of how people design with the engine, or keep a record for yourself:

• Features: each of the Studio's features can be turned off. While you take part in a study, its condition sets them and holds them, so that each can be compared against a control.
• Load a protocol: a researcher gives you one, sealed before any data. You see what it studies before you choose. "Take part" assigns your condition by this browser's key, so it is fixed before you begin.
• Kept, in this browser only, once you ask:
  • which of Improve's candidates you applied, with the engine's best of them;
  • which kept generator you opened in the Workbench;
  • your answers on ownership ("How much is this yours?", five items from 1 to 7);
  • the probe tasks you do with the assistant paused, scored by the engine.
• My record: the engine's measures of what you made and did, each computed again from it.
• Export my record: your record sealed with this browser's key, saved as a file to give the researcher. Nothing is sent. "Leave the study" gives you the features back.

Your taste

"Your taste", in the Workbench, learns what you prefer from your own choices:

• Compare two shows the two kept generators your profile is least sure of. The engine proves that they do the same thing, so the choice is about taste, never correctness. "This one" keeps it, and "About" says what it was for: economy, clarity, insight, precision or utility.
• From Alternatives too: an alternative that is the same circuit as the draft, taken whole or refused whole, is a choice between the two. One taken in part says nothing. Improve orders its candidates by your profile once it has a choice.
• Rank by my taste orders the kept generators. Each shows its typicality (how near the known constructions it is built), which the profile never learns and only the dial moves from typical to novel. The ranking says where a part, or the cost, puts another first, and whether its first three are built more alike than the cost's.
• Profiles: each name is a profile of its own, kept in this browser; nothing pools them. The summary says how many of your choices the profile predicts, each from the ones before.

Versions

The Versions pane records each change to the program and who made it:

• what the reader types is theirs, recorded once they pause, before a run, and before anything else changes the program;
• a proposal is its proposer's: the assistant's program, an alternative (the engine's or the model's), a generator opened from the Workbench;
• a fix is the engine's;
• an example, a file, a link or an earlier run is where the program came from.

A proposal is taken change by change. Its changes are listed with their lines, each with a box, and the program waits until the reader chooses. Only the changes taken reach the program. The version keeps the whole proposal and which changes were taken, so a rejected one stays readable.

Lines of work. The versions are drawn as lines of work. "Open" puts an older version in the editor, and what is changed from it starts a line of its own. "Bring in" shows another line's head change by change against the program, and the changes taken are recorded as a merge of both.

Whose hand. "Who wrote it" marks each line in the editor's gutter and each gate on the diagram: the reader, the assistant, an agent, the engine, where it came from, or a model's line the reader then edited, which is in both hands. The pane shows each contributor's gates and lines.

On the receipt. A run's request carries the account of the version in the editor: its digest, and the gates and lines in each hand. The receipt binds it, and the result shows "written by" and the account recomputed here from the versions. The versions are kept in this browser, each sealed with its key (the desktop app's, in the app). "Download" saves program.qasm and program.history.json, which wai-quantum history verify program.qasm checks.

An embedding page can offer a program as someone's proposal with window.quantumStudio.propose(qasm, {kind, name}, note); it resolves once the reader has chosen.

Rules for proposals

Under the editor, "Rules for proposals" holds what no proposal may change:

• Held lines: "Hold the selected lines" marks them in the program with // @lock and // @unlock. They are shaded in the editor, and their gates are marked on the diagram.
• Gates: the gates a proposal may add, and gates to avoid.
• Qubits: "Hold the qubit declarations".
• Text to avoid.
• A region: "Keep the next proposal to the selected lines", let go once that proposal is decided.

The engine checks every proposal against them change by change: the assistant's program, an alternative, a fix, a generator from the Workbench. A change that breaks a rule is shown in the review with the rule and cannot be taken. The version in Versions records it as blocked. An alternative whose every change breaks a rule is left out, with the reason. The model is told the rules with every request. What you type is yours to change.

The assistant

The Assistant pane talks to a language model on this machine: any server with the chat-completions interface and tool calls, such as the JouleClaw runtime or a llama.cpp server. The address goes under "Model…" and is http://127.0.0.1:8080/v1 by default. Nothing leaves the machine unless the address points elsewhere. In the desktop app the app makes the call itself, so no browser origin rule stands in the way.

The engine is the model's tool, not an afterthought:

• Its tools are the Studio's engine: read the program, lint, draw, plan, run, and say what is new in a program. Its first turn must call one of them, so every answer starts from the engine. It may call a program new only when the engine says so, and then as the engine's distance, not a search of the literature.
• Every program it proposes is checked before it is offered. The engine reads it here. One that does not parse goes back to the model once, with the engine's reason, to be corrected. One that parses is run, with the settings the model used, so the counts it quoted are the counts shown. Then "Apply" puts it in the editor.
• Every proposal shows its verdict as a badge: the level the engine checked it to (refused, parsed, executed, checked as evidence, checked as proof), with the engine's statement. The model is told to give run_job an intent and to quote the verdict, never to call a program valid beyond it.
• It may state only figures the engine returned. A figure in its prose that no tool returned is marked "Not from a run".
• Answers are plain text. LaTeX a model writes anyway is shown as Unicode.

node test/assistant-live.mjs URL drives the assistant against a real model server and prints what it did. It is not part of CI, which has no model.

Answer views

Under Answer views, an answer in the answer view layer (quantum-answers.md) is drawn as it arrives: the program in a fenced qasm block, and views whose numbers come from engine calls written with @ (counts = Histogram(@Sample(bell, 1000)), check = Verdict(@Check(bell, {"00": 0.5, "11": 0.5})), seal = Receipt(@Seal([bell, counts, check]))). Paste one and choose Draw, or ask the connected model for one: it is told the layer, streams its answer, and each view is drawn as soon as its statement and what it names have arrived, a program's circuit growing gate by gate while its lines stream in.

• The text goes through the engine's own reader (AnswerStream in the page, the native one on the desktop), so what is drawn is what the layer says.
• Every number in a view is the engine's, from its call carried out here; a view whose argument is a number the model wrote is refused with J104, and every other problem is listed with its line and code. A view whose call the engine refuses shows the refusal, for that view alone.
• A Receipt is the seal of the statements it names, checked here. Save with its receipt saves the answer with the marker line that lets anyone check it again by running it.

Correctness record

Under the assistant, Correctness record keeps, when you turn it on, one record of each answer the model gives (an assistant's proposal, or an answer in the layer): the diagnostic codes it drew, the level the engine checked it to and whether its intent held, the repairs made, whether you took it (Apply and Take it) or set it aside (Not this), and its receipt. It is off by default: until you turn it on nothing is recorded and nothing is written, not even a key in this browser's storage. Nothing is ever sent anywhere. Export the record saves it to a file; Export the failures as an eval corpus saves the answers that did not hold, or that you set aside, in the conformance format, which wai-quantum eval run --tasks takes.

Views for agent hosts

src/views/ is the same interface as six views an agent host draws through the Model Context Protocol's extension for interactive views (io.modelcontextprotocol/ui, version 2026-01-26): a result with its verdict, a receipt, a circuit, a critique, an estimate's frontier and a device target's map, each from the Studio's components (circuit-svg.js, verdict-view.js, result-parts.js, device.js, estimate-view.js, critique-view.js). build-views.mjs puts them into one self-contained page with the engine inside it (wai/wai-quantum-views), as WebAssembly and translated to JavaScript, which wai/wai-quantum-views/build.sh writes to wai/wai-quantum/views/ for both MCP servers to serve; node build-views.mjs --check says whether that page is built from the sources as they are.

What is stable

The Studio is an application. What it promises is the engine's, through what it gives: a job in the engine's job JSON, which follows its schemas, its result naming the engine that made it and its schema, and a receipt that verifies in every later version; and the history files wai-quantum history verify checks. What each WAI Quantum version promises, and how a change is announced: the policy; what is deprecated: the deprecations.

Hosting it

Build it with npm ci && node build.mjs. That writes dist/:

File	What it is
studio.js	the interface, bundled
worker.js	the engine's worker
studio.css	the Studio's styles
tokens.css	the site's design tokens, for when it stands alone
index.html	the page that stands alone

A host mounts the Studio on an element:

<div id="studio"
     data-engine-pkg="/quantum-ide/pkg/wai_quantum_ide.js"
     data-worker="/quantum-studio/worker.js"
     data-service="/quantum-jobs"></div>
<script type="module" src="/quantum-studio/studio.js"></script>

data-embedded tells the Studio the host page has its own heading, so the Studio's name is not a second h1. data-lang (en or zh-CN) pins the language. data-engine-pkg names the engine's browser package: wai-web built with the feature quantum_engine. node build.mjs --pkg DIR copies such a package into dist/pkg/ for index.html. On the desktop, window.__TAURI__ is present and the Studio uses the native engine instead.

Testing it

node test/telemetry.test.mjs holds the correctness record to its rule without a browser: while it is off, nothing is recorded, nothing is written to storage and the engine is not asked.

WQ_CLI=PATH/wai-quantum [WQ_SERVICE=PATH/wai-quantum-service] node test/views.test.mjs is a scripted agent host in the installed browser: it finds each tool's view, reads the six pages (each within 1 MiB), and draws each in a sandboxed frame under the extension's default content-security policy and under that policy with WebAssembly allowed; the receipt is checked in the view (as JavaScript and as WebAssembly), a changed result fails the check, the model is told the check, the service's running job is followed by the view, and no view makes a request of its own.

The Studio itself:

node build.mjs --pkg PATH/TO/PKG && node test/studio.test.mjs

The test runs the Studio in the installed browser:

• lint, draw and plan as the program is typed;

• a run in the browser, with its receipt checked there;

• an error marked on its line;

• a rotation run on the state vector;

• the same job on the live service giving the counts run here, shot for shot;

• Ctrl+Enter;

• the program and the history surviving a reload;

• the estimate pane: a gate under three controls counted through an ancilla, the estimate on a chosen qubit, the frontier plotted and listed, its seals verified and the request re-run in the page;

• the assistant, against a scripted model server: a tool call run on the engine, a proposal the engine cannot read sent back with its reason, the corrected one checked and run before it is offered, and Apply;

• stepping through teleportation on the bit-exact method: the slider forward and back to the same bits, the next step named and marked, each qubit's Bloch sphere and phase disk, the amplitudes, a reduced state, the four branches a quarter each, one chosen and the state it leaves, and the noisy state against the noiseless one;

• editing by the drawing: a gate dropped from the palette onto a wire, one dragged to another wire, moved and deleted from the keyboard, each recorded as your edit, and a gate of a broadcast refused with its line;

• the circuit described in the engine's words, and the drawing saved as SVG and as LaTeX;

• the course, in English: a lesson's starter loaded and checked, what went wrong, a hint with its pointer, the solution passed and kept in the browser, a rule and a generator's cases each with their verdict;

• the course in Chinese from the browser's language, the switch to English and back, and the layout at a phone's width with the course open;

• the layout at a phone's width.

• the correctness record, off by default and nothing kept while off; turned on, a proposal recorded with its level, "Not this" kept, and the failures exported as a corpus;

• answer views: an answer drawn from its text, its numbers the engine's, a number the model wrote refused with J104, the seal checked here, and an answer the scripted model streams drawn view by view before the stream ends;

STUDIO_SKIP_SERVICE=1 leaves the service step out. It saves screenshots of both colour schemes in test/screenshots/.