# 代码演示

> **16 章 × 3 个 = 48 个可运行的 uniqc Python 演示**，每个演示独立成页：实现要点、完整源码与运行结果。
>
> 配套：[UnifiedQuantum 完整教程](https://tutorial.chenzhaoyun.com/unified-quantum-tutorial/) · [API 文档](https://github.com/IAI-USTC-Quantum/UnifiedQuantum) · [⌂ 教程门户](https://tutorial.chenzhaoyun.com/)
>
> 安装：`pip install "unified-quantum[visualization,simulation]"`

每个 demo 是一个独立 Python 脚本，使用 `unified-quantum` PyPI 包（`from uniqc import Circuit, submit_task, wait_for_result`），通过 `dummy:local:simulator` 后端本地执行，无需云平台凭证。跑完会输出关键统计到 stdout + 保存 matplotlib PNG 到同名 `.png` 文件。

```{toctree}
:hidden:
ch01-basics/index
ch02-qnn/index
ch03-algo-basics/index
ch04-classic-algorithms/index
ch05-hamiltonian-qsp/index
ch06-scientific-computing/index
ch07-quantum-info/index
ch08-qml/index
ch09-algebra-number-theory/index
ch10-hidden-structures/index
ch11-query-complexity/index
ch12-quantum-graphs/index
ch13-topology-statistical-physics/index
ch14-optimization-numerics/index
ch15-learning-spectral/index
ch16-cryptanalysis-coding/index
```


## 模块一：基础与工具（ch01–ch02，6 个 demo）

| 章 | demo | 核心可视化 |
|---|---|---|
| [ch01 基础](ch01-basics/index.md) | 1. [Bloch 球轨迹](ch01-basics/01_bloch_sphere.md) — 6 个基准态的 ⟨X⟩,⟨Y⟩,⟨Z⟩ 测得 Bloch 矢量画在单位球上 | 球面 6 个箭头 |
| | 2. [\|±⟩ 测量概率](ch01-basics/02_measurement_probability.md) — 在 X/Y/Z 基上 P(0)/P(1) 分组柱图 | 4 根/基 柱状 |
| | 3. [Bell 态](ch01-basics/03_bell_state.md) — 4 个 Bell 态联合测量直方图 | 4 子图柱状 |
| [ch02 QNN](ch02-qnn/index.md) | 1. [参数化 RY 扫描](ch02-qnn/01_parametrized_rx_ry.md) — 扫描 θ 画 ⟨Z⟩ = cos θ 曲线 + 误差标注 | 单图曲线+误差条 |
| | 2. [参数平移梯度](ch02-qnn/02_parameter_shift.md) — 解析 / 平移 / 有限差分梯度对比 | 双图：曲线+误差柱 |
| | 3. [QNN 拟合 sin(x)](ch02-qnn/03_qnn_ansatz.md) — 1-qubit re-uploading ansatz 网格搜索最优点 | 双图：MSE 等高线+拟合曲线 |

## 模块二：算法主线（ch03–ch04，6 个 demo）

| 章 | demo | 核心可视化 |
|---|---|---|
| [ch03 算法基础](ch03-algo-basics/index.md) | 1. [Deutsch-Jozsa](ch03-algo-basics/01_dj_constant_balanced.md) — 4-qubit 常数 vs 平衡 Oracle 一次查询 | 双子图柱状 |
| | 2. [Grover 4-qubit](ch03-algo-basics/02_grover_4qubit.md) — 迭代 0/1/2/4 测量概率演化 | 2×2 子图 |
| | 3. [QFT 振幅相位](ch03-algo-basics/03_qft_4qubit.md) — QFT_4\|0010⟩ 16 个分量的极坐标散点 | 双图：振幅+相位 |
| [ch04 经典算法](ch04-classic-algorithms/index.md) | 1. [Shor N=15](ch04-classic-algorithms/01_shor_N15.md) — 因子分解 15=3×5 全流程 + 周期读取 | 3 子图（U_7 矩阵、周期轨道、QPE 相位）|
| | 2. [Bernstein-Vazirani](ch04-classic-algorithms/02_bv_4qubit.md) — 4-qubit 一次查询读出隐藏 s=1011 | 双子图（测量柱+oracle 示意）|
| | 3. [Simon 算法](ch04-classic-algorithms/03_simon_3qubit.md) — 3-qubit 隐藏 s=110 经典高斯消元恢复 | 3 子图 |

## 模块三：现代算法体系（ch05–ch08，12 个 demo）

| 章 | demo | 核心可视化 |
|---|---|---|
| [ch05 QSP/QSVT](ch05-hamiltonian-qsp/index.md) | 1. [Trotter Ising 链](ch05-hamiltonian-qsp/01_trotter_ising.md) — 一阶/二阶 Trotter 误差对数曲线 | 3 子图（H+误差+末态分布）|
| | 2. [块编码](ch05-hamiltonian-qsp/02_block_encoding_hermitian.md) — 2×2 厄米矩阵 A 的 4-qubit 块编码 U_A 验证 | 3 子图（U_A+A+A/α+测量）|
| | 3. [QSVT sign 近似](ch05-hamiltonian-qsp/03_qsvt_sign.md) — 17 个 x 处 P(0)/P(1) 与 sign(x) 对比 | 3 子图（相位+多项式+测量）|
| [ch06 科学计算](ch06-scientific-computing/index.md) | 1. [HHL 2×2](ch06-scientific-computing/01_hhl_2x2.md) — QPE 提本征相位 + 重建 x = A⁻¹\|b⟩ | 单子图 |
| | 2. [Gibbs 态制备](ch06-scientific-computing/02_gibbs_state.md) — 4 β 扫描的 P(\|00⟩)=1/Z 反推 | 单子图（4 柱对比）|
| | 3. [QAOA 4-node MaxCut](ch06-scientific-computing/03_qaoa_maxcut.md) — 25×25 (γ,β) 网格扫描 | 2D 热图+最优 cuts |
| [ch07 量子信息](ch07-quantum-info/index.md) | 1. [BB84 QKD](ch07-quantum-info/01_bb84_qkd.md) — 1000 轮 QBER 与密钥长度对比 | 双子图 |
| | 2. [态层析](ch07-quantum-info/02_state_tomography.md) — 3 态 3 基重建 Bloch 矢量 | 3D 球+3 子图 |
| | 3. [不可克隆](ch07-quantum-info/03_no_cloning.md) — CNOT 克隆机对 9 态保真度 vs B-H 上界 | 双图：保真度+Bob Bloch 长度 |
| [ch08 QML](ch08-qml/index.md) | 1. [VQE H₂](ch08-qml/01_vqe_h2.md) — UCCSD + COBYLA 估 H₂ 基态 ≈ -2.016 Ha | 双子图（收敛+vs FCI）|
| | 2. [QAOA MaxCut 4-node](ch08-qml/02_qaoa_maxcut_4node.md) — 14×14 网格+爬山轨迹 | 双图（热图+top bitstring）|
| | 3. [量子核 SVM](ch08-qml/03_quantum_kernel.md) — 2-qubit ZZFeatureMap 核矩阵 + 决策边界 | 双图（核矩阵+边界）|

## 模块四：应用与前沿专题（ch09–ch16，24 个 demo）

| 章 | demo | 核心可视化 |
|---|---|---|
| [ch09 数论](ch09-algebra-number-theory/index.md) | 1. [Shor 离散对数](ch09-algebra-number-theory/01_discrete_log.md) — N=15 离散对数骨架 + QPE 相位 | 双图（轨道+直方图）|
| | 2. [模幂 U_7](ch09-algebra-number-theory/02_modular_exp.md) — 16 输入态全测 + QPE | 3 子图 |
| | 3. [CRT 恢复](ch09-algebra-number-theory/03_crt_recovery.md) — Z_3^* + Z_5^* 拆解后合并 | 3 子图（子群轨道+CRT 流程）|
| [ch10 HSP](ch10-hidden-structures/index.md) | 1. [Simon HSP](ch10-hidden-structures/01_simon_hsp.md) — 3-qubit H^⊥ 样本 + F_2 高斯消元 | 双图（分布+RREF）|
| | 2. [Abel HSP 离散对数](ch10-hidden-structures/02_abel_hsp.md) — N=15 拆 p1, p2 + CRT | 双图 |
| | 3. [隐藏位移](ch10-hidden-structures/03_hidden_shift.md) — 7-qubit van Dam 量子算法 + 经典/量子查询数对比 | 双图 |
| [ch11 查询复杂度](ch11-query-complexity/index.md) | 1. [碰撞 BHT](ch11-query-complexity/01_collision_bht.md) — N=8 标记命中 + log-log 查询数对比 | 双图 |
| | 2. [元素唯一性](ch11-query-complexity/02_element_distinctness.md) — toy 数组 + O(N) vs O(N^{2/3}) + Johnson 平衡 | 双图 |
| | 3. [矩阵秩](ch11-query-complexity/03_matrix_rank.md) — 4×4 高斯消元 + 量子查询复杂度 | 3 子图 |
| [ch12 图算法](ch12-quantum-graphs/index.md) | 1. [K3 量子行走](ch12-quantum-graphs/01_graph_walk.md) — 4 步位置概率演化 | 双图（轨迹+经典对照）|
| | 2. [Welded Tree](ch12-quantum-graphs/02_welded_tree.md) — 14 顶点焊缝树 + 经典 vs 量子 P(EXIT) | 2 子图 |
| | 3. [Childs-Goldstone 空间搜索](ch12-quantum-graphs/03_spatial_search.md) — C4 + γ=1/√2 + Rabi 振荡 | 3 子图 |
| [ch13 拓扑/统计物理](ch13-topology-statistical-physics/index.md) | 1. [Kitaev 链](ch13-topology-statistical-physics/01_kitaev_chain.md) — 6-site H 谱 + ⟨Z⟩ 边缘 + (J,K) 能隙 | 3 子图 |
| | 2. [配分函数](ch13-topology-statistical-physics/02_partition_function.md) — Z = 1/P(ground) 估 Z(β) | 单子图（4 柱）|
| | 3. [字符串重写](ch13-topology-statistical-physics/03_string_rewriting.md) — 经典步数 vs Grover 迭代 | 双图 |
| [ch14 优化](ch14-optimization-numerics/index.md) | 1. [QAOA K4 MaxCut](ch14-optimization-numerics/01_qaoa_maxcut_4node.md) — 11×11 网格 + 爬山 | 双图（热图+top cuts）|
| | 2. [凸优化](ch14-optimization-numerics/02_convex_optimization.md) — FD 经典 vs Jordan 量子梯度 | 2 子图 |
| | 3. [QAOA 投资组合](ch14-optimization-numerics/03_qaoa_portfolio.md) — 3 资产 Markowitz QUBO | 双图 |
| [ch15 谱方法](ch15-learning-spectral/index.md) | 1. [量子 PCA](ch15-learning-spectral/01_quantum_pca.md) — 4×4 块编码+QPE 估前 2 特征值 | 单子图 |
| | 2. [主特征向量](ch15-learning-spectral/02_principal_eigenvector.md) — 经典 power iter + 量子态制备 | 双图 |
| | 3. [谱和](ch15-learning-spectral/03_spectral_sums.md) — Tr(A^k) Hadamard/QPE 估 | 单子图（4 柱对比）|
| [ch16 密码分析](ch16-cryptanalysis-coding/index.md) | 1. [Shor 破 RSA](ch16-cryptanalysis-coding/01_shor_rsa.md) — 3+3 qubit QPE 估 r=4 + GCD | 单子图 |
| | 2. [Steane 量子译码](ch16-cryptanalysis-coding/02_quantum_decoding.md) — 7-qubit CSS 码 + syndrome 校正 | 单子图 |
| | 3. [Grover 密码破解](ch16-cryptanalysis-coding/03_grover_code_crack.md) — 8-qubit 搜索 P=0b11010110 | 单子图 |

## 使用方式

### 跑单个 demo

```bash
# 从仓库根目录
.venv/bin/python3 demos/ch01-basics/01_bloch_sphere.py
# 输出 PNG 到 demos/ch01-basics/01_bloch_sphere.png
# 关键统计到 stdout
```

### 跑全章

```bash
for f in demos/ch01-basics/*.py; do
  .venv/bin/python3 "$f"
done
```

### 跑全部 48 个

```bash
for f in demos/ch*/*.py; do
  .venv/bin/python3 "$f"
done
```

## 技术约定

- **后端**：`dummy:local:simulator`（无云依赖）
- **shots**：默认 2000（多数 demo 总 shots ≤ 3000）
- **可读性**：matplotlib 默认 DejaVu Sans 不带中文，标签统一用英文；中文仅出现在 docstring 与 stdout
- **公式**：LaTeX 用 `$\sqrt{N}$` 等 mathtext 兼容语法（无单参数 `\sqrt N`）
- **代码量**：每个 .py < 200 行

## 已知限制

- `dummy:local:simulator` 没有真正的中间测量，phase kickback / teleportation 类 demo 只能展示终态分布
- `add_gate('U', matrix=...)` 不支持；自定义酉只能通过基础门组合 + `get_matrix()` 验证
- `result.get_expectation(...)` 只支持单 Z 测；多 Pauli 串会抛 `NotImplementedError`
- 大矩阵（如 4×4 以上）的 block-encoding demo 受限，多数用 2×2 / 4×4 + 经典对照

## 相关链接

- [UnifiedQuantum 完整教程](https://tutorial.chenzhaoyun.com/unified-quantum-tutorial/)
- [UnifiedQuantum GitHub](https://github.com/IAI-USTC-Quantum/UnifiedQuantum)
- [主站 103 篇教程](https://tutorial.chenzhaoyun.com/quantum-tutorial/)
- [课程幻灯片（30 课 · 每页绑定讲义）](https://tutorial.chenzhaoyun.com/slides/)
- [主站 chenzhaoyun.com](https://chenzhaoyun.com/)