From 505d478724c8a98ac27dfc822c9c93bae6b6fcf7 Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 12 Aug 2026 13:59:51 +0800 Subject: [PATCH] Add amplitude_damping teaching noise for quantum run trajectories. Extends Q5 with a dissipative jump channel and EN/ZH golds so docs can show energy loss, not only Pauli flips. Co-authored-by: Cursor --- doc/design/ext-quantum-q5.5.md | 48 ++++++++++++++++++ doc/design/ext-quantum-q5.md | 2 +- doc/design/ext-quantum.md | 2 +- doc/roadmap/ext-quantum.md | 5 +- ext/quantum/quantum.mq.md | 2 +- ext/quantum/量子.mq.md | 2 +- plugins/quantum/src/sim.rs | 59 +++++++++++++++-------- tests/ext/quantum-amp-damp-smoke.mq.md | 18 +++++++ tests/ext/quantum-amp-damp-zh-smoke.mq.md | 18 +++++++ tests/gold.rs | 22 +++++++++ 10 files changed, 153 insertions(+), 25 deletions(-) create mode 100644 doc/design/ext-quantum-q5.5.md create mode 100644 tests/ext/quantum-amp-damp-smoke.mq.md create mode 100644 tests/ext/quantum-amp-damp-zh-smoke.mq.md diff --git a/doc/design/ext-quantum-q5.5.md b/doc/design/ext-quantum-q5.5.md new file mode 100644 index 0000000..7f600eb --- /dev/null +++ b/doc/design/ext-quantum-q5.5.md @@ -0,0 +1,48 @@ +# `ext/quantum` Q5.5 — 振幅阻尼(教学轨迹) + +| | | +|---|---| +| 状态 | **Accepted · 已落地** | +| 日期 | 2026-08-12 | +| 父设计 | [ext-quantum.md](ext-quantum.md) · [ext-quantum-q5.md](ext-quantum-q5.md) | +| 路线图 | [roadmap/ext-quantum.md](../roadmap/ext-quantum.md) | + +--- + +## 1. 目标 + +在 Q5 的 `bitflip` / `depolarizing` 之外,补一种**耗散**教学噪声:`amplitude_damping`(中文 `振幅阻尼`),仍只影响 `run` 轨迹;`simulate` / `probabilities` 忽略。 + +**刻意不做:** 完整 Kraus 表 API、任意算符噪声、密度矩阵引擎、相位阻尼完整 Lindblad。 + +--- + +## 2. 作者面 + +```markdown +*`qc` = > `qc`.noise kind=amplitude_damping p=0.1 * +# 中文 +*`qc` = > `qc`.噪声 种类=振幅阻尼 概率=0.1 * +``` + +别名:`amp_damp` / `amplitude-damping`。 + +--- + +## 3. 模拟语义 + +与 Q5 相同:每个改态门后,对涉及比特独立掷骰。 + +对每个比特,以概率 `p` 施加**跳跃**算符 \(E_1 = |0\rangle\langle 1|\)(只作用该比特),再归一化: + +- 若态在该比特上几乎全为 `|0⟩`(范数 ≈ 0),跳跃无效,态不变。 +- 否则振幅从 `|…1…⟩` 搬到对应 `|…0…⟩` 并归一化。 + +金样:`X` 后 `amplitude_damping p=1` → 全部 shot 落在 `|0⟩`。 + +--- + +## 4. 验收 + +- `tests/ext/quantum-amp-damp-smoke.mq.md`(+ 中文对称) +- L1 EN/ZH 文档列出第三种 `kind` diff --git a/doc/design/ext-quantum-q5.md b/doc/design/ext-quantum-q5.md index 72a0195..3c5176d 100644 --- a/doc/design/ext-quantum-q5.md +++ b/doc/design/ext-quantum-q5.md @@ -13,7 +13,7 @@ 在 **不** 引入完整开放系统 / 云后端的前提下,让教学文档能写「带噪声的采样」,金样可复现。 -**刻意不做(本 Q5 切片):** 任意 Kraus 组、振幅阻尼完整表、>12 qubits 张量网络、噪声参数学习。 +**刻意不做(本 Q5 切片):** 任意 Kraus 组、振幅阻尼完整表、>12 qubits 张量网络、噪声参数学习。振幅阻尼教学轨迹见 [ext-quantum-q5.5.md](ext-quantum-q5.5.md)。 --- diff --git a/doc/design/ext-quantum.md b/doc/design/ext-quantum.md index 0524008..f1f6194 100644 --- a/doc/design/ext-quantum.md +++ b/doc/design/ext-quantum.md @@ -2,7 +2,7 @@ | | | |---|---| -| 状态 | **Accepted · Q0–Q5 最小切片已落地**(教学噪声 + barrier/measure/append/state;完整开放系统另文) | +| 状态 | **Accepted · Q0–Q5.5 已落地**(教学噪声含振幅阻尼;完整开放系统另文) | | 日期 | 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` / `量子`) | diff --git a/doc/roadmap/ext-quantum.md b/doc/roadmap/ext-quantum.md index 870d274..38e9382 100644 --- a/doc/roadmap/ext-quantum.md +++ b/doc/roadmap/ext-quantum.md @@ -2,7 +2,7 @@ | | | |---|---| -| 状态 | **Q0–Q5 最小切片已落地**(教学噪声 + 作者面补齐;更大 n / 完整开放系统另文) | +| 状态 | **Q0–Q5 最小 + Q5.5 振幅阻尼已落地**(更大 n / 完整开放系统另文) | | 日期 | 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) | @@ -28,8 +28,9 @@ | **Q3** | `steps=` 电路表;`draw` 轨线 SVG;view `record_plot` 或值识别 | **done** | | **Q4** | 概率条 / 布洛赫;`matches_matrix`;examples + 用户文档 | **done** | | **Q5** | 教学噪声 + barrier/measure/append/state — [ext-quantum-q5.md](../design/ext-quantum-q5.md) | **done(最小)** | +| **Q5.5** | `amplitude_damping` 轨迹 — [ext-quantum-q5.5.md](../design/ext-quantum-q5.5.md) | **done** | -验收金样:`tests/ext/quantum-bell-smoke.mq.md`、`quantum-draw-smoke.mq.md`、`quantum-gate-matrix-smoke.mq.md`、`quantum-gate-heatmap-smoke.mq.md`、`quantum-author-api-smoke.mq.md`、`quantum-noise-smoke.mq.md`、中文对称样例(`quantum-author-api-zh-smoke` / `quantum-noise-zh-smoke`)。 +验收金样:`tests/ext/quantum-bell-smoke.mq.md`、`quantum-draw-smoke.mq.md`、`quantum-gate-matrix-smoke.mq.md`、`quantum-gate-heatmap-smoke.mq.md`、`quantum-author-api-smoke.mq.md`、`quantum-noise-smoke.mq.md`、`quantum-amp-damp-smoke.mq.md`、中文对称样例(`quantum-author-api-zh-smoke` / `quantum-noise-zh-smoke` / `quantum-amp-damp-zh-smoke`)。 --- diff --git a/ext/quantum/quantum.mq.md b/ext/quantum/quantum.mq.md index 8d079f7..9725159 100644 --- a/ext/quantum/quantum.mq.md +++ b/ext/quantum/quantum.mq.md @@ -122,7 +122,7 @@ Append another circuit's ops or a `{gate,qubits}` op map. + `kind` + `p` -Teaching noise for `run` trajectories (`bitflip` / `depolarizing`). Ignored by `simulate` / `probabilities`. +Teaching noise for `run` trajectories (`bitflip` / `depolarizing` / `amplitude_damping`). Ignored by `simulate` / `probabilities`. **> quantum_noise circuit=`self` kind=`kind` p=`p`** diff --git a/ext/quantum/量子.mq.md b/ext/quantum/量子.mq.md index 99719b4..2d57c91 100644 --- a/ext/quantum/量子.mq.md +++ b/ext/quantum/量子.mq.md @@ -122,7 +122,7 @@ description: 官方量子电路模拟(中文)。门 + 电路;ABI 插件。 + `种类` + `概率` -教学噪声,供 `运行` 轨迹使用(`bitflip` / `depolarizing` 或中文名)。`模拟` / `概率` 忽略。 +教学噪声,供 `运行` 轨迹使用(`bitflip` / `depolarizing` / `amplitude_damping`,或中文:比特翻转 / 退极化 / 振幅阻尼)。`模拟` / `概率` 忽略。 **> quantum_noise circuit=`self` kind=`种类` p=`概率`** diff --git a/plugins/quantum/src/sim.rs b/plugins/quantum/src/sim.rs index 9c68e35..bda895e 100644 --- a/plugins/quantum/src/sim.rs +++ b/plugins/quantum/src/sim.rs @@ -474,10 +474,25 @@ pub fn is_unitary_op(op: &Op) -> bool { #[derive(Clone, Debug)] pub struct NoiseSpec { - pub kind: String, // bitflip | depolarizing + pub kind: String, // bitflip | depolarizing | amplitude_damping pub p: f64, } +fn normalize_noise_kind(k: &str) -> Result<&'static str, String> { + match k.trim().to_ascii_lowercase().as_str() { + "bitflip" | "bit_flip" | "比特翻转" => Ok("bitflip"), + "depolarizing" | "depolarise" | "退极化" => Ok("depolarizing"), + "amplitude_damping" + | "amplitude-damping" + | "amp_damp" + | "ampdamp" + | "振幅阻尼" => Ok("amplitude_damping"), + other => Err(format!( + "unknown noise kind `{other}` (bitflip|depolarizing|amplitude_damping)" + )), + } +} + pub fn parse_noise(circuit: &Value) -> Result, String> { let kind = circuit .get("noise_kind") @@ -494,15 +509,7 @@ pub fn parse_noise(circuit: &Value) -> Result, String> { if !(0.0..=1.0).contains(&p) { return Err("noise p must be in [0,1]".into()); } - let kind = match k.as_str() { - "bitflip" | "bit_flip" | "比特翻转" => "bitflip".into(), - "depolarizing" | "depolarise" | "退极化" => "depolarizing".into(), - other => { - return Err(format!( - "unknown noise kind `{other}` (bitflip|depolarizing)" - )); - } - }; + let kind = normalize_noise_kind(&k)?.to_string(); Ok(Some(NoiseSpec { kind, p })) } _ => Err("noise needs both kind and p".into()), @@ -513,15 +520,7 @@ pub fn set_noise(circuit: &Value, kind: &str, p: f64) -> Result { if !(0.0..=1.0).contains(&p) { return Err("noise p must be in [0,1]".into()); } - let k = match kind.trim().to_ascii_lowercase().as_str() { - "bitflip" | "bit_flip" | "比特翻转" => "bitflip", - "depolarizing" | "depolarise" | "退极化" => "depolarizing", - other => { - return Err(format!( - "unknown noise kind `{other}` (bitflip|depolarizing)" - )); - } - }; + let k = normalize_noise_kind(kind)?; let mut obj = circuit.as_object().cloned().unwrap_or_default(); obj.insert("noise_kind".into(), json!(k)); obj.insert("noise_p".into(), json!(p)); @@ -580,6 +579,27 @@ impl Rng { } } +fn apply_amplitude_damping_jump(amps: &mut [C], q: usize) { + // Jump Kraus E1 = |0⟩⟨1| on qubit q, then renormalize. + let n = amps.len(); + let mut out = vec![C::zero(); n]; + for i in 0..n { + if bit(i, q) { + let j = flip(i, q); + out[j] = out[j].add(amps[i]); + } + } + let norm_sq: f64 = out.iter().map(|c| c.norm_sq()).sum(); + if norm_sq < 1e-30 { + // State had no |1⟩ weight on q — jump is a no-op. + return; + } + let inv = 1.0 / norm_sq.sqrt(); + for i in 0..n { + amps[i] = out[i].scale(inv); + } +} + fn apply_noise_on_qubits( amps: &mut [C], qs: &[usize], @@ -600,6 +620,7 @@ fn apply_noise_on_qubits( 1 => apply_y(amps, q), _ => apply_z(amps, q), }, + "amplitude_damping" => apply_amplitude_damping_jump(amps, q), _ => {} } } diff --git a/tests/ext/quantum-amp-damp-smoke.mq.md b/tests/ext/quantum-amp-damp-smoke.mq.md new file mode 100644 index 0000000..69611c6 --- /dev/null +++ b/tests/ext/quantum-amp-damp-smoke.mq.md @@ -0,0 +1,18 @@ +--- +title: quantum amplitude damping smoke +description: X then amplitude_damping p=1 returns all shots to |0>. +> ext/quantum/quantum.mq.md +--- + +# main + +*`qc` = > quantum.circuit qubits=1 * +*`qc` = > `qc`.x qubit=0 * +*`qc` = > `qc`.noise kind=amplitude_damping p=1 * +*`r` = > `qc`.run shots=32 seed=7 * +*`c0` = `r`[^counts][^0] * + +1. `c0` == 32 + > print text=amp-ok +2. * + > print text=amp-fail diff --git a/tests/ext/quantum-amp-damp-zh-smoke.mq.md b/tests/ext/quantum-amp-damp-zh-smoke.mq.md new file mode 100644 index 0000000..690cd09 --- /dev/null +++ b/tests/ext/quantum-amp-damp-zh-smoke.mq.md @@ -0,0 +1,18 @@ +--- +title: quantum amplitude damping zh smoke +description: 泡利X 后 振幅阻尼 p=1 全部落回 |0⟩. +> ext/quantum/量子.mq.md +--- + +# main + +*`qc` = > 量子.电路 比特数=1 * +*`qc` = > `qc`.泡利X 比特=0 * +*`qc` = > `qc`.噪声 种类=振幅阻尼 概率=1 * +*`r` = > `qc`.运行 次数=32 种子=7 * +*`c0` = `r`[^counts][^0] * + +1. `c0` == 32 + > print text=amp-ok +2. * + > print text=amp-fail diff --git a/tests/gold.rs b/tests/gold.rs index ed44a0a..f1e642e 100644 --- a/tests/gold.rs +++ b/tests/gold.rs @@ -1608,6 +1608,28 @@ fn ext_quantum_noise_zh_smoke() { assert_out("tests/ext/quantum-noise-zh-smoke.mq.md", "noise-ok"); } +#[test] +fn ext_quantum_amp_damp_smoke() { + let status = Command::new("cargo") + .args(["build", "-p", "marqdo_plugin_quantum"]) + .current_dir(env!("CARGO_MANIFEST_DIR")) + .status() + .expect("build quantum plugin"); + assert!(status.success(), "failed to build marqdo_plugin_quantum"); + assert_out("tests/ext/quantum-amp-damp-smoke.mq.md", "amp-ok"); +} + +#[test] +fn ext_quantum_amp_damp_zh_smoke() { + let status = Command::new("cargo") + .args(["build", "-p", "marqdo_plugin_quantum"]) + .current_dir(env!("CARGO_MANIFEST_DIR")) + .status() + .expect("build quantum plugin"); + assert!(status.success(), "failed to build marqdo_plugin_quantum"); + assert_out("tests/ext/quantum-amp-damp-zh-smoke.mq.md", "amp-ok"); +} + #[test] fn ext_agent_framework_smoke() { let status = Command::new("cargo")