# 快速开始

用一个可训练角度，把单量子比特电路的 Pauli-Z 期望值拟合到目标值 `0.2`。这个示例对应首页“应用教程”的 ArcQML 入门流程，可以先了解训练过程，再进入 VQE 和 QNN 的完整任务。

## 准备环境

请先阅读[安装与环境配置](docs/arcqml/installation.html)及[发行状态与许可证](docs/arcqml/index.html#license)。本次为 Windows 实验性预览版，使用 CPython 3.11；请按 [ArcQML 仓库](https://github.com/Quill-ArcLight/ArcQML)的当前步骤安装随附的 Windows wheel。网站安装页中的 Linux 命令保留为历史环境示例。

使用 Rust 原生接口时，可从 [VQE 教程](docs/arcqml/vqe.html)或 [QNN 教程](docs/arcqml/qnn.html)开始；两篇默认展示 Rust，在配对代码框中可同步切换 Python。

## 运行最小训练示例

将以下代码保存为 `quick_start.py`，在已安装 ArcQML 的 Python 环境中执行 `python quick_start.py`。代码依次构建电路、定义训练目标、更新参数，并读取训练结果。

```python
# 构建含一个可训练角度的单量子比特电路。
import arcqml

circuit = arcqml.Circuit(num_qubits=1)
circuit.ry(angle=0.3, qubit=0)
print("trainable parameters:", circuit.num_parameters)

# 定义观测量与模拟器，再设置目标值和优化器。
observable = arcqml.PauliSum.z(num_qubits=1, qubit=0)
simulator = arcqml.StateVectorSimulator(num_qubits=1)

target = arcqml.tensor(0.2)
optimizer = arcqml.Adam(learning_rate=0.05)

# 前向计算期望值与损失，反向传播后更新电路参数。
for step in range(1, 101):
    optimizer.zero_grad(circuit=circuit)

    prediction = simulator.run(circuit=circuit, observable=observable)
    loss = arcqml.mse_loss(prediction=prediction, target=target)

    loss.backward()
    optimizer.step(circuit=circuit)

    if step == 1 or step % 20 == 0:
        print(f"step {step:>2}: loss = {loss.item():.6f}")

# 推理时关闭梯度记录，读取训练后的期望值。
with arcqml.no_grad():
    prediction = simulator.run(circuit=circuit, observable=observable).item()

print(f"final <Z> = {prediction:.6f}")
print("target    = 0.200000")
```

## 理解训练过程

- `circuit.ry` 添加可训练旋转门，优化器调整其角度。
- `simulator.run` 返回可微分的期望值 `Tensor`，`mse_loss` 计算它与目标值的均方误差。
- `loss.backward()` 把损失梯度传回电路参数，`optimizer.step` 完成更新；每轮先清空旧梯度，避免累加。
- `no_grad()` 在最终读取结果时关闭梯度记录。

程序会打印参数数量、部分训练轮次的损失及最终期望值。观察最终期望值是否接近 `0.2`，并比较训练初期与后期的损失；不要求每一步都单调下降。

量子线路如何接入经典自动微分图，见[可训练前向与反向的数据流](docs/arcqml/installation.html#section-2-4)。Rust 训练循环与自定义损失见[损失函数与优化器](docs/arcqml/training.html)。

## 继续学习

- [VQE：求解 H₂ 基态能量](docs/arcqml/vqe.html)：学习哈密顿量、初态制备与变分能量优化。
- [QNN：构建量子神经网络分类器](docs/arcqml/qnn.html)：学习数据编码、批量前向、分类损失与验证。