文档版本

VQESamplingBenchmarkConfig¶

from cascaqit import VQESamplingBenchmarkConfig

VQESamplingBenchmarkConfig ¶

VQESamplingBenchmarkConfig(
    repeats: int,
    objective_evaluation_budget: int,
    optimizer: OptimizerConfig,
    measurement: PauliMeasurementConfig,
    sampled_selection: SampledSelectionConfig,
    fixed_objective_repeats: int = 2,
    adaptive_objective_repeats: int = 2,
    adaptive_max_objective_repeats: int = 4,
    adaptive_standard_error_target: float = 0.05,
    final_shots: int = 1024,
    confidence_level: float = 0.95,
    root_seed: int = 0,
    schema_version: str = VQE_SAMPLING_BENCHMARK_SCHEMA_VERSION,
)

配置四种 VQE 目标估计策略的成对比较：exact、sampled_single、sampled_fixed、sampled_adaptive。传给 VQE.benchmark_sampling() 后才实际执行。同一轮共享派生种子与初始参数；repeats 至少为 2，每轮都执行四种策略。

optimizer 必须为 SPSA、starts=1、initialization="random"、seed=None，且不设置 max_evaluations 或 max_backend_executions；基准流程统一分配预算和种子。基础 SPSA 必须是单次、固定目标估计。objective_evaluation_budget 为正整数，至少是 4 * max(fixed_objective_repeats, adaptive_objective_repeats)；更多方向、校准或停止条件还可能要求更高预算，运行前仍会检查。

measurement 配置采样策略的分组与 shots，sampled_selection 配置独立候选确认。fixed_objective_repeats 与 adaptive_objective_repeats 至少为 2，adaptive_max_objective_repeats 严格大于起始次数，adaptive_standard_error_target 必须为正。final_shots 为正整数，confidence_level 在 (0,1) 内，root_seed 为非负整数。

共同的目标求值上限不代表四种策略使用相同后端调用数或总采样量；确认、最终采样和独立精确诊断另计。基准会额外精确评估采样策略选中的参数点。其“精确参考”来自同轮 exact 优化，不是已知基态；当前入口也没有 noise/options 参数。

from cascaqit import HamiltonianTerm, OptimizerConfig, PauliHamiltonian, PauliZ, VQE

vqe = VQE(PauliHamiltonian("z", (HamiltonianTerm("z", 1.0, PauliZ("q0")),),
                           logical_order=("q0",)))
from cascaqit import PauliMeasurementConfig, SampledSelectionConfig, VQESamplingBenchmarkConfig

config = VQESamplingBenchmarkConfig(
    repeats=2, objective_evaluation_budget=8,
    optimizer=OptimizerConfig(method="SPSA", max_iterations=1),
    measurement=PauliMeasurementConfig(shots_per_group=16),
    sampled_selection=SampledSelectionConfig(candidate_count=2, repeats_per_candidate=2),
    final_shots=8, root_seed=7,
)
assert config.optimizer.seed is None
assert config.objective_evaluation_budget == 8
assert VQESamplingBenchmarkConfig.from_json(config.to_json()) == config

from_dict ¶

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

从字典还原 VQESamplingBenchmarkConfig。必须提供 repeats、objective_evaluation_budget 和三种嵌套配置；恢复时重新执行策略与预算约束。缺少必需字段或字段不合法时可能抛出 KeyError、TypeError 或 ValueError。

from_json ¶

from_json(text: str) -> VQESamplingBenchmarkConfig

解析 JSON 对象并调用 from_dict()，返回 VQESamplingBenchmarkConfig。非法 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 十六进制摘要。字段、标识或元数据变化都可能改变摘要；它用于比较保存内容，不判断两个声明在物理上是否等价。