open-standards/wai/wai-quantum/src/engine/mod.rs

//! 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.
//! - [`formats`]: programs in other formats, QIR (under its base and
//!   adaptive profiles) and jeff, read to the one program and written from
//!   it, every construct a reader cannot hold refused with its code and its
//!   place, and each conversion checked by the equivalence ladder.
//! - [`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.
//! - [`pulse`]: pulse runs. A pulse program (OpenPulse calibrations on
//!   physical qubits, `crate::qasm::pulse`) integrated by the pulse
//!   simulator (`crate::quantum_pulse`) as a job of the method `pulse`, its
//!   device from a target and the options, its result bounded and the same
//!   bits everywhere, its receipt binding the control program, its
//!   calibrations, the device and target snapshot, and the integrator and
//!   its step; its schedule as a view; and a pulse job checked by running
//!   it again.
//! - [`registry`]: the extension points. Each simulation method, compiler
//!   pass, noise channel and program format is a component behind a trait
//!   ([`registry::Method`], [`registry::Pass`], [`registry::Channel`],
//!   [`registry::FrontEnd`]), held in one registry the planner, the run, the
//!   compile and the conversions go through; every built-in registers through
//!   the same trait, and a host registers its own
//!   ([`registry::Registry::register`]), its identity sealed in every result
//!   it takes part in and marked as registered, never as built in.
//! - [`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.

pub mod algorithms;
#[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 formats;
pub mod fabric;
pub mod fabric_measured;
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 pulse;
pub mod refusal;
pub mod registry;
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 variational;
#[cfg(feature = "quantum_receipt")]
pub mod versions;
#[cfg(feature = "quantum_receipt")]
pub mod views;
pub mod visual;