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

# @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.0 of the package. It carries the engine of `wai-quantum` 0.7.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

```sh
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 })`.

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

await init();
const engine = new QuantumEngine(crypto.getRandomValues(new Uint8Array(32)), 256);
const job = JSON.parse(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,
})));
console.log(job.method, job.result.counts);
console.log(JSON.parse(engine_verify(JSON.stringify(job))).valid); // true
```

## In Node

Node is given the WebAssembly's bytes:

```js
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 job = JSON.parse(engine.run(JSON.stringify({ qasm: 'OPENQASM 3.0; qubit[1] q; bit[1] c; h q[0]; c = measure q;', shots: 100 })));
console.log(job.result.counts, JSON.parse(engine_verify(JSON.stringify(job))).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.
- `methods()`: each method, its accuracy, and the most qubits it holds here.

**Functions:**

- `engine_verify(job)`: whether a job's receipt seals its request and result: `{"valid", "key", "signer"}`. Any change to either after sealing makes it false.
- `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.