SPSAIterationIR¶
from cascaqit import SPSAIterationIR
SPSAIterationIR ¶
SPSAIterationIR(
iteration_index: int,
learning_rate: float,
perturbation: float,
center_parameters: Mapping[str, float],
directions: tuple[SPSADirectionIR, ...],
gradient_estimate: Mapping[str, float],
gradient_standard_error: Mapping[str, float] | None,
unprojected_parameters: Mapping[str, float],
updated_parameters: Mapping[str, float],
update_norm: float,
projection_applied: bool,
schema_version: str = ALGORITHM_SCHEMA_VERSION,
)
保存一次 SPSA 更新，通常从 result.optimization_starts[i].spsa_iterations 读取。learning_rate 与 perturbation 是本轮实际值，已经应用随迭代编号变化的公式；iteration_index 从 0 开始。
directions 保存各随机方向的正负参数、重复目标估计与方向梯度。gradient_estimate 是这些方向梯度的均值。只有一个方向时 gradient_standard_error 为 None；至少两个方向时，它按方向间样本标准差除以方向数平方根计算，不能当作所有误差来源的总和。
center_parameters、unprojected_parameters、updated_parameters 分别保存更新前、减去学习率乘梯度后、投影后的参数。update_norm 是实际更新的欧氏范数。projection_applied 可由扰动点或更新点触碰边界触发，不只描述最终点。
各参数映射必须有相同的有序键，方向编号从 0 连续排列。构造和恢复会复核方向梯度、平均梯度、标准误差与更新范数；它不会调用后端补全缺失记录。
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 SPSAIterationIR
iteration = result.optimization_starts[0].spsa_iterations[0]
assert iteration.iteration_index == 0
assert len(iteration.directions) == 1
assert iteration.gradient_standard_error is None
assert SPSAIterationIR.from_dict(iteration.to_dict()).stable_hash() == iteration.stable_hash()
从字典还原 SPSADirectionIR 等嵌套记录并重新验证派生值，返回 SPSAIterationIR。缺字段或不一致记录会报错。没有 from_json()；JSON 文本先用 json.loads() 解析。
返回完整记录的 JSON 兼容字典，嵌套对象也会序列化。它保存已有数据，不重新执行实验。
返回完整记录的 JSON 字符串；indent 可设置缩进，不写文件。
返回完整记录规范 JSON 的 SHA-256 摘要，用于内容比较与来源引用。它不证明实验结论正确，也不等于物理等价性判断。