wai-quantum 0.4.3: metered runs, placement by a run's energy, and a fabric that falls back #226

Merged

dcharlot merged 4 commits from wai-quantum-fabric-energy into main 2026-10-12 19:59:15 -04:00

Conversation 0 Commits 4 Files changed 13 +1479 -49

dcharlot commented 2026-10-12 15:46:02 -04:00

Owner

Copy link

Why

The fabric now has several members that give the same bits: the CPU reference, and the WebGPU member's per-gate and tile implementations. What it lacked was a way to choose between them by what a run costs, and a way to run a circuit that survives one member refusing it. This adds both without estimating anything. An energy figure is a labelled measurement or it is absent.

What

Run meters (quantum_fabric::RunMeter, member-neutral, no new dependency)

• start just before a run's first submission, stop after its last readback.
• No implementation ships in the crate; a meter belongs with the energy source it reads.
• A reading reaches a result only when the label check accepts it. Otherwise the run is unmetered.
• Every start is matched by one stop. A refused run's reading is discarded.

The WebGPU member, metered

• simulate_metered and member_metered, with blocking wrappers.
• The window runs from the first submission to the last readback. The member's detail states what it holds.

Placement figures only from metered calibrations

• EnergyCalibration turns metered runs into a KernelEntry::energy figure: nanojoules per pair-update, rounded up, with the runs' class and the uncertainty the rounding adds.
• An unmetered run, a refused label, a second class, or an uncertainty that no longer fits its field leaves no figure.
• detect_local_metered gives the CPU reference its figures.

Placement for a run

• place_for picks the least predicted energy when every candidate has a prediction, so a small circuit stays on the CPU and a wide one goes to the GPU.
• place is unchanged.
• place_for and Fabric read figures on only some candidates as figures on none. A calibration that earns a figure on one member alone cannot place that member first whatever it costs.

The Fabric wrapper

• It runs a circuit on the placed member and falls back down the placement order on TooWide, OutOfRange, Memory, Timeout or Device. It stops at once on an invalid circuit or a defect.
• The receipt is sealed with the member and implementation that produced the state. The refusals are listed beside it; the receipt's signed bytes are unchanged.
• A Runner states the member it is. A member paired with a runner of another id is refused before anything runs, so a receipt cannot name a member that did not do the work.
• ready(future) drives Fabric::run natively without an executor.

Review

An independent review found no wrong figure, pairing or fallback in the arithmetic. It found four things the code did not hold, all fixed here:

• the runner/member pairing was unchecked;
• the "figures on both or neither" rule was documented, not enforced;
• one assertion held for any implementation, and two paths had no test;
• one detail phrase overstated the window.

Each fix has a mutant: with the fix undone, a named test fails.

Checked

On a second machine (a different Metal GPU from the one the earlier stages ran on):

• the release suite and the wasm32-wasip2 run pass;
• the device tests on Metal pass. Both implementations reproduce the pinned digests, every shader mutant is caught, and the metered and fabric cases cover the tile implementation too;
• the conformance corpus passes through the GPU;
• the browser member passes: bit-exact, four of four, for both implementations;
• the shader checker, the SPIR-V validator, the minimum-Rust-version check and the package dry-run pass.

wai-quantum 0.4.3 is additive: default features, full, both implementations and every existing pin and digest are unchanged.

🤖 Generated with Claude Code

## Why The fabric now has several members that give the same bits: the CPU reference, and the WebGPU member's per-gate and tile implementations. What it lacked was a way to choose between them by what a run costs, and a way to run a circuit that survives one member refusing it. This adds both without estimating anything. An energy figure is a labelled measurement or it is absent. ## What **Run meters** (`quantum_fabric::RunMeter`, member-neutral, no new dependency) - `start` just before a run's first submission, `stop` after its last readback. - No implementation ships in the crate; a meter belongs with the energy source it reads. - A reading reaches a result only when the label check accepts it. Otherwise the run is unmetered. - Every start is matched by one stop. A refused run's reading is discarded. **The WebGPU member, metered** - `simulate_metered` and `member_metered`, with `blocking` wrappers. - The window runs from the first submission to the last readback. The member's `detail` states what it holds. **Placement figures only from metered calibrations** - `EnergyCalibration` turns metered runs into a `KernelEntry::energy` figure: nanojoules per pair-update, rounded up, with the runs' class and the uncertainty the rounding adds. - An unmetered run, a refused label, a second class, or an uncertainty that no longer fits its field leaves no figure. - `detect_local_metered` gives the CPU reference its figures. **Placement for a run** - `place_for` picks the least predicted energy when every candidate has a prediction, so a small circuit stays on the CPU and a wide one goes to the GPU. - `place` is unchanged. - `place_for` and `Fabric` read figures on only some candidates as figures on none. A calibration that earns a figure on one member alone cannot place that member first whatever it costs. **The `Fabric` wrapper** - It runs a circuit on the placed member and falls back down the placement order on `TooWide`, `OutOfRange`, `Memory`, `Timeout` or `Device`. It stops at once on an invalid circuit or a defect. - The receipt is sealed with the member and implementation that produced the state. The refusals are listed beside it; the receipt's signed bytes are unchanged. - A `Runner` states the member it is. A member paired with a runner of another id is refused before anything runs, so a receipt cannot name a member that did not do the work. - `ready(future)` drives `Fabric::run` natively without an executor. ## Review An independent review found no wrong figure, pairing or fallback in the arithmetic. It found four things the code did not hold, all fixed here: - the runner/member pairing was unchecked; - the "figures on both or neither" rule was documented, not enforced; - one assertion held for any implementation, and two paths had no test; - one `detail` phrase overstated the window. Each fix has a mutant: with the fix undone, a named test fails. ## Checked On a second machine (a different Metal GPU from the one the earlier stages ran on): - the release suite and the `wasm32-wasip2` run pass; - the device tests on Metal pass. Both implementations reproduce the pinned digests, every shader mutant is caught, and the metered and fabric cases cover the tile implementation too; - the conformance corpus passes through the GPU; - the browser member passes: bit-exact, four of four, for both implementations; - the shader checker, the SPIR-V validator, the minimum-Rust-version check and the package dry-run pass. wai-quantum 0.4.3 is additive: default features, `full`, both implementations and every existing pin and digest are unchanged. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

dcharlot added 4 commits 2026-10-12 15:46:02 -04:00

wai-quantum fabric: run meters, metered calibration, place_for, and the Fabric wrapper ... 852cd42e80

Stage 6 of the WebGPU member plan (energy, and placement that can choose the GPU).

- quantum_fabric: the member-neutral RunMeter trait (no meter ships in the crate);
  a reading reaches a result only when check_label accepts it, every start is
  matched by one stop, and a refused run's reading is discarded. EnergyCalibration
  turns metered runs into a KernelEntry figure (nJ per pair-update, rounded up,
  the runs' class with the rounding folded into its uncertainty), or no figure at
  all; detect_local_metered gives the CPU reference its figure. place_for places
  one run by a caller's picojoule model when every candidate has a prediction,
  else as place. Fabric runs a circuit on the placed member, falls back down the
  placement order on TooWide, OutOfRange, Memory, Timeout or Device, and seals the
  receipt with the member that produced the result, the refusals beside it.
- quantum_fabric_webgpu: simulate_metered brackets a run from its first submission
  to its last readback (device work only; detail says so), member_metered
  certifies and calibrates in one pass, the member is a Runner for its own
  implementation, and WebGpuError maps onto MemberError.
- Tests: CPU-side tests with synthetic meters, figures, models and refusing
  members; device test g13 (metered runs, a metered calibration, and the fabric
  falling back from a member held to three qubits); the member script expects 14
  tests and a fabric line per declared adapter.

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

wai-quantum 0.4.3: metered runs, placement by run, and the fabric wrapper ... b3dae20921

Additive release of Stage 6. The CHANGELOG gains a 0.4.3 section above 0.4.2; the
version changes in Cargo.toml and in the version line of the six lockfiles that
resolve wai-quantum. The quantum-wasip2 job requires each new fabric test by name.
The place_for test now also drops the CPU's prediction, so a missing prediction
read as zero would place the CPU where place places the GPU, and fail.

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

Merge remote-tracking branch 'origin/main' into wai-quantum-fabric-energy 136b16f0f2

wai-quantum fabric: the review of the energy stage, fixed ... 1665baee8f

An independent review found no wrong figure, pairing or fallback in the
arithmetic; it found four things the code did not hold.

- A receipt's member was whatever Member the caller paired with a runner:
  nothing compared them, so a member paired with another adapter's runner gave a
  signed, verifying receipt for work it did not do. A Runner now states the
  member it is (member_id), and Fabric::run refuses a pairing whose ids differ
  as a defect, before anything runs.
- "Figures on both members or on neither" was documented, not held: a
  calibration that earns no figure on one member (its readings under the
  resolution floor, say) left the other placed first whatever it cost. place is
  unchanged; place_for and Fabric now read figures on only some candidates as
  figures on none.
- Tests: the assertion that only placeable candidates are predicted held for
  any implementation, and is now a closure that panics on an unplaceable one
  over a list that holds two; a runner that hands back a refused label, or a
  label with no figure, is sealed as unmetered; the device test runs the tile
  implementation metered and on the fabric.
- The member's detail said a window "covers device work only"; it also holds
  the host's waits and copies between submissions, and says so.

Also: a calibration whose uncertainty no longer fits its field once the rounding
is added earns no figure rather than a capped one; ready() drives Fabric::run
natively without an executor; &R is a Runner and &mut M a RunMeter.

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

dcharlot merged commit 7a732c097e into main 2026-10-12 19:59:15 -04:00

dcharlot referenced this pull request from a commit 2026-10-12 19:59:17 -04:00

Merge pull request 'wai-quantum 0.4.3: metered runs, placement by a run's energy, and a fabric that falls back' (#226) from wai-quantum-fabric-energy 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!226

No description provided.