open-standards/wai/wai-quantum-js

@transaction-science/wai-quantum

The WAI quantum job service's engine in WebAssembly, for a page or for Node. A job is planned, run and sealed here exactly as the service plans, runs and seals it. The answer is the service's JSON, signed with a key you hold, and any job's receipt, the service's included, is checked here. Programs are linted, drawn and critiqued before they run.

This is version 0.1.2 of the package. It carries the engine of wai-quantum 0.9.0, built from wai-web with its quantum_engine feature. The package keeps its own version line, as the Python package does. The module also holds the rest of wai-web's browser surface (reading WAI envelopes among it); this page is about the quantum engine.

Install

npm install @transaction-science/wai-quantum

It is an ES module with its TypeScript declarations, and has no dependencies.

In a page

init() fetches wai_quantum_bg.wasm from beside the module. With a bundler that does not serve it there, pass its URL: init({ module_or_path: url }).

import init, { QuantumEngine, engine_verify } from '@transaction-science/wai-quantum';

await init();
const engine = new QuantumEngine(crypto.getRandomValues(new Uint8Array(32)), 256);
const text = engine.run(JSON.stringify({
  qasm: 'OPENQASM 3.0; qubit[2] q; bit[2] c; h q[0]; cx q[0], q[1]; c = measure q;',
  shots: 1000,
}));
const job = JSON.parse(text);
console.log(job.method, job.result.counts);
console.log(JSON.parse(engine_verify(text)).valid); // true: the receipt checked on the text it came in

In Node

Node is given the WebAssembly's bytes:

import init, { QuantumEngine, engine_verify } from '@transaction-science/wai-quantum';
import { readFile } from 'node:fs/promises';
import { createRequire } from 'node:module';
import { randomBytes } from 'node:crypto';

const wasm = createRequire(import.meta.url).resolve('@transaction-science/wai-quantum/wai_quantum_bg.wasm');
await init({ module_or_path: await readFile(wasm) });
const engine = new QuantumEngine(randomBytes(32), 256);
const text = engine.run(JSON.stringify({ qasm: 'OPENQASM 3.0; qubit[1] q; bit[1] c; h q[0]; c = measure q;', shots: 100 }));
console.log(JSON.parse(text).result.counts, JSON.parse(engine_verify(text)).signer);

What it offers

Requests and answers are JSON strings, the job service's own. A call that cannot be answered returns {"error": …}; a program the engine refuses also gives its diagnostic code (such as Q310) and its meaning.

new QuantumEngine(seed, memory_mb): an engine that signs with the Ed25519 key whose 32-byte seed is seed, and admits a job of at most memory_mb MiB. Keep the seed to keep the key.

• signer_did(): the key the receipts name, as a did:key.
• run(request): a job run and sealed. The answer holds status, method, why, request and result, with the result's receipt. The request is the service's (qasm, shots, seed, method, observables, amplitudes, noise, intent, verdict, target, compile, mitigate and more).
• plan(request): the method a job would run on and why, its memory and work, without running it.
• compile(request): a program compiled ({"qasm", "epsilon", "level", "basis"}), with a certificate of every pass, sealed.
• estimate(request): what a fault-tolerant machine would need to run a program, each estimate sealed.
• qec(op, args): error correction (code, decode or threshold), the answer sealed.
• landscape(op, request): an energy-landscape job (wai.quantum.landscape/1): op is run, sweep, compare or replay, request the job form's own (the program in epuML under program, and its seed, temperature, seeds, temperatures and parity). The answer (the state, its exact energy, every arrangement checked up to 16 variables, the verdict, the work, the joules priced at rates measured elsewhere, the replay digest, and the member that ran it at its parity) is sealed with the engine's key; a program the reader refuses gives {"error", "line"}. landscape_answer(op, request) gives the answer's bytes without a seal. Nothing here is a quantum effect: it is a classical emulation of a settling model.
• methods(): each method, its accuracy, and the most qubits it holds here.

Functions:

• engine_verify(text): whether a job's receipt seals its request and result and every rule of its form holds (the provider protocol's section 8.4, and §8.6 for a set): {"valid", "reasons", "key", "form", "signer"}, each reason naming a rule broken. An energy-landscape job is held to its own form too (landscape_form, the extension's §5.4), and its verdict adds landscape: the operation, the member and its parity, each rule broken, and whether the answer's energy and plan are its program's (recomputed). Give it the job's text as it came: an object parsed and written out again by JavaScript can differ from what was sealed (a member named by digits moves first, and a large whole number is rewritten), and a member named twice is gone once it is parsed.
• engine_verdict(job, intent, memory_mb): a job's verdict against its intent (or the one given).
• engine_estimate_verify(answer): an estimate's seal, its receipts, and its request re-run to the same figures.
• engine_lint(src): a program read as the engine reads it: {"ok": true, "qubits", "gates", …}, or {"ok": false, "error", "line", "code"}.
• engine_draw(src, width): the circuit as text ({"text"}); engine_layout(src) gives it as data for a page to draw.
• engine_critique(src): what the engine can say about a program before it runs: its measures and its smells, each with its lines.
• engine_equivalent(a, b): whether two programs apply the same gates up to a global phase, and how that was decided.
• engine_repair(src, options): a program repaired on the lines its diagnostics flag.
• engine_shortcuts(src, thorough): every exact classical route to simulating a program, with its cost.
• engine_diagnostic_codes(): every diagnostic code the reader uses, with its meaning.
• engine_course(locale), and the course's lessons, checks and hints: the circuits course, checked by the engine.

The declarations (wai_quantum.d.ts) list every export.

A run in a page or in Node does not meter its energy, and its result says so.

Elsewhere

The same engine runs as the command line (wai-quantum), as the Python package wai-quantum, and as the job service, and a job's receipt verifies in each. The source, its schemas and the versioning policy are at https://git.transaction.science/Transaction-Science/open-standards under wai/; Quantum Studio, an editor built on this package, is at https://wai.transaction.science/quantum-studio/.

Licence

Apache-2.0.