Document ext/quantum design and implementation roadmap.
Lock author API, simulator bounds, view SVG plan, and Q0–Q5 phases before coding the ABI plugin. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
1 parent
e4be0b0492
commit
25b6b86c26
3 files changed
+435
-182
No files matched your search
@@ -50,7 +50,7 @@ Future optional ext domains get their own subdirs (e.g. `ext/web/`, `ext/quantum
|
||||
| `llm` | `ai/llm.mq.md`, `ai/大模型.mq.md` |
|
||||
| `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md`, **`native/libagent.so`** (or `.dylib`) |
|
||||
| `web` | `web/web.mq.md`, `web/网页.mq.md`, **`native/libweb.so`** — 见 [ext-web.md](ext-web.md) · [roadmap](../roadmap/ext-web.md) |
|
||||
| `quantum`(规划) | `quantum/quantum.mq.md`, `quantum/量子.mq.md`, **`native/libquantum.so`** — 见 [ext-quantum.md](../roadmap/ext-quantum.md) |
|
||||
| `quantum`(规划) | `quantum/quantum.mq.md`, `quantum/量子.mq.md`, **`native/libquantum.so`** — 见 [ext-quantum.md](ext-quantum.md) · [roadmap](../roadmap/ext-quantum.md) |
|
||||
|
||||
`add agent` copies the built native plugin into `MARQDO_EXT/native/`. Build it first:
|
||||
|
||||
|
||||
@@ -0,0 +1,402 @@
|
||||
# 官方扩展:`ext/quantum` 量子计算模拟
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 待实现**(作者面与分期已锁定;实现未开工) |
|
||||
| 日期 | 2026-08-12 |
|
||||
| 相关 | [stdlib-math.md](stdlib-math.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [ext-web.md](ext-web.md) · [view.md](view.md) · [stdlib-i18n.md](stdlib-i18n.md) · [roadmap/ext-quantum.md](../roadmap/ext-quantum.md) |
|
||||
| 安装(目标) | `marqdo ext add quantum`(中英:`quantum` / `量子`) |
|
||||
| 本文目的 | 锁定**作者面**、**模拟语义**、**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 「代码即文档」在这里的作用
|
||||
|
||||
典型教学页:
|
||||
|
||||
```markdown
|
||||
# 贝尔态 |Φ+⟩
|
||||
|
||||
对 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. **中英分文件**:`quantum.mq.md` / `量子.mq.md`,**禁止**混排 API([stdlib-i18n.md](stdlib-i18n.md))。
|
||||
4. **不改核心语法**;电路表单元格保持字面量;门名/比特下标由类方法解析。
|
||||
5. **模拟器有硬上限**(默认 ≤ 12 qubits);超限报错,不静默截断。
|
||||
6. **view 必须有专项展示**(结构卡 + 执行区 SVG),禁止只 dump JSON。
|
||||
|
||||
---
|
||||
|
||||
## 3. 布局与安装
|
||||
|
||||
```text
|
||||
ext/quantum/
|
||||
quantum.mq.md # 英文类 API
|
||||
量子.mq.md # 中文类 API
|
||||
plugins/quantum/
|
||||
Cargo.toml
|
||||
src/lib.rs # ABI v2:线性代数 / 施门 / 画 SVG
|
||||
examples/quantum-bell/ # 规范示例(Q3)
|
||||
tests/ext/quantum-*.mq.md
|
||||
```
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_quantum
|
||||
marqdo ext add quantum
|
||||
```
|
||||
|
||||
导入:
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/quantum/quantum.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
或中文:`> 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` = `` + `$$…$$` 书写门矩阵或态(**展示 + 教学核对**):
|
||||
|
||||
````markdown
|
||||
`H_matrix` =
|
||||
$$
|
||||
\frac{1}{\sqrt{2}}\begin{pmatrix}1&1\\1&-1\end{pmatrix}
|
||||
$$
|
||||
|
||||
*`H` = > quantum.gate name=H *
|
||||
*`ok` = > `H`.matches_matrix matrix=`H_matrix` *
|
||||
````
|
||||
|
||||
- v1:**具名门**以插件内置酉矩阵为准;`matches_matrix` 为可选数值核对(容差)。
|
||||
- 叙述区无名 `$$` 仍只是注释(同 [stdlib-math.md](stdlib-math.md) §2.4)。
|
||||
- **不**要求核心 `Value::Formula` 理解量子;矩阵核对可走「公式 ASCII/LaTeX → 插件解析子集」或作者显式 `matrix=` 表。
|
||||
|
||||
**v1 优先路径:** 电路用**表 + 方法**;`$$` 作文档展示;矩阵核对可放 **Q3**。
|
||||
|
||||
---
|
||||
|
||||
## 5. 作者面 API(锁定草图)
|
||||
|
||||
### 5.1 英文 `ext/quantum/quantum.mq.md`
|
||||
|
||||
```markdown
|
||||
# gate
|
||||
+ `name`=None # H X Y Z S T I CX CZ SWAP …
|
||||
+ `theta`=None # Rx/Ry/Rz
|
||||
|
||||
## matrix # → 振幅表 / 嵌套 list(文档与调试)
|
||||
## draw # → quantum_svg(单门符号)
|
||||
## 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 产物
|
||||
## 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` | `绘图` |
|
||||
| `measure` | `测量` |
|
||||
| `qubits` | `比特数` |
|
||||
| `steps` | `步骤` |
|
||||
| `shots` / `seed` | `次数` / `种子` |
|
||||
|
||||
插件 FFI 名稳定英文:`quantum_circuit_new`、`quantum_h`、`quantum_cx`、`quantum_simulate`、`quantum_draw_circuit`…
|
||||
|
||||
### 5.3 电路表(文档优先写法)
|
||||
|
||||
```markdown
|
||||
`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](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](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` |
|
||||
| 测量概率条形图 | **必须** | `probabilities` / `run` 后可 `draw kind=probs` |
|
||||
| 单比特布洛赫球(SVG) | 应有 | 仅 n=1 或指定 qubit 约化(纯态投影) |
|
||||
| 门矩阵热力图 | 可后 | Q4 |
|
||||
| 交互拖拽编辑电路 | **不做** | 静态文档足够 |
|
||||
|
||||
视觉:内联 CSS;**无外链**字体/CDN(同 view 硬规则)。
|
||||
|
||||
---
|
||||
|
||||
## 8. 分期(开发计划)
|
||||
|
||||
```text
|
||||
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/
|
||||
Q4 概率/布洛赫图;matches_matrix;文档站 public/features
|
||||
Q5 (可选,另文)噪声/密度矩阵;>12 qubits 张量网络——不挡 Accepted
|
||||
```
|
||||
|
||||
| 阶段 | 交付物 | 验收 |
|
||||
|------|--------|------|
|
||||
| **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** | 概率图 + 布洛赫;用户文档页 | `view output` 可浏览示例 |
|
||||
|
||||
实现路线图跟踪见 [roadmap/ext-quantum.md](../roadmap/ext-quantum.md)。
|
||||
|
||||
---
|
||||
|
||||
## 9. 规范示例(目标作者体验)
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: Bell state
|
||||
> ext/quantum/quantum.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 管希尔伯特空间上的可执行说明书。**
|
||||
+32
-181
@@ -1,203 +1,54 @@
|
||||
# 官方扩展:量子计算模拟(未来规划)
|
||||
# 官方扩展:`ext/quantum` 实现路线图
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **规划 / 未开工** |
|
||||
| 日期 | 2026-08-09 |
|
||||
| 相关 | [ext-cli.md](../design/ext-cli.md) · [ext-abi.md](../design/ext-abi.md) · [stdlib-math.md](../design/stdlib-math.md) · [ext-web.md](ext-web.md) |
|
||||
| 安装草案 | `marqdo ext add quantum`(中英面:`quantum` / `量子`) |
|
||||
| 状态 | **Q0 未开工**(设计已 Accepted) |
|
||||
| 日期 | 2026-08-12 |
|
||||
| **锁定设计** | [design/ext-quantum.md](../design/ext-quantum.md) |
|
||||
| 相关 | [ext-cli.md](../design/ext-cli.md) · [ext-abi.md](../design/ext-abi.md) · [stdlib-math.md](../design/stdlib-math.md) · [view.md](../design/view.md) |
|
||||
| 安装 | `marqdo ext add quantum`(`quantum` / `量子`) |
|
||||
|
||||
本文只跟踪**实现阶段**。作者面、模拟语义、view 可视化、分期以设计文为准。
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
## 1. 目标回顾(一句)
|
||||
|
||||
为教学、算法演示与智能体「可运行的量子电路文档」提供官方扩展:
|
||||
|
||||
- 在 `.mq.md` 里**声明量子比特与电路**(可读即文档)
|
||||
- 支持**基础量子门**与常见电路写法
|
||||
- **经典模拟**量子态在电路下的演化,输出状态向量 / 概率 /(可选)测量采样
|
||||
- 重计算进 **ABI 插件**;安装走现有 `marqdo ext` 惯例
|
||||
|
||||
不宣称替代专业量子 SDK(Qiskit / Cirq 等),定位:**Marqdo 文档内可执行的最小量子模拟层**。
|
||||
**可运行的量子电路文档**:表声明门序列 → ABI 模拟概率/采样 → view 内嵌电路/概率 SVG;文档跑通即公式约定成立。
|
||||
|
||||
---
|
||||
|
||||
## 2. 范围
|
||||
## 2. 落地阶段
|
||||
|
||||
### 2.1 在范围内
|
||||
| 阶段 | 内容 | 状态 |
|
||||
|------|------|------|
|
||||
| **Q0** | CATALOG + `plugins/quantum` ping + L1 `ensure_plugin` | pending |
|
||||
| **Q1** | 态向量;I/X/H/CX;`simulate` / `probabilities`;贝尔态 gold | pending |
|
||||
| **Q2** | Y/Z/S/T/R\* /CZ/SWAP;`run seed=`;中英 API | pending |
|
||||
| **Q3** | `steps=` 电路表;`draw` 轨线 SVG;view `record_plot` 或值识别 | pending |
|
||||
| **Q4** | 概率条 / 布洛赫;`matches_matrix`;examples + 用户文档 | pending |
|
||||
| **Q5** | (可选)噪声 / 更大 n —— 另文 | pending |
|
||||
|
||||
| 能力 | 说明 |
|
||||
|------|------|
|
||||
| 状态表示 | 纯态状态向量(复数振幅);qubit 数有明确上限(见 §6) |
|
||||
| 基础单比特门 | 至少:`I` `X` `Y` `Z` `H` `S` `T` 及 `Rx/Ry/Rz(θ)` |
|
||||
| 基础多比特门 | 至少:`CNOT`(CX)、`CZ`;可选 `SWAP`、Toffoli(可用分解) |
|
||||
| 电路构建 | 按序追加门;支持指定目标/控制比特下标 |
|
||||
| 模拟 | 初态(默认 \|0…0⟩)→ 应用电路 → 返回状态或测量概率 |
|
||||
| 测量 | 计算基概率;可选按概率采样坍缩(经典 RNG) |
|
||||
| L1 API | `ext/quantum/quantum.mq.md` · `ext/quantum/量子.mq.md` |
|
||||
| **ABI 插件** | `plugins/quantum`:线性代数与门作用热路径 |
|
||||
| **CLI 安装** | `marqdo ext add quantum` / `remove` / `list` |
|
||||
|
||||
### 2.2 非目标(本规划)
|
||||
|
||||
- 真机 / 云量子后端调度
|
||||
- 开放系统密度矩阵、噪声模型(可列二期)
|
||||
- 符号电路优化编译器
|
||||
- 把量子核链进 `marqdo` 主二进制
|
||||
- 无上限比特数的「生产级」模拟器
|
||||
验收金样(目标):`tests/ext/quantum-bell-smoke.mq.md`、`quantum-draw-smoke.mq.md`、中文对称样例。
|
||||
|
||||
---
|
||||
|
||||
## 3. 布局与安装(对齐惯例)
|
||||
## 3. 已收敛的原开放点
|
||||
|
||||
```text
|
||||
ext/
|
||||
quantum/
|
||||
quantum.mq.md
|
||||
量子.mq.md
|
||||
examples/ # 可选:贝尔态、量子传送草稿
|
||||
plugins/
|
||||
quantum/
|
||||
Cargo.toml
|
||||
src/lib.rs # ABI v2
|
||||
```
|
||||
|
||||
```text
|
||||
marqdo ext add quantum
|
||||
marqdo ext remove quantum
|
||||
```
|
||||
|
||||
安装:复制 L1 源 + `native/libquantum.so`(等)到 `MARQDO_EXT`,与 [ext-cli.md](../design/ext-cli.md) / agent 插件一致。
|
||||
|
||||
导入:
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/quantum/quantum.mq.md
|
||||
---
|
||||
```
|
||||
| 原疑问 | 锁定结论(见设计文) |
|
||||
|--------|----------------------|
|
||||
| 并进 math? | **否**,独立 `ext/quantum` |
|
||||
| 电路表 | **要做**(Q3),与方法链等价 |
|
||||
| view 图 | 自绘 SVG;优先 `host_query("record_plot")`;不依赖 web |
|
||||
| 自由函数面 | **不**与对象面并行 |
|
||||
|
||||
---
|
||||
|
||||
## 4. API 外形(草案)
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/quantum/quantum.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`qc` = > quantum.circuit qubits=2 *
|
||||
> `qc`.h qubit=0
|
||||
> `qc`.cx control=0 target=1
|
||||
*`state` = > `qc`.simulate *
|
||||
*`probs` = > `qc`.probabilities *
|
||||
> print text=`probs`
|
||||
```
|
||||
|
||||
中文面示例:
|
||||
|
||||
```markdown
|
||||
*`电路` = > 量子.电路 比特数=2 *
|
||||
> `电路`.哈达玛 比特=0
|
||||
> `电路`.控非 控制=0 目标=1
|
||||
*`概率` = > `电路`.概率 *
|
||||
```
|
||||
|
||||
门命名中英对照表在落地时写入 L1 文档头;插件注册名建议稳定英文(`quantum_h`、`quantum_cx`、`quantum_simulate`)。
|
||||
|
||||
### 4.1 返回值形态
|
||||
|
||||
| 方法 | 建议返回 |
|
||||
|------|----------|
|
||||
| `simulate` | map:`qubits`、`amplitudes`(复数列表或 `{re,im}` 对)、可选 `dim` |
|
||||
| `probabilities` | 列表或 map:基态标签 → 概率(如 `"00"` → 0.5) |
|
||||
| `measure` | 采样得到的比特串 +(可选)坍缩后状态 |
|
||||
|
||||
复数如何进 Marqdo `Value`:优先 `{re, im}` map 列表,避免过早引入原生复数类型(若语言日后有复数,再收紧)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 电路即文档
|
||||
|
||||
鼓励把电路写在可读段落旁:
|
||||
|
||||
```markdown
|
||||
# 贝尔态
|
||||
|
||||
制备 `|Φ+⟩`:H 后 CNOT。
|
||||
|
||||
# main
|
||||
|
||||
*`qc` = > quantum.circuit qubits=2 *
|
||||
…
|
||||
```
|
||||
|
||||
可选:GFM 表描述门序列(与 [tables-maps-footnotes.md](tables-maps-footnotes.md) 横表字典对齐,**不阻塞**本扩展 v1——v1 以方法链为准)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 模拟器约束
|
||||
|
||||
| 项 | 提案 |
|
||||
|----|------|
|
||||
| 默认上限 | **≤ 12 qubits**(状态 2^12;可 env `MARQDO_QUANTUM_MAX_QUBITS` 下调) |
|
||||
| 超限 | 明确错误,不静默截断 |
|
||||
| 数值 | `f64` 振幅;门后可选重归一化阈值 |
|
||||
| 确定性 | `simulate` / `probabilities` 无 RNG;`measure` 可传 `seed=` |
|
||||
|
||||
实现放在插件内(`nalgebra` / 手写 Kronecker + 稀疏门作用均可);L1 只做参数校验与结果包装。
|
||||
|
||||
---
|
||||
|
||||
## 7. ABI 边界
|
||||
|
||||
| 插件 | `.mq.md` |
|
||||
|------|----------|
|
||||
| 分配/更新状态向量、施门、算概率 | 电路编排、打印、教学叙述 |
|
||||
| 参数化旋转门 | `theta=` 从 Marqdo 传入 |
|
||||
|
||||
遵守:
|
||||
|
||||
- ABI v2 + JSON([ext-abi.md](../design/ext-abi.md))
|
||||
- `ext/quantum/**` **禁止** `host_*`;经 `plugin.load`
|
||||
- 与 [module-namespace.md](../design/module-namespace.md) / agent 硬规则一致:域逻辑不进核心 `HostFn`
|
||||
|
||||
---
|
||||
|
||||
## 8. 推荐落地顺序
|
||||
|
||||
```text
|
||||
Q0 ext-cli 登记 quantum;插件注册 quantum_sim_version;L1 加载失败可读
|
||||
Q1 n qubits 全零态 + H/X/CNOT + simulate/probabilities;金样贝尔态
|
||||
Q2 Y/Z/S/T/Rz + measure seed=;中英 API
|
||||
Q3 examples/ + catalog/OKF 可选 Module 页;文档
|
||||
Q4 (可选)电路表语法糖;密度矩阵二期另文
|
||||
```
|
||||
|
||||
验收:
|
||||
|
||||
1. `marqdo ext add quantum` 后可跑贝尔态金样,概率约 `00/11 ≈ 0.5`。
|
||||
2. 无原生插件时错误指引 `ext add` / 构建 `marqdo_plugin_quantum`。
|
||||
3. 超比特上限失败信息含上限值。
|
||||
4. 双端(若金样走 tree)稳定;不强制 bytecode 同步若无量子 opcode(电路走插件即可)。
|
||||
|
||||
---
|
||||
|
||||
## 9. 开放点
|
||||
|
||||
1. 是否提供无对象的自由函数面(`## h circuit=…`)与对象面并行。
|
||||
2. 振幅列表过大时是否写临时文件而非全进 Value。
|
||||
3. 与 [stdlib-math.md](../design/stdlib-math.md) 复用:仅角度常数,不把量子并进 math 库。
|
||||
4. 教学是否依赖 [ext-web.md](ext-web.md) 做布洛赫球可视化(可选、非阻塞)。
|
||||
|
||||
---
|
||||
|
||||
## 10. 与其它规划的关系
|
||||
## 4. 与其它文档
|
||||
|
||||
| 文档 | 关系 |
|
||||
|------|------|
|
||||
| [ext-web.md](ext-web.md) | 同属「新域官方 ext + ABI + CLI」模板;可互为示例 |
|
||||
| [object-inheritance.md](object-inheritance.md) | 可选:`# 变分电路 = > quantum.circuit`(不阻塞 Q1) |
|
||||
| [agent-streaming.md](agent-streaming.md) | 无直接依赖;智能体可 `plan` 生成电路文件再 simulate |
|
||||
| [design/ext-quantum.md](../design/ext-quantum.md) | **真理** |
|
||||
| [stdlib-math.md](../design/stdlib-math.md) | 公式/作图精神对照;实现分离 |
|
||||
| [ext-web.md](../design/ext-web.md) | 同属官方 ext + ABI + `ext add` 模板 |
|
||||
| [view.md](../design/view.md) | 结构卡 + Execution 内嵌 SVG |
|
||||
Reference in new issue
Block a user