Files
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

16 KiB
Executable File
Raw Permalink Blame History

官方扩展:ext/quantum 量子计算模拟

状态 Accepted · Q0–Q7 完结 · Q8a/Q8b 完结(ext-quantum-q7.md · ext-quantum-viz-style.md;Q8c 高级态图换肤待做)
日期 2026-08-12(初版)· 2026-08-28(Q7 · Q8 viz)
相关 stdlib-math.md · ext-abi.md · ext-cli.md · ext-web.md · view.md · stdlib-i18n.md · roadmap/ext-quantum.md
安装(目标) marqdo ext add quantum(中英:quantum / 量子)
当前手册 根入口 · 中文入口 · 2026-11-08 优化记录
本文目的 锁定作者面、模拟语义、view 可视化与分期;指导 ABI 插件实现

0. 一句话

ext/quantum 用 GFM 表格 + 类方法 +(可选)$$ 狄拉克/矩阵公式 描述量子门与电路;经典状态向量模拟给出概率与采样。
文档能跑通,公式与电路约定就成立——这是 Marqdo「代码即文档」在量子教学上的最强展示位。

不改 Marqdo 核心语法;热路径只在 ABI 插件;禁止把量子核链进 marqdo 主二进制或在 ext/** 里调用 host_*。


1. 为何做量子扩展(与 math 的关系)

1.1 与 lib/math 的相似处

math quantum
`f` = + $$…$$ → formula 门矩阵 / 态矢量可用 $$ 展示与核对
库函数对公式求值、求导、作图 类方法对电路施门、模拟、画图
view 内嵌 SVG;CLI 可 path= view 内嵌电路图 / 概率条 / 布洛赫;CLI 可落盘
金样例失败 = 文档/公式错 金样例失败 = 门定义或电路叙述错

math 是高中符号与曲线;quantum 是离散希尔伯特空间上的可执行电路文档。两者都是「写出公式 → 跑通 → 证明文档正确」。

1.2 与 math 的刻意分界

做 不做
量子在 ext/quantum,经 plugin.load 不并进 lib/math(避免 stdlib 膨胀)
复数振幅用 {re, im} map(与现有 Value 兼容) 不为量子在核心新增 Value::Complex(可二期)
角度可用 math.pi 等常量 不在 quantum 插件内重写 CAS

1.3 「代码即文档」在这里的作用

典型教学页:

# 贝尔态 |Φ+⟩

对 qubit 0 施 H,再 CNOT(0→1)。理想测量:`00` 与 `11` 各约 1/2。

# main

`steps` =

| 步 | 门 | 比特 |
|----|----|------|
| 1 | H | 0 |
| 2 | CX | 0,1 |

*`qc` = > quantum.circuit qubits=2 steps=`steps` *
*`p` = > `qc`.probabilities *
  • 叙述与表格是给人看的电路说明;
  • 同一文件是可执行程序;
  • gold / CI 断言概率 → 文档与物理约定同步,无需另维护「幻灯片公式」。

2. 硬约束(评审锁定)

  1. 仅 ABI 插件接入:plugins/quantum → libquantum.so;L1 在 ext/quantum/*.mq.md。
  2. ext/quantum/** 禁止 host_*;经 plugin.native_path + plugin.load(同 web/agent)。
  3. 中英分文件:同一包 ext/quantum/ 内英文模块树 + 量子/ 中文树,禁止混排 API(stdlib-i18n.md)。
  4. 不改核心语法;电路表单元格保持字面量;门名/比特下标由类方法解析。
  5. 模拟器有硬上限(默认 ≤ 12 qubits);超限报错,不静默截断。
  6. view 必须有专项展示(结构卡 + 执行区 SVG),禁止只 dump JSON。

3. 布局与安装

Skill / tools 树(012 试点;契约 ext-index-skill-tools.md,范式 ext-skill-tools-paradigm.md):

ext/quantum/                      # 一个扩展包(同 web/ai:中英同目录)
  index.mq.md                     # EN 根 SKILL
  circuit/ · gate/ · simulate/ · state/ · density/ · viz/
  _capability/index.mq.md
  量子/                           # ZH 根与模块(同等 skill 标准)
    索引.mq.md
    电路/ · 门/ · 模拟/ · 态/ · 密度/ · 可视化/ · 能力/
plugins/quantum/
  Cargo.toml
  src/lib.rs                      # ABI v2
examples/quantum-bell/
tests/ext/quantum-*.mq.md

安装产物(~/.marqdo/ext 或 MARQDO_EXT,不是仓库 ext/ 源码树):

quantum/...
native/libquantum.so
quantum.plugin                    # 绝对路径提示;勿提交
cargo build -p marqdo_plugin_quantum
marqdo ext add quantum

导入:

---
import:
  quantum: ext/quantum/circuit/index.mq.md
---

或中文:导入 量子:ext/quantum/量子/电路/索引.mq.md(根 skill:ext/quantum/量子/索引.mq.md)。


4. 核心模型

4.1 运行时句柄(JSON map + _type)

_type(英) 中文类名 含义
quantum_gate 量子门 具名门或自定义酉矩阵
quantum_circuit 量子电路 n qubits + 有序门列表
quantum_state 量子态 状态向量(振幅列表)
quantum_result 量子结果 概率 / 采样 / 可选坍缩态
quantum_svg (产物) 带 svg 字段的可视化结果

插件返回 map;Marqdo 对象系统挂 _type 后可用方法链。

4.2 状态表示

  • 纯态状态向量:长度 2^n,每元 {re, im}(f64)。
  • 默认初态:|0…0⟩(仅 index 0 振幅为 1)。
  • 门作用后可选重归一化(阈值误差阈值,默认开)。

4.3 公式面(对齐 math 精神,不抢 math 实现)

允许用 `G` = + $$…$$ 书写门矩阵(可执行,见 ext-quantum-custom-gate.md):

`H_matrix` =
$$
\frac{1}{\sqrt{2}}\begin{pmatrix}1&1\\1&-1\end{pmatrix}
$$

*`U` = > quantum.gate matrix=`H_matrix` *
*`qc` = > `qc`.apply gate=`U` qubits=0 *
*`ok` = > `H`.matches_matrix matrix=`H_matrix` *
  • v1:具名门以插件内置酉矩阵为准;matrix= 可从嵌套 list / $$ 矩阵围栏构造自定义门。
  • $$ 含 [[…]] 或 \begin{pmatrix} 时解析期求值为数值 list;标量公式仍为 Formula。
  • matches_matrix 仍可用于核对。

5. 作者面 API(锁定草图)

5.1 英文 ext/quantum/circuit/index.mq.md

# gate
    + `name`=None          # H X Y Z S T I CX CZ SWAP …
    + `theta`=None         # Rx/Ry/Rz

## matrix                 # → 振幅表 / 嵌套 list(文档与调试)
## draw                   # → quantum_svg(`kind=gate|matrix` 符号 / 热力图)
## matches_matrix
    + `matrix`
    + `tol`=1e-9

# circuit
    + `qubits`
    + `steps`=None         # 可选:GFM 门序列表

## h / x / y / z / s / t
    + `qubit`
## rx / ry / rz
    + `qubit`
    + `theta`
## cx / cz
    + `control`
    + `target`
## swap
    + `a`
    + `b`
## barrier                 # 仅可视化分隔,不改变态
## measure                 # 标记测量(模拟时按计算基)
    + `qubits`=None        # 默认全部
## append                  # 追加另一电路或门
    + `op`
## simulate                # → quantum_state(不坍缩)
## probabilities           # → map 基矢标签 → 概率
## run
    + `shots`=1024
    + `seed`=None          # → quantum_result(计数直方图)
## draw
    + `path`=None          # SVG;无 path 时仍可进 view 产物
    + `kind`=circuit       # circuit|probs|bloch|hinton|…(见 Q7)
    + `theme`=dark         # dark|light|bw(Q8;电路/概率/布洛赫)
## state                   # 当前缓存态(若已 simulate)

门方法返回更新后的 circuit 句柄(与 web compose_* 相同: `qc` = > `qc`.h qubit=0 *)。

5.2 中文 ext/quantum/量子/(根 索引.mq.md)

英文 中文
gate 门
circuit 电路
h 哈达玛
x / y / z 泡利X / 泡利Y / 泡利Z
cx 控非
cz 控相
rx/ry/rz 绕X/绕Y/绕Z
simulate 模拟
probabilities 概率
run 运行
draw 绘图
kind 种类
theme 主题
measure 测量
qubits 比特数
steps 步骤
shots / seed 次数 / 种子

插件 FFI 名稳定英文:quantum_circuit_new、quantum_h、quantum_cx、quantum_simulate、quantum_draw_circuit…

5.3 电路表(文档优先写法)

`steps` =

| 步 | 门 | 比特 | 参数 |
|----|----|------|------|
| 1 | H | 0 | |
| 2 | CX | 0,1 | |
| 3 | RZ | 1 | pi/4 |

列名中英兼容:步|step、门|gate、比特|qubits|qubit、参数|theta|params。

*qc = > quantum.circuit qubits=2 steps=steps *` 与方法链等价;表更适合「整页即电路说明书」。

5.4 返回值形态

方法 返回
simulate {_type, qubits, dim, amplitudes:[{re,im},…]}
probabilities { "00": 0.5, "11": 0.5 }(标签为小端比特串,文档写死)
run { counts: {…}, shots, seed }
draw {_type: quantum_svg, kind: circuit|gate|probs|bloch, svg: "…" }

6. 模拟器语义

项 锁定
模型 封闭系统纯态;计算基测量
默认上限 12 qubits;MARQDO_QUANTUM_MAX_QUBITS 可下调(不可暗中上调超过编译期硬顶,硬顶建议 16)
超限 错误信息含当前 n 与上限
simulate / probabilities 无 RNG、确定性
run 多项式采样;seed= 可复现(金样必用)
数值 f64;门后 ‖ψ‖ 偏离阈值则重归一化并可选 warning 字段

实现:插件内 Kronecker / 按比特作用稀疏更新;可用 nalgebra 或手写,不捆绑外部量子云。


7. view 模式支持(专项)

对齐 view.md 与 math 作图:Structure / Execution / Source 共用渲染;禁止第二套皮肤。

7.1 Structure(结构区)

源形态 展示
`qc` = + 电路表 circuit-card:比特数、门序列时间线(文本/紧凑 SVG)
`G` = + $$ 门矩阵 沿用 formula-card(KaTeX);徽章可标 gate(若绑定来自 quantum.gate)
方法链语句 普通调用行;不强制每步展开

7.2 Execution(执行区)

产物 展示
quantum_svg 与 math plots 同级:内嵌 SVG(电路轨线图 / 概率直方图 / 单比特布洛赫)
probabilities / counts 表格 + 可选自动条形 SVG
quantum_state 默认折叠振幅表;小 n(≤3)可并排显示基矢

7.3 产物如何进入 view(实现锁定)

插件不能直接碰核心 HostContext.plots。采用其一(实现时二选一,优先 A):

方案 做法
A(推荐) ABI host_query("record_plot"):参数 JSON {svg};写入与 math 相同的 plots 列表(ext-abi.md allowlist 增补一条)
B 仅返回 quantum_svg;view 在渲染执行值时识别 _type/svg 字段并内嵌(不扩 ABI)

CLI:draw path=bell.svg 写沙箱文件;无 path 时不把整段 SVG 灌 stdout(同 math §5)。

7.4 可视化内容(v1 必须 / 可后)

图 v1 说明
电路轨线(qubit 线 + 门盒 + 控点) 必须 circuit.draw;Q8 默认 theme=dark(标签芯片 + 门族分色)
测量概率条形图 必须 probabilities / run 后可 draw kind=probs
单比特布洛赫球(SVG) 应有 仅 n=1 或指定 qubit 约化(纯态投影)
门矩阵热力图 必须 gate.draw kind=matrix(幅值热图 + 小数标注)
高级态图(hinton/city/…) Q7 见 ext-quantum-q7.md;换肤见 Q8c
交互拖拽编辑电路 不做 静态文档足够

视觉:内联 SVG 色与字体栈;无外链字体/CDN(同 view 硬规则)。主题令牌与布局:ext-quantum-viz-style.md。view 对 svg[data-theme=dark] 使用深色图框。


8. 分期(开发计划)

Q0  脚手架:CATALOG + plugins/quantum Hello + L1 ensure_plugin
Q1  态向量 + I/X/H/CX + simulate/probabilities;贝尔态 gold
Q2  Y/Z/S/T/Rx/Ry/Rz/CZ/SWAP + run(seed) + 中英 API 对齐
Q3  电路表 steps= + draw 电路 SVG + view record_plot/识别;examples/
Q5  教学噪声 + barrier/measure/append/state — 见 [ext-quantum-q5.md](ext-quantum-q5.md)  ← **done(最小)**
阶段 交付物 验收
Q0 marqdo_plugin_quantum 注册 quantum_ping;L1 加载失败可读 ext add quantum 路径通
Q1 贝尔态 probabilities ≈ 0.5/0.5 tests/ext/quantum-bell-smoke.mq.md
Q2 旋转门 + run seed= 计数稳定 中英双金样
Q3 steps= 表;draw SVG 在 view HTML 含 <svg 与 math-plot 同级断言
Q4 概率图 + 布洛赫;matches_matrix;用户文档页 quantum-draw-smoke / quantum-gate-matrix-smoke;view output 可浏览示例
Q5 noise 轨迹;barrier/measure/append/state quantum-noise-smoke / quantum-author-api-smoke
Q6 公式/matrix= 自定义门 ext-quantum-custom-gate.md
Q7 密度矩阵线性代数 + Hinton/City/QSphere 等 SVG + 纠缠示例 ext-quantum-q7.md ✅
Q8 可视化美学:theme + 标签 gutter + 门族分色 ext-quantum-viz-style.md · Q8a/Q8b ✅ · Q8c 待做

实现路线图跟踪见 roadmap/ext-quantum.md。


9. 规范示例(目标作者体验)

---
title: Bell state
import:
  quantum: ext/quantum/circuit/index.mq.md
---

# Bell |Φ+⟩

H on qubit 0, then CNOT. Expect |00⟩ and |11⟩ each with probability 1/2.

# main

`steps` =

| step | gate | qubits |
|------|------|--------|
| 1 | H | 0 |
| 2 | CX | 0,1 |

*`qc` = > quantum.circuit qubits=2 steps=`steps` *
*`p` = > `qc`.probabilities *
*`svg` = > `qc`.draw *

> print text=`p`

中文面对称:量子.电路、哈达玛、控非、概率、绘图。


10. 刻意不做(本 Accepted 范围)

  • 真机 / 云后端(IBM、Braket…)
  • 开放系统、完整噪声模型(可 Q5+)
  • 符号电路编译优化器
  • 交互式电路编辑器
  • 把量子并入 lib/math 或核心 opcode
  • 无上限比特的「生产级」模拟

11. 开放点(已收敛 / 剩余)

议题 结论
对象面 vs 自由函数 主推对象/方法链;自由函数不平行提供
电路表 v1 纳入(Q3),与方法链等价
振幅过大 v1 全进 Value;n≤12 可接受;超限已挡
view 产物 优先 host_query("record_plot")
与 web 不依赖 web 做可视化;SVG 自绘

12. 评审清单

  1. ABI-only + 中英分文件是否认可?
  2. 默认 12 qubits 上限是否合适?
  3. 电路表列设计(步/门/比特/参数)是否够用?
  4. view:电路轨线 + 概率条为 v1 必须,是否同意?
  5. $$ 矩阵核对放 Q4,是否同意先表驱动?

评审通过后:本文冻结为 Accepted → 按 §8 从 Q0 实现。


13. 一句话

表格写出电路,类方法模拟与绘图;跑通金样即证明文档中的量子公式与步骤成立——math 管曲线,quantum 管希尔伯特空间上的可执行说明书。