SPSAConfig¶
from cascaqit import SPSAConfig
SPSAConfig ¶
SPSAConfig(
learning_rate: float | None = 0.2,
perturbation: float = 0.1,
stability_constant: float = 0.0,
learning_rate_exponent: float = 0.602,
perturbation_exponent: float = 0.101,
directions_per_iteration: int = 1,
objective_repeats: int = 1,
max_objective_repeats: int | None = None,
objective_standard_error_target: float | None = None,
learning_rate_calibration: SPSALearningRateCalibrationConfig
| None = None,
stopping: SPSAStoppingConfig | None = None,
schema_version: str = ALGORITHM_SCHEMA_VERSION,
)
设置同时扰动随机近似（SPSA）的步长、方向数与重复估计。它通过随机正负扰动估计梯度，通常不需要逐个参数分别求导；每个方向仍需在正负两侧求值，重复估计会继续增加成本。
设迭代编号 k 从 0 开始，学习率为 a / (k + 1 + A)**alpha，扰动为 c / (k + 1)**gamma。a 对应 learning_rate，c 对应 perturbation，A 对应 stability_constant。c 必须为正，A 非负，alpha 在 (0.5, 1]，gamma 在 [0, 0.5]，且 alpha-gamma > 0.5。固定学习率尺度 a 必须为正；若启用 learning_rate_calibration，则必须显式设 learning_rate=None。
directions_per_iteration 是每次更新的正整数方向数。objective_repeats 是每个逻辑目标的固定重复次数或自适应模式的起始次数。自适应模式必须同时提供 max_objective_repeats 与正的 objective_standard_error_target，起始次数至少 2，上限严格大于起始次数。目标是重复估计的标准误差，不是能量真值误差；达到上限或预算也会停止重复。
当前 objective_repeats > 1 需要采样 VQE，不能直接用于精确目标路径。正负扰动点与更新点会受参数边界投影影响；扰动退化为同一点时会报错。stopping 可设置 SPSAStoppingConfig，其标准误差条件要求足够的方向数或重复数。
from cascaqit import SPSAConfig
fixed = SPSAConfig(learning_rate=0.2, perturbation=0.1)
adaptive = SPSAConfig(objective_repeats=2, max_objective_repeats=5,
objective_standard_error_target=0.02)
assert fixed.objective_repeat_mode == "fixed"
assert adaptive.objective_repeat_mode == "adaptive"
assert adaptive.effective_max_objective_repeats == 5
assert SPSAConfig.from_json(adaptive.to_json()) == adaptive
未设置 max_objective_repeats 时返回 fixed，否则返回 adaptive。这是配置模式，不代表某次运行已达到误差目标。
固定模式返回 objective_repeats，自适应模式返回 max_objective_repeats。此上限针对一个逻辑目标，不是整个优化过程。
从字典还原 SPSAConfig。省略字段使用默认值，嵌套配置还原后重新校验。 缺少必需字段或字段不合法时可能抛出 KeyError、TypeError 或 ValueError。
解析 JSON 对象并调用 from_dict()，返回 SPSAConfig。非法 JSON 会抛出解析错误；顶层不是对象时抛出 TypeError。
固定重复模式省略两个自适应字段；未启用的 stopping 和 learning_rate_calibration 也省略。 返回可写入 JSON 的字典，嵌套对象一并序列化。元组转成数组；这个字典是保存的声明，不是执行结果。
返回 JSON 字符串，不写文件。indent=None 使用紧凑格式；提供缩进宽度可便于阅读。
返回规范 JSON 的 SHA-256 十六进制摘要。字段、标识或元数据变化都可能改变摘要；它用于比较保存内容，不判断两个声明在物理上是否等价。