wai-quantum: exact gradients, deterministic optimisers, VQE, QAOA and algorithm builders, each answer checked or bounded, on every surface #555

Merged

dcharlot merged 12 commits from wai/quantum-variational into main 2026-10-31 11:28:07 -04:00

Conversation 0 Commits 12 Files changed 52 +25053 -845

dcharlot commented 2026-10-31 09:54:00 -04:00

Owner

Copy link

A variational and algorithm library on every surface. Jobs bind their programs' parameters, gradients are exact, optimisers give the same bytes everywhere, and VQE and QAOA are held to exact answers. Phase estimation, amplitude estimation, an adder and QSVT are built as programs, each checked against a reference built from its definition, not from its gates. Every number that is a double says so and states an a priori bound on its rounding.

What it adds

Parameters (qasm, engine::catalog)

• A job's params gives each input float and input angle of its program a value, bound exactly before the program is read. A parameter left without one is refused (Q114, J050).
• A sweep may fix some parameters in params and sweep the others.
• qasm::tangents reads a program with every gate's derivative by each parameter, carried forward through arithmetic, the built-in functions, gate definitions, broadcast and loops. What it cannot follow (a modifier, a classical variable, a condition, an index, a loop range, a subroutine, a sized type) is refused on its line (Q129).

Gradients (engine::variational)

• A Hamiltonian's expectation over a program's parameters, and its gradient, by adjoint differentiation or by the parameter-shift rule: two terms where the gate's generator has two eigenvalues, four for crx, cry, crz and cu's θ.
• Every result states its method, arithmetic: f64, exact: false, and an a priori rounding bound for the value and for each component.
• Each method is held to gradients worked out by hand for every parameterised gate within that bound, to central finite differences, and to the other method.

Optimisers

• Gradient descent, Adam, and SPSA with a seeded generator.
• Every step is a link of a BLAKE3 digest chain from the request. The receipt seals the program, every step, the method and the seed.
• variational::verify checks the chain and runs the answer again to the same bytes. The answers' digests are pinned and the same on x86_64 Linux, arm64 macOS and wasm32.

VQE and QAOA

• The variational eigensolver, its built-in ansatz the one quantum_vml trains (a test holds its distribution and gradient to that module's), beside the exact ground energy by diagonalisation up to 8 qubits.
• QAOA for Max-Cut from a graph, beside brute force, its p = 1 expected cut the closed form on an edge and on a ring.

Algorithm builders (engine::algorithms)

• Phase estimation of p(2πφ) on t counting qubits; amplitude estimation by phase estimation of the Grover operator built from A; the ripple-carry adder in place; and quantum signal processing on a signal, or on a real symmetric matrix through its block encoding, the phases turned to the reflection's convention.
• Each answer carries the equivalence ladder's verdict against a reference built from the definitions. The ladder gains a rung against a reference matrix (equiv::against_matrix) and one against a truth table (equiv::against_permutation).
• The tests hold phase and amplitude estimation to the Fejér distribution, the adder to a truth table written apart and run as a job bit-exact, and QSVT to the Chebyshev polynomials of a signal and of a matrix by their recursion.
• The smoke found the adder with given addends checked against the bare adder's truth table. Its reference now flips the prepared qubits first, and a test holds it.

Surfaces

• CLI: gradient, optimize, vqe, qaoa and build. run, plan and submit take --param. verify checks an optimisation's chain and runs any of these answers again to the same bytes.
• Both MCP servers: gradient_qasm, optimize_qasm, vqe_ground_state, qaoa_maxcut and build_algorithm, in one wording, and a job's params on run_quantum_circuit.
• Service: POST /v1/gradient, /v1/optimize, /v1/vqe, /v1/qaoa and /v1/build, with OpenAPI entries.
• wasm: QuantumEngine.variational(op, args), its gradient the native build's pinned bytes in wasm32.
• Every answer follows the new schema wai.quantum.algorithms/1.
• Codes: J050 (parameters), J051 (gradient), J052 (optimisation, VQE, QAOA), J053 (builders), in a decade of their own. None was released before.
• Docs: docs/variational.md, every block run by the documentation check; the engine, CLI and service READMEs with their translations; the feature matrix (what a float or angle input now is); the regenerated agent docs; the changelog.
• CI: wai-quantum-variational.yml runs every test of the library by name on x86_64 and arm64 Linux, the byte pins among them, and builds each feature set without warnings. The contract requires the new schema test.

Bounds

• Gradients run on a double-precision state vector of at most 20 qubits, with no noise and measurements only at the end.
• Optimisers take at most 2000 steps. QAOA takes graphs of at most 20 vertices.
• References are built for every basis state up to 8 qubits (exact), random product states up to 10 (random, evidence), and the adder's truth table up to 16. A wider program's verdict is unchecked.
• On the service: 16 qubits, 500 steps and about 4×10⁹ gate amplitudes a call. Past them it answers J031 and names the command that runs it on your machine.

Checked

Where	Result
Linux build host	Engine engine:: qasm::: 370 passed. The library's tests with --features full: 32 passed. The new workflow's job, replayed step by step: every named test found, three feature sets clean under -D warnings. CLI: 70 passed (bin) and every other target, with and without BLESS. Service: 37 passed; mcp:: 14 passed. wai-web native quantum_engine::: 27 passed. CLI and service smoke passed. Breaking gate: no unacknowledged break. Repository checks: every line ok. check_schemas.py: 32 schema files, 46 and 26 tools, 43 live answers valid. check_docs.py on each touched page: every new block passed.
macOS build host	wai-web wasm32 under Node: 19 passed.
After rebasing onto the formats PR (Linux build host)	Service mcp::: 14 passed. CLI: 72 passed (bin) and every integration target. Service: 37 + 1. wai-web native: 29 passed. Engine --features full --lib: 1133 passed (engine::variational 11, algorithms 6, pulse 7, formats 24, refusal 4, schema 10). CLI and service smoke: every check held. Breaking gate: no unacknowledged break. Repository checks: all 10 lines ok. check_schemas.py: service-mcp.json's 29 tools valid, and 47 tool answers follow their schemas.
After rebasing onto the formats PR (macOS build host)	wai-web wasm32: 21 passed.
After rebasing onto main de3fce0d3	The tree is the one checked above plus main's changes since: the formats PR as merged (its one change, to wai-conformance.yml), the receipt ledger's tariff version 3 (#550) and the route record's version 2 (#552). Those are in wai-rs's receipt_ledger and route_record modules, wai-ledger, their specifications and corpora, and the conformance workflow. Every changed line is main's. No crate this PR changes compiles them (wai-web's features reach neither module), so nothing was run again by hand; this PR's CI runs every leg.

The rebase onto pulse and the other formats.

• Both branches grew engine::schema::FILES from 22 to 23, and the rebase took that one change once, which left the array declared 23 long with 24 entries. It is declared 24 (pulse.v1.json and algorithms.v1.json), and the changelog says the schemas grow from 23 to 24.
• Merging both branches' endpoint lists in GET /v1 took a key for an item. The list is rebuilt from both, in the service's order.
• Both servers add the pulse tools before the library's, so the tool-list tests name them in that order.
• The agent docs are blessed from all three together.

The views page. The library changes the engine inside the views page, so the page was rebuilt (54232be73) with wai/wai-quantum-views/build.sh in catthehacker/ubuntu:act-22.04 with Rust 1.98.0, as the views workflow rebuilds it.

Not done

• A Studio panel, a desktop view and Python bindings for the library.
• References for wider programs. The builders have no qubit cap of their own, but a program past the reference sizes above reports unchecked.

Breaking

api:rust:wai_quantum::engine::schema::FILES grew from 23 to 24 (algorithms.v1.json). The changelog acknowledges it.

🤖 Generated with Claude Code

A variational and algorithm library on every surface. Jobs bind their programs' parameters, gradients are exact, optimisers give the same bytes everywhere, and VQE and QAOA are held to exact answers. Phase estimation, amplitude estimation, an adder and QSVT are built as programs, each checked against a reference built from its definition, not from its gates. Every number that is a double says so and states an a priori bound on its rounding. ## What it adds **Parameters** (`qasm`, `engine::catalog`) - A job's `params` gives each `input float` and `input angle` of its program a value, bound exactly before the program is read. A parameter left without one is refused (`Q114`, `J050`). - A sweep may fix some parameters in `params` and sweep the others. - `qasm::tangents` reads a program with every gate's derivative by each parameter, carried forward through arithmetic, the built-in functions, gate definitions, broadcast and loops. What it cannot follow (a modifier, a classical variable, a condition, an index, a loop range, a subroutine, a sized type) is refused on its line (`Q129`). **Gradients** (`engine::variational`) - A Hamiltonian's expectation over a program's parameters, and its gradient, by adjoint differentiation or by the parameter-shift rule: two terms where the gate's generator has two eigenvalues, four for `crx`, `cry`, `crz` and `cu`'s θ. - Every result states its method, `arithmetic: f64`, `exact: false`, and an a priori rounding bound for the value and for each component. - Each method is held to gradients worked out by hand for every parameterised gate within that bound, to central finite differences, and to the other method. **Optimisers** - Gradient descent, Adam, and SPSA with a seeded generator. - Every step is a link of a BLAKE3 digest chain from the request. The receipt seals the program, every step, the method and the seed. - `variational::verify` checks the chain and runs the answer again to the same bytes. The answers' digests are pinned and the same on x86_64 Linux, arm64 macOS and wasm32. **VQE and QAOA** - The variational eigensolver, its built-in ansatz the one `quantum_vml` trains (a test holds its distribution and gradient to that module's), beside the exact ground energy by diagonalisation up to 8 qubits. - QAOA for Max-Cut from a graph, beside brute force, its p = 1 expected cut the closed form on an edge and on a ring. **Algorithm builders** (`engine::algorithms`) - Phase estimation of p(2πφ) on t counting qubits; amplitude estimation by phase estimation of the Grover operator built from A; the ripple-carry adder in place; and quantum signal processing on a signal, or on a real symmetric matrix through its block encoding, the phases turned to the reflection's convention. - Each answer carries the equivalence ladder's verdict against a reference built from the definitions. The ladder gains a rung against a reference matrix (`equiv::against_matrix`) and one against a truth table (`equiv::against_permutation`). - The tests hold phase and amplitude estimation to the Fejér distribution, the adder to a truth table written apart and run as a job bit-exact, and QSVT to the Chebyshev polynomials of a signal and of a matrix by their recursion. - The smoke found the adder with given addends checked against the bare adder's truth table. Its reference now flips the prepared qubits first, and a test holds it. **Surfaces** - CLI: `gradient`, `optimize`, `vqe`, `qaoa` and `build`. `run`, `plan` and `submit` take `--param`. `verify` checks an optimisation's chain and runs any of these answers again to the same bytes. - Both MCP servers: `gradient_qasm`, `optimize_qasm`, `vqe_ground_state`, `qaoa_maxcut` and `build_algorithm`, in one wording, and a job's `params` on `run_quantum_circuit`. - Service: `POST /v1/gradient`, `/v1/optimize`, `/v1/vqe`, `/v1/qaoa` and `/v1/build`, with OpenAPI entries. - wasm: `QuantumEngine.variational(op, args)`, its gradient the native build's pinned bytes in wasm32. - Every answer follows the new schema `wai.quantum.algorithms/1`. - Codes: `J050` (parameters), `J051` (gradient), `J052` (optimisation, VQE, QAOA), `J053` (builders), in a decade of their own. None was released before. - Docs: `docs/variational.md`, every block run by the documentation check; the engine, CLI and service READMEs with their translations; the feature matrix (what a float or angle input now is); the regenerated agent docs; the changelog. - CI: `wai-quantum-variational.yml` runs every test of the library by name on x86_64 and arm64 Linux, the byte pins among them, and builds each feature set without warnings. The contract requires the new schema test. ## Bounds - Gradients run on a double-precision state vector of at most 20 qubits, with no noise and measurements only at the end. - Optimisers take at most 2000 steps. QAOA takes graphs of at most 20 vertices. - References are built for every basis state up to 8 qubits (`exact`), random product states up to 10 (`random`, evidence), and the adder's truth table up to 16. A wider program's verdict is `unchecked`. - On the service: 16 qubits, 500 steps and about 4×10⁹ gate amplitudes a call. Past them it answers `J031` and names the command that runs it on your machine. ## Checked | Where | Result | |---|---| | Linux build host | Engine `engine:: qasm::`: 370 passed. The library's tests with `--features full`: 32 passed. The new workflow's job, replayed step by step: every named test found, three feature sets clean under `-D warnings`. CLI: 70 passed (bin) and every other target, with and without `BLESS`. Service: 37 passed; `mcp::` 14 passed. wai-web native `quantum_engine::`: 27 passed. CLI and service smoke passed. Breaking gate: no unacknowledged break. Repository checks: every line ok. `check_schemas.py`: 32 schema files, 46 and 26 tools, 43 live answers valid. `check_docs.py` on each touched page: every new block passed. | | macOS build host | wai-web wasm32 under Node: 19 passed. | | After rebasing onto the formats PR (Linux build host) | Service `mcp::`: 14 passed. CLI: 72 passed (bin) and every integration target. Service: 37 + 1. wai-web native: 29 passed. Engine `--features full --lib`: 1133 passed (`engine::variational` 11, `algorithms` 6, `pulse` 7, `formats` 24, `refusal` 4, `schema` 10). CLI and service smoke: every check held. Breaking gate: no unacknowledged break. Repository checks: all 10 lines ok. `check_schemas.py`: `service-mcp.json`'s 29 tools valid, and 47 tool answers follow their schemas. | | After rebasing onto the formats PR (macOS build host) | wai-web wasm32: 21 passed. | | After rebasing onto main `de3fce0d3` | The tree is the one checked above plus main's changes since: the formats PR as merged (its one change, to `wai-conformance.yml`), the receipt ledger's tariff version 3 (#550) and the route record's version 2 (#552). Those are in `wai-rs`'s `receipt_ledger` and `route_record` modules, `wai-ledger`, their specifications and corpora, and the conformance workflow. Every changed line is main's. No crate this PR changes compiles them (wai-web's features reach neither module), so nothing was run again by hand; this PR's CI runs every leg. | **The rebase onto pulse and the other formats.** - Both branches grew `engine::schema::FILES` from 22 to 23, and the rebase took that one change once, which left the array declared 23 long with 24 entries. It is declared 24 (`pulse.v1.json` and `algorithms.v1.json`), and the changelog says the schemas grow from 23 to 24. - Merging both branches' endpoint lists in `GET /v1` took a key for an item. The list is rebuilt from both, in the service's order. - Both servers add the pulse tools before the library's, so the tool-list tests name them in that order. - The agent docs are blessed from all three together. **The views page.** The library changes the engine inside the views page, so the page was rebuilt (`54232be73`) with `wai/wai-quantum-views/build.sh` in `catthehacker/ubuntu:act-22.04` with Rust 1.98.0, as the views workflow rebuilds it. ## Not done - A Studio panel, a desktop view and Python bindings for the library. - References for wider programs. The builders have no qubit cap of their own, but a program past the reference sizes above reports `unchecked`. ## Breaking `api:rust:wai_quantum::engine::schema::FILES` grew from 23 to 24 (`algorithms.v1.json`). The changelog acknowledges it. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

dcharlot added 12 commits 2026-10-31 09:54:00 -04:00

wai-quantum: a job binds its parameters, and the reader carries each gate's derivative by them ... d1c6860248

A job's "params" gives each of its program's parameters (input float,
input angle) its value, bound exactly before the program is read; a
parameter left without one is refused (Q114, J040), and a sweep may fix
some parameters in "params" while it sweeps the others. qasm::tangents
reads a program with every gate's derivative by each parameter, carried
forward through arithmetic, the built-in functions, gate definitions,
broadcast and loops; what it cannot follow is refused on its line (Q129).
The job codes for gradients, optimisation and the builders (J041 to J043)
join the table.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

wai-quantum engine::variational: exact gradients, deterministic optimisers, VQE and QAOA ... d40d404084

A Hamiltonian's expectation over a program's parameters, and its gradient
by each, exactly, by adjoint differentiation or the parameter-shift rule
(two terms for a generator with two eigenvalues, four for a controlled
rotation): each held to gradients worked out by hand within its stated
rounding bound, to central finite differences, and to each other. Every
result says it is f64, approximate, and states an a priori bound on its
rounding. Gradient descent, Adam and seeded SPSA, each step a link of a
digest chain from the request, the same bytes on x86_64 Linux and arm64
macOS (pinned). The variational eigensolver beside the exact ground energy
by diagonalisation; QAOA for Max-Cut beside brute force, its p = 1 expected
cut the closed form on an edge and a ring. The ansatz is the variational
ML module's, its distribution and gradient held to that module's.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

wai-quantum engine::algorithms: phase estimation, amplitude estimation, an adder and QSVT, each checked against a reference ... 79d42ac49e

Programs every surface runs: phase estimation of p(2πφ) on t counting
qubits, amplitude estimation by phase estimation of the Grover operator
built from A, the ripple-carry adder in place, and quantum signal
processing (a signal, or a real symmetric matrix through its block
encoding, the phases turned to the reflection's convention). Each answer
carries the equivalence ladder's verdict against a reference built from
the definitions, not the program's gates: the ladder gains a rung against
a reference matrix and one against a truth table. The tests hold phase and
amplitude estimation to the Fejér distribution, the adder to a truth table
written apart and run as a job bit-exact, and QSVT to the Chebyshev
polynomials of a signal and of a matrix by their recursion.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

wai-quantum: gradients, optimisation, VQE, QAOA and the algorithm builders on every surface ... fa68a97f92

The command line gains gradient, optimize, vqe, qaoa and build, and run,
plan and submit take --param; verify checks an optimisation's chain and
runs any of these answers again to the same bytes. Both MCP servers serve
gradient_qasm, optimize_qasm, vqe_ground_state, qaoa_maxcut and
build_algorithm in one wording, and a job's params on run_quantum_circuit.
The job service answers POST /v1/gradient, /v1/optimize, /v1/vqe,
/v1/qaoa and /v1/build within its own bounds (J031 past them, naming the
local command). The page engine gains variational(op, args), its gradient
the native build's pinned bytes in wasm32. Every answer follows the new
schema wai.quantum.algorithms/1; the agent docs are regenerated.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

wai-quantum: the library's CI leg, its smoke checks, and an adder's reference with its inputs prepared ... 84169c2b87

wai-quantum-variational.yml runs every test of the library by name on
x86_64 and arm64 Linux, the byte pins among them, and builds each feature
set the hosts build without warnings; the contract requires the new schema
test. Both smoke scripts check the new commands and endpoints, the
service's within the two submissions a client's window has left. The smoke
found the adder with its addends given checked against the bare adder's
truth table; its reference now flips the prepared qubits first, and a test
holds it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

wai-quantum: the variational and algorithm library documented, and its changelog entry ... 90b6f02bfa

docs/variational.md describes each call on every surface, every block of
it run by the documentation check: a job's parameters, the gradient
methods and what the rounding bound counts, the optimisers and the digest
chain, the variational eigensolver, QAOA, and the builders with their
references. The crate, command-line and service READMEs (and their
translations) gain the library, the feature matrix says what a float or
angle input now is, the agent docs are regenerated, and wai/CHANGELOG.md
acknowledges the one breaking change, engine::schema::FILES growing to 23.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

wai-quantum: the library's job codes in a decade of their own, J050 to J053 ... 0460ae3a39

The table groups its codes in tens by theme, and J040 and J041 go to
another branch's codes. PARAMS is now J050, GRADIENT J051, OPTIMIZE J052
and BUILD J053, in the table and its page, every message and test, the
service's OpenAPI and tool descriptions, the job schema, the reference
page, the feature matrix, the changelog entry and the regenerated agent
docs. No released code changes: these four were never released.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

wai-quantum: engine::schema::FILES holds 24 with pulse.v1.json and algorithms.v1.json both ... e4afb8fca1

The pulse branch and this one each grew FILES from 22 to 23, and the rebase took the same change
once, so the array was declared 23 long with 24 entries. It is declared 24, and this branch's
changelog line says the schemas grow from 23 to 24.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

wai-quantum-service: the endpoints list with every route, the rebase's merge of it rebuilt ... 13c278684c

Merging the pulse and variational branches' endpoint lists in GET /v1 took the key for an item,
which left the line unclosed. It is rebuilt from both lists, in the service's order.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

wai-quantum views: the page rebuilt with the engine the variational library changed, in the image CI rebuilds it in ... 86ad0c12ab

Rebuilt with wai/wai-quantum-views/build.sh in catthehacker/ubuntu:act-22.04 with Rust 1.98.0, as the
views workflow rebuilds it, so the engine inside the page is the one these sources build.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

wai-quantum-cli, wai-quantum-service: the tool lists in the order the servers give them, pulse's before the library's ... 13afcfe815

Both servers add the pulse tools before the variational library's, so the tests that hold the
tool list name them in that order.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

wai-quantum-cli docs: the agent docs blessed from pulse, other formats and the variational library together ... 77180f0036

Co-Authored-By: Claude Opus 5.5 <[email protected]>

dcharlot merged commit 886eec5845 into main 2026-10-31 11:28:07 -04:00

dcharlot referenced this pull request from a commit 2026-10-31 11:28:09 -04:00

Merge pull request 'wai-quantum: exact gradients, deterministic optimisers, VQE, QAOA and algorithm builders, each answer checked or bounded, on every surface' (#555) from wai/quantum-variational into main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

Transaction-Science/open-standards!555

No description provided.