8436745b66
RFC 8785's spelling of a large whole double is taken; a set's receipt is section 8.6, with three reasons, and every surface judges a set by it; a receipt is checked on its text in the Studio, the desktop app and the npm example; set requests are screened; the tools take a job's text; qubit_names covers every qubit qasm3 acts on; the service's verify schema describes signer. Corpus: two sets made by the command line, fourteen set vectors, five number vectors, one names vector; three more plants. Work in progress: its battery is running. Co-Authored-By: Claude Opus 5.5 <[email protected]>
88 lines
5.7 KiB
Markdown
88 lines
5.7 KiB
Markdown
# @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.1 of the package. It carries the engine of `wai-quantum` 0.8.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 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:
|
|
|
|
```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 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.
|
|
- `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. 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.
|