文档版本

VQEStabilityDiagnosticResult¶

from cascaqit import VQEStabilityDiagnosticResult

VQEStabilityDiagnosticResult ¶

VQEStabilityDiagnosticResult(
    diagnostic_id: str,
    source_result_hash: str,
    source_result: VariationalResult[Any],
    config: VQEStabilityConfig,
    starts: tuple[VQEStartStabilityDiagnosticIR, ...],
    selected_start_index: int,
    status: VQEStabilityStatus,
    optimality_claim: Literal[
        "not_claimed"
    ] = "not_claimed",
    convergence_claim: Literal[
        "not_claimed"
    ] = "not_claimed",
    schema_version: str = VQE_STABILITY_SCHEMA_VERSION,
)

保存一次只读稳定性诊断及完整源结果。只接受原生 SPSA 的 VQE 记录。常用入口为 result.diagnose_stability() 或 create()，不建议手工填写 starts 与 status。

source_result/hash 绑定原始结果，config 保存阈值，starts 保存各初值的末尾窗口、逐项检查、成本与终止原因。selected_start_index 沿用原结果的选中初值；总体 status 只采用该初值的状态，不能理解为所有初值均稳定。状态为 stable、unstable 或 insufficient_evidence。

直接构造或恢复会从源结果重新推导各初值诊断，核对源摘要、诊断 ID 与总体状态。optimality_claim 和 convergence_claim 必须都是 not_claimed。更改阈值需重新 create()，不能只改已保存状态。

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 VQEStabilityConfig, VQEStabilityDiagnosticResult

diagnostic = VQEStabilityDiagnosticResult.create(result, VQEStabilityConfig())
assert diagnostic.status == "insufficient_evidence"
assert diagnostic.convergence_claim == "not_claimed"
restored = VQEStabilityDiagnosticResult.from_json(diagnostic.to_json())
assert restored.stable_hash() == diagnostic.stable_hash()
assert diagnostic.report().profile == "algorithm"

create ¶

create(
    source_result: VariationalResult[Any],
    config: VQEStabilityConfig,
) -> VQEStabilityDiagnosticResult

根据完整源结果与 VQEStabilityConfig 推导诊断、生成 ID 和源摘要，返回 VQEStabilityDiagnosticResult，不调用模拟器。类型不符、非 SPSA VQE 或缺少初值记录会报错。

report ¶

report(
    output: str | PathLike[str] | None = None,
    *,
    language: Literal["en", "zh"] = "en",
    title: str | None = None,
) -> ExperimentReport

返回 algorithm 类型 ExperimentReport。output 非空时立即保存 HTML，language 选择该次保存的中/英文，title 可自定义标题。output=None 时只返回报告；之后 to_html()/save() 仍需显式传 language，不会保留本次语言参数。

from_dict ¶

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

从字典还原 VQEStabilityDiagnosticResult。恢复完整源结果与配置，重算并核对各项诊断；源数据、摘要或状态不一致会拒绝。缺少必需字段或字段不合法时可能抛出 KeyError、TypeError 或 ValueError。

from_json ¶

from_json(text: str) -> VQEStabilityDiagnosticResult

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

to_dict ¶

to_dict() -> dict[str, Any]

返回完整记录的 JSON 兼容字典，嵌套对象也会序列化。它保存已有数据，不重新执行实验。

to_json ¶

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

返回完整记录的 JSON 字符串；indent 可设置缩进，不写文件。

stable_hash ¶

stable_hash() -> str

返回完整记录规范 JSON 的 SHA-256 摘要，用于内容比较与来源引用。它不证明实验结论正确，也不等于物理等价性判断。