# 快速开始：安装与第一个量子电路

本章带你从零完成一次端到端体验：安装 UnifiedQuantum → 构建 Bell 态电路 → 查看它的 OriginIR 表示 → 本地模拟得到测量统计 → 通过统一的执行入口在 dummy 后端上跑一遍。走完这一页，你的环境就完全可用了。

理论背景（Bell 态为什么测量结果只有 `00` 和 `11`）见[量子计算算法教程·量子计算基础](https://chenzhaoyun.com/quantum-tutorial/ch01-basics/quantum-computing-basics.html)。本页示例基于 `unified-quantum` **0.1.0**（PyPI 最新版），所有输出均为实际运行结果。

:::{admonition} 本课知识点
:class: tip

1. **[安装与环境验证](#install-verify)**——能安装 `unified-quantum` 并用一条命令验证 `uniqc` 可以导入、版本正确。
2. **[用 Circuit 构建量子线路](#first-circuit)**——能用 `Circuit` 的链式 API 写出 H 门 + CNOT + 测量，制备 Bell 态。
3. **[OriginIR 线路表示](#originir-repr)**——能读懂一段 OriginIR（QINIT/CREG/门/MEASURE 各行的含义），并知道它是UnifiedQuantum 各后端交换线路的通用格式。
4. **[本地模拟与测量统计](#local-simulation)**——能用 `Simulator.simulate_shots` 本地模拟线路，解释计数结果与理论概率的对应与涨落。
5. **[统一执行入口与 dummy 后端](#unified-execution)**——能用 `submit_task` + `wait_for_result` 在 `dummy:local:simulator` 后端执行线路，并读懂 `UnifiedResult` 的各字段。

:::

(install-verify)=
## 1. 安装与环境验证

推荐在虚拟环境中安装：

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install unified-quantum
```

验证安装（也是全书约定：示例代码都可以直接复制运行）：

```python
import uniqc
print(uniqc.__version__)
```

```text
0.1.0
```

UnifiedQuantum 的 Python 模块名是 `uniqc`（包名与模块名不同，这是常见布局）。此外它还提供 `uniqc` 命令行工具，安装后即可用 `uniqc --help` 查看——命令行用法见第 5 章，本页先用 Python API。

(first-circuit)=
## 2. 第一个电路：制备 Bell 态

我们构建教科书里最经典的纠缠态线路：对 `q[0]` 加 H 门制造叠加，再用 CNOT 把纠缠"复制"到 `q[1]`，最后测量两个比特。

```python
from uniqc import Circuit

circuit = Circuit()
circuit.h(0)          # 对量子比特 0 施加 Hadamard 门
circuit.cnot(0, 1)    # 以比特 0 为控制、比特 1 为目标的 CNOT
circuit.measure(0, 1) # 测量比特 0 与 1，分别写入经典寄存器
```

三行对应三个动作：**单比特门 → 双比特门 → 测量**。`Circuit()` 不需要预先声明比特数，首次用到某个比特时自动扩展寄存器；`measure(0, 1)` 的参数是要测量的量子比特编号，结果依次写入经典比特。

(originir-repr)=
## 3. OriginIR：线路的通用表示

`.originir` 属性把线路导出为 OriginIR 文本——这是 UnifiedQuantum 连接多平台后端的通用交换格式：

```python
print(circuit.originir)
```

```text
QINIT 2
CREG 2
H q[0]
CNOT q[0], q[1]
MEASURE q[0], c[0]
MEASURE q[1], c[1]
```

逐行读：`QINIT 2` 声明 2 个量子比特、`CREG 2` 声明 2 个经典比特；`H q[0]` 与 `CNOT q[0], q[1]` 是两行门操作；`MEASURE q[i], c[i]` 把测量结果写入经典寄存器。除了用 API 构建，你也可以直接用任何能产出 OriginIR（或 OpenQASM 2.0）的工具生成线路文本再交给 UnifiedQuantum 执行——这就是"任意方式构建线路、统一入口执行"的设计。

(local-simulation)=
## 4. 本地模拟：测量统计

`Simulator` 在本地对线路做态矢量模拟，`simulate_shots` 按 shots 次测量采样并统计计数：

```python
from uniqc.simulator import Simulator

sim = Simulator()
counts = sim.simulate_shots(circuit.originir, shots=1024)
print(counts)
```

```text
{0: 497, 3: 527}
```

结果只有两个键：`0`（二进制 `00`）和 `3`（二进制 `11`），各约占一半——这正是 Bell 态 $|\Phi^+\rangle = \frac{1}{\sqrt 2}(|00\rangle + |11\rangle)$ 的理论预测：测得 `00` 与 `11` 的概率各为 $1/2$，`01`、`10` 概率为 0。计数不会精确等于 512/512，1024 次采样下几百的涨落是正常的统计涨落（标准差约 $\sqrt{1024 \times 0.25} = 16$ 次）。注意本地 `simulate_shots` 返回的键是十进制整数。

(unified-execution)=
## 5. 统一执行入口：submit_task 与 dummy 后端

真实工作流中我们不直接调用模拟器，而是把线路**提交**给某个后端。`submit_task` 是统一入口：同一份代码，把 `backend` 换成任何支持的平台（本地 dummy、OriginQ 真机、天衍等）即可，这正是"Unified"的含义。

```python
from uniqc import submit_task, wait_for_result

task_id = submit_task(circuit, backend="dummy:local:simulator", shots=1024)
result = wait_for_result(task_id)
print(result)
```

```text
UnifiedResult(counts={'00': 512, '11': 512}, probabilities={'00': 0.5, '11': 0.5}, shots=1024, platform='dummy', task_id='uqt_8bb8e454c2eb4eab8df387e4af9a087a', backend_name='dummy:local:simulator', execution_time=None, error_message=None)
```

`UnifiedResult` 把各平台的结果归一成统一结构，常用字段：

- `counts`：各测量结果的计数（这里键是二进制串 `'00'`/`'11'`）；
- `probabilities`：归一化概率；
- `shots`、`platform`、`backend_name`、`task_id`：执行元信息。

`dummy:local:simulator` 是无约束、无噪声的本地虚拟后端，适合教学与调试。dummy 家族还有带拓扑约束与含噪声的成员，第 3 章展开。

## 下一步

- 想系统学习量子计算理论（为什么 Bell 态是这样的测量分布），去[量子计算算法教程](https://chenzhaoyun.com/quantum-tutorial/)
- 想掌握更多线路构建手段（参数化门、QASM 互导），继续[第 2 章：线路构建](../ch02-circuits/index.md)

## 练习题

**练习 1【安装与环境验证】**（→ [第 1 节](#install-verify)）

1. 在全新的虚拟环境中安装 `unified-quantum`，运行 `import uniqc; print(uniqc.__version__)` 并确认输出版本号。
2. 运行 `uniqc --help`，列出它提供的子命令（后续章节会逐一用到）。

**练习 2【用 Circuit 构建量子线路】**（→ [第 2 节](#first-circuit)）

1. 把本章电路中的 `cnot(0, 1)` 改成 `cnot(1, 0)`（控制与目标互换），先笔算新线路的测量分布，再用模拟验证你的预测。
2. 构建一个三比特线路：`h(0)`、`cnot(0,1)`、`cnot(0,2)`，写出它的 OriginIR 并预测测量结果只可能出现哪几个串。

> 提示：三比特线路制备的是 GHZ 态 $\frac{1}{\sqrt2}(|000\rangle+|111\rangle)$。

**练习 3【OriginIR 线路表示】**（→ [第 3 节](#originir-repr)）

1. 解释 OriginIR 中 `QINIT`、`CREG`、`MEASURE q[0], c[0]` 各自的作用。
2. 手写一段两比特的 OriginIR：先对两个比特各加一个 H 门再测量，然后用 `Simulator().simulate_shots(...)` 执行它，验证四个结果各占约 1/4。

**练习 4【本地模拟与测量统计】**（→ [第 4 节](#local-simulation)）

1. 把 `shots` 从 1024 改成 100 再改成 10000，观察 `00` 与 `11` 计数偏离 50/50 的程度如何变化，并用二项分布标准差 $\sqrt{Np(1-p)}$ 解释。
2. 对 Bell 态线路把 `h(0)` 换成 `x(0)`（Pauli-X 门），先预测测量结果再运行验证。

**练习 5【统一执行入口与 dummy 后端】**（→ [第 5 节](#unified-execution)）

1. 用 `submit_task` 在 `dummy:local:simulator` 上执行 GHZ 线路，打印 `UnifiedResult` 并指出 `counts` 与 `probabilities` 的关系。
2. 对比 `Simulator().simulate_shots` 与 `wait_for_result(...)` 返回的计数键格式（整数 vs 二进制串），解释为什么统一入口要规定键格式。

> 提示：统一格式让同一份后处理代码可以不加修改地跑在所有平台上。