diff --git a/doc/design/ext-cli.md b/doc/design/ext-cli.md index 0f27118..4a4b0a8 100644 --- a/doc/design/ext-cli.md +++ b/doc/design/ext-cli.md @@ -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: diff --git a/doc/design/ext-quantum.md b/doc/design/ext-quantum.md new file mode 100644 index 0000000..5c5a13c --- /dev/null +++ b/doc/design/ext-quantum.md @@ -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 含 ` 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 管希尔伯特空间上的可执行说明书。** diff --git a/doc/roadmap/ext-quantum.md b/doc/roadmap/ext-quantum.md index d0e7cd0..42f69c2 100644 --- a/doc/roadmap/ext-quantum.md +++ b/doc/roadmap/ext-quantum.md @@ -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 |