VariationalResult¶
from cascaqit import VariationalResult
VariationalResult ¶
VariationalResult(
algorithm_run_id: str,
algorithm_kind: AlgorithmKind,
hamiltonian: PauliHamiltonian,
ansatz: AnsatzSpecIR,
optimizer: OptimizerConfig,
evaluations: tuple[VariationalObjectiveT, ...],
best_evaluation_index: int,
termination: OptimizerTerminationIR,
gradients: tuple[ObjectiveGradientIR, ...] = (),
optimization_starts: tuple[
OptimizationStartIR, ...
] = (),
selected_start_index: int | None = None,
sampled_selection: SampledSelectionIR | None = None,
final_result: ResultIR | None = None,
most_probable_candidate: AlgorithmCandidateIR
| None = None,
best_observed_candidate: AlgorithmCandidateIR
| None = None,
baseline: ClassicalBaselineIR | None = None,
cardinality_subspace: CardinalitySubspaceEvidenceIR
| None = None,
problem_id: str | None = None,
problem_hash: str | None = None,
optimality_claim: Literal[
"not_claimed"
] = "not_claimed",
metadata: Mapping[str, Any] = dict(),
schema_version: str = ALGORITHM_SCHEMA_VERSION,
)
VQE 或 QAOA 的完整工作流结果，关联哈密顿量、ansatz、优化配置、目标求值、梯度、多初值记录、确认采样与最终后端结果。通常由算法 run() 返回，直接构造主要用于恢复或高级集成；构造器会核对引用、来源、选择结果和记录一致性。
evaluations 保存优化历史。SPSA 使用重复估计时，best_evaluation_index 指向按合并目标选中的来源记录；其他路径按最低观测能量选择。若使用独立候选确认，最终选点可能不同，应读取 selected_evaluation；它返回对应的优化历史记录，确认后的汇总统计在 sampled_selection 中。termination 与各 optimization_starts[i].termination 说明停止原因，不能仅凭 success 判断得到全局最优。
final_result 是可选 ResultIR，保存最终计算基采样。most_probable_candidate 是出现最多的候选，best_observed_candidate 是按问题目标评估的最佳已见候选，二者含义不同。一般 Pauli 哈密顿量可能没有经典问题候选或 baseline。cardinality_subspace 保存适用的固定基数子空间记录，problem_id/hash 保存问题来源；optimality_claim 固定为 not_claimed。
阅读成本时合计优化、确认、最终采样与独立诊断各阶段，不要用 evaluations 数量代替后端调用数或总 shots。
from cascaqit import HamiltonianTerm, OptimizerConfig, PauliHamiltonian, PauliZ, VQE
vqe = VQE(PauliHamiltonian("z", (HamiltonianTerm("z", 1.0, PauliZ("q0")),),
logical_order=("q0",)))
result = vqe.run(optimizer=OptimizerConfig(method="SPSA", max_iterations=2, seed=7),
initial_parameters=(0.4, 0.2), final_shots=16)
from cascaqit import VariationalResult
assert result.best_evaluation.energy == min(item.energy for item in result.evaluations)
assert result.selected_evaluation is result.best_evaluation
assert sum(result.final_result.counts.values()) == 16
restored = VariationalResult.from_json(result.to_json())
assert restored.stable_hash() == result.stable_hash()
assert restored.optimality_claim == "not_claimed"
返回 evaluations[best_evaluation_index]。重复估计的 SPSA 按各初值的合并目标选择，因此该来源记录不一定是单次采样能量最低的一项；应同时查看各初值的 best_objective 与合并估计。其他路径选择最低观测能量，两者都不是已知真实最小值。
未做候选确认时等于 best_evaluation；否则根据 sampled_selection.selected_source_evaluation_index 返回被确认选中的原始求值记录。独立确认统计并不会覆盖这个原始记录。
有显式梯度记录时返回第一项的共享 ParameterShiftPlanIR，否则返回 None。SPSA 的扰动记录保存在各初值的 spsa_iterations，不通过此属性返回。
diagnose_stability ¶
diagnose_stability(
config: VQEStabilityConfig | None = None,
) -> VQEStabilityDiagnosticResult
从保存的记录生成 VQEStabilityDiagnosticResult，不重跑优化。config=None 使用默认阈值。当前只支持具有 optimization_starts 的原生 SPSA VQE；QAOA、Adam 或其他优化器会被拒绝。
从字典还原 VariationalResult。还原精确或采样求值、梯度、初值、确认和最终 ResultIR，再重新检查关联与派生结果。 缺少必需字段或字段不合法时可能抛出 KeyError、TypeError 或 ValueError。
解析 JSON 对象并调用 from_dict()，返回 VariationalResult。非法 JSON 会抛出解析错误；顶层不是对象时抛出 TypeError。
返回完整记录的 JSON 兼容字典，嵌套对象也会序列化。它保存已有数据，不重新执行实验。
返回完整记录的 JSON 字符串；indent 可设置缩进，不写文件。
返回完整记录规范 JSON 的 SHA-256 摘要，用于内容比较与来源引用。它不证明实验结论正确，也不等于物理等价性判断。