4. 实验参数与元数据管理

在量子计算实验中，一个电路能否被正确执行、结果能否被复现，往往不取决于算法本身有多复杂，而取决于一组容易被忽视的“伴随信息”：这段电路实际跑在哪些物理量子比特上、当时这些比特的校准状态如何、门被编译成了什么形式、随机数从哪个种子出发、整个实验的配置是什么版本。这些信息统称为实验参数与元数据。本节讨论如何把它们规范化地记录下来，使一次实验从“跑过一次”变成“可被他人精确重跑”。

为什么元数据决定可复现性

量子硬件是时变的。同一个逻辑电路，今天映射到物理比特 (0,1,2)，明天可能因为某个比特的读出误差升高而被映射到 (3,4,5)；同一个 CNOT 门，在不同校准周期下的错误率可能相差数倍。如果只保存“电路 + 测量计数”，复现者拿到的是一份无法对齐的结果。因此，元数据不是附属品，而是实验记录的一等公民。它至少要回答五个问题：跑在哪些物理比特上（映射）、当时硬件状态如何（校准）、门如何被实现（门参数）、随机性从何而来（种子）、整体配置是什么（配置文件）。

量子比特映射：从逻辑到物理的对应关系

量子程序通常以逻辑比特编号书写，例如 qc = QuantumCircuit(3) 中的 0、1、2。但真实后端只提供带拓扑约束的物理比特，例如线性链 (0—1—2—3—4) 或重六边形耦合图。编译器需要把逻辑比特分配到物理比特上，这一过程称为布局（layout）；当两个逻辑比特之间的门无法直接在相邻物理比特上执行时，还要插入 SWAP 门来移动量子态，这一过程称为路由（routing）。

记录映射时，至少要保存三样东西：初始布局（逻辑 i → 物理 q）、最终布局（经过 SWAP 后的对应关系）、插入的 SWAP 数量与位置。例如一次 3 比特实验可能记录为：初始布局 {0→1, 1→2, 2→3}，最终布局 {0→2, 1→1, 2→3}，插入 SWAP 2 个。复现者据此可以判断：如果换一个后端或换一个优化等级，映射结果会不同，因此不能简单地把计数结果直接对比。

校准数据：硬件状态的“时间戳快照”

校准数据描述的是某个时刻硬件的工作状态，主要包括：每个物理比特的 T1（能量弛豫时间）、T2（相位退相干时间）、读出误差（把 |0⟩ 误判为 |1⟩ 或反之的概率）、单比特门错误率、两比特门错误率，以及 读出频率、驱动频率 等。这些量会随温度漂移、电磁环境变化而缓慢变化，因此校准数据必须带采集时间戳和校准周期编号。

一个常见的做法是：在实验记录中保存一份“校准快照”，只包含本次实验实际用到的物理比特及其相邻耦合边的参数。例如：

calibration_snapshot:
  backend: ibm_brisbane
  timestamp: 2025-03-14T09:22:31Z
  qubits:
    - id: 1  T1: 182.4us  T2: 96.7us  readout_err: 0.012
    - id: 2  T1: 210.1us  T2: 143.2us readout_err: 0.008
    - id: 3  T1: 155.8us  T2: 88.3us  readout_err: 0.021
  edges:
    - (1,2)  cx_err: 0.0071
    - (2,3)  cx_err: 0.0094

注意这些数值是示例，用于说明字段结构，并非某次真实校准结果。复现者拿到这份快照后，可以判断当时的硬件质量是否足以支撑该实验的结论。

门参数：编译后的实际实现

逻辑门与物理实现之间往往不是一一对应。一个逻辑 CNOT 可能被编译成 ECR + 单比特旋转 的组合；一个任意旋转门可能被分解为若干 √X 和 RZ。门参数记录的是编译后实际下发的脉冲级或门级指令，包括：门类型、作用比特、旋转角度、脉冲时长、脉冲幅度、以及该门的标定错误率。

如果实验使用了随机化编译（randomized compiling），还要记录每个门被包裹的随机 Pauli 层及其种子。否则，即使电路相同，不同随机化实例下的错误率也会有统计差异，导致结果无法对齐。

随机种子：让随机性可重放

量子实验中的随机性来源不止一种：测量坍缩本身是概率性的，但给定电路和 shots 后，其统计行为由后端决定；随机化编译、随机基准测试中的随机序列、参数化电路的随机初始化、采样顺序等则依赖伪随机数生成器。要让这些环节可复现，必须记录：

• 主种子（master seed）：整个实验的根种子，通常是一个整数，如 seed=20250314。
• 派生种子：由主种子按固定规则派生出各子模块的种子，例如 seed_rc = hash(master, "rc")、seed_init = hash(master, "init")。
• 随机化编译实例编号：如果同一电路跑了多个随机化实例，记录实例数与每个实例的种子。

需要强调的是：种子只能保证经典随机过程可重放，不能保证量子测量结果逐次相同。复现的目标是统计分布一致，而不是单次计数完全一致。

实验配置文件：把一切固定下来

配置文件是上述所有参数的容器，通常采用 YAML 或 JSON 格式，并带有版本号与内容哈希。一个规范的配置文件至少包含：后端名称、shots 数、优化等级、映射策略、是否启用随机化编译、校准快照引用、门参数引用、随机种子、以及实验唯一 ID。下面是一个可直接参考的配置样例：

experiment_id: exp-20250314-001
version: 1.2.0
backend: ibm_brisbane
shots: 4096
optimization_level: 3
mapping:
  strategy: sabre
  initial_layout: {0: 1, 1: 2, 2: 3}
  final_layout:   {0: 2, 1: 1, 2: 3}
  swap_count: 2
calibration_ref: cal-20250314-0922
gate_params_ref: gate-20250314-0922
randomization:
  enabled: true
  master_seed: 20250314
  rc_instances: 8
  rc_seed_rule: "hash(master, instance_id)"
result_ref: result-20250314-001
config_hash: "sha256:9f2c...e1a7"

其中 config_hash 是对配置文件内容计算的哈希值，用于快速判断两次实验是否使用了完全相同的配置。只要哈希一致，就可以认为参数层面完全对齐；哈希不同，则需要逐字段比对差异。

规范化记录的最小检查清单

综合以上内容，一次可复现的量子实验记录至少应包含以下字段。可以把这份清单作为实验提交前的自检表：