open-standards/wai/wai-quantum/README.zh-CN.md

<!-- 机器辅助翻译（machine-assisted translation）：在对外推广之前，须由熟练的读者审校。 -->

# wai-quantum

> 本文为机器辅助翻译，尚待熟练的读者审校。英文原文：[README.md](README.md)。

一个**以纯 Rust 实现的确定性量子栈**：字节级一致的线路模拟、围绕它的操作层，以及把每个阶段绑定在一起的、带能耗核算的签名回执。

不需要 QPU，不需要云服务，不需要厂商 SDK，也**不依赖任何系统库**——因此同一份源代码可以原生运行，可以通过 wasm 在浏览器中运行，也可以作为 WASI 组件在边缘运行，并且**在这三种环境中得到字节级一致的结果和回执**。有九个需显式启用的特性会触及 crate 之外：`quantum_fabric_webgpu`（平台的 GPU 接口）、`quantum_fabric_cuda`（CUDA 驱动与运行时编译器）和 `quantum_fabric_opencl`（OpenCL ICD 加载器），后两者在首次使用时加载；`quantum_fabric_fpga`（Verilator，首次使用时作为程序运行）、`quantum_fabric_npu`（平台的模型运行时，macOS 上）、`quantum_fabric_sme`（处理器的流式向量模式，通过内联汇编）、`quantum_fabric_vector`（处理器的向量扩展）、`quantum_fabric_dsp`（信号处理器的向量单元，在为该处理器构建时）以及 `quantum_fabric_dataflow`（数据流设备的库，首次使用时加载）；任何默认特性都不触及系统库。

```toml
[dependencies]
wai-quantum = "0.10"
```

```rust runnable
use wai_quantum::quantum::Circuit;
use wai_quantum::quantum_toolchain as qt;

let mut c = Circuit::new(3);
c.h(0).cx(0, 1).cx(1, 2);              // GHZ
let sv = c.simulate().unwrap();
println!("{:?}", qt::top_outcomes(&sv, 2));   // |000> 0.5, |111> 0.5
// a portable identity for the reconstruction — same on every machine
let h: [u8; 32] = sv.statevector_hash();
```

## 包含哪些内容

**跨架构可复现性是经过测试的，而不是仅凭声称。** CI 在 wasmtime 上的 `wasm32-wasip2` 下以及原生环境中，运行固定到精确 IEEE-754 位模式的浮点结果（熵、Holevo 界）以及线路核心的单元测试；因此，一个计算结果不同的平台会让测试套件失败，而不是悄悄返回另一个数字（`.github/workflows/wai-conformance.yml` 中的 `quantum-wasip2` 作业）：

```sh norun=ci:wai-conformance.yml
CARGO_TARGET_WASM32_WASIP2_RUNNER='wasmtime run -W nan-canonicalization=y -W relaxed-simd-deterministic=y' cargo test --locked --target wasm32-wasip2 --features full --test bit_identity
```


命令行的研究工具回答的是一个态*携带*了什么，而不只是一条线路做了什么：

```sh runnable
wai-quantum lab entropy bell --keep 0    # 半个 Bell 对：1 比特，态矢量看不出来
wai-quantum lab channel depolarizing --prob 0.5
wai-quantum lab bb84 --eavesdrop         # 截获会在错误率中显现出来
wai-quantum lab chsh                     # 精确为 2 sqrt(2)，并非采样所得
wai-quantum lab qutrit                   # d = 3，不只是量子比特
```

`channel` 会打印信道作用前后的 Holevo 界，而它只会下降：噪声从不创造信息。

| 特性 | 提供的功能 |
|---|---|
| `quantum` | 字节级一致的态矢量模拟（二进（dyadic）Clifford+T+P(k)），默认为 `wai.quantum.circuit2`，也可使用已冻结的 `wai.quantum.circuit` |
| `quantum_toolchain` | 算法库、后端推荐、**通过唯一的读取器导入 OpenQASM 2/3**（`from_qasm`）：读取器接受的一切内容，只要符合逐位精确线路的限制——二进角度、测量位于末尾——都可导入，否则以读取器的代码拒绝（非二进角度会被拒绝，绝不舍入）；由修饰符写出的受控门保持为一个整体，因此 `to_qasm` 的输出能逐门读回；**可直接用于设备的 OpenQASM 2/3**（`device::device_qasm`）：每个门都被精确降级（lower）到其方言的标准库，包括多控制门，每个量子比特都测量到 `c[i]` 中，服务返回的计数再读回到本 crate 的基上；**原生程序**（`native::compile`）：处理器自己的基（`rz`/`sx`/`x`/`cz`；`prx`/`cz`；或角度以圈为单位、精确写出的 `gpi`/`gpi2`/`zz`；Z 旋转承载在后两者的相位中），作用于处理器自身的量子比特，在其耦合图上路由，并在发送之前通过模拟与原线路核对——Bloch / 纠缠 / 纯度分析 |
| `quantum_lang` | **OpenQASM 读取器，所有入口共用一套语法**（`qasm::read`、`qasm::parse`）：作业服务、命令行、两个 MCP 服务器、Studio、桌面应用、边缘组件和浏览器内 IDE 都通过它读取。支持 OpenQASM 3.1 以及常用的 OpenQASM 2 写法，分三个阶段读取，并保留每个元素的源代码位置：寄存器、别名与切片；门定义；任意门上的每一种修饰符（`ctrl @`、`negctrl @`、`inv @`、`pow(k) @`、精确的分数次幂），均精确降级；`def` 子程序，内联展开，返回的测量结果写入调用方的比特；经典类型（`int`、`uint`、`float`、`angle[n]`、`complex`、`bool`、`bit`、数组）及其算术、类型转换和内置函数，在读取时求值，在所有平台上得到相同的位；`for`、`while`（次数已知时展开，否则基于测量比特最多运行 `@wai.max_iterations N` 次）、`switch`、`break`、`continue`、`end`；基于测量比特、带比较运算以及 `&&`、`||` 和 `!` 的条件，编译为向前分支的步骤；`output` 带入结果；`delay`、`box`、`stretch` 和 `barrier` 作为时序信息保留，并在某种方法忽略时长时加以标注；`defcal` 和 `cal` 原样保留，从不执行。生成器：整数 `input`，使一个程序可以描述一族线路（`qasm::read_with`、`qasm::instantiate`）。**每一条拒绝和警告都带有稳定的代码**（`line 3: unknown gate foo [Q103]`，也以数据形式给出，附带行、列和长度）：[代码表](docs/qasm-diagnostics.md)（`qasm::diag::codes()`、`wai-quantum diagnostics`），以及[读取器如何处理 OpenQASM 3.1 的每种构造](docs/qasm-feature-matrix.md)。[一致性语料库](../quantum-conformance/qasm3/)收录了规范中的示例以及针对每种构造的程序，分别在原生环境、wasm32-wasip2 下和浏览器中运行 |
| `quantum_qasm` | 把读取器得到的程序降级为各方法的输入，在相差一个全局相位的意义下精确：稠密矩阵、供矩阵乘积态使用的两量子比特矩阵、Pauli 旋转、Clifford 门，以及二进线路（`Program::dyadic`）；对于所有测量都位于末尾的程序，`qasm::dyadic_circuit` 给出精确态矢量所用的线路，其他程序则以相应代码拒绝 |
| `quantum_engine` | **量子作业服务的引擎，适用于所有宿主**：一个作业（一个 OpenQASM 程序以及对它的要求：采样次数（shots）、Pauli 期望值、振幅、噪声）被规划到它所允许的最强方法上，并给出理由以及将占用的内存和工作量；然后运行；以服务的 JSON 返回结果并附上精度等级；再以请求和结果的规范 JSON 加以封存（`engine::job`、`engine::receipt`），因此无论结果来自服务、命令行还是浏览器标签页，都以同样的方式校验。此外还有：以文本绘制程序的线路（`engine::draw`），以及绘制为独立的 SVG 图——即 Studio 中的那幅图，每个门都标明出自谁之手（`engine::svg`，Python 包在 notebook 中用它绘图：`wai/wai-quantum-py`）；规范与评估器工作台（`engine::discover`：一份规范，引擎对某个生成器在每个规模上的判定，以及一个存档，记录由两项度量划分出的每个格子中已验证的最廉价生成器，并加以封存）；带署名的程序历史（`engine::versions`：版本构成一条封存的链，每个版本记录由谁、以何种方式产生，提案逐项变更地审阅，每一行、每个门都归于写下它的人，作业的回执可以绑定这些信息）；使用者为提案设定的规则（`engine::locks`：锁定的代码块、允许的门、量子比特声明、需要避免的内容以及一个区域，逐项变更地检查）；程序中有什么新东西（`engine::novelty`：它与已知构造及给定程序之间的结构距离，它被证明等同于哪些已知构造、是否经由不同的路径，以及代价函数并未要求的长处；只违反某条规则的工作台候选被视为偏离（aberration），并附上它本应具有的代价）；研究（`engine::study`：在获得任何数据之前就封存的研究方案，每位参与者的实验条件由其密钥固定，其记录也用该密钥封存，各项度量由引擎根据参与者的产出计算，以及带有固定种子的 bootstrap 区间和 Cronbach's alpha 的群组报告）；趋同（`engine::converge`：沿着程序的历史，使用者的版本在多大程度上建立在模型的提案之上、模型在门中所占的份额，并把使用者独立完成的版本与其余版本并列；以及一个群组的多样性、其 Vendi 分数、质心和随时间的收窄）；保持线路含义的重写（`engine::rewrite`：消去、合并、Hadamard 共轭，以及把门移过与之对易的门，每一步都在它触及的量子比特上加以检查，因此一连串重写可以在任意宽度上证明两个程序相等、解释一次优化，并且每次向使用者提供一个重写）；使用者的偏好（`engine::taste`：针对使用者在引擎证明等价的程序之间所作的选择，按评分细则逐项建立的 Bradley–Terry 模型，典型性显示在旁边且只能通过一个调节旋钮改变，并测量它对使用者选择的预测效果）；告诉智能体的内容（`engine::guide`：读取器接受的语言、它的诊断信息——每一项都由测试保证与读取器一致——各种方法及其精度等级、每个都附有意图的示例，以及智能体须遵守的规则，两个 MCP 服务器都将其作为资源和提示词提供）；编辑器所需的语言服务（`engine::editor`：读取器的拒绝和评审（critique）发现的代码异味作为诊断显示在相应的行上，根据光标所在位置可接受的内容进行补全，悬停提示中每个标准门的矩阵精确写出并与引擎自身的矩阵核对、用户定义门的矩阵由其组成门计算得出，以及引擎所计的每个门的代价，定义、引用、重命名、大纲、折叠，以及只有一种排版、保留每个词法单元的格式化器，全部是纯逻辑，不含任何协议）；带证书的编译（`engine::compile`：经过检查的各遍处理（pass），由 `engine::synth` 在 ε 预算内把每个旋转写成 Clifford+T，每遍处理及距离都记录在一份封存的记录中；参见 [docs/compiler.md](docs/compiler.md)）；基于程序的资源估算（`engine::estimate`：逻辑计数，其中每个旋转按综合后的 `T` 门数计；物理估算，其码模型拟合自本 crate 自己的解码器；前沿（frontier）；每个估算都加以封存；参见 [docs/estimate.md](docs/estimate.md)）；调试器（`engine::debug`：在逐位精确或双精度的态矢量上，或在有噪声的密度矩阵上（与其无噪声的态并列），逐个操作地向前和向后单步执行程序，在某一行之前停下，并在任意位置探查其振幅和相位、每个量子比特的 Bloch 矢量和纯度、所选量子比特的约化密度矩阵以及跨某个切分的纠缠；在中途测量处给出每个分支及其权重，对于无噪声的 Clifford 程序则由稳定子表给出精确分数；重放已录制的路径；同一个态看两次，位完全相同，而精确方法在最后一个门之后的态就是精确运行所得的态，以其哈希值为证；超过 16 个量子比特（有噪声时超过 8 个）则拒绝）；以纯 TikZ 写成 LaTeX 的线路（`engine::latex`），以及供屏幕阅读器使用的文字描述（`engine::describe`）；通过线路图编辑线路：在一根线上放置、移动或删除一个门，都会经由语法树转化为对程序文本本身的编辑（`engine::visual`）；针对给定分布、对采样结果进行的 Pearson 卡方检验和 G 检验，p 值在任何地方都是相同的位（`engine::stats`）；以及操作系统内核为单个进程统计的 CPU 能耗（`engine::energy`）。它可以为 `wasm32-unknown-unknown` 构建，在该目标上单线程运行，且不声称任何耗时；以及其他格式的程序（`engine::formats`）：按入口点所声明的基础（base）或自适应（adaptive）配置文件读取 QIR（1.x 和 2.x；配置文件禁止的内容按行拒绝，任意角度的旋转按其精确的双精度值读取），并写出为 QIR 2.0；通过本 crate 自带的 Cap'n Proto 读写器读写 jeff。读取器无法精确表示的每种构造都以代码（`Q700` 到 `Q721`）及其位置拒绝，每次转换都由等价判定阶梯检查（[格式说明](docs/formats.md)、[一致性测试集](../quantum-conformance/formats/)） |
| `quantum_stabilizer` | 稳定子（CHP）表——`O(n²)`，可扩展的规模远超态矢量 |
| `quantum_mps` | 张量网络（矩阵乘积态）后端 |
| `quantum_pauli` | 在二进门集上进行稀疏 Pauli / Heisenberg 绘景的可观测量传播（最多 64 个量子比特） |
| `quantum_spd` | **实用规模（utility scale）的稀疏 Pauli 动力学**：在最多 1024 个量子比特上进行任意角度的 Pauli 旋转，精确的 Clifford 旋转和四分之一圈旋转，截断可能使结果偏移多少的严格上界，以及 127 量子比特 heavy-hex 踢动 Ising（kicked-Ising）线路——它在全部 127 个量子比特上复现了精确计算得到的 5 步磁化强度 |
| `quantum_spd_receipt` | 针对一次稀疏 Pauli 动力学运行的、带能耗核算的签名回执，可在任何机器上逐位重新校验 |
| `quantum_bptn` | **硬件图上的张量网络态**：采用置信传播（belief propagation）环境和重新规范（re-gauging）的简单更新（simple-update）演化，设备的耦合逐层并行施加（与逐个施加的结果逐位一致）；使用 `Tns::with_blocked_linalg` 时，更新、消息与重新规范都由 `quantum_svd` 的稠密例程完成，适用于数百的键维，在任意工作线程数下、在 arm64 与 x86_64 上结果逐位相同。置信传播遗漏的部分可以逐个区域补回：`Tns::expect_region_bp` 在边界上用消息闭合、精确收缩任意区域（其中的环在估计工作量最小处切开），`loop_cluster_terms` 与 `cluster_combine` 把这些区域组合成围绕置信传播的环簇展开（J. Gray、G. Park、G. Evenbly、N. Pancotti、E. F. Kjønstad 与 G. K.-L. Chan 2025），并给出每个环自身的修正（`loop_weight`）。在树上是精确的；在 127 量子比特晶格上，键维数为 32 时，它与精确计算的 5 步磁化强度相差在 4e-7 以内——这是对稀疏 Pauli 动力学的独立检验，二者的误差并不相同。它还带来 `quantum_svd`：边长达数千的稠密复矩阵的 SVD、瘦 QR 与矩阵乘积，多线程，在任意线程数下、在 arm64 与 x86_64 上结果逐位相同（见下文） |
| `quantum_peaked` | **按构造时植入的结构读取峰值线路**：把线路整理为若干层双量子比特块；从每个候选中心向两侧各生长几层线路算子，算子保持最小之处即某个块与其近似逆相接的位置（`scan`）；从该位置向外把整条线路生长为算子，张量网络建在门所连接的图上：某个门第一次连接两个量子比特时建立一条键，键维降回 1 时删去，可选的反交换（unswapping）把隐藏的置换变为重新标号（`cancel`、`cancel_unswapping`）；在 `\|0…0⟩` 上用精确收缩读出峰值，并给出任意比特串在整条线路中的振幅 `⟨s\|C\|0…0⟩`（`Operator::peak`、`Operator::amplitude`）。对全连接线路另有 `chain`：在线路块数的一半处切开，把线路作为链上的矩阵乘积算子生长，每一侧在吸收时布线到链上，规模超过阈值时用反交换剥去隐藏置换，并用沿链的精确条件解码读出峰值（`grow_chain`、`ChainOperator::peak`、`::sample`、`::amplitude`） |
| `quantum_resource` | **容错资源估算**：从程序的逻辑计数（量子比特、T 门、Toffoli 门和旋转门、测量）出发，得到码距、通过穷举搜索找到的 T 态工厂、物理量子比特数和运行时间，覆盖六种参考量子比特和三种码，并给出量子比特数与时间之间的前沿。按已发表算例所印的精度复现了这些算例 |
| `quantum_resource_receipt` | 针对一次估算的、带能耗核算的签名回执，可在任何机器上逐位重新校验 |
| `quantum_qio` | **量子启发式优化**：Ising 与 Max-Cut 问题（G-set 读取器、自旋玻璃生成器），弹道式、离散式和加热式的模拟分岔（每遍批量运行八次试验，与逐次运行的结果逐位一致），模拟退火，单翻转下降，最多 34 个自旋的精确 Gray 码参照，以及求解所需步数（step-to-solution）。在七个 G-set 实例上达到已知最优割 |
| `quantum_landscape` | **能量景观作业**：epuML 程序对三态变量（自旋 1，带单离子代价）给出能量，在沉降模型的经典模拟器上运行：整数运算的确定性核，以及在两个切点之间做一次抽样的采样核，两者在每个平台上比特一致；最多 16 个变量时检查每一种排列，并按问题自身的检查为每个最低能量状态评分；焦耳按注明来源的费率定价，这里从不测量；同一实例上以相同预算运行模拟退火、禁忌搜索和贪心下降，并发布结果表；以及 GPU 或 FPGA 板运行所经由的接缝（`extensions/quantum-landscape.md`）。它的第二版（`extensions/quantum-landscape-2.md`，请求中的 `"protocol": "wai.quantum.landscape/2"`）让每个变量有自己的代价，可正可负，并能写出独热、至多一个和基数约束（`exactly`、`atmost`），因此着色问题和 2×2 以上的指派问题可以运行；温度为 0 的运行按本项目 FPGA 成员实测的沉降费率定价，采样运行则不定价，并说明原因；只有 CPU 参考实现运行它。`quantum_engine` 和 `full` 都会启用它 |
| `quantum_landscape_webgpu`、`quantum_landscape_cuda`、`quantum_landscape_metal` | **GPU 上的能量景观作业**：沉降核与采样核分别通过 WebGPU（32 位通道，另有至多只能达到统计一致的着色核）、CUDA 与 Metal（64 位场）运行，每个成员都由主机在其声明的容量内于一致性集合上认证，且不会被分到超出该容量的工作负载；作业会跳过未经认证的核或运行失败的成员（`job::call_placed`） |
| `quantum_uf` | **近线性时间的并查集（union-find）解码**，基于同一个匹配图：在整数权重上由事件驱动的簇生长（用基数堆为填充事件排序）、合并以及剥离（peeling）。在相同的采样上与精确匹配对比：失败次数为其 0.92–1.18 倍，在 `d = 11` 时最多快 77 倍 |
| `quantum_dmrg` | **用 DMRG 求自旋链的基态**：最近邻链的矩阵乘积算符（外场中的 XXZ Heisenberg 链、横场 Ising 链），带 Lanczos 和密度矩阵截断的双格点扫描，纠缠熵，一个对称矩阵本征求解器，以及两个精确参照：最多 22 个格点的完全对角化，以及任意长度 Ising 链的自由费米子解。在 200 个格点上，临界 Ising 链的复现精度约为每格点 `10⁻¹¹` |
| `quantum_tdvp` | **用 TDVP 计算自旋链的时间演化**：前后往返的双格点扫描，遇到无法收敛的步长就将其减半的 Lanczos 指数运算，用奇异值分解拆分键，并用零空间向量补全每个基，使乘积态的小键不会阻碍演化。测量格点和键上的可观测量、每个键上的纠缠、能量以及 Loschmidt 回波。以两个精确参照为准：最多 20 个格点的全振幅 Krylov 演化，以及任意长度 Ising 淬火的自由费米子解。在键维数 64、100 个格点的临界淬火中，直到纠缠填满键之前，它与精确解的偏差都保持在 `10⁻⁹` 以内；超过之后，其误差随它所报告的舍弃权重变化 |
| `quantum_chem` | **用 DMRG 计算分子**：FCIDUMP 积分，自旋轨道上的二次量子化哈密顿量编译为精确的 MPO（最小顶点覆盖，无数值压缩），从 Hartree–Fock 出发、使用完备基的 DMRG，以及作为参照的完全组态相互作用（full CI）。LiH 和 H₂O 与 full CI 一致到 `10⁻¹³` |
| `quantum_nqs` | **神经网络量子态**：任意图上的自旋模型（Heisenberg、阻挫 J₁–J₂、横场 Ising），受限玻尔兹曼机，可用实参数（在二分晶格上配合 Marshall 符号规则），也可用复参数来学习无人提供的符号结构，可投影到某个动量与自旋翻转扇区，通过 Metropolis 链或精确枚举进行变分蒙特卡罗，以及在参数空间与样本空间中较小的那个里求解的随机重构（stochastic reconfiguration）。以精确对角化以及同一算符和上的 DMRG 为参照 |
| `quantum_noisy` | **含噪声线路**：态矢量上的量子轨迹（去极化、退相位、振幅阻尼、读出），最多 12 个量子比特、复用相同内核的精确密度矩阵参照，线性交叉熵保真度（采样所得的、精确的以及线路自身的），以及数字误差模型。测量该模型在哪里有偏差：它低于真实保真度，差距随错误率而不是随深度增长 |
| `quantum_ldpc` | **线路级的 qLDPC 存储**：由两个多项式构造的双变量自行车（bivariate-bicycle）码（由秩求 `k`，逻辑基），带线路级噪声的深度 8 校验子周期，它的探测器误差模型，以及 BP-OSD 解码（带自适应缩放的最小和、带组合扫描的有序统计）。该误差模型与原作自带的解码矩阵具有相同的列，并且在相同的校验子上，解码器逐次采样地作出与原作相同的决策 |
| `quantum_arch` | **架构级估算**：轭合（yoked）表面码存储（在码块（patch）上进行行与网格奇偶校验，分热存储与冷存储），从已发表的模拟曲线读取的魔术态培育（cultivation），CCZ 工厂，以及由格点手术（lattice surgery）、魔术态供应和控制回路三者中最慢者决定的时钟。可组装整机估算；其存储搜索与原作的占用面积（footprint）工具逐个布局吻合 |
| `quantum_receipt` | 针对一次重构的、带能耗核算的签名回执 |
| `quantum_ops` | 操作/证明（operations/attestation）层 |
| `quantum_cal`, `quantum_control`, `quantum_noise` | 校准、滤波函数鲁棒控制、DD 噪声谱学、Cycle-Benchmarking 噪声学习 |
| `quantum_pulse` | **脉冲程序**：把 OpenPulse 校准读入为帧上的时序（`qasm::pulse`：端口、帧、波形模板与显式采样、播放、延迟、相位与频率的改变、采集、屏障），并在 Lindblad 主方程下积分（由 T1 和 T2 给出弛豫与退相，二能级或三能级，静态耦合），所用的定步长级数在每个平台上结果比特一致，误差有界并予以说明；在作业中即方法 `pulse`（`engine::pulse`），其回执绑定控制程序、其校准、设备与目标快照以及积分器（[docs/pulse.md](docs/pulse.md)） |
| `quantum_mitigate` | 零噪声外推、读出 M3、经典影子 |
| `quantum_qec` | CSS 码（码距通过穷举搜索验证，而非仅凭声称）——**旋转表面码** `[[d²,1,d]]`、环面码、双变量自行车码，以及 **`[[7,1,3]]` 色码**，其自对偶性带来一个*横向*（transversal）逻辑 Hadamard——一轮完成，无需辅助比特，无需手术——已在模拟器上验证，并展示了表面码在同样操作下的失败——配有**两个解码器**：并查集（加权匹配、单次（single-shot）、带错误测量的时空解码，**以及带钩子错误（hook error）的线路级解码**；可**导入和导出** Stim 语法的探测器误差模型，因此其他工具的噪声模型可以在这里解码，我们的也可以在那里解码）以及 Relay-BP（用于 qLDPC） |
| `quantum_frame` | **QEC 规模的含噪声 Clifford 线路**：读取生态系统通用的线路文本；通过按位打包的 Pauli 帧模拟（每个字 64 次采样）对探测事件采样；通过反向灵敏度推导探测器误差模型，拒绝非确定性的探测器；按参考布局逐字节生成旋转表面码存储实验；并通过**精确的最小权完美匹配**（基于整数权重的 Edmonds 开花算法）解码。测量逻辑错误率，并拟合资源估算所假定的码模型 |
| `quantum_tn` | **张量网络缩并**：线路（任意量子比特上的任意幺正）转化为网络；带种子的超优化器从随机贪心和多层划分两类方法中找到缩并树，在子树中对其进行最优重构，并按内存上限对其切片，再围绕切片进行第二轮搜索；各切片以固定顺序、多线程缩并，在任何地方都得到相同的位。支持单个振幅或开放输出的批量计算 |
| `quantum_cutrank` | **在乘积基下测量的 Clifford 线路，精确计算**：稳定子态的图形式（`Tableau::graph_form`）加上最后一层任意角度的单量子比特门，沿某个顺序逐个量子比特求和，使用一个含 `2^{cut-rank}` 个条目的表。精确的振幅、概率和样本（借助 Parseval 定理），代价由该顺序各切分上的纠缠决定，而不是由量子比特数决定；通过退火寻找工作量更小的顺序；表可用双精度或单精度；在任意线程数下得到相同的位 |
| `quantum_gbs` | **精确的高斯玻色采样**：hafnian（幂迹、Hessenberg + 特征多项式，`O(n³ 2^{n/2})`）、torontonian、由压缩光、热光或压扁光经任意有损传输矩阵或时域环路程序产生的有损高斯态、精确的点击概率与光子数概率、逐模式抽取的精确样本、将观测样本与精确的单模和双模点击统计进行比对的检验，以及任意规模下精确的总光子数分布与光子数累积量；还有有损态的经典采样器（`quantum_gbs_mps`）：把态拆成一个纯态部分与经典噪声，纯态部分按模式顺序表示为矩阵乘积态，每个样本各抽一次位移，在每台机器上得到相同的比特 |
| `quantum_sv` | **任意角度的稠密态矢量**：带对角快速路径的单量子比特、双量子比特和 `k` 量子比特内核，围绕多量子比特门的门融合，在相互独立的块上多线程运行；每条内核路径都以相同的顺序计算每个振幅，因此多线程从不改变任何一位。与一个独立模拟器的结果一致到 2·10⁻¹⁶ |
| `quantum_compile` | Clifford 路由 + 稳定子表等价性证明 |
| `quantum_atom` | 中性原子寄存器制备（匈牙利算法 / LSAP） |
| `quantum_qir` | **QIR 导出 + 导入**——生成并解析 QIR（QIR Alliance 基于 LLVM 的 IR）；生成的模块用 `llvm-as` 验证，目录中 10 个算法里有 9 个重新导入后得到逐位一致的态矢量 |
| `quantum_comm` | **密钥分发与安全**：带截获-重发窃听者的 BB84（安静的信道给出完美的密钥；截获会使其损失四分之一），以及对不可克隆定理的代价核算 |
| `quantum_qudit` | **2、3、4 和 6 能级的 qudit**：Weyl–Heisenberg 群（移位与时钟）、`Z_d` 上的 Fourier 门、受控加法门以及单位根相位，采用电路模拟器的定点数：每台机器上整数相同，每个常数要么精确，要么是 `2^-30` 上的最近值（`√3/2` 以及 `1/√3` 等 Fourier 条目），其他维度一律拒绝，每个门的误差都有界并加以说明。`d = 2` 时与 circuit2 逐振幅一致；`F_4` 即两量子比特 Fourier 变换。在作业中为 `engine::qudit`（需 `quantum_engine`）：以种子测量的 qudit 门程序，计数连同状态与结果的界一并封存，`wai-quantum qudit run`（[quantum-sim §9](../extensions/quantum-sim.md)，[一致性集合](../quantum-conformance/qudit/)） |
| `quantum_info` | **混合态**：密度矩阵、偏迹、纯度、精确的 Pauli 期望值，以及与经典界和 Tsirelson 界对照的 CHSH |
| `quantum_source` | **编码与传输的极限**：von Neumann 熵、Schumacher 极限和 Holevo 界——后者表明 `n` 个量子比特最多携带 `n` 个经典比特，因此量子无法压缩经典媒体 |
| `quantum_channel` | **传输本身**：Kraus 信道（比特翻转、退相位、去极化、振幅阻尼），以及用于查看实际到达内容的线性反演层析——遵循信道只会*丢失*信息、从不创造信息的定律 |
| `quantum_qbom` | 量子物料清单（Quantum Bill of Materials）——把各阶段的回执汇总为一份清单 |
| `quantum_vml`, `quantum_phasor`, `quantum_qfhrr`, `quantum_kernel`, `quantum_qdata`, `quantum_phasor_meter` | 干涉 / 相量机器学习层 |
| `quantum_fabric` | **计算结构**：成员（CPU 和各类加速器，其中包括量子处理器），每个内核实现都在使用它的进程中对照 CPU 参考实现进行认证（逐位精确、在给定容差内，或在给定采样次数上按经典保真度进行统计认证），证书注明认证是在何处获得的（硅片、仿真器或模拟器）；按一致性（parity）、来源（provenance）和计量能耗进行放置；签名回执写明结果背后的成员与实现。两个内核：apply（线路的态）和 sample（其测量计数），后者配有 CPU 参考采样器、为量子处理器设计的语料库，以及一个虚拟量子处理器，其给定的噪声模型使处理器路径上的每一步都可以在没有真实处理器的情况下运行和测试；其证书注明是在模拟器中获得的。`quantum_fabric::stablehlo` 把门写成可移植的张量程序（StableHLO），每个值都是永不溢出的 64 位整数，供任何张量编译器为其自己的设备构建；`stablehlo_gate` 示例把它连同一批输入以及构建结果必须给出的精确输出一起写出，`ci/tensor-program/check.sh` 运行一次构建并以这些输出对其检验 |
| `quantum_fabric_webgpu` | **计算结构的 WebGPU 成员**，需显式启用，不包含在 `full` 中：以 WGSL 编写的 32 位通道门内核，每个门一次调度（dispatch），原生环境下经由 Metal、Vulkan 或 DX12，在 `wasm32-unknown-unknown` 上经由浏览器的 WebGPU；第二种实现按分块（tile）逐块施加一串门，每串一次调度，并单独认证。每个适配器都在使用它的进程中对照 CPU 的算术进行探测，并通过复现 CPU 参考实现固定的语料库摘要被认证为逐位精确；超出 32 位的结果会被拒绝，绝不返回。属于触及 crate 之外的特性之一 |
| `quantum_fabric_cuda` | **计算结构的 CUDA 成员**，需显式启用，不包含在 `full` 中，仅限原生目标：以 CUDA C 编写、使用精确 64 位整数的门内核，在运行时为每个设备自身的架构编译，每个门一次启动（launch）。CUDA 驱动和运行时编译器在首次使用时加载，因此启用该特性的构建可以在没有 CUDA 的宿主上运行，此时找不到成员，并说明原因。每个设备都在使用它的进程中对照 CPU 的算术进行探测，并通过复现 CPU 参考实现固定的语料库摘要被认证为逐位精确；超出 32 位的结果会被拒绝，绝不返回。在计算能力 8.0 或更高的设备上，**第二个内核在张量核心上计算每个乘积**（`CudaMember::tensor`）：每个值表示为 bf16 中的四个 8 位分段（limb），在 f32 中累加，f32 能精确容纳每个部分和；以自己的实现 id 进行探测和认证，并有自己的变异体（mutant）。同时启用 `quantum_sv` 时，**稠密 f64 态矢量**在设备上的运行与在 CPU 上逐位相同：即 CPU 自己的那些启动（对角、单量子比特和分组公式），每一次都是不含融合乘加的 IEEE binary64 运算，并对照固定的语料库摘要进行认证。同时启用 `quantum_spd` 时，**稀疏 Pauli 动力学的项之和驻留在设备上**（`CudaMember::spd`、`quantum_spd::device`），对照 CPU 的传播进行认证，结果和最终的表都相同 |
| `quantum_fabric_metal` | **计算结构的 Metal 成员**，需显式启用，不包含在 `full` 中，macOS：以 Metal 着色语言编写、使用精确 64 位整数的门内核，在运行时由操作系统自带的编译器编译，在一个命令缓冲区中每个门一次串行调度，态存放在 GPU 与宿主共享的内存中。在其他平台上，构建找不到成员并说明原因。每个设备都在使用它的进程中对照 CPU 的算术进行探测，并通过复现 CPU 参考实现固定的语料库摘要被认证为逐位精确，以其 GPU 家族编号为键（`gpu-msl-<family>`）。在支持 SIMD 组矩阵的 GPU 上，**第二个内核用矩阵乘法计算每个乘积**（`MetalMember::matrix`）：每个值表示为 bf16 中的四个 8 位分段，在 f32 中累加，f32 能精确容纳每个部分和；以自己的实现 id 进行探测和认证，并有自己的变异体。在操作系统 26 或更高版本上，**第三个内核用着色语言的张量运算计算每个乘积**（`MetalMember::tensor_ops`），平台会在 GPU 具备矩阵硬件时将其映射到该硬件上：bf16 中的偏移二进制 8 位分段，在 f32 中累加，经由每个线程组的暂存区 |
| `quantum_fabric_hip` | **计算结构的 HIP 成员**，需显式启用，不包含在 `full` 中，Linux：CUDA 成员的内核源文本，原封不动，在运行时由 HIP 的运行时编译器为每个设备自身的架构编译，每个门一次启动。运行时及其编译器在首次使用时加载，因此启用该特性的构建可以在没有它们的宿主上运行，此时找不到成员，并说明原因；设备属性按运行时冻结的布局读取，否则拒绝该设备。与 CUDA 成员一样进行探测和认证，使用自己的实现 id；同时启用 `quantum_sv` 时，稠密 f64 态矢量的运行与在 CPU 上逐位相同。在 gfx11 GPU 上，**第二个内核用 bf16 矩阵指令计算每个乘积**（`HipMember::wmma`）：每个值采用偏移二进制，表示为四个无符号 8 位分段，因为一旦和中出现负项，该指令的累加就不再精确；偏移量在 64 位整数中去除。以自己的实现 id 进行探测和认证，并有自己的变异体 |
| `quantum_fabric_opencl` | **计算结构的 OpenCL 成员**，需显式启用，不包含在 `full` 中，仅限原生目标：同样精确的 64 位内核，以 OpenCL C 编写，在运行时由每个设备自己的编译器构建，每个门一次启动，可运行在任何 OpenCL GPU 或 CPU 上（OpenCL 加速器会被拒绝：没有任何计算结构类别对应它）。ICD 加载器在首次使用时打开，因此启用该特性的构建可以在没有 OpenCL 的宿主上运行，此时找不到成员，并说明原因。每个设备都像 CUDA 成员的设备那样进行探测和认证，并以其厂商 id 为键（`opencl-<kind>-<vendor id>`）。同时启用 `quantum_sv` 时，在每个支持 binary64 的设备上（关闭浮点收缩（contraction）），稠密 f64 态矢量的运行与在 CPU 上逐位相同；不支持 binary64 的设备会拒绝，并说明这一点 |
| `quantum_fabric_fpga` | **计算结构的 FPGA 成员（模拟）**，需显式启用，不包含在 `full` 中，仅限原生目标：以 Verilog 编写的门数据通路（每个 32×32 乘积由四个 16 位部分积构成，这正是 FPGA 乘法器块的大小；一块态 RAM；每两个周期一个数对），在运行时由 Verilator 编译为周期精确的模拟，通过管道驱动。像其他成员一样进行探测和认证，且每个证书都注明是在模拟器中获得的，因此放置时它排在硅片之后。没有 Verilator 的宿主找不到该成员，并说明原因 |
| `quantum_fabric_npu` | **计算结构的神经处理器成员**，需显式启用，不包含在 `full` 中，仅限 macOS：每个 32 位操作数拆分为八个 4 位分段，每个分段乘积和分段之和都在平台的神经处理器上以 fp16 计算（无论以何种顺序相加，每个值都是 fp16 能精确表示的整数），由宿主组装每个乘积并执行定点算术。只有当平台模型运行时的计算计划把模型的每个操作都放在神经处理器上时，该成员才存在；若模型会被放到别处运行，则拒绝，并附上运行时报告的放置情况。像所有成员一样进行探测和认证 |
| `quantum_fabric_npu_cores` | **计算结构的 npu-cores 成员**，需显式启用，不包含在 `full` 中，Linux：门的定点算术运行在神经处理器分块阵列（tile array）的一个计算核心上，直接编程，而不经过模型运行时：在核心上计算精确的 64 位乘积，由宿主收集每个门的数对并检查每一行的范围。运行时，该成员通过驱动找到设备，用分块阵列的开放工具链构建核心程序（`WAI_QUANTUM_NPU_CORES_PYTHON` 指定其 Python；程序按变体、代际和工具链缓存），并针对设备运行时编译其宿主端。三个内核变异体各自是独立的程序，且都必须被捕获。像其他成员一样进行探测和认证；其证书的来源为硅片 |
| `quantum_fabric_tensor_engine` | **计算结构的张量引擎成员**，需显式启用，不包含在 `full` 中：在张量处理器的矩阵引擎上，把门的乘积作为精确的分段卷积来计算，每个数对分块做一次 bf16 矩阵乘法、在 fp32 中累加（每个值四个 8 位分段，bf16 能精确表示；每个部分和都是小于 `2^24` 的整数，无论以何种顺序相加 fp32 都能精确表示），由宿主组装乘积并执行定点算术。内核作为辅助程序在该引擎的内核工具链下运行（`WAI_QUANTUM_TENSOR_ENGINE_PYTHON`）；当其目标是该工具链的模拟器时，每个证书都会注明。必须捕获四个变异体，其中包括引擎无法容纳的九位分段 |
| `quantum_fabric_sme` | **计算结构的矩阵扩展成员**，需显式启用，不包含在 `full` 中，仅限 aarch64：门的定点算术运行在处理器的流式向量模式（SME）下，64 位通道，由宿主收集每个门的数对并检查每一行的范围。它使用的每条指令都只存在于该模式中，因此内核只要运行了，就一定是在该模式下运行的。通过处理器的特性标志检测（在 Linux 上为内核的 `AT_HWCAP2`，用户态仿真器也会提供它）；在仿真器下运行时，运行器会注明这一点（`WAI_QUANTUM_SME_EMULATOR`），并且每个证书都会带上该信息。编译进了三个内核变异体，且都必须被捕获 |
| `quantum_fabric_dsp` | **计算结构的 DSP 向量单元成员**，需显式启用，不包含在 `full` 中，用于为信号处理器构建、且其向量单元处于 128 字节模式的情形：门的定点算术运行在 32 位通道中，每个 64 位值是一对字，每个乘积都是向量单元的精确 32×32 乘法，并保留每一次进位和借位；由宿主收集每个门的数对并检查每一行的范围。它的指令只存在于该单元上，因此内核只要运行了，就一定是在那里运行的。在仿真器下运行时，运行器会注明这一点（`WAI_QUANTUM_DSP_EMULATOR`），并且每个证书都会带上该信息。编译进了三个内核变异体，且都必须被捕获。其类别为 `dsp` |
| `quantum_fabric_vector` | **计算结构的 CPU 向量单元成员**，需显式启用，不包含在 `full` 中：门的定点算术运行在处理器自身的向量扩展中，每种指令集一个内核，处理器具备的每种指令集对应一个成员——`avx2`（x86-64，256 位）、`avx512`（x86-64，512 位，使用该单元自身的 64 位算术移位）、`sve`（aarch64，可伸缩向量扩展，任意长度）和 `rvv`（riscv64，向量扩展 1.0，任意长度）——每个操作数符号扩展到 64 位通道，由宿主收集每个门的数对并检查每一行的范围。可伸缩内核在每一遍中设置自己的长度；成员从单元读取长度，并在其 id 和详细信息中写明。通过处理器的特性标志检测（在 Linux 上，向量扩展用 `AT_HWCAP`，用户态仿真器也会提供它）；在仿真器下运行时，运行器会注明这一点（`WAI_QUANTUM_VECTOR_EMULATOR`）。其 id 在 CPU 参考实现的 id 基础上扩展而来，因此在没有能耗数据时，放置仍保留参考实现。每种指令集编译进三个内核变异体，且都必须被捕获 |
| `quantum_fabric_dataflow` | **计算结构的数据流成员**，需显式启用，不包含在 `full` 中，Linux：门的定点算术运行在数据流加速器 32 个计算分块中每个分块的第一个 RISC-V 核心上，每个核心处理一个门的数对中连续的一段。程序在本 crate 中构建（`quantum_fabric::rv32`，一个 RV32IM 编码器，其汇编清单可由一个独立的汇编器逐字复现）：每个 64 位值是一对字，乘积用 `mul`/`mulh`，进位和借位用 `sltu`。设备的库（`WAI_QUANTUM_DATAFLOW_LIB`，在运行时加载）把设备呈现为一个 PCI 端点；宿主在每个分块上打开两个内存窗口，使其核心保持复位状态，在复位地址处写入程序，并在旁边写入该分块的参数和切片，然后释放这些第一个核心，并驱动设备时钟，直到每个分块都报告完成。设备以其 PCI id 命名（`dataflow-1e52-<device>`）；该库是一个模拟器，每个证书都会注明（`WAI_QUANTUM_DATAFLOW_SIMULATOR`）。编译进了三个内核变异体。在其向量引擎做 23 位数乘法的那一代设备上，第二个成员（`-vector`）在该引擎上运行门，每次 32 个通道：第一个核心配置分块的解包器和打包器，并以内联方式把指令交给分块（`quantum_fabric::tensix`，从模拟器自己的表转录并与之核对；`quantum_fabric::vector_engine`），每个 32×32 乘积由四个 23 位部分积构成 |
| `full` | 全部特性 |

默认特性为 `quantum`、`quantum_toolchain`、`quantum_receipt`。

## 速度

字节级一致是契约，因此模拟器只采用不会改变任何一个振幅的优化方式：恒等门什么都不做；对角门用一次乘法而不是四次，为一半的态加上相位；`X`——因而 `CX` 也是——只是一次交换，完全没有算术运算。在这种定点表示中 `fxmul(ONE, x) == x` 精确成立，正是这一点使这些路径可以被证明完全相同，而不仅仅是接近；并且它们会逐个振幅地与先前的实现进行核对。

全实数矩阵——`H` 以及任何实旋转——同样能把乘法次数减半，因为虚部交叉项都是乘以精确的零。

在 20 个量子比特时，这意味着：`Z` 上 8.9 倍，`X` 上 7.1 倍，`CZ` 上 4.6 倍，`CX` 上 4.3 倍，`T` 上 3.4 倍，`Y` 上 1.9 倍，`H` 上 1.8 倍。

## 实用规模

`quantum_spd` 演化的是可观测量而不是态，因此一条线路的代价取决于其非 Clifford 旋转，而不是 `2ⁿ`：

```sh runnable cargo=. timeout=1800
cargo run --release --example utility --features quantum_spd -- 0.2 20 1e-4
```

它在不到一秒内算出 127 量子比特 heavy-hex 踢动 Ising 线路经过 20 个 Trotter 步之后的 ⟨Z₆₂⟩，并给出截断可能使其偏移多远的上界。`--example utility_mz` 针对每个角度，把 5 步磁化强度与精确计算值进行核对，`tests/utility_reference.rs` 保存了已发表的参考值。`quantum_bptn` 以张量网络计算同样的线路（`--example utility_bptn`），因此结果可以用第二种方法核对，而这种方法并不共享第一种方法的近似。

**稠密 SVD**（`quantum_svd`，随 `quantum_bptn` 提供）。张量网络要分解边长为键维平方的矩阵；标量单边 Jacobi 旋转在几百阶时就要数秒。`quantum_svd::svd` 用 Householder 反射把复矩阵化为实双对角矩阵（高度至少为宽度两倍的矩阵先化为三角矩阵），每一步的两次更新共用对剩余矩阵的两遍扫描；在双对角矩阵上运行 Demmel 与 Kahan 的隐式位移 QR 迭代并记录其平面旋转；按每 8 列一块施加这些旋转，每块由一个工作线程完成；再把反射以每 32 个一组的 `I − V·T·V†` 形式作用回所保留的奇异向量。截断时（上限与相对最大奇异值的截断阈值）只构造保留的向量；`Keep::Values` 只给出奇异值。每个数都由一个工作线程按矩阵形状所固定的顺序算出，对行的求和按 64 行一块进行、按块的顺序相加，不使用融合乘加，也不调用库函数，因此在任意线程数下、在 arm64 与 x86_64 上结果逐位相同。`examples/svd_bench.rs` 将其与 Jacobi 旋转对比计时，并对输出取散列（`cargo run --release --example svd_bench --features quantum_engine,quantum_receipt,quantum_bptn`）。在一台与其他工作共用的 32 核 x86_64 主机上单线程运行时，64² 耗时 1.5 毫秒，256² 为 59 毫秒，512² 为 0.40 秒，1024² 为 3.2 秒，2048² 为 28 秒（Jacobi 旋转在 64²、256² 与 512² 时分别为 22 毫秒、0.79 秒和 5.8 秒），4096 × 1024 的矩阵为 13 秒；在这些繁忙的主机上，增加线程至多带来两倍的速度（2048²：16 个线程时 13.5 秒）。十二个矩阵的散列在 1、4、16 个线程下以及在 macOS arm64 上都相同（`tests/data/svd/`、`tests/svd_bench.rs`），残差 `‖A − U·S·V†‖/‖A‖` 为 4·10⁻¹⁵ 到 2·10⁻¹⁴，`U`、`V` 的正交归一误差不超过 3·10⁻¹⁴。

**已发表的实例。** 一个公开的量子优势候选追踪项目发布了线路和哈密顿量，以及设备为其测得的值和与之并列提交的经典值。`examples/tracker_*.rs` 复现其中的实例：每个实例从固定提交的追踪项目检出中读取输入，核对其 SHA-256，并为每次运行写出一份签名回执，附带墙钟时间和平台给出的能耗数据（`examples/tracker/`，`tests/data/tracker/README.md`）：

```sh norun=data
cargo run --release --example tracker_ole --features quantum_engine,quantum_receipt,quantum_spd_receipt,quantum_bptn,quantum_mpsim -- TRACKER 49x1296 bptn 32 64
```

（`TRACKER` 是该检出；`tracker_guided` 也可以从此处保存的固定数据运行：`-- tests/data/tracker random:1 8 16`。）

- `tracker_guided`：在哈密顿量的精确 MPO 上用 DMRG 求 49 量子比特引导稀疏问题的基态。从键维 8 的伪随机起点出发，它得到 −85.586625069865，与已发表的基态能量相差不超过 6·10⁻¹³，键维 16 到 64 的结果相同（基态只需键维 4）。从引导基态出发，它停在一个乘积态 −85.556625069865，即某个选择组态相互作用（selected-CI）提交所报告的值。
- `tracker_su2`：用稀疏泡利动力学计算 120 量子比特 SU(2) 格点规范线路经过 20 个 Trotter 步之后的守恒荷，两种初态下均为 60，上界为 7.4·10⁻¹⁵。
- `tracker_ole`：算子 Loschmidt 回波，可以用稀疏泡利动力学（`quantum_spd::echo`）计算，可以作为耦合图上的张量网络计算（回波经过纯化，其可观测量所在的环精确收缩，`Tns::expect_loop_bp`），也可以作为从扰动中心沿链生长的线路算子计算，并对阈值或键维进行扫描。`fast` 用稠密分块线性代数（`Tns::with_blocked_linalg`）运行纯化网络。在 49 量子比特、648 个双量子比特门的线路上，χ = 64、96、128、160、192、256、320 时其值依次为 0.8735、0.8473、0.8347、0.8280、0.8243、0.8208、0.8195，截断累计丢弃的权重从 0.088 降到 0.0015；值随丢弃权重呈直线变化（最后三个点偏离直线不超过 10⁻⁶），外推到丢弃权重为零时为 0.8185（若按 1/χ² 外推则为 0.8172）；已发表的张量网络值为 0.8203 和 0.8217（键维 192 和 512）。这是该收缩方式在 χ 上的收敛；每条边在扰动之前承载六个双量子比特门，因此从 χ = 64 起网络精确地保存前半段，只在其后截断。图中其余五个环仍由置信传播闭合，而精确闭合可观测量自身所在的环会使值改变 +0.049：同样的网络沿环上的弧读出，在 χ = 320 时为 0.771，用键权重作环境时为 0.769。χ = 320 在一台共享的 16 核 arm64 主机上用 10 个工作线程耗时 274 秒、12.4 GB；χ = 64 到 192 的每个值在 Linux x86_64 上的比特完全相同。`loops` 用围绕置信传播的环簇展开读取同样的网络（`quantum_bptn::clusters`）：一阶是精确收缩可观测量所在的环，二阶把它与和它共享一段路径的两个环分别合并，三阶与每一对相连的环合并；每个区域在边界上用置信传播的消息闭合并精确收缩，各区域按其计数系数组合。二阶在 χ = 64 时增加 +0.0019，随 χ 增大到 χ = 320 时的 +0.0040（0.8235），是一阶相对于弧所增加量的十九分之一到十二分之一；它随丢弃权重呈直线变化（最后三个点偏离直线不超过 3·10⁻⁶），外推到丢弃权重为零时为 0.8225。三阶只有在 χ = 64 时才能达到，而且只能收缩五个三环区域中的四个，余下一个的表格（309 GB）任何主机都放不下：它增加 +2.2·10⁻⁵，是二阶增量的 1.2%；χ = 64 以上，其区域最多需要 1.2·10¹⁶ 次乘加。若此后每一阶增加的量与前一阶之比都等于二阶与一阶之比（这是一个假设，不是界），未运行的各阶在 χ = 320 时共增加 3.5·10⁻⁴，外推值为 0.8229；在 χ = 64 时，这一假设预言三阶增加 +9.8·10⁻⁵，是实际增量的 4.5 倍。作为对照：设备测得 0.824，已发表的张量网络值为 0.8203 和 0.8217，单路径蒙特卡罗为 0.808。每个环自身的环修正（`Tns::loop_weight`，即环关联检验）的大小都低于 3·10⁻⁴。χ = 96 时展开的每个数在 Linux x86_64 与 macOS arm64 上的比特完全相同。在更深的线路上（49 和 70 量子比特，深度加倍，扰动之前每条边十二个门）没有任何方法收敛：χ = 32 到 64 时累计丢弃权重超过 10，值的变化以十分之一计（49 量子比特从 0.05 到 0.54，70 量子比特从 0.04 到 0.44）；去掉扰动后（此时精确回波为 1），49 量子比特的网络在相同键维下读出 0.054 和 0.548，因此这些值主要是截断丢失的部分，不能给出任何界。环簇展开修正的是收缩，而不是截断，而且在那里推不远：可观测量所在环的每条键都达到 χ，二阶在 χ = 32 时需要 6·10¹³ 到 10¹⁴ 次乘加，在 χ = 64 时需要 1.6·10¹⁶ 次。稀疏泡利动力学在阈值 10⁻³ 到 10⁻⁴ 时把演化后的可观测量截断为零；生长算子的截断丢掉了它偏离恒等算子的全部部分，其值一直为 1。回执保存了每一次扫描。
- `tracker_peaked`：峰值线路，按构造时植入的结构读取（`quantum_peaked`）。每条线路由一段线路 `R`、一个块 `U` 及其近似逆 `U†`（角度经过扰动、按小块重新综合，在全连接硬件上还经过隐藏的置换）以及一段为使 `R` 出峰而训练的线路 `P` 组成（arXiv:2510.25838）。从每个候选中心向两侧各生长几层线路算子，只有在 `U` 与 `U†` 相接处算子才保持很小：在 49×5072 上是第 138.5 块层（对数规模 2.8，而 545 个中心的中位数为 105）。从该处向外生长，算子从向外第 7 层到第 134 层都是恒等算子，一条键都没有，只在两端最后六层（`R` 与 `P`）内才重新出现键（键维至多 8）。在 `|0…0⟩` 上读出的峰值为 `1001100011100000001010100001011111111011110010110`（量子比特 48 在前），正是追踪项目中迭代抵消（iterative cancellation）提交所给出的比特串，`|⟨s|C|0⟩|² = 0.709`。在 49×4020 上，相接处位于第 109.5 块层，键维不超过 4：峰值为 `0110011000010000100101000110001101000000100001001`（量子比特 48 在前），概率 0.694；追踪项目没有给出该线路的比特串，有一份提交称其峰值约占 70%。每次运行在 CPU 上耗时 6 到 19 秒（大部分用于扫描），内存不到 75 MB。`verify STRING` 不经读出即可核对一个比特串：它在整条线路中的振幅，网络以该比特串闭合并精确收缩，在截断阈值 10⁻² 到 10⁻³ 下、并从另一个中心出发计算，49×5072 上为 0.7089 到 0.7094，49×4020 上为 0.6934 到 0.6997。在全连接的 56×1917 线路（`P9_Hqap_56x1917`）上，图上的算子找不到峰值：没有哪个中心突出（向两侧各生长四层，最小的探测对数规模为 55），从中部带反交换生长，每侧 14 层后已有 237 条键、10⁷ 个数。它的块按小块重新综合并经过隐藏置换，没有哪个门与其镜像逐层相遇。`chain` 按已发表解法（arXiv:2604.21908）的方式读取它：1885 个块从一半处切开，算子是链上的矩阵乘积算子，每一侧在吸收时布线到链上，截断阈值 2·10⁻³、键维上限 8192，超过 10⁶ 个数时进行反交换。按整个格点布线（一个量子比特的行与列一起移动，这是我们的改动：已发表的布线只移动一侧的指标，每把一行移离其列就要付出一条键）时，在一台与其他工作共用的 32 核 Linux x86_64 主机上运行耗时 139 秒（16 个线程，388 MB；开始时负载 45），键维至多 512、数至多 975,352 个，布线 SWAP 17,341 个，反交换在 9,033 次尝试中保留 813 个，截断丢弃 2.3·10⁻⁴ 的权重。沿链精确条件解码读出的峰值为 `01101110111001100000100000001010011100101101010111110111`（量子比特 0 在前），正是已发表解法用来核对其采样的比特串，`|⟨s|C|0⟩|² = 0.0999`；1000 次精确采样中有 103 次是它（已发表的运行约为 10.6%），它的任何单比特改变都不超过 0.0042。`chainverify STRING` 给出一个比特串在以其他截断阈值（或从其他切点）生长的算子中的振幅，不经读出：截断阈值 2·10⁻³ 时为 0.09996，10⁻³ 时为 0.09999，5·10⁻⁴ 时为 0.09999。同样的运行在 Linux arm64（10 个线程，277 秒）和 macOS arm64（8 个线程，504 秒，进程自身的能耗计数为 504 焦耳）上给出与 x86_64 运行逐位相同的每一个数。按已发表的方式只布线每一侧的指标时，同样的设置耗时 762 秒、607 MB，布线 SWAP 30,124 个，反交换在 70,076 次尝试中保留 9,927 个，得到同一个峰值和 0.09996。耦合图上的态网络与链上的算子（`run`、`gauged`、`mpo`）在 χ ≤ 32 时都没有显示出峰：链上的一个切口会跨过多条耦合，每条都带一条键。

```sh norun=data
cargo run --release --example tracker_peaked --features quantum_engine,quantum_receipt,quantum_bptn,quantum_mpsim,quantum_peaked -- TRACKER 49x5072 structure
cargo run --release --example tracker_peaked --features quantum_engine,quantum_receipt,quantum_bptn,quantum_mpsim,quantum_peaked -- TRACKER P9_Hqap_56x1917 chain route=both
```

`tests/tracker_reference.rs` 重新运行 DMRG 以及各次扫描中代价最低的回执，在小线路上把每种方法与精确参考值对照，并检查每份回执的签章。`tests/tracker_peaked.rs` 从与固定数据一起保存的线路重新恢复两条 heavy-hex 线路的峰值，要求 49×5072 的峰值与已发表的比特串一致，并检查各次核对扫描的回执；在 56×1917 上，它重新运行链上算子的前 62 层（经过第一次反交换），结果与回执记录的逐位相同，并要求回执中的峰值与已发表的比特串一致。

**在 GPU 上，与 CPU 逐位一致**（`quantum_spd::device`）。项之和可以驻留在设备上：设备对所有项同时执行每一步的算术（乘以 `sin` 一次、乘以 `cos` 一次、新项遇到旧项时相加一次、改变符号；构建时不使用融合乘加），而决定项集合的一切由主机掌握。一次旋转产生的新项在表中查找（包括已失效的槽位），其余的按其来源项的顺序、经保序前缀和追加到表尾；主机清点失效项和存活项，并在与 CPU 完全相同的时刻压缩；截断按表序交回所丢弃的数值，误差上界和结果值在主机上按表序相加。`HostDevice` 在 CPU 上执行这一协议，并与 CPU 的传播逐位一致（包括最终的表）。CUDA 成员（`CudaSpd`，配合 `quantum_fabric_cuda`）在固定语料（`SPD_DEFAULT`：40 个用例，占一到四个字，含项数与权重上限，以及被复活和被抵消的项）上对照 CPU 认证，每个值、上界、所达到的阈值、计数和最终的表都相同；`pauli` 作业用 `fabric`（`accelerator`，或成员的 id 或键）请求它，得到与 CPU 逐字节相同的答案，结果写明该成员。`auto` 把 `pauli` 方法留在 CPU 上：没有任何成员被测得对它更快。

## 容错资源

一个程序在尚不存在的机器上需要什么，就是一份资源估算；而关于那台机器的种种说法，都以这样一份估算为依据。`quantum_resource` 使估算成为其输入的确定性函数：

```sh runnable
wai-quantum lab estimate factoring                    # 2048 位整数分解，六种参考量子比特
wai-quantum lab estimate chemistry --qubit ns-e4 --frontier
wai-quantum lab estimate factoring --qubit ns-e4 --receipt | wai-quantum verify
wai-quantum estimate prog.qasm                        # 根据程序自身的计数（见下文）
```

模型采用 arXiv:2211.07629 中的平面 ISA 模型：表面码和 Floquet 码的码块、格点手术，以及通过对单元类型、码距和副本数进行穷举搜索而选出的 15 到 1 蒸馏工厂。测试复现了该文献自己的表格：
- 其按量子比特列出的整数分解表中的每个码距和工厂，细致到副本数；
- 其汇总表中全部十二行整数分解与化学条目的码距、工厂数、物理量子比特数和运行时间；
- 其动力学各行的全部十二个工厂数。在 `(ns, 10⁻⁴)` 量子比特上，整数分解的结果为 `d = 13`、18 个工厂、8,716,258 个物理量子比特和 17 小时 43 分钟。

用这些表格检验模型时，暴露出原作文字与其数字不一致的几处地方，以及一个并非其自身模型最小值的工厂。每一处都记录在模块中，并以表格为准加以裁定。

一份封存的估算会写明它的整个作业（计数、量子比特、码、预算、减速因子和搜索上限，精确到位）。在任何地方重新运行它，都必须复现每一个数字，细致到每一轮工厂；原生运行和作为 WASI 组件运行得到的字节完全相同。

## 优化

```sh norun=data
wai-quantum lab qio --gset G22 --method dsb --dt 0.5 --steps 20000 --trials 64 --target 13359   # G-set 基准中的 G22 文件
wai-quantum lab qio --gset G14 --method sa --steps 300000 --beta0 0.2 --beta1 4 --target 3064
```

```sh runnable
wai-quantum lab qio --sk 24 --method exact --spins          # 真实基态，适用于小规模问题
```

优化是关于量子硬件最常见的说法，而每一个这样的说法都是与某个经典求解器的比较。`quantum_qio` 就是一个可以重复运行的经典求解器。它提供：
- 模拟分岔（弹道式、离散式，以及二者的加热版本）；
- 模拟退火；
- 单翻转下降；
- 一个能对小规模实例给出定论的精确参照。

结果是一个自旋构型，因此任何人都可以一遍就重新核对它的割值或能量。在 G-set Max-Cut 基准上，G1、G2、G3、G11、G14、G22 和 G43 达到了已知最优割。在 G55 上，找到的最好结果是 10,292，对照值为 10,299。模块记录了每项设置及其成功率，以及稀疏图对时间步长施加的上限。
## 自旋链

```sh runnable timeout=1200
wai-quantum lab dmrg -n 200 --bond 64 --sweeps 4                 # 临界 Ising 链，与其精确能量对照
wai-quantum lab dmrg --chain heisenberg -n 100 --bond 128         # 包含纠缠分布与舍弃权重
```

声称经典计算机无法模拟某种材料，本质上是关于纠缠的声称。对于一维系统，密度矩阵重整化群通常能够模拟它，并自行报告误差。`quantum_dmrg` 就是这种方法，并以精确解为准加以检验：
- 短链的完全对角化；
- 任意长度横场 Ising 链的自由费米子解。

在 200 个格点上，临界 Ising 链的结果与其精确能量相差约每格点 `10⁻¹¹` 以内。在任意线程数下，无论原生运行还是作为 WebAssembly 运行，结果都逐位重复。

## 时间演化

```sh runnable timeout=2400
wai-quantum lab tdvp -n 100 --bond 64 --dt 0.1 --t 4             # 临界 Ising 淬火，与自由费米子对照
wai-quantum lab tdvp --chain heisenberg -n 100 --bond 64 --t 3    # Néel 态的融化，包含纠缠
```

当经典方法能够跟上时，对动力学的量子模拟就是可核查的。`quantum_tdvp` 用含时变分原理演化矩阵乘积态，并报告它舍弃了什么：舍弃权重、能量漂移以及每个键上的纠缠。它在短链上以每个振幅的精确演化为准，在任意长度上以 Ising 淬火的自由费米子解为准，包括 Loschmidt 回波。

在键维数 64 的 100 格点临界 Ising 淬火中，直到 `t = 3`，每个格点的 `σˣ` 都与精确解相差在 `10⁻⁹` 以内，Loschmidt 率吻合到七位数字。当纠缠超出键的容量时，误差随舍弃权重上升，运行也会如实说明。足够小、能被键容纳的链，在任意时间步长下都精确演化（仅有舍入误差）。在任意线程数下，无论原生运行还是作为 WebAssembly 运行，结果都逐位重复。

## 分子

```sh norun=data
wai-quantum lab chem --fcidump h2o.fcidump --bond 64 --sweeps 2   # 来自化学软件包的分子积分：与 Hartree–Fock 及 full CI 对照
```

量子化学是人们最常说量子计算机会带来回报的领域；而当经典方法能得到同一个数字时，关于某个分子能量的说法就是可核查的。`quantum_chem` 读取分子的积分，把其哈密顿量写成精确的矩阵乘积算符，并用 DMRG 求基态，以同一 crate 中计算的完全组态相互作用为准。LiH 和水在一次扫描内就与 full CI 一致到 `10⁻¹³`。N₂ 在 20 个自旋轨道、键维数 64 下与之相差在 `4·10⁻⁴` 以内，并报告了造成这一差异的舍弃权重。

## 神经网络量子态

```sh runnable timeout=900
wai-quantum lab nqs --lx 8 --exact --steps 200 --lr 0.1          # 枚举每个构型：没有采样噪声
wai-quantum lab nqs --model ising --lx 4 --ly 4 --h 3.044 --alpha 1 --steps 400
wai-quantum lab nqs --model j1j2 --lx 8 --periodic --complex --exact --steps 250 --lr 0.1   # 阻挫：符号由学习得到
wai-quantum lab nqs --lx 10 --periodic --complex --project --kpi --odd --exact --steps 200 --lr 0.1   # 限定在其扇区内
```

神经网络波函数被用作证据，来说明那些任何精确方法都无法触及的系统。`quantum_nqs` 以标准方式训练这样的网络，并以精确解检验它。在 4 × 4 晶格上、Ising 模型的临界场下，它与精确对角化的差距落在其自身的误差棒以内。超出精确方法的范围之后，同一个哈密顿量通过其精确 MPO 交给 DMRG，于是两种独立的方法在同一个数字上相遇。对于阻挫模型，其符号没有任何规则可以给出，复数网络会把它们学出来。在 Majumdar–Ghosh 环上，它在舍入误差内达到精确能量。投影到晶格的平移和全局自旋翻转上之后，网络被限定在基态所在的扇区内。各个环都在舍入误差内达到其精确能量，而 `J₂ = 0.5` 处的阻挫 4 × 4 环面则在百分之一以内。

## 含噪声线路

```sh runnable timeout=900
wai-quantum lab noisy --file circuit.jsonl --depol2 0.01 --depol1 0.001 --readout 0.01 --trajectories 4000 --xeb
wai-quantum lab noisy --file circuit.jsonl --damping 0.02 --expect "Z0; X3 X4" --exact
```

迄今为止的每一个量子优势实验都在含噪声的硬件上运行，并报告一个保真度。对于随机线路采样，这个保真度是一个交叉熵估计值，并与一个数字误差模型作比较，该模型把每个门和每次读出的成功概率相乘。`quantum_noisy` 用三种方式核查这一算术：
- 态矢量上的量子轨迹；
- 精确密度矩阵，适用于最多 12 个量子比特的寄存器；
- 该模型本身。

在去极化噪声下的随机砖墙（brickwork）线路上，精确保真度比模型的预测高出几个百分点。这一差距随错误率增长，而不随深度增长；对于不发生置乱（scramble）的线路，差距更大。模块以表格列出了这一差距。

## 设备目标

```sh runnable
wai-quantum targets import props.json --name lab        # 一台设备的校准快照，保存为 "lab"
wai-quantum run bell.qasm --target lab                  # 按该设备的方式运行
wai-quantum run ghz.qasm --target synthetic-heavy-hex-27 --json
```

`engine::targets`（需 `quantum_engine` 和 `quantum_receipt`）了解真实设备：它们的量子比特，包括 T1、T2、频率、读出分配错误和测量时间；它们的原生门，包括每个量子比特和每对量子比特上的错误率与时长；耦合图；以及校准快照的 id 和时间。一个目标就是一份被严格读取的 JSON 文档 `wai.quantum.target/1`，附带 JSON Schema（`targets::schema`），其 RFC 8785 文本的 BLAKE3 哈希值在回执中标识该快照。

- **导入器**（`targets::import`）读取：超导设备服务发布的每量子比特和每个门的校准属性，可单独提供，也可与设备配置一起提供（已发布的快照设备即以这种形式提供）；指令属性（instruction-properties）目标；云量子服务为门模型设备返回的设备能力文档；以及开放提供方协议的 `describe`。没有指定快照的来源会获得一个内容 id。
- **噪声**（`targets::noise`）：编译后的程序在每个门的量子比特一空闲时就调度该门。每个门报告的错误率被转化为一个去极化信道，使其与该门时长带来的弛豫合在一起，恰好具有所报告的平均不保真度。T1 和 T2 给出门执行期间以及量子比特空闲时的振幅阻尼和退相位，每个量子比特的读出则由其分配矩阵描述。密度矩阵和量子轨迹将其作为一个信道调度表（`quantum_noisy::Schedule`）接收，每个信道有自己的强度。这是设备的一个模型，每个结果都会注明这一点。
- **布局**（`targets::layout`）：比较多种布局及其最可靠的路由，保留期望成功率最高者（计入每个门的成功率和每个被测量子比特的读出）。编译器自己的选择——交换次数最少者——除非被超越，否则胜出；程序会由逐位精确的模拟器与原线路进行核对。双量子比特门为 `cx`、`ecr`、`ms` 或 `zz` 而不是 `cz` 的目标，按其自身的门计算代价，并且计划中会说明单量子比特修正未计入。
- **作业**（`targets::job`）：作业的 `target` 是一份文档或一个内置目标的名称。计划会说明布局、其期望成功率（与交换次数最少的布局的期望成功率并列）以及推导出的噪声；结果在回执内包含同样的信息以及目标的哈希值，并说明其分布与线路的理想分布相距多远。由于程序是精确编译的，每个角度都必须是 2π 的二进分数倍。

四个内置目标（`targets::library`）都是合成的，每种格式各一个，其数值均由固定种子的生成器编造：一条 5 量子比特的线、一个 8 量子比特的环、一个 27 量子比特的 heavy-hexagon 晶格，以及 5 个全耦合的量子比特。已对照真实值核验：无错误的目标在三种门集中的每一种上都给出理想分布，精度达 1e-12；T1 衰减、T2 相干和分配矩阵都给出其闭式结果；按 Choi 态计算，每个门的信道恰好具有所报告的平均不保真度；在线形拓扑上选出的布局就是穷举搜索找到的最优布局。在一个目标上的运行，原生运行和作为 WASI 组件运行会得到相同的字节。

## 快速解码

```sh runnable timeout=900
wai-quantum lab qec -d 9 --p 0.005 --shots 20000 --decoder uf     # 并查集（union-find）
wai-quantum lab qec -d 9 --p 0.005 --shots 20000 --decoder exact  # 精确匹配，相同的采样
```

容错机器必须在下一轮校验子到来之前解码完当前这一轮。`quantum_uf` 是基于精确匹配所用的同一个匹配图的并查集解码器。簇从被触发的探测器开始生长，并随着边被填满而合并，然后剥离每个簇的生成树，得到纠正操作。它每次采样的耗时随被触发探测器的数量线性增长。在相同的采样上，它的失败次数是精确匹配的 0.92 到 1.18 倍。模块按码距和噪声以表格列出两种解码器的结果及各自的耗时。

## qLDPC 存储

```sh runnable timeout=900
wai-quantum lab ldpc --code 144 --p 0.004 --cycles 12 --shots 1000   # 每个周期的失败率，两半均给出
wai-quantum lab ldpc --circuit --code 72 --cycles 6 --p 0.003        # 线路本身
```

容错中预计节省的量子比特，大部分来自高码率码，而这些码的核心数字是线路噪声下每个校验子周期的逻辑失败率。`quantum_ldpc` 针对双变量自行车码族（arXiv:2308.07915）重新推导这些数字：
- 由多项式构造码；
- 逐门写出深度为 8 的校验子周期；
- 用 Pauli 帧模拟器对线路采样；
- 用置信传播加有序统计对其误差模型进行解码。

原作公开了其模拟软件，运行它即可得到参照答案（oracle）。在 72 量子比特码上，推导出的误差模型与原作的列逐个探测器一致，并且在相同的校验子上，解码器逐次采样地作出与原作相同的决策。逻辑失败率与原作吻合；唯一尚未解决的残差——在最高噪声下其中一半偏离 2.3σ——已记录在模块中。在 144 量子比特码上，失败率落在原作已发表的曲线上。

## 架构

```sh runnable
wai-quantum lab arch factoring --bits 2048     # 整台机器，逐个区域
wai-quantum lab arch storage --target 1e-15    # 最廉价的普通、行轭合与网格轭合布局
wai-quantum lab arch cultivate --p 1e-3 --target 1e-7
```

近来预计容错代价的下降，大部分来自码周围的架构，而不是更好的量子比特。空闲的量子比特存放在轭合存储中（arXiv:2312.04522）。T 态在单个码块内部培育，而不是蒸馏（arXiv:2409.17595）。时钟以格点手术、魔术态供应和控制回路三者中最慢者的节奏运行。`quantum_arch` 为其中每一项估算代价。

它重新运行了 2025 年的那项估算：在不到一百万个含噪声量子比特上，2048 位整数分解用时不到一周（arXiv:2505.15917）。
- **已复现。** 其 897,864 个物理量子比特、每个逻辑量子比特 429.03 个量子比特的存储密度，以及表中每种密钥长度的 Toffoli 门数，均按参考实现自身的舍入复现。
- **已修正。** 重新运行发现原作有六处自相矛盾，每一处都记录在模块中。其热存储数量低于它自己的峰值公式。其冷存储假定了分数个块。其印出的运行时间比它自己的统计高 14%。应用所有修正后，这台机器需要 958,480 个量子比特和 4.3 天。结论依然成立。

## 线路级纠错

一个纠错实验由一条含噪声的 Clifford 线路、其探测器和其逻辑可观测量构成。`quantum_frame` 对它采样，推导其探测器误差模型，并精确地解码：

```sh runnable timeout=900
wai-quantum lab qec -d 5 --p 0.003 --shots 100000       # 表面码存储，每轮逻辑错误率
wai-quantum lab qec --circuit -d 3 > circuit.txt         # 线路，采用生态系统通用的文本格式
wai-quantum lab qec --file circuit.txt --shots 100000    # 该文本格式的任意线路
wai-quantum lab qec --dem -d 3                           # 其探测器误差模型
wai-quantum lab qec --fit                                # 测量 P(d) = a·(p/p*)^((d+1)/2) 中的 a 和 p*
```

该模型已对照一个独立实现进行核查：
- 在码距 2–15、轮数 1–8 范围内，生成的线路逐字节相同；
- 在两种基下的表面码（旋转与非旋转）以及重复码上，推导出的误差模型逐个机制吻合，概率精确到 10⁻¹²；
- 解码后的逻辑错误率逐点吻合，差异在采样误差之内。

`tests/frame_reference.rs` 在仓库中保留了其中两个测试夹具。拟合得到的码模型为 `a ≈ 0.023`、`p* ≈ 0.0100`。资源估算（`quantum_resource`）原本只能凭信任采用这些常数，而这是它们的实测值，可以直接输入到估算中。

## 各个入口上的纠错

```sh norun=data
wai-quantum qec code color:7                           # 校验、k、解码器，以及经过认证的距离
wai-quantum qec decode --code surface:5 --error 3,12   # 解码校验子，并判定残差
wai-quantum qec decode --memory 5,5,0.003 --shots 20000 --decoder correlated
wai-quantum qec decode --model run.dem --detectors 4,9 # 模型文本，读取其中的分解
wai-quantum qec threshold --distances 3,5,7 --p 0.002,0.004 --shots 20000
```

`engine::qec` 是命令行、两个 MCP 服务器（`qec_code`、`qec_decode`、`qec_threshold`）、作业服务（`POST /v1/qec/{code,decode,threshold}`）、Studio 的纠错面板、桌面应用和 Python（`wai_quantum.qec_code` 等）共用的同一个调用，每个回答都以作业的形式封存。一个码附带**距离证书**：在每个扇区中，找到的逻辑算符的最小权重、该权重的一个见证，以及在连通支撑上经穷举搜索排除的每个更轻的支撑，可以逐个节点地重新检查。每个解码器都经受同样的穷举测试：低于距离一半的每个错误都纠正为平凡残差（在线路级模型上，则是低于图距离一半的每个边集）。每个解码器保证什么、窗口的延迟预算，以及每种缓解方法的假设，见 [docs/qec.md](docs/qec.md)。

## 脉冲与动力学

脉冲程序以产生各个门的控制信号来给出这些门：作用于物理量子比特的 OpenPulse 校准。`wai-quantum pulse schedule` 画出它的时序；`wai-quantum run` 加上 `--method pulse` 在主方程下对它积分，结果有界，并且在每个平台上比特一致；`wai-quantum pulse check` 通过重新运行，把一个已封存的脉冲作业与其请求对照检查。同样的运行在每个入口上都是作业（两个 MCP 服务器的运行工具、作业服务、页面），两个 MCP 服务器都提供 `pulse_schedule` 和 `pulse_check`。其回执绑定控制程序、其校准、它所运行的设备与目标快照，以及积分器及其步长。模型、误差上界和选项见 [docs/pulse.md](docs/pulse.md)。

## 能量景观作业

这类作业不给出线路：它对三态变量给出能量，并要求一个低能量状态。`wai-quantum landscape run` 在沉降模型的经典模拟器上运行程序。答案给出状态、其精确能量、规模足够小时检查过的每一种排列、统计的工作量，以及按注明来源的费率定价的焦耳，这里从不测量。`wai-quantum landscape compare` 在同一实例上以相同预算运行模拟退火、禁忌搜索和贪心下降，已发布的结果表说明它们在哪里领先。作业形式以及 GPU 或 FPGA 板运行所经由的接缝见扩展 [quantum-landscape](../extensions/quantum-landscape.md)，其余内容见 [docs/landscape.md](docs/landscape.md)。指明 `wai.quantum.landscape/2` 的请求在 CPU 参考实现上运行第二版（[quantum-landscape-2](../extensions/quantum-landscape-2.md)），可以通过命令行、作业服务、Python、浏览器包、桌面应用、Quantum Studio、MCP 工具 `run_landscape`，以及你自己的、其描述列出该版本的提供方来运行；`verify` 按该版本的形式检查其回执。

## 变分算法与算法库

```sh runnable
cat > ansatz.qasm <<'EOF'
OPENQASM 3.0;
input float t;
qubit[2] q;
h q[0];
crx(t) q[0], q[1];
EOF
wai-quantum run ansatz.qasm --param t=0.4 -o Z1                      # 精确绑定一个参数
wai-quantum gradient ansatz.qasm --param t=0.4 --term Z1 --term "0.5 X0"   # E 及其梯度，附舍入误差界
wai-quantum optimize ansatz.qasm --param t=0.4 --term Z1 --steps 50 --json > opt.json
wai-quantum verify opt.json                                          # 回执、每一步的摘要链，并重新运行
wai-quantum vqe --term "X0 X1" --term "Y0 Y1" --term "Z0 Z1" --layers 2 --steps 200
wai-quantum build qpe --counting 5 --phase 0.3 > qpe.qasm            # 对照其参考加以检查
wai-quantum run qpe.qasm --shots 1000
```

作业的 `params` 精确地绑定程序的参数（`input float theta;`、`input angle phi;`）。`engine::variational` 计算哈密顿量的期望值及其对每个参数的梯度，方法是精确的：伴随微分或参数平移规则（两项，受控旋转为四项）；读取器把每个门对每个参数的导数沿算术运算和门定义一路带到门上（`qasm::tangents`，无法跟随之处以 `Q129` 拒绝）。每个回答都注明它以 f64 计算、是近似值，并给出其舍入误差的先验界。梯度下降、Adam 和带种子的 SPSA 在每个平台上给出相同的字节，每一步都是回执所封存的摘要链中的一环；变分本征求解器把找到的能量与精确基态能量并列，QAOA 把所得的割与穷举得到的最大割并列。`engine::algorithms` 写出相位估计、振幅估计、行波进位加法器和 QSVT 的程序，每个都由等价性阶梯对照按其定义构造的参考加以检查。命令行、两个 MCP 服务器、作业服务和浏览器引擎共用同一个调用；见 [docs/variational.md](docs/variational.md)。

## 态矢量

```sh runnable
wai-quantum lab sv --file circuit.jsonl --top 8            # 最可能的结果
wai-quantum lab sv --file circuit.jsonl --expect "Z0 Z1; X3"
wai-quantum lab sv --file circuit.jsonl --sample 1000 --seed 7
```

`quantum_sv` 以双精度在最多 32 个量子比特上运行任意角度的任意门。`gates` 按名称为它和张量网络提供标准门（H、S、T、√X、√Y、√W、旋转门、CX、CZ、iSWAP、fSim……）。一条 26 量子比特、深度 20 的随机线路在一台机器上约九秒跑完，而且结果的每一位都与运行它的线程数无关。

### 态在哪里运行

```sh runnable
wai-quantum fabric                                    # 本机上态矢量可放置其上的成员
wai-quantum run circuit.qasm --method statevector --fabric cpu --fabric cpu --fabric cpu --fabric cpu --shots 100 --json > split.json
```

作业的 `fabric` 把 `statevector` 方法的态放到计算结构的成员上（`engine::fabric`）。编译进 CUDA、HIP 或 OpenCL 成员（`quantum_fabric_cuda`、`quantum_fabric_hip`、`quantum_fabric_opencl`，配合 `quantum_engine`）后，本进程找到的每个设备都以驻留方式运行稠密 f64 态矢量（`quantum_fabric::sv64`）：态在设备上清零（分区时则上传一次），所有门的参数作为一张表一次上传，每个门按 CPU 的启动顺序在设备上运行、其间不等待，态最后读回一次。每个成员在固定语料上对照 CPU 认证，其一次作用于三个以上量子比特的门（融合宽度 4 到 6，或更宽的门）所用的内核另有自己的语料（`sv64::SV_WIDE`，120 个用例）；只有认证为逐位一致的成员才会被放置，且只用于它已认证的内核，因此放到其上的作业给出与 CPU 逐字节相同的答案。默认的 `auto` 只按测量结果把态放到成员上（见下文），否则留在 CPU 上；作业请求成员时，成员运行它。`accelerator` 把它放到第一个能容纳它的已认证成员上（GPU 优先），若该成员在运行中失败，由下一个接替；`cpu` 或成员的 id 或键把它放到那里；成员列表（数量为 2 的幂）按最高位量子比特把态划分为若干分区，每个成员一个分区。每个分区在自己的振幅上运行 CPU 规划的同一组启动；作用于分区量子比特的门，先经主机上的态副本把该量子比特与一个本地量子比特交换（`quantum_fabric::sv64::run_split`），因此拼合后的态与 CPU 的逐位相同。结果的 `fabric` 指明成员（或每个分区的成员）及其证书的一致性等级、摘要和语料，并由收据封存；未请求成员、也未放置时，结果与以往相同。每个成员说明它能容纳的最多量子比特数，超过此数的态或分区会被拒绝，主机无法兑现的任何放置也会被拒绝（`J013`）。

**按测量结果的 `auto`**（`engine::fabric_measured`）。在 CPU 和每个成员上对同一族线路（每个量子比特十层任意角度旋转，加砖墙式纠缠对，1000 次采样）的完整作业计时，二者交替各运行五次，融合宽度为 3、2 和 1，从 18 个量子比特到主机一半内存所能容纳的规模；该表连同每台主机、其负载和日期都在源代码中，`cargo run --release --example fabric_timing` 可以重新测量。若成员上的每次运行都快于 CPU 上的每次运行，则该行记为“更快”。`auto` 从这样一个最小的测量规模开始把态放到成员上：从它到最大测量规模的每一行都更快；上限为最大测量规模，只用于所测的融合宽度，且作业的规划至少有所测线路的启动次数；尚未发现其成员的进程，只在节省的时间还能抵消表中所列的发现开销时才这样放置。由 `auto` 放置的作业，其收据带有规则及其所依据的那一行（`fabric.auto`），`wai-quantum fabric` 打印规则、它在本机的放置范围以及每个测量行。测量结果（中位数，2026-10-30）：在笔记本上（20 线程 CPU，计算能力 8.9 的 GPU），从 22 个量子比特起，在任何融合宽度下，GPU 作为完整作业都不更快（融合宽度 3、26 个量子比特：CPU 3.74 秒，CUDA 4.44 秒，OpenCL 4.29 秒），因此 `auto` 把每个态都留在其 CPU 上。在与集成 GPU（gfx1151）共享 128 GiB 内存的 32 线程 CPU 上，融合宽度 3 和 2 时，从 18 到 28 个量子比特，GPU 的每次运行都快于 CPU（融合宽度 3、22 个量子比特：CPU 205 毫秒，HIP 108 毫秒，OpenCL 102 毫秒；28 个量子比特：9.81 秒对 8.47 秒和 8.14 秒），融合宽度 1 时从 22 个量子比特起则更慢；发现其成员每个进程需 1.2 秒，超过 28 个量子比特以下的节省，因此已发现成员的进程从 18 个量子比特起由 `auto` 放到 GPU 上，新进程只在 28 个量子比特时这样做。在与集成 GPU（计算能力 11.0）共享 122 GiB 内存的 14 核 aarch64 CPU 上（2026-10-31），GPU（经 CUDA 和经 OpenCL 都一样）在 24 个量子比特以下赢了部分测量行，但从 26 个量子比特起在每个融合宽度下都更慢（融合宽度 3、28 个量子比特：CPU 22.5 秒，CUDA 和 OpenCL 都是 27.7 秒），因此没有任何规模之后的各行都更快，`auto` 把其态留在 CPU 上。其他主机、成员或融合宽度都留在 CPU 上。

## 张量网络

线路的一个振幅就是一个张量网络，而缩并的顺序决定了它的代价是 `2³⁰` 次运算还是 `2⁶⁰` 次。`quantum_tn` 搜索这一顺序，将其切片以适应内存，然后进行缩并：

```sh runnable
wai-quantum lab tn --file circuit.jsonl --bits 0110010110   # 单个振幅
wai-quantum lab tn --file circuit.jsonl --open 0,5,9        # 三个开放输出上的一批结果
wai-quantum lab tn --file circuit.jsonl --plan-only --cap-log2 30
```

线路采用 JSON lines 格式，每行一个门：`{"q":[a,b],"m":[re,im, …]}`。

每个门都在它呈块对角的量子比特处拆分：即控制比特，或门在其上为对角的量子比特。该量子比特的部分是一个精确的三指标 delta，通过一个维数为 2 的键与门的其余部分相连，因此穿过受控 Z 门的切分代价为 2，而不是其两根线的 4。随后，凡是某个张量只允许取一个值的指标，都在那里固定下来，于是输入和输出投影可以穿过对角门：紧挨着投影输出的受控 Z 门变成标量。在深度 8 到 20 的 61 量子比特受控 Z 线路上，在拆分并约简后的网络上找到的缩并树，其代价比在整门网络上找到的低 2.7 到 5.4 个数量级。`--whole-gates` 让每个门保持为一个张量，网络保持构建时的原样。

对于 54 量子比特优势实验网格上随机线路的单个振幅，搜索在几秒内找到的缩并树在 10 个周期时为 `10¹⁰·⁵` 次运算，在 20 个周期时为 `10¹⁸·⁸` 次。一个独立开发的超优化器在相同的网络上得到的结果，在每个深度上都与这些结果相差在 2.5 倍以内，有高有低。54 量子比特、10 个周期的振幅在这里分 16 个切片缩并，与一个独立缩并的结果吻合到 12 位有效数字。模块文档说明了切片在深层线路上的代价，以及标量执行器能够缩并和不能缩并的内容。

## 带证书的编译

```sh runnable
wai-quantum compile prog.qasm --epsilon 1e-6 --level 2 > prog.ct.qasm
wai-quantum run prog.qasm --compile 1e-6 --shots 1000     # 先编译，再以逐位精确方式运行
```

`engine::compile` 让程序依次经过一系列具名的处理遍（pass）：降级、引擎经过检查的重写、相位折叠、单量子比特和双量子比特的重新综合（Clifford+T 门串化为 `T` 门最少的范式，双量子比特块通过 KAK 分解为至多三个 CNOT），以及在门集（basis）为 `clifford_t` 时，把每个旋转在其分得的预算 `ε` 份额内写成 Clifford+T 门序列（word）（Ross–Selinger 方法，在 `Z[1/√2, i]` 上精确运算）。每一遍都在其作用之处加以检查：通过精确的环运算或重新计算的相位多项式（属于证明），或在稠密矩阵上检查（精确到舍入误差）。证书记录每一遍的计数和检查结果，以及输出与程序之间（在相差一个全局相位的意义下）算子范数距离的上界，该上界从不超过 `ε`；在八个量子比特以内，还会把整个输出与整个程序进行比对测量。一个旋转的门序列约含 `3·log₂(1/ε)` 个 `T` 门。[docs/compiler.md](docs/compiler.md) 介绍了各遍处理、级别、证书的字段以及如何理解 `ε`。

## 基于程序的资源估算

```sh runnable
wai-quantum estimate prog.qasm --qubit us-e3 --budget 1e-4   # 计数、估算、前沿；已签名
wai-quantum estimate prog.qasm --json > est.json && wai-quantum verify est.json
wai-quantum estimate --counts counts.json                    # 或者一份逻辑计数文档
wai-quantum estimate prog.qasm --export routine              # 把计数导出为 routine 文档
```

`engine::estimate` 直接接收程序本身。它把程序写成 Clifford 门、`T` 门、旋转、Toffoli 门和测量（多控制门借助干净的辅助比特写成一串 Toffoli 门构成的阶梯），对每个旋转按其自身角度、在其分得的误差预算份额内进行综合（其 `T` 门数取自综合出的门序列，而不是某个公式），然后统计 `T` 门、Toffoli 门、旋转、测量、`T` 深度、总深度，以及逻辑量子比特及其辅助比特。平面模型对这些计数进行布局，估算码距、工厂、物理量子比特数和在某种物理量子比特上的运行时间，并给出量子比特数与时间之间的前沿。对于基于门的量子比特，码模型的 `a` 和 `p*` 是用本 crate 自己的解码器在表面码存储实验上拟合得到的（精确匹配：`a = 0.0233`、`p* = 0.01004`；并查集：`a = 0.0214`、`p* = 0.00952`），所依据的实测点表格会在发布测试中重新测量。每个估算都连同程序的摘要及其 ε 预算一起封存在资源估算回执族中，`verify` 会重新运行它。逻辑计数 JSON 和 routine 交换格式都可以导入和导出。同一个估算也可以通过 `POST /v1/estimate`、MCP 工具 `estimate_resources`、Studio 的 Estimate 面板以及 `wai_quantum.estimate` 获得。[docs/estimate.md](docs/estimate.md) 解释了每一个数字及其所作的假设。
## 判定：引擎检查到了什么程度

```sh runnable
wai-quantum run prog.qasm --intent ref.qasm              # 是同一条线路吗？判定结果，已封存
wai-quantum run prog.qasm --intent dist.json             # {"000": 0.5, "111": 0.5}：精确分布
wai-quantum repair prog.qasm > fixed.qasm                # 机械性修复，仅作用于被标记的行
```

`engine::verdict` 为关于一个程序的每个答案给出有序阶梯中的一个级别：`refused`、`parsed`、`executed`、`evidence`（已检查，其中一个意图借助随机乘积态或样本的统计检验来检查）或 `proof`（每个意图都经证明检查），并用一行朴素的文字说明各意图是否成立以及所达到的级别。作业通过 `"intent"`（一个精确分布、一个它必须等于的参考程序，或一个它必须制备出其态的参考程序）或 `"verdict": true` 来请求判定，其结果会带上判定并由回执封存；两者都不请求的作业，给出的字节与以往完全相同。`engine::repair` 在诊断所标记的行上进行机械性修复（缺失的 `;`、未声明寄存器的大小、没有目标的测量、为无界的 `while` 给出上界、把非二进角度舍入到所选位数并说明其舍入），拒绝会改动任何其他行的修复提议，并说明哪些需要人来处理。针对程序所提要求的拒绝以作业层代码（`J…`）结尾，与读取器的代码（`Q…`）并列。[docs/verdicts.md](docs/verdicts.md) 介绍了阶梯、字段、意图和规则；[docs/job-refusals.md](docs/job-refusals.md) 列出了各个代码。

## 模型给出的答案：绘制并检查

````text
root = Answer([bell, counts, check, seal])
```qasm bell
OPENQASM 3.0;
qubit[2] q;
bit[2] c;
h q[0];
cx q[0], q[1];
c = measure q;
```
counts = Histogram(@Sample(bell, 1000))
check = Verdict(@Check(bell, {"00": 0.5, "11": 0.5}))
seal = Receipt(@Seal([bell, counts, check]))
````

`engine::answer` 读取答案视图层（[extensions/quantum-answers.md](../extensions/quantum-answers.md)，一个草案扩展）：在一个 OpenQASM 3 程序之上的视图语句，每个视图的数字都绑定到以 `@` 写出的引擎调用，因此答案显示的是引擎算出的数字，而不是模型写下的数字。读取器以流的方式工作（`Stream::push`、`snapshot`、`finish`）：每条语句或已就绪，或在等待尚未到来的语句，或被丢弃并附上其代码；完成后的答案与整段文本读出的答案相同，无论文本如何被切分。语句的问题使用代码 `J100`–`J112`（丢弃、默认或警告）；程序的问题保留读取器的 `Q…`。`answer::eval` 执行这些调用，以作业的形式封存 `@Seal` 所指的内容，并通过重新运行来检查已存答案的回执标记。它的一致性测试集见 [quantum-conformance/answers/](../quantum-conformance/answers/)。

`engine::views` 通过模型上下文协议的交互视图扩展（`io.modelcontextprotocol/ui`，2026-01-26）向智能体宿主提供引擎回答的六种交互视图（线路、带判定的结果、回执、评析、估算的前沿、设备目标的图）：`ui://wai-quantum/*` 资源，一个保持在 1 MiB 以内的自包含页面（`views/`，由 `wai/wai-quantum-views/build.sh` 构建），它用内置的引擎检查所显示内容的回执，以 WebAssembly 运行，或在拒绝 WebAssembly 的策略下以转换成的 JavaScript 运行。两个 MCP 服务器都提供这些视图；对于不绘制视图的宿主，`views::text` 以纯文字给出每个回答。

`engine::telemetry` 是使用者开启后由宿主保存的正确性记录：每个答案的代码、判定级别、修复、使用者的接受或拒绝以及它的回执；`telemetry::corpus` 把其中的失败转换为一致性测试格式的评测语料。

## 乘积基下的 Clifford 线路

一条 Clifford 线路之后再接一层单量子比特门（任意门、任意角度），就超出了稳定子表的能力范围。它的振幅仍然是在一个图态上的求和，`quantum_cutrank` 逐个量子比特地计算这个和。它携带的表有 `2^r` 个条目，其中 `r` 是该态在求和当前所到达的切分处的切秩（cut-rank，即以比特计的纠缠）。因此，代价由沿该顺序最宽的切分决定，而不是由量子比特数决定。`anneal_order` 搜索切分更窄的顺序，`work` 报告各遍计算所触及的条目。

```sh runnable cargo=. timeout=1800
cargo run --release --example cutrank_qasm --features quantum_cutrank -- circuit.qasm cuts
cargo run --release --example cutrank_qasm --features quantum_cutrank -- circuit.qasm order 300000 1 > order.txt
CUTRANK_ORDER=order.txt CUTRANK_PRECISION=single \
  cargo run --release --example cutrank_qasm --features quantum_cutrank -- circuit.qasm sample 1000 7
```

`order` 通过退火寻找工作量最少的顺序，并打印它找到的顺序。搜索的一步把一个量子比特移到另一个位置，只需重新计算这两个位置之间的切分，因此在下文的 70 量子比特线路上做 300 000 步只需几秒钟。`sample` 打印每个精确样本及其 `2^n · p`。

稳定子表只能在相差一个全局相位的意义下确定一个态，图形式也继承了这一点。`PhasedTableau` 携带这个相位：它在稳定子表之外，逐门跟踪支撑集中的一个基态及其精确振幅——`2^{-1/2}` 的某次幂乘以一个八次单位根。Hadamard 门读取 X 部分恰好是那一个量子比特的稳定子，这是对稳定子的一次约化。随后 `ProductMeasured::scale` 把每个振幅调整到线路自身的相位：乘以被跟踪振幅与图形式在同一基态上的振幅之比（`with_last` 配合恒等门），再乘以调用方在降级为 Clifford 门时丢掉的相位。

一条 70 量子比特的图态采样线路，主体是最近邻的 Clifford 门，随后在每个量子比特上使用非 Clifford 基。采用退火得到的顺序时，每个切分都不超过 29 比特。在一台工作站上，一个振幅约需半秒，一个精确样本需 1.1 到 1.5 秒，单精度下最大的表为 4 GiB。不同顺序之间、不同精度之间，振幅的相对吻合程度约为 10⁻⁷。

## 写成稳定子态之和的 Clifford+T 线路

```sh runnable
cat > ct.qasm <<'QASM'
OPENQASM 3.0;
qubit[40] q;
h q;
t q[0];
cx q[0], q[1];
tdg q[1];
cx q[1], q[39];
t q[39];
h q;
QASM
wai-quantum run ct.qasm -a 0000000000000000000000000000000000000000 -o "Z0 Z1"
wai-quantum run ct.qasm --method stabilizer_rank -a 0000000000000000000000000000000000000000 --option terms=2000 --json > ct-sampled.json
```

一个 T 门是两个等权 Clifford 门之和，`T = (e^{iπ/8} I + e^{−iπ/8} S) / (2 cos π/8)`，因此含 `t` 个 T 和 T† 门的线路是 `2^t` 个稳定子态之和。`quantum_stabrank` 在带相位的稳定子表上遍历每个分支，表给出稳定子态每个振幅的精确值（`PhasedTableau::amplitudes`，只需对稳定子做一次约化），并把每一项（`1/√2` 的幂乘以整数个十六分之一圈的相位）作为整数计数，因此无论分支如何在线程间划分，和都相同，最后以双精度求值一次。期望值 `⟨ψ|P|ψ⟩` 是振幅 `⟨0|U†PU|0⟩`，是对两倍 T 门的求和。作业引擎的 `stabilizer_rank` 方法把程序中的 `t`、`tdg`，π/4 奇数倍的 `p`、`rz`、`rx`、`ry`，π/2 奇数倍的 `cp`，以及 `ccz` 和 `ccx` 降为 T 门，每个 Clifford 门按稳定子表的方式降低，并精确保留全局相位；当分支在一个作业的工作量之内时，`auto` 会在稠密态矢量之外为振幅或期望值选用它，因此按 T 门数来选择。

抽样模式（`--option terms=N`，或 `--option epsilon=E` 取达到该界所需的项数，置信度 `--option confidence=C`，默认 0.95）以种子均匀抽取 `N` 个分支，每个来自各自的流：这是态的无偏估计，与态的均方距离为 `(sec²(π/8)^t − 1) / N`。因此每个振幅，以及经由各自求和的每个期望值，以至少 `C` 的概率落在精确值的 `sqrt((sec²(π/8)^t − 1) / (N (1 − C)))` 之内。结果的类别为 `estimate`，每个值旁给出该界及其置信度：由 T 门数、项数和置信度算出，从不依据结果。

两种模式都以稠密态矢量为准检验：最多 7 个量子比特、10 个 T 门的随机 Clifford+T 线路，每个振幅（含相位）误差在 `10⁻¹²` 之内，保真度与 1 相差在 `10⁻¹²` 之内，每个期望值同样如此；抽样界在至少其所述的比例中成立，在整个态上测量。

## 高斯玻色采样

```sh runnable
wai-quantum lab gbs --squeezing 0.9,0.7,0.8,0.6 --eta 0.5 --seed 3            # 精确的点击统计
wai-quantum lab gbs --squeezing 0.9,0.7,0.8,0.6 --eta 0.5 --seed 3 --sample 20000 > s.txt
wai-quantum lab gbs --squeezing 0.9,0.7,0.8,0.6 --eta 0.5 --seed 3 --check s.txt
```

光子采样器的结果概率是其高斯态的 hafnian（光子数探测）或 torontonian（阈值探测）。`quantum_gbs` 精确计算这两者。它们与一个独立实现的结果吻合：
- 概率以及最大 `20 × 20` 的 hafnian 吻合到 10⁻¹²；
- `36 × 36` 时吻合到 10⁻⁷。

`--check` 用该态精确的单模与双模统计来检验一个观测点击模式文件。这些统计对任意模式数都可以计算，该态的每一个采样器都必须复现它们。

该模块还能由任意有损传输矩阵构建高斯态（`GaussianState::through`），每个输入可以是压缩光、热光或"压扁"光（squashed light）。它能由程序重建时域环路干涉仪（`Loops`），并在任意规模下给出总光子数的精确分布，以及精确的一阶和二阶光子数累积量。借助这些，`examples/gbs_loops.rs` 将一台 2022 年时域光子采样器（Madsen 等，Nature 606, 75）公开发布的样本与其精确的基准真值进行比对：

```sh norun=data
wai/tools/quantum-gbs/fetch.sh DATA fig2
cargo run --release --example gbs_loops --features quantum_gbs,quantum_engine,quantum_receipt -- DATA fig2 --receipt fig2.json
```

- **16 个模式，8400 万个样本。** 三到六个光子的每一种模式都有其精确概率，各为一个 hafnian。在每个总光子数之内，样本与之的保真度达 99.66%，距离不超过 6.5%，与论文所述一致。热光、压扁光和相干光在每个总光子数上都偏离更远。
- **72 到 288 个模式。** 样本的平均光子数就是论文公布的数值。精确的基准真值对成对累积量的解释优于任何具有相同模式均值的经典假设。

每次运行都会封存一张回执。`tests/gbs_reference.rs` 将回执与公开发布的数值对照，并逐位重跑最多四个光子的 16 模式比对。

`quantum_gbs_mps` 用 Oh、Liu、Alexeev、Fefferman 和 Jiang（2024）的方法对这样的有损态做经典采样，依据其论文写成：把态拆成一个纯态部分和一个随机位移，纯态部分按模式顺序表示为矩阵乘积态，每个切口保留 `χ` 个 Schmidt 向量，每个样本各抽一次位移。不截断时，其样本就是精确样本。`examples/gbs_sampler.rs` 在同样的实例上运行它，并把它的样本与设备的样本并列评分：

```sh norun=data
cargo run --release --example gbs_sampler --features quantum_gbs,quantum_engine,quantum_receipt -- DATA fig3a sample --chi 512 --shots 1000000 --out s.npy --receipt run.json
cargo run --release --example gbs_sampler --features quantum_gbs,quantum_engine,quantum_receipt -- DATA fig3a score --sampler s.npy --label chi512 --scores 10-16 --receipt score.json
```

在设备自己的样本上，每次运行都与设备同样数量的样本并列比较（全部表格见 `tests/data/gbs/README.md`，表中每个数字和每个结论都由 `tests/gbs_sampler_reference.rs` 对照已封存的回执检查）：
- **`fig3a`，216 个模式，低压缩。** 在 `χ = 512` 下，1,000,000 个样本（在一台 16 核主机上用时 5.5 小时）在总光子数的距离和均值上，以及 2024 年论文三项成对统计量中的两项上，比设备的前 1,000,000 个样本更接近精确的基准真值：相关系数 0.9497 对 0.9364，距离 0.0190 对 0.0205。它们在成对斜率（0.9086 对 0.9191）以及总光子数的二阶和三阶累积量上偏离更远。在 `χ ≤ 256` 时，设备在成对斜率上更好，其原始成对相关系数也更高；扣除采样噪声后，各次运行的成对累积量与精确值的相关性比设备更好（0.995 到 0.996 对 0.977）。
- **`fig4`，216 个模式，高压缩。** 在 `χ = 1,024` 下，100,000 个样本（2.8 小时，6.9 GB 张量）在总光子数的距离和均值上比设备的前 100,000 个样本更接近精确的基准真值，在成对斜率上偏离更远（0.9277 对 0.9427）。其原始成对相关系数和距离也更差，但在 100,000 个样本下这两项主要是采样噪声，而运行的噪声底更高：扣除噪声后，运行的成对累积量与精确值的相关性更好（0.994 对 0.984），距离也不更远（打平）。在 `χ = 256` 和 64 时，它们在总光子数的距离和均值上也偏离更远。
- **`figS15`，288 个模式。** 在 `χ = 1,024` 下，50,000 个样本（1.4 小时，9.3 GB 张量）在总光子数的距离和均值上比设备的前 50,000 个样本更接近精确的基准真值，成对斜率与之打平。按原始值，它们在成对相关系数和距离上偏离更远；扣除采样噪声后两项都打平。在 `χ = 256` 时，它们在总光子数的距离和均值上更接近，扣除噪声后成对相关系数也更好，而在成对斜率和距离上偏离更远。
- **交叉熵**（`fig3a`，10 到 16 个光子）无法把任何一次运行与设备区分开，即使是 `χ = 64` 也不能。

论文的采样器在 `χ = 600` 和 10,000、每个模式一块 GPU 的条件下，以 1,000,000 个样本评分，在每个数据集上的全部三项成对统计量都优于设备。这一点在这里没有达到：在不受采样噪声偏置的成对斜率上，没有一次运行优于设备。

## 扩展点：你自己的方法、编译遍、噪声信道或格式

```sh runnable
wai-quantum components           # 引擎在本机所经过的每个组件，及其身份
```

`engine::registry` 持有引擎规划、运行、编译和转换所经过的每个模拟方法、编译遍、噪声信道和程序格式，各在一个 trait 之后（`Method`、`Pass`、`Channel`、`FrontEnd`）。内置组件通过同样的 trait 注册；嵌入引擎的宿主在自己的进程中用 `Registry::with_builtins()` 和 `register(...)` 在它们旁边注册自己的组件：不从文件或请求加载任何东西，命令行、MCP 服务器和作业服务只运行内置组件。注册的组件在内置组件运行的地方运行（作业的规划与运行、`auto` 的选择、编译的 `passes`、作业的 `noise`、转换或作业的 `source`），引擎检查它给出的东西：方法的结果带有它声明的精度等级，并且不改动引擎写入的成员；编译遍在整条线路上按等价阶梯或距离界与其输入对照；信道的 Kraus 算子在每个作业的取值下检查为完全正且保迹；格式读出的程序必须可读。每个组件的身份是它的名称、版本及其描述符的 BLAKE3 摘要。只由内置组件做出的结果与以往逐字节相同；有注册组件参与的结果带有 `components`，即做出它的每个组件，注册的组件标为 `registered` 和 `certified: false`，并由收据封存。[docs/extension-points.md](docs/extension-points.md) 说明如何编写，附一个注册并运行的信道；[examples/extension_points.rs](examples/extension_points.rs) 有一个方法、一个编译遍、一个信道和一个格式的端到端运行。

## 确定性

模拟是**字节级一致**的：振幅是二进定点数，因此一条线路在每台机器、每个目标上都重构出相同的 `statevector_hash`。近似方法（MPS 截断、稀疏 Pauli 动力学、相量/机器学习层）是*可复现的 f64*：严格遵循 IEEE-754，在每个平台上给定相同的输入和种子时结果完全相同。文档如实地这样描述它们，而不声称它们字节级一致。它们的 `sin`、`cos`、`ln` 和 `atan2` 都在 crate 内部由 `+ − × ÷` 计算得出，因为各平台的数学库在最后一位上存在差异——这种差异足以让其中四个层曾经在原生运行和作为 WASI 组件运行时给出不同的位。`tests/bit_identity.rs` 为每个层固定一个结果，因此任何算术不同的平台都会在那里失败。

一条线路携带其相位所来自的 `Gateset`，其 `circuit_hash` 也会标明它，因此两种门集中的相同门构成的是不同的线路。`Circuit::new` 和 `Circuit::qft` 构建的是 `wai.quantum.circuit2`（`Gateset::V2`，容器魔数 `WQC2`），其表保存着最接近每个 `e^{2πi/2^k}` 的整数。`wai.quantum.circuit`（`Gateset::V1`，`WQC1`）被逐位保留，以便用它产生的每个文件、哈希和回执都能复现；它的表在 `P(k ≥ 8)` 时偏离理想相位，在 `k ≥ 19` 时不施加任何相位。从容器读取的线路采用容器的门集，由另一条线路派生的线路保留原有的门集。

回执如实地区分代价的两半：**工作量**是可移植且精确的（`n_ops · 2^n` 次振幅更新，由验证方重新计算，因此接收方无法夸大它），**能耗**则是经测量并证明的（只有签名者能为它自己的硅片担保）。签名之所以能在不同底层平台之间通行，是因为计算是可复现的——而不是因为两个运行时约定了相互信任。

一个能耗数字只有在说明了其获取方式时，才能与另一个数字比较——是从硅片自身的计数器读取的、来自经过校准的仪器、来自模型，还是一个常数。`quantum_energy::Labelled` 把这一获取类别连同其声明的不确定度一起封存在回执的签名之内，`LabelledQbom` 则对物料清单的每一项做同样的事。不带标签封存的回执，其字节与以往完全相同。`MaybeLabelled` 能解析并验证以任一种形式到来的回执，并在任一种形式下检查作业与其校准之间的关联。标签声明的不确定度必须至少为把数字舍入到整微焦时引入的 `0.5/√3` µJ（≈ 0.289 µJ）：即 `joules_micro × relative_ppm` 至少为 288 676。

## 版本与稳定性

本 crate 中什么是公开的（docs.rs 上记录的每一项，启用全部特性）、版本号作何承诺、支持期限，以及变更在发生之前如何宣布：[版本策略](https://git.transaction.science/Transaction-Science/open-standards/src/branch/main/wai/wai-quantum/VERSIONING.md)。每个已弃用的项目、弃用它的版本及其替代：[弃用页面](https://git.transaction.science/Transaction-Science/open-standards/src/branch/main/wai/wai-quantum/DEPRECATIONS.md)。在 1.0 之前，破坏性变更只随 0.y 的升级而来，CI 会对照最后发布的版本检查这一点。

作业引擎所写的每种文档都有一个带版本的 JSON Schema，作为数据提交在 [`schemas/`](https://git.transaction.science/Transaction-Science/open-standards/src/branch/main/wai/wai-quantum/schemas) 中，并由测试保证与代码所写的内容一致。每个结果都写明产生它的引擎及其遵循的模式（`"engine": {"name": "wai-quantum", "version": …}`、`"schema": "wai.quantum.job-result/1"`），位于其回执所封存的内容之内；在结果开始携带这些字段之前签发的回执，仍像以前一样通过校验。

## 从 0.3 升级

- `Circuit::new` 构建 `Gateset::V2`。要复现或验证用 0.3 制作的产物，请读取其 `WQC1` 文件，或者对在代码中构建的线路设置 `c.gateset = Gateset::V1`。
- `quantum::phase`、`quantum::inv_sqrt2` 和 `quantum::CAPABILITY` 已移除，由 `Gateset::phase`、`Gateset::inv_sqrt2` 和 `Gateset::capability` 取代。
- `to_wqc`、`circuit_hash` 和 `quantum_toolchain::circuit_id` 返回 `Result`。它们只在线路不被其门集允许时失败，因此对已经成功模拟过的线路从不失败。
- `Circuit` 和 `QuantumError` 标注为 `#[non_exhaustive]`，并且 `QuantumError` 有一个 `Contract` 变体和一个 `kind()`。
- `quantum_fabric::certify_lanes` 和 `lanes::random_circuit` 接受一个门集参数。
- `from_wqc` 拒绝 extensions/quantum-sim §8 所列的 circuit/1 载荷；`validate` 拒绝控制比特超过 255 个的门；回执的 `from_json` 拒绝其字段无法容纳的量子比特数或操作数。

## 另外提供

- 命令行工具 `wai-quantum`（[`wai-quantum-cli`](../wai-quantum-cli/README.zh-CN.md) crate）：运行、检查、绘制、编译和估算程序，封存与验证回执，向智能体提供其工具，以及 `wai-quantum lab` 下的研究工具，可原生运行，也可在 `wasmtime` 下运行。
- 一个 WASI-HTTP 组件，把整个栈作为普通的 HTTP 处理程序提供服务。
- 线路课程，从第一条线路一直到资源估算，每道练习都由引擎检查：[`course/`](course/README.md)，可在 Studio 中学习，也可通过 `wai-quantum learn` 学习，提供英文和简体中文版本。
- 浏览器演示：<https://wai.transaction.science/quantum-ide>；关于干涉与学习的课程：<https://wai.transaction.science/quantum-learn>。
- 按主题整理的全部文档：[docs/README.zh-CN.md](docs/README.zh-CN.md)。
- 你自己的量子硬件：[`wai-quantum-qpu`](../wai-quantum-qpu/bring-your-own-quantum.md) 通过[开放提供方协议](../extensions/quantum-providers.md)或内置客户端，在使用者自带的设备、账户或模拟器上运行作业，并在提交之前显示其费用。`engine::provider` 读取这样的作业，把提供方给出的计数与线路的精确分布并列，并加以封存：来自处理器的标注为 `measured`，来自提供方模拟器的标注为 `simulated`，同时写明计数的来源（`counts_source`）以及在提供方处关闭了什么（`execution`）；`engine::catalog` 拒绝指定了提供方的作业，因此无法连接任何提供方的宿主绝不会用它自己的方法来运行这种作业。

## 许可证

Apache-2.0