Files
marqdo/doc/design/ext-quantum-q7.md
T
cflmyandCursor b6cceab218 docs(linalg): design formula-first linear algebra extension
Add research, design, and roadmap for ext/linalg; cross-link from
stdlib-math and quantum Q7 so classic MatExpr stays out of lib/math.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 10:53:56 +08:00

9.3 KiB
Raw Blame History

ext/quantum Q7 — 高阶线性代数 + 高级可视化

状态 Accepted · Q7a/Q7b/Q7c 已落地
日期 2026-08-28
父设计 ext-quantum.md
路线图 roadmap/ext-quantum.md
对照 IBM Quantum state plots · QuTiP visualization · Cirq plot_density_matrix

0. 一句话

在 Q0–Q6 态向量教学模拟之上,补齐两块「教科书级」能力:

  1. 高阶线性代数(密度矩阵、Kronecker、部分迹、Hermitian 谱分解、Schmidt / SVD、Pauli 期望值)
  2. 高级静态 SVG 展示(Hinton / City / Pauli 向量 / QSphere 风格 / 多比特布洛赫)

全部经 plugins/quantum ABI;ext/quantum/** 只做 L1 表包装,禁止 host_*。


1. 动机与业界对照(联网调研 2026-08)

1.1 为何现在做

已有(Q0–Q6) 缺口
纯态态向量 + 施门 + 采样 混态 / 约化子系统无法一等公民表达
bloch 单比特约化 纠缠与多比特关联只能猜
gate.draw kind=matrix 热力图 无密度矩阵 / Pauli 分解 / 球面振幅布局
内部 apply_unitary / Kronecker 未暴露为作者面 API

教学文档写「贝尔态纠缠」时,读者需要:约化密度矩阵 → 纯度 < 1 → Schmidt 系数 → Hinton/QSphere 图。这些正是 Qiskit / QuTiP / Cirq 的标配。

1.2 可视化对标(只取可静态 SVG 落地的子集)

业界 含义 Q7 决策
Qiskit plot_state_hinton 元大小表示幅值,色表示正负 ✅ kind=hinton
Qiskit plot_state_city Re/Im 三维条 ✅ 2.5D 等轴测 SVG(非 Matplotlib)
Qiskit plot_state_paulivec Pauli 串期望值柱 ✅ kind=paulivec
Qiskit plot_state_qsphere 振幅点在球面上,色=相位 ✅ kind=qsphere(教学投影)
Qiskit plot_bloch_multivector 每比特一球 ✅ kind=multibloch
Cirq density Argand 格 每元幅值圆 + 相位针 ✅ 并入 kind=density(默认)
QuTiP Wigner / 过程层析 连续相空间 / χ 矩阵 ❌ 本切片不做

1.3 线性代数对标(经典模拟侧,非量子算法)

能力 教学用途 Q7
ρ = |ψ⟩⟨ψ| 纯→密度 ✅
Kronecker / 张量积 复合系统 ✅
部分迹 约化、纠缠证据 ✅
Hermitian 本征分解 谱 / 测量可观测量 ✅(小维)
Schmidt(纯态二分)= 整形 SVD 纠缠熵入口 ✅
Pauli 期望 ⟨P⟩ 布洛赫 / paulivec 数据源 ✅
纯度 Tr(ρ²)、保真度 混态度量 ✅ 最小
量子奇异值变换 / VQSVD / 云后端 算法研究 ❌

2. 硬约束(沿用 + 本切片追加)

  1. 仅 ABI:新 FFI 全部注册在 marqdo_plugin_init;L1 经 plugin.load。
  2. ext/** 无 host_*。
  3. 中英分文件,禁止混 API。
  4. 维数上限:
    • 态向量模拟:仍 ≤ 12 qubits(既有)。
    • 密度矩阵稠密运算(部分迹结果展示、谱分解、Hinton/City):默认 ≤ 6 qubits(dim ≤ 64);超限显式报错。
  5. 无新核心依赖:插件内手写复数矩阵 + Jacobi / 薄 SVD;不捆绑 BLAS / nalgebra(可后续再议)。
  6. view:仍走 host_query("record_plot") + quantum_svg;无外链字体/CDN。

3. 新运行时类型

_type(英) 中文 字段(锁定)
quantum_state 量子态 既有:qubits, amplitudes:[{re,im}]
quantum_density 密度矩阵 qubits, dim, matrix(dim×dim 嵌套 {re,im})
quantum_spectrum 谱 eigenvalues:[f64], eigenvectors(列向量嵌套 list)
quantum_schmidt 施密特 coeffs:[f64], ua, ub(局域基),entropy(可选)
quantum_svg — 既有;kind 扩展见 §5

4. 作者面 API

4.1 英文(ext/quantum/quantum.mq.md)

在既有 # circuit / # gate 之外增加(或扩展方法):

# density
    + `state`=None          # quantum_state 或 circuit(先 simulate)
    + `matrix`=None         # 直接给定 ρ

## matrix                   # → 嵌套 list
## purity                   # Tr(ρ²)
## expect
    + `obs`                 # Pauli 串 "ZI" / "XX" 或门矩阵
## partial_trace
    + `keep`                # 保留的比特列表(LSB=0)
## eig                      # Hermitian 谱 → quantum_spectrum
## draw
    + `kind`=hinton         # hinton|city|density|paulivec
    + `path`=None

# linop                     # 自由线性代数(也可挂在 quantum.* 模块函数)
## kron
    + `a`
    + `b`                   # 矩阵或态 → 张量积
## schmidt
    + `state`
    + `cut`=1               # 前 cut 个比特为 A,其余为 B
## fidelity
    + `a`
    + `b`                   # 两态或两密度(纯态公式优先)

电路侧便捷方法(返回新句柄,不改旧对象):

## density                  # simulate 后 ρ=|ψ⟩⟨ψ|
## expect
    + `obs`
## schmidt
    + `cut`=1
## draw
    + `kind`=…              # 扩展:hinton|city|density|paulivec|qsphere|multibloch

4.2 中文对称

英文 中文
density 密度
partial_trace 部分迹
purity 纯度
expect 期望
eig 本征
kron 张量积
schmidt 施密特
fidelity 保真度
hinton / city / paulivec / qsphere / multibloch 同音译或 欣顿/城市/泡利向量/球/多布洛赫(L1 锁定中英别名表)

4.3 ABI 函数名(稳定英文)

FFI 作用
quantum_density_from_state 态 / 电路 → quantum_density
quantum_density_from_matrix 校验 Hermitian / 维数 → 句柄
quantum_density_matrix 取出嵌套矩阵
quantum_density_purity Tr(ρ²)
quantum_density_partial_trace keep 列表
quantum_density_eig Jacobi Hermitian
quantum_density_expect Pauli 串或矩阵
quantum_density_draw hinton/city/density/paulivec
quantum_kron 两矩阵或两态振幅
quantum_schmidt 纯态二分
quantum_fidelity 两态
quantum_draw_circuit 扩展 kind 枚举(向后兼容)

5. 高级绘图语义

kind 输入 SVG 要点
hinton ρ 网格方块;边长 ∝ √|ρᵢⱼ|;正 Re 浅 / 负深;小 dim 可标数值
city ρ 等轴测「楼宇」:左 Re、右 Im 两城,或单城双色柱
density ρ Cirq 风格:每格幅值圆 + 相位线段;对角概率矩形
paulivec 态或 ρ 全 Pauli 基(n≤3)或用户 ops= 列表;柱高 = ⟨P⟩
qsphere 纯态 基矢点映射到球/圆;半径∝振幅,色相∝arg;n≤4 推荐
multibloch 纯态 每比特约化布洛赫并排

既有 circuit|probs|bloch|gate|matrix 不变。


6. 数值语义(锁定)

项 规则
比特序 qubit 0 = LSB(与既有概率标签一致)
partial_trace keep= 保留比特升序组成新系统的 LSB…MSB
Pauli 串 左→右 = 高位→低位 或文档写死「左=qubit n-1」——锁定:字符串左端 = 最高比特(qubit n−1),与 Qiskit 习惯一致;文档 + 金样双锁
Hermitian 检查 ‖ρ−ρ†‖_F < 1e-8,否则报错
谱 实特征值降序;特征向量列归一
Schmidt 将 |ψ⟩ 整形为 2^cut × 2^(n-cut) 复矩阵做薄 SVD;奇异值 = Schmidt 系数
纯度 纯态 ≈ 1;最大混态 = 1/dim

7. 分期交付

子阶段 内容 验收
Q7a density / kron / partial_trace / eig / schmidt / expect / purity / fidelity + L1 中英 tests/ext/quantum-linalg-smoke.mq.md(+ zh)
Q7b draw kinds:hinton, city, density, paulivec, qsphere, multibloch tests/ext/quantum-viz-advanced-smoke.mq.md(SVG 含关键标记)
Q7c 示例页 + 用户站短页 + skill/reference 摘要 examples/quantum-entanglement/ 或扩展 bell

8. 刻意不做(本 Q7)

  • 任意 Kraus / 完整 CPTP 通道库(仍用 Q5 轨迹噪声)
  • 6 qubit 稠密 ρ 的谱 / Hinton(请用态向量 API)

  • Matplotlib / WebGL / 交互拖拽
  • 量子线性系统算法(HHL)、QSVT 电路构造
  • 把线性代数并入 lib/math(经典公式优先的 LA 见规划 ext-linalg.md,作者面与 quantum 分离)

9. 评审清单

  1. 密度矩阵上限 6 qubits 是否可接受?
  2. Pauli 串左右端比特约定是否锁定为「左=高比特」?
  3. City 用 2.5D SVG 而非真 3D 是否足够?
  4. # density 独立类 vs 仅 circuit.density —— 两者都提供(类用于给定矩阵;电路方法便捷)?

评审默认:全部锁定为上文;实现按 Q7a → Q7b → Q7c。


10. 一句话

Q7 让 Marqdo 量子文档能「算清纠缠、画清态」:线性代数在 ABI 里跑,高级图用自绘 SVG 进 view——仍是代码即文档。