open-standards/wai/tools/wai-quantum-editor

WAI Quantum for editors

OpenQASM 3, and the OpenQASM 2 forms in common use, with the WAI Quantum engine in the editor. The editor extension highlights OpenQASM and starts the language server, wai-quantum lsp, which brings:

• Diagnostics from the engine. The reader's refusal of a program, on its line, and the critique's smells on theirs: gates that cancel, rotations that merge or do nothing, idle qubits, qubits acted on and never measured. A generator (a program with integer inputs) is read at the values in waiQuantum.inputs, and at 4 for any input not given.
• Completion. The keywords, the standard gates with their parameters as placeholders, and the registers, gates, subroutines and variables the program declares, by what the cursor's place takes: qubits after a gate's name, values in its parameters, integers in an index, bits after ->. In an empty file, whole sample programs.
• Hover. A standard gate's matrix written exactly (1/√2, e^{iπ/4}, cos(θ/2)), held to the engine's own matrix; a user gate's matrix computed from the engine's matrices of its gates, in double precision; and each gate's cost as the engine counts it: two-qubit gates, T count, depth, and whether it is Clifford, at the call's angles or at generic ones, said which. A register's size, a declaration's type, a keyword's meaning.
• Definitions, references, renames, an outline, folding (blocks, comments, and held blocks from // @lock to // @unlock), and formatting in one layout (wai-quantum fmt formats the same way).
• Run, Plan, Critique, Shortcuts and Receipt above the program, and in the command palette. They run on this machine, through the engine the command line uses; a run is signed with this user's key, as wai-quantum run signs it. The answer goes to the WAI Quantum output panel, and a receipt can be saved as JSON.
• A debugger, wai-quantum dap: breakpoints by line, steps forward and back through the program one gate, measurement or reset at a time, and the engine's state at each step as variables (below).

Nothing leaves the machine.

Debugging

"Debug the program" in the command palette, or the run view with no launch configuration, steps through the program in the editor, stopped before its first step. A launch configuration of type wai-quantum takes:

Attribute	What it does
program	The program to step through (${file}, the one in the editor)
stopOnEntry	Stop before the first step, rather than at the first breakpoint
inputs	The values a generator's inputs are read at, as {"n": 4}
noise	Noise channels and their probabilities: the density matrix is stepped, beside the noiseless state
method	auto, exact (the bit-exact state vector), statevector or density_matrix
outcomes	The outcome of each measurement the path meets, in order: a recorded path, replayed. The likelier is taken where none is given

The engine steps the program 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 the density matrix under noise. Up to 16 qubits are stepped, or 8 under noise; a wider program is refused with the reason. Stepping back runs the program again from a saved state, so a state seen twice is the same bits.

While stopped, the variables are the engine's:

• Qubits: each qubit's Bloch vector and purity, and its probability of reading 1;
• State: the method, the amplitudes with their probabilities and phases (or, for a mixed state, the probabilities), the entanglement across the first half of the qubits, the fidelity to the noiseless state under noise, and the state's digest;
• Classical bits as the path has set them;
• Path: the position, the path's weight, and each measurement's outcome with its probability and whether it was given or the likelier;
• Branches: every outcome of every measurement in the middle of the program, as a tree, each with its weight (exact fractions for a noiseless Clifford program), and at each leaf the outcomes that replay it and the distribution of the final measurements.

In the debug console, reduced 0 1 gives the reduced density matrix of qubits 0 and 1, cut 0 1 the entanglement across that cut, and outcomes 1 0 follows another path from the start.

Installing it

The extension needs a wai-quantum command line with the lsp verb (wai-quantum lsp --help says whether it has it):

Where	How
Any platform with Rust	cargo install wai-quantum-cli
macOS or Linux, with Homebrew	brew tap transaction-science/tap https://git.transaction.science/Transaction-Science/homebrew-tap then brew install wai-quantum
Windows, with Scoop	scoop bucket add transaction-science https://git.transaction.science/Transaction-Science/scoop-bucket then scoop install wai-quantum

If the editor cannot run it, the extension says so, with these commands, and offers the setting for its path.

The extension itself is the file wai-quantum.vsix, built from this directory (below). Install it in an editor that takes extensions in that form, from the editor's command for installing an extension from a file. It is not yet listed in an extension registry.

Settings

Setting	What it does
waiQuantum.path	The command line to run, wai-quantum on the PATH by default
waiQuantum.serverArgs	More arguments for wai-quantum lsp: ["--key", "/path/to/key"] to sign with that key, ["--demo-key"] for the published demo key
waiQuantum.inputs	The values a generator's inputs are read at, as {"n": 8}
waiQuantum.shots	The shots Run and Receipt sample
waiQuantum.trace.server	Log the protocol's messages, for a report

The settings and the commands are the extension's public surface. A setting is renamed or removed only as the policy says: in a major release, after at least one minor release in which its deprecationMessage names its replacement, and listed in the deprecations.

Building it

With Node.js 22:

npm ci
npm run package          # dist/extension.js, then wai-quantum.vsix
node test/check.mjs --vsix wai-quantum.vsix

npm test (node test/check.mjs) checks the manifest against the language server's commands and the debug adapter's launch settings, the highlighting token by token, the message when the command line is missing (with the install commands of the command line's README), the other editors' configurations, and, given the package, that it holds exactly the extension's files. With WAI_QUANTUM_BIN set to a built wai-quantum, it checks the extension finds it.

Other editors

Any editor that speaks the language server protocol can run wai-quantum lsp (standard input and output; positions in UTF-16, or UTF-8 when the editor offers it), and any that speaks the debug adapter protocol can run wai-quantum dap (standard input and output; lines from 1). The grammar for highlighting is ../tree-sitter-openqasm. editors/ holds a configuration for three kinds of editor; CI parses each and checks it names the server and the grammar.

The server's settings, in initializationOptions or a configuration change, at the top level or under wai-quantum, are inputs (an object of integers) and shots. Its commands, for an editor to bind, are wai-quantum.run, wai-quantum.plan, wai-quantum.critique, wai-quantum.shortcuts and wai-quantum.receipt, each taking the document's URI; each answers with summary, text and the engine's json, and shows the summary as a message.

An editor configured in Lua

editors/wai-quantum.lua: copy it into the configuration's plugin/ directory. It sets the .qasm file type, starts the server (through the built-in configuration from version 0.11, or the lspconfig plugin before it), registers the grammar with the tree-sitter plugin (:TSInstall openqasm builds it), and adds :QuantumRun, :QuantumPlan, :QuantumCritique, :QuantumShortcuts and :QuantumReceipt, each showing the answer in a split. With the debug adapter plugin, it registers wai-quantum dap as the adapter for OpenQASM, with a configuration that debugs the current file. The grammar's own queries are in this editor's capture names; if the plugin does not install them, copy ../tree-sitter-openqasm/queries/*.scm to queries/openqasm/ in the configuration directory.

An editor configured by languages.toml

editors/languages.toml: add it to languages.toml in the configuration directory, copy editors/runtime/queries/openqasm/ to runtime/queries/openqasm/ there, then fetch and build the grammar with the editor's own grammar commands (--grammar fetch, then --grammar build). It runs the server, formats with wai-quantum fmt, highlights with the grammar, and debugs with wai-quantum dap (its template asks for the program).

An editor with WebAssembly extensions described by extension.toml

editors/extension/: install the directory as a development extension. It names the grammar, its highlighting in that editor's capture names, and a small extension (src/lib.rs) that finds wai-quantum on the PATH (or at lsp.wai-quantum.binary.path in the settings) and starts wai-quantum lsp, passing any initialization_options the settings give. CI builds it for wasm32-wasip2.

The query copies under editors/ are written from the grammar's by npm test -- --write-queries, and the check fails when one differs.

Publishing

The extension is not published. Listing it in the open extension registry and in the main extension marketplace needs the owner's publisher accounts on each; the publisher in package.json is the name it would be listed under.