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 <cursoragent@cursor.com>
This commit is contained in:
cflmyandCursor committed 2026-08-12 13:59:51 +08:00
1 parent b842644686
commit 505d478724
10 files changed
+153 -25

No files matched your search

+48
View File
@@ -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`
+1 -1
View File
@@ -13,7 +13,7 @@
在 **不** 引入完整开放系统 / 云后端的前提下,让教学文档能写「带噪声的采样」,金样可复现。
**刻意不做(本 Q5 切片):** 任意 Kraus 组、振幅阻尼完整表、>12 qubits 张量网络、噪声参数学习。
**刻意不做(本 Q5 切片):** 任意 Kraus 组、振幅阻尼完整表、>12 qubits 张量网络、噪声参数学习。振幅阻尼教学轨迹见 [ext-quantum-q5.5.md](ext-quantum-q5.5.md)。
---
+1 -1
View File
@@ -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` / `量子`) |
+3 -2
View File
@@ -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`)。
---
+1 -1
View File
@@ -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`**
+1 -1
View File
@@ -122,7 +122,7 @@ description: 官方量子电路模拟(中文)。门 + 电路;ABI 插件。
+ `种类`
+ `概率`
教学噪声,供 `运行` 轨迹使用(`bitflip` / `depolarizing` 或中文名)。`模拟` / `概率` 忽略。
教学噪声,供 `运行` 轨迹使用(`bitflip` / `depolarizing` / `amplitude_damping`,或中文:比特翻转 / 退极化 / 振幅阻尼)。`模拟` / `概率` 忽略。
**> quantum_noise circuit=`self` kind=`种类` p=`概率`**
+40 -19
View File
@@ -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<Option<NoiseSpec>, String> {
let kind = circuit
.get("noise_kind")
@@ -494,15 +509,7 @@ pub fn parse_noise(circuit: &Value) -> Result<Option<NoiseSpec>, 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<Value, String> {
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),
_ => {}
}
}
+18
View File
@@ -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
+18
View File
@@ -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
+22
View File
@@ -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")