文档版本

AdamIterationIR¶

from cascaqit import AdamIterationIR

AdamIterationIR ¶

AdamIterationIR(
    iteration_index: int,
    config: AdamConfig,
    center_objective_evaluation_index: int,
    updated_objective_evaluation_index: int,
    center_parameters: Mapping[str, float],
    gradient_index: int,
    gradient_hash: str,
    gradient: Mapping[str, float],
    gradient_covariance: Mapping[str, Mapping[str, float]],
    gradient_standard_errors: Mapping[str, float],
    gradient_uncertainty_norm: float,
    gradient_repeat_count: int,
    gradient_repeat_stop_reason: Literal[
        "fixed_repeats",
        "target_reached",
        "max_repeats_reached",
        "evaluation_budget_exhausted",
        "backend_budget_exhausted",
    ],
    previous_first_moment: Mapping[str, float],
    previous_second_moment: Mapping[str, float],
    first_moment: Mapping[str, float],
    second_moment: Mapping[str, float],
    bias_corrected_first_moment: Mapping[str, float],
    bias_corrected_second_moment: Mapping[str, float],
    step: Mapping[str, float],
    bounds: Mapping[str, tuple[float, float]],
    unprojected_parameters: Mapping[str, float],
    updated_parameters: Mapping[str, float],
    update_norm: float,
    projection_applied: bool,
    gradient_objective_evaluation_count: int,
    gradient_backend_execution_count: int,
    gradient_total_shots: int,
    iteration_hash: str = "",
    schema_version: str = ADAM_SCHEMA_VERSION,
)

保存一次 Adam 更新及其关联梯度，通常从 result.optimization_starts[i].adam_iterations 读取。iteration_index 从 0 开始；center_objective_evaluation_index 与 updated_objective_evaluation_index 指向更新前后的目标记录，后者必须紧随前者。gradient_index/hash 关联梯度记录，不代表在读取时重新计算梯度。

字段组	含义
center_parameters、gradient	当前参数与保存的梯度，各映射必须使用同一参数顺序
gradient_covariance、gradient_standard_errors、gradient_uncertainty_norm	梯度估计协方差、对角方差平方根及 sqrt(trace(covariance))，与梯度范数不同
gradient_repeat_count、gradient_repeat_stop_reason	重复估计次数及因固定次数、目标、上限或预算停止的原因
previous_、first_moment、second_moment、bias_corrected_	上一时刻动量、本次动量及偏差修正后的动量
step、unprojected_parameters、updated_parameters、bounds	Adam 步长向量、减去步长后的参数、边界投影后的参数与边界
update_norm、projection_applied	实际参数更新范数及本次更新是否受边界投影影响
gradient_objective_evaluation_count、gradient_backend_execution_count、gradient_total_shots	此梯度估计的成本，不是整个优化的总成本

直接构造会重新核对动量、更新公式、不确定度、投影与摘要。iteration_hash 省略或为空时自动计算，否则必须匹配内容；不要手工拼接不相符的计算记录。

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

vqe = VQE(PauliHamiltonian("z", (HamiltonianTerm("z", 1.0, PauliZ("q0")),),
                           logical_order=("q0",)))
from cascaqit import AdamIterationIR
from cascaqit.algorithms import GradientConfig

result = vqe.run(optimizer=OptimizerConfig(method="ADAM", max_iterations=1,
    gradient=GradientConfig(), seed=7), initial_parameters=(0.4, 0.2), final_shots=8)
iteration = result.optimization_starts[0].adam_iterations[0]
assert iteration.verify_hash()
assert iteration.updated_objective_evaluation_index == iteration.center_objective_evaluation_index + 1
assert AdamIterationIR.from_json(iteration.to_json()).iteration_hash == iteration.iteration_hash

create ¶

create(
    *,
    iteration_index: int,
    config: AdamConfig,
    center_objective_evaluation_index: int,
    updated_objective_evaluation_index: int,
    center_parameters: Mapping[str, float],
    gradient_index: int,
    gradient_hash: str,
    gradient: Mapping[str, float],
    gradient_covariance: Mapping[str, Mapping[str, float]],
    gradient_standard_errors: Mapping[str, float],
    gradient_uncertainty_norm: float,
    gradient_repeat_count: int,
    gradient_repeat_stop_reason: Literal[
        "fixed_repeats",
        "target_reached",
        "max_repeats_reached",
        "evaluation_budget_exhausted",
        "backend_budget_exhausted",
    ],
    previous_first_moment: Mapping[str, float],
    previous_second_moment: Mapping[str, float],
    bounds: Mapping[str, tuple[float, float]],
    gradient_objective_evaluation_count: int,
    gradient_backend_execution_count: int,
    gradient_total_shots: int,
) -> AdamIterationIR

从参数、梯度、上一时刻动量、配置与来源索引计算本次动量、偏差修正、步长、边界投影及摘要，返回 AdamIterationIR。它只计算一次经典更新，不调用后端，也不评估更新后能量；传入索引和成本必须来自真实记录。

compute_iteration_hash ¶

compute_iteration_hash() -> str

计算除 iteration_hash 字段自身以外的保存内容摘要，返回 SHA-256 十六进制字符串，不改写对象。与包含该字段的 stable_hash() 用途不同。

verify_hash ¶

verify_hash() -> bool

比较保存的 iteration_hash 与重新计算的摘要，返回布尔值。它检查内容一致性，不重新运行量子实验。

from_dict ¶

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

从字典还原 AdamIterationIR。还原所有梯度与动量字段，并重新验证更新公式、协方差派生量和摘要。缺少必需字段或字段不合法时可能抛出 KeyError、TypeError 或 ValueError。

from_json ¶

from_json(text: str) -> AdamIterationIR

解析 JSON 对象并调用 from_dict()，返回 AdamIterationIR。非法 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 摘要，用于内容比较与来源引用。它不证明实验结论正确，也不等于物理等价性判断。