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>
9.3 KiB
9.3 KiB
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 态向量教学模拟之上,补齐两块「教科书级」能力:
- 高阶线性代数(密度矩阵、Kronecker、部分迹、Hermitian 谱分解、Schmidt / SVD、Pauli 期望值)
- 高级静态 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. 硬约束(沿用 + 本切片追加)
- 仅 ABI:新 FFI 全部注册在
marqdo_plugin_init;L1 经plugin.load。 ext/**无host_*。- 中英分文件,禁止混 API。
- 维数上限:
- 态向量模拟:仍 ≤ 12 qubits(既有)。
- 密度矩阵稠密运算(部分迹结果展示、谱分解、Hinton/City):默认 ≤ 6 qubits(dim ≤ 64);超限显式报错。
- 无新核心依赖:插件内手写复数矩阵 + Jacobi / 薄 SVD;不捆绑 BLAS / nalgebra(可后续再议)。
- 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. 评审清单
- 密度矩阵上限 6 qubits 是否可接受?
- Pauli 串左右端比特约定是否锁定为「左=高比特」?
- City 用 2.5D SVG 而非真 3D 是否足够?
# density独立类 vs 仅circuit.density—— 两者都提供(类用于给定矩阵;电路方法便捷)?
评审默认:全部锁定为上文;实现按 Q7a → Q7b → Q7c。
10. 一句话
Q7 让 Marqdo 量子文档能「算清纠缠、画清态」:线性代数在 ABI 里跑,高级图用自绘 SVG 进 view——仍是代码即文档。