文档版本

PauliMeasurementConfig¶

from cascaqit import PauliMeasurementConfig

PauliMeasurementConfig ¶

PauliMeasurementConfig(
    shots_per_group: int = 1024,
    grouping: Literal[
        "qubit_wise_commuting"
    ] = "qubit_wise_commuting",
    allocation: Literal[
        "uniform", "coefficient_l1", "pilot_variance"
    ] = "uniform",
    pilot_shots_per_group: int | None = None,
    mitigation: ReadoutMitigationConfig | None = None,
    schema_version: str = MEASUREMENT_SCHEMA_VERSION,
)

配置有限采样的 Pauli 能量估计，传给 VQE.evaluate_sampled() 或 VQE.run() 的 measurement 参数。只支持逐比特对易分组 qubit_wise_commuting：同组各项在每个比特上的非恒等 Pauli 轴兼容，可以共享一批旋转基测量。构造配置本身不执行采样。

shots_per_group 必须是至少 2 的整数。若测量计划有 G 组，一次目标估计的总预算为 G * shots_per_group；constant 不增加测量组。恒等 Pauli 项按同一规则分组；只含恒等项的哈密顿量仍会产生一组。

allocation	如何分配采样
uniform	每组实际使用 shots_per_group 次
coefficient_l1	按各组系数绝对值之和分配总预算，每组至少 2 次
pilot_variance	先对每组试采样，再按组能量的观测方差分配剩余预算；通常每组有两次后端执行

只有 pilot_variance 接受 pilot_shots_per_group。试采样至少 2 次，并须为每组第二阶段留下至少 2 次，因此 shots_per_group 至少为 4。未显式指定时使用 resolved_pilot_shots_per_group 的规则。试采样与后续采样都计入总预算，应从返回计划和分配记录读取各组实际次数。

mitigation 可附加 ReadoutMitigationConfig。它使用显式校准计算缓解后的能量与不确定度，原始计数仍保留。

from cascaqit import HamiltonianTerm, PauliHamiltonian, PauliMeasurementConfig, PauliX, PauliZ, VQE

hamiltonian = PauliHamiltonian("xz", (
    HamiltonianTerm("x", 0.2, PauliX("q0")),
    HamiltonianTerm("z", 0.8, PauliZ("q0")),
), logical_order=("q0",))
measurement = PauliMeasurementConfig(shots_per_group=32, allocation="coefficient_l1")
result = VQE(hamiltonian).evaluate_sampled((0.3, 0.1), measurement=measurement, seed=7)
assert len(result.plan.groups) == 2
assert result.total_shots == 64
assert sum(group.shots for group in result.group_results) == 64
assert result.group_results[0].shots != result.group_results[1].shots

resolved_pilot_shots_per_group ¶

resolved_pilot_shots_per_group: int

返回显式试采样整数，或默认 max(2, min(32, shots_per_group // 4))。其他分配方式也能读取此计算值，但不会据此增加试采样阶段。构造时另行检查试采样是否为第二阶段留下足够预算。

from_dict ¶

from_dict(
    data: Mapping[str, Any],
) -> PauliMeasurementConfig

从字典还原 PauliMeasurementConfig。省略项使用默认值；嵌套缓解配置会还原并重新校验。缺少必需字段或字段不合法时可能抛出 KeyError、TypeError 或 ValueError。

from_json ¶

from_json(text: str) -> PauliMeasurementConfig

解析 JSON 对象并调用 from_dict()，返回 PauliMeasurementConfig。非法 JSON 会抛出解析错误；顶层不是对象时抛出 TypeError。

to_dict ¶

to_dict() -> dict[str, Any]

返回可写入 JSON 的字典，嵌套对象一并序列化。元组转成数组；这个字典是保存的声明，不是执行结果。

to_json ¶

to_json(*, indent: int | None = None) -> str

返回 JSON 字符串，不写文件。indent=None 使用紧凑格式；提供缩进宽度可便于阅读。

stable_hash ¶

stable_hash() -> str

返回规范 JSON 的 SHA-256 十六进制摘要。字段、标识或元数据变化都可能改变摘要；它用于比较保存内容，不判断两个声明在物理上是否等价。