状态向量模拟
适用版本 · ArcQML 0.1.0
本页目录
StateVectorSimulator：有状态与无状态接口
| 接口 | 状态影响 | 返回值 | 主要用途 |
|---|---|---|---|
new / from_state_tensor |
创建初态 | 模拟器 | 默认零态或导入已归一化自定义态。 |
apply_gate / apply_operation |
修改当前 state |
&mut Self |
逐步执行固定参数 Gate/Operation。 |
apply_circuit |
修改当前 state |
&mut Self |
读取 Circuit 当前参数并逐门执行。 |
run |
不修改当前 state |
可微 F64 标量 Tensor |
训练与函数式前向。 |
amplitudes |
方法本身不改态 | 当前 C64 Tensor 的共享句柄 |
读取振幅，保留已有图连接。 |
sample_counts |
只读 | BTreeMap<String, usize> |
当前态的末端全量子比特抽样。 |
值得注意的是，apply_circuit 与 run 不能混为一谈。前者改变模拟器 state，所以多次调用会在已演化状态上继续作用；后者从调用方当前 state 复制出前向缓冲区并返回期望值，不改变 self。若需要反复从零态执行同一电路，可使用新模拟器或在 apply_circuit 前调用 reset；训练循环通常使用 run。
Rust amplitudes() 返回的共享 Tensor 不是独立数值副本；通过其存储执行原地写入会影响原状态，也可能破坏归一化或已记录图的版本约束。Python numpy() 则复制为独立数组。
初态导入与验证
单态 from_state_tensor 接受连续、CPU、Dense 的 C64 一维 Tensor，shape 必须严格为 [d]；batch 版本要求二维 [B, d]、batch 大小非零，并逐行检查归一化。其中，d 是状态空间维数，两种接口均采用该节给出的归一化容差。
从 Python NumPy 导入时，单态要求 C 连续 complex128 一维数组，batch 要求 C 连续 complex128 二维数组。绑定首先检查 Python 维度，再复制到 FlatC64 Tensor，随后由 Rust 模拟器执行同样的归一化与布局验证。
BatchStateVectorSimulator
BatchStateVectorSimulator 的 state 形状是 [batch_size, d]，每行是一条彼此独立的纯态。apply_circuit 对每一行施加相同电路；run 返回 shape 为 [batch_size] 的 F64 Tensor。Runtime 按行主序解释批量状态；启用 parallel feature 时，公开 Rust 层使用 Rayon 进行 batch 外层任务调度。因此线程数、批量大小、状态维度和内存带宽都会影响实际性能。
batch 的含义 batch 不是“一个量子态中的并行分支”，而是一批独立初态共享同一条 Circuit 与同一个 SparsePauliOp。它不能表达每条样本使用不同门拓扑或不同量子比特数的情形。Batch 路径适合在移植传统机器学习任务处理较大数据集时使用。