fb230d8a62
engine::course reads the course from wai-quantum/course/: 21 lessons from a first circuit through superposition, entanglement, interference, the standard algorithms, noise and mitigation, error correction and fault tolerance to resource estimates, each a Markdown text in English and Simplified Chinese and an exercise.json with a schema. A check runs each case of an exercise (a generator's inputs) with its intent and the verdict, measures its constraints (the gates allowed, counts, the T count, the critique's smells, the resource estimate's counts), and says what went wrong from the diagnostics, the verdict and the critique, never from the solution. The tests hold every solution to pass by proof, every known wrong answer to fail for its stated reason, and every locale to every text and message. wai-quantum learn shows, starts, checks, hints and explains a lesson, keeps progress only on this machine, and speaks the language --lang or LANG names; the command summaries and docs topics have Chinese translations held to the English they came from. The verdict gains of_diagnostic for a generator's refusal. llms.txt names the course. Co-Authored-By: Claude Opus 5.5 <[email protected]>
230 lines
12 KiB
Rust
230 lines
12 KiB
Rust
//! The job service's engine: a program and what is asked of it, planned onto a
|
|
//! method, run, and answered as JSON. The service, the command line and the
|
|
//! desktop app plan and run a job the same way, so the same job gives the same
|
|
//! result on each.
|
|
//!
|
|
//! - [`catalog`]: a job read and checked ([`catalog::Request`]), the methods
|
|
//! and their limits, and [`catalog::plan`], which picks a method for a job
|
|
//! and says why, with the memory and work it will take.
|
|
//! - [`run`]: [`run::run`] carries a plan out and gives the result: counts,
|
|
//! expectation values, amplitudes, the accuracy class and what the method
|
|
//! did.
|
|
//! - [`dynamic`]: programs that measure in the middle, reset or branch on a
|
|
//! measured bit, run branch by branch.
|
|
//! - [`receipt`] (with `quantum_receipt`): a result sealed with a key over
|
|
//! the request and the result in their canonical JSON, and checked. The
|
|
//! service seals with its key and the command line with the user's, in one
|
|
//! form.
|
|
//! - [`job`] (with `quantum_receipt`): a job end to end, planned, run and
|
|
//! sealed, in the service's form; its check; and a program's lint.
|
|
//! - [`provider`] (with `quantum_receipt`): a job on the person's own
|
|
//! provider (a processor, an on-premises device or a simulator, reached by
|
|
//! a host that holds their credentials): what it may ask, its measured
|
|
//! counts set beside the circuit's exact distribution, and its seal. A
|
|
//! request that names a provider is refused by [`catalog::read`], so a host
|
|
//! that reaches none never runs one in its place.
|
|
//! - [`debug`]: the debugger. A program stepped forward and back one
|
|
//! operation at a time on a method where every number is exact for it (the
|
|
//! bit-exact or double-precision state vector, or the density matrix under
|
|
//! noise), stopped at a line, and looked into at any point (amplitudes,
|
|
//! probabilities, each qubit's Bloch vector and purity, the reduced state of
|
|
//! chosen qubits, entanglement across a cut); every branch at its
|
|
//! measurements in the middle with its exact weight, and a recorded path
|
|
//! replayed.
|
|
//! - [`targets`] (with `quantum_receipt`): device targets. A device's qubits,
|
|
//! couplings, native gates, durations and errors and its calibration
|
|
//! snapshot in one model, read from the snapshots devices publish; the
|
|
//! noise model they give, per qubit and per pair; the layout and routes
|
|
//! most likely to succeed; and a job that names a target, compiled, placed
|
|
//! and simulated as the device would run it, the target's hash in its
|
|
//! receipt.
|
|
//! - [`draw`]: a program's circuit as text.
|
|
//! - [`svg`]: the same circuit as a standalone SVG drawing, the Studio's
|
|
//! picture, each gate marked with whose hand it is in when that is given.
|
|
//! - [`latex`]: the same circuit as LaTeX, one picture in plain TikZ.
|
|
//! - [`describe`]: the same circuit in words, column by column, for a reader
|
|
//! who cannot see the drawing (a screen reader's description).
|
|
//! - [`visual`]: the circuit edited by its drawing (a gate put on a wire,
|
|
//! moved or deleted) as an edit to the program's own text.
|
|
//! - [`editor`]: the language service an editor needs (diagnostics,
|
|
//! completion, hover with each gate's matrix and cost, definitions,
|
|
//! references, renames, symbols, folding, lenses) and the formatter, pure
|
|
//! and with no protocol in it; `wai-quantum lsp` and `wai-quantum fmt` serve
|
|
//! it.
|
|
//! - [`converge`] (with `quantum_receipt`): whether a person's designs
|
|
//! converge on a model's proposals along a program's history, and how
|
|
//! diverse a cohort's designs are (the Vendi score, the centroid, the
|
|
//! score over time).
|
|
//! - [`critique`]: what the engine can say about a design before it runs (its
|
|
//! measures and its smells, each with its lines), and the variants its fixes
|
|
//! make, each checked equivalent before it is offered.
|
|
//! - [`equiv`]: whether two programs apply the same gates up to a global
|
|
//! phase, and how that was decided (a tableau, every basis state, or random
|
|
//! product states).
|
|
//! - [`compile`]: a program carried through named passes (lowering,
|
|
//! rewrites, phase folding, one- and two-qubit resynthesis, and the
|
|
//! approximation of every rotation in Clifford+T within an ε budget), each
|
|
//! checked where it acts, with one certificate per compile that states
|
|
//! every pass's check and the output's distance from the program.
|
|
//! - [`synth`]: the synthesis the passes use: exact Clifford+T normal forms,
|
|
//! rotations within ε, Euler angles, KAK, phase polynomials.
|
|
//! - [`estimate`]: what a fault-tolerant machine would need to run a
|
|
//! program: its logical counts (each rotation's `T` count its synthesised
|
|
//! word's), physical qubits, runtime and factories on a physical qubit
|
|
//! with the code model calibrated from the crate's own decoders, and the
|
|
//! frontier between qubits and time; every estimate sealed in the
|
|
//! resource-estimate receipt family, with the program's digest and its ε
|
|
//! budget. The logical-counts and routine documents go in and out.
|
|
//! - [`rewrite`]: rewrites that keep a circuit's meaning, each checked on
|
|
//! the qubits it touches: a gate and its inverse cancel, rotations merge,
|
|
//! Hadamards conjugate, a gate is carried past what it commutes with. A
|
|
//! chain of them explains an optimisation, offers a person one rewrite at a
|
|
//! time, and proves two programs equal at any width.
|
|
//! - [`shortcuts`]: every exact classical route the engine knows for a
|
|
//! circuit, each with its cost on it, and the cheapest for each question. A
|
|
//! cheap route proves a design classically easy; none being cheap proves
|
|
//! nothing.
|
|
//! - [`stats`]: sampled outcomes checked against a stated distribution by
|
|
//! Pearson's chi-squared test or the G-test at a stated significance, the
|
|
//! p-value the same bits everywhere (the test runner's statistical intents).
|
|
//! - [`guide`]: what an agent, or a person new to the engine, is told: the
|
|
//! language the reader takes, its diagnostics, the methods and their
|
|
//! accuracy classes, worked examples each with what it must do, and the
|
|
//! rules an agent keeps; both MCP servers serve them as resources and
|
|
//! prompts from here.
|
|
//! - [`verdict`]: how far the engine checked an answer, as one level of an
|
|
//! ordered ladder (refused, parsed, executed, checked as evidence, checked
|
|
//! as proof): what the reader said, the method and its accuracy class,
|
|
//! each intent checked (an exact distribution with its distance, the same
|
|
//! circuit as a reference, the same state), the critique's findings and
|
|
//! the repairs made, with the level in one plain line. A job that asks for
|
|
//! it carries it in its result, sealed by its receipt.
|
|
//! - [`answer`] (with `quantum_receipt`): the answer view layer, a few view
|
|
//! statements over OpenQASM 3 each bound to an engine call written with
|
|
//! `@` (`Histogram(@Sample(bell, 1000))`), read as it streams, every
|
|
//! problem a stable code, the calls carried out and sealed.
|
|
//! - [`telemetry`]: correctness telemetry, one record per answer a model
|
|
//! gives (its codes, its verdict's level, the repairs, the person's accept
|
|
//! or reject, its receipt), kept only where the person turns it on, and the
|
|
//! failures among them as an evaluation corpus in the conformance format.
|
|
//! - [`views`] (with `quantum_receipt`): the engine's answers as interactive
|
|
//! views inside an agent host (a circuit, a result with its verdict, a
|
|
//! receipt checked in the view, a critique, an estimate's frontier, a
|
|
//! device target's map), one self-contained page served as `ui://`
|
|
//! resources by both MCP servers, with each answer in plain words for a
|
|
//! host that draws none.
|
|
//! - [`repair`]: a program repaired from its diagnostics, on the lines they
|
|
//! flag alone: the mechanical fixes made, a proposal held to those lines,
|
|
//! and what needs a person, with the reader's advice.
|
|
//! - [`sets`] (with `quantum_receipt`): sets and sweeps. One request with a
|
|
//! list of programs, or one program over a grid of its inputs, run as one
|
|
//! set: a result per item, each with its own receipt, and one receipt over
|
|
//! the set's head, which holds the Merkle root of every item's leaf.
|
|
//! - [`course`]: the circuits course, kept as data in `course/` (Markdown
|
|
//! and a JSON exercise for each lesson, in every locale): first circuits
|
|
//! through superposition, entanglement, interference, the standard
|
|
//! algorithms, noise, mitigation, error correction and fault tolerance to
|
|
//! resource estimates. Each exercise is checked by its intent with the
|
|
//! verdict, and its constraints measured; what went wrong and the hints
|
|
//! come from the diagnostics, the verdict and the critique, never from the
|
|
//! solution.
|
|
//! - [`refusal`]: the job layer's refusal codes (`J…`), beside the reader's
|
|
//! (`Q…`): the request, the method, an intent, a repair and the host.
|
|
//! - [`energy`]: what the CPU cores spent for one process, as the kernel counts
|
|
//! it, and the figure a result carries: the service reads each exited
|
|
//! worker, the workbench its own process while it searches.
|
|
//! - [`discover`] (with `quantum_receipt`): the specification-and-evaluator
|
|
//! workbench. A person writes what a family of circuits must do and what it
|
|
//! costs, proposers write generators, the engine checks each at every size,
|
|
//! and an archive keeps the cheapest verified generator of every kind.
|
|
//! - [`locks`] (with `quantum_receipt`): the person's rules for what a
|
|
//! proposal may change (blocks held between `// @lock` and `// @unlock`,
|
|
//! the gates allowed, the qubit declarations, gates and text to avoid, the
|
|
//! region asked for), checked change by change.
|
|
//! - [`novelty`] (with `quantum_receipt`): what is new in a circuit. Its
|
|
//! structural distance to an inspiring set (the known constructions and the
|
|
//! caller's own circuits), each known construction the engine proves it to
|
|
//! be found again (and whether by a different route), and the strengths a
|
|
//! cost did not ask for.
|
|
//! - [`study`] (with `quantum_receipt`): measuring whether the co-design
|
|
//! works. A protocol sealed before any data, each participant's condition
|
|
//! fixed by their key, their record sealed with it, the report's eight
|
|
//! measures computed by the engine, and a cohort report with bootstrap
|
|
//! intervals.
|
|
//! - [`taste`] (with `quantum_receipt`): a person's taste in circuits,
|
|
//! learned from their own choices between programs the engine proves
|
|
//! equal, part by part of a rubric; typicality shown beside it and moved
|
|
//! only by a dial, and how well it predicts the person measured.
|
|
//! - [`versions`] (with `quantum_receipt`): a program's history, attributed.
|
|
//! Every version names its parents, who made it (the person, a model, an
|
|
//! outside agent, the engine) and how (an edit, a proposal reviewed change
|
|
//! by change, a merge), in a sealed chain. Each line and each gate is in the
|
|
//! hand that wrote it, and a job's receipt can bind the count.
|
|
//! - [`schema`]: the documents the engine writes, as versioned JSON Schemas
|
|
//! kept as data (`schemas/` beside this crate's manifest); the stamp that
|
|
//! names a result's engine and schema inside what its receipt seals; and
|
|
//! the versions a host reports.
|
|
//!
|
|
//! Requests and results are the service's JSON (`/v1/openapi.json` there),
|
|
//! and follow the schemas in [`schema`].
|
|
//! Keys, metering a job's energy, queueing and limits per client stay with
|
|
//! whatever hosts the engine.
|
|
|
|
#[cfg(feature = "quantum_receipt")]
|
|
pub mod answer;
|
|
pub mod catalog;
|
|
pub mod compile;
|
|
#[cfg(feature = "quantum_receipt")]
|
|
pub mod converge;
|
|
pub mod course;
|
|
pub mod critique;
|
|
pub mod debug;
|
|
pub mod describe;
|
|
pub mod draw;
|
|
pub mod dynamic;
|
|
pub mod editor;
|
|
#[cfg(feature = "quantum_receipt")]
|
|
pub mod discover;
|
|
pub mod energy;
|
|
pub mod equiv;
|
|
pub mod estimate;
|
|
pub mod guide;
|
|
pub mod latex;
|
|
#[cfg(feature = "quantum_noise")]
|
|
pub mod mitigate;
|
|
#[cfg(feature = "quantum_qec")]
|
|
pub mod qec;
|
|
#[cfg(feature = "quantum_receipt")]
|
|
pub mod job;
|
|
#[cfg(feature = "quantum_receipt")]
|
|
pub mod locks;
|
|
#[cfg(feature = "quantum_receipt")]
|
|
pub mod novelty;
|
|
#[cfg(feature = "quantum_receipt")]
|
|
pub mod provider;
|
|
#[cfg(feature = "quantum_receipt")]
|
|
pub mod receipt;
|
|
pub mod refusal;
|
|
pub mod repair;
|
|
#[cfg(feature = "quantum_receipt")]
|
|
pub mod sets;
|
|
pub mod rewrite;
|
|
pub mod run;
|
|
pub mod schema;
|
|
pub mod shortcuts;
|
|
pub mod synth;
|
|
pub mod stats;
|
|
#[cfg(feature = "quantum_receipt")]
|
|
pub mod study;
|
|
pub mod svg;
|
|
#[cfg(feature = "quantum_receipt")]
|
|
pub mod targets;
|
|
#[cfg(feature = "quantum_receipt")]
|
|
pub mod taste;
|
|
pub mod telemetry;
|
|
pub mod verdict;
|
|
#[cfg(feature = "quantum_receipt")]
|
|
pub mod versions;
|
|
#[cfg(feature = "quantum_receipt")]
|
|
pub mod views;
|
|
pub mod visual;
|