VQESamplingBenchmarkResult¶
from cascaqit import VQESamplingBenchmarkResult
VQESamplingBenchmarkResult ¶
VQESamplingBenchmarkResult(
benchmark_id: str,
algorithm_id: str,
hamiltonian_hash: str,
ansatz_hash: str,
logical_order: tuple[str, ...],
config: VQESamplingBenchmarkConfig,
runs: tuple[VQESamplingBenchmarkRunIR, ...],
statistics: tuple[VQESamplingStrategyStatisticsIR, ...],
optimality_claim: Literal[
"not_claimed"
] = "not_claimed",
schema_version: str = VQE_SAMPLING_BENCHMARK_SCHEMA_VERSION,
)
保存四种策略的全部运行与汇总统计，通常由 VQE.benchmark_sampling() 返回。runs 按“重复轮次优先、每轮四种固定策略”的顺序排列；statistics 按 exact、sampled_single、sampled_fixed、sampled_adaptive 排列。各运行必须共享哈密顿量、ansatz 和逻辑顺序，同轮还要共享种子与初值。
每个 run 保存完整 VariationalResult。selected_estimator_energy 是该策略的选点估计；exact_selected_energy 是该参数点的精确能量，采样策略有独立 exact_check。estimator_error 衡量估计偏差，paired_exact_reference_gap 比较该点与同轮 exact 优化选点的精确能量，不是与真实基态的差距。精确策略本身不需要额外 exact_check。
成本字段分别记录优化求值、后端调用、采样、候选确认、最终采样及诊断。statistics 汇总重复实验的均值、样本方差、标准误差、区间、估计误差均方根与成对差距。少量重复只适合演示，不能据此宣称某策略普遍更优。
config 保留实验设计，benchmark_id 与摘要记录绑定内容；optimality_claim 固定为 not_claimed。直接构造与恢复会检查完整策略矩阵、成对条件、成本、统计来源和 ID。
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,
)
from cascaqit import VQESamplingBenchmarkResult
result = vqe.benchmark_sampling(config)
assert len(result.runs) == 8
assert tuple(item.strategy for item in result.statistics) == (
"exact", "sampled_single", "sampled_fixed", "sampled_adaptive")
assert all(item.objective_evaluation_count <= 8 for item in result.runs)
assert result.optimality_claim == "not_claimed"
assert VQESamplingBenchmarkResult.from_json(result.to_json()).stable_hash() == result.stable_hash()
create ¶
create(
*,
algorithm_id: str,
config: VQESamplingBenchmarkConfig,
runs: Sequence[VQESamplingBenchmarkRunIR],
) -> VQESamplingBenchmarkResult
从完整且按规定顺序排列的已完成 VQESamplingBenchmarkRunIR 序列计算四组统计与 benchmark_id，返回结果。不会替你执行缺少的策略；输入必须非空，并覆盖 config.repeats 的全部四种策略。
report ¶
report(
output: str | PathLike[str] | None = None,
*,
language: Literal["en", "zh"] = "en",
title: str | None = None,
) -> ExperimentReport
返回 algorithm 类型 ExperimentReport，可用 output 保存 HTML，title 设置标题。language 只控制本次实际保存；output=None 时之后渲染或保存仍需指定语言。目录须已存在，现有目标文件可被覆盖，规则与 visualize() 相同。
从字典还原 VQESamplingBenchmarkResult。恢复每轮完整结果与精确诊断，重新验证策略顺序、配对、统计和来源标识。 缺少必需字段或字段不合法时可能抛出 KeyError、TypeError 或 ValueError。
解析 JSON 对象并调用 from_dict()，返回 VQESamplingBenchmarkResult。非法 JSON 会抛出解析错误；顶层不是对象时抛出 TypeError。
返回完整记录的 JSON 兼容字典，嵌套对象也会序列化。它保存已有数据，不重新执行实验。
返回完整记录的 JSON 字符串；indent 可设置缩进，不写文件。
返回完整记录规范 JSON 的 SHA-256 摘要，用于内容比较与来源引用。它不证明实验结论正确，也不等于物理等价性判断。