QAOA¶
from cascaqit import QAOA
QAOA ¶
QAOA(
problem: OptimizationProblem,
layers: int = 1,
mis_penalty: float = 2.0,
mwis_penalty: float | None = None,
algorithm_id: str | None = None,
)
从 GraphProblemIR、MISInstance、MWISProblemIR、QUBOProblemIR 或 IsingModelIR 构造 QAOA。图输入按 MIS 处理；一般 PauliHamiltonian 不是这个构造器的输入。投影后的目标只能含单体 Z、双体 ZZ 与常数。layers 必须为正整数；algorithm_id 缺省来自问题标识。
mis_penalty 用于 MIS 投影，必须为有限实数且大于1。mwis_penalty 用于 MWIS，必须为正且严格超过每条边两端较小权重的最大值；缺省值由问题权重计算。QUBO/Ising 已给定目标，不使用这些罚项重新构造约束。
参数顺序先列全部 gamma，再列全部 beta。所有角度按弧度使用；数值映射必须完整匹配 parameter_names，序列必须按其顺序且长度一致。各值为有限实数，不接受布尔值。
下面将所有角度设为0，得到均匀分布，能量等于四个二进制赋值的平均值；随后运行一次短优化。
from math import isclose
from cascaqit import OptimizerConfig, QAOA, QUBOProblemIR
problem = QUBOProblemIR.from_terms(problem_id="pair", linear_terms={"a": -1, "b": -2},
quadratic_terms={("a", "b"): 3}, offset=0.25)
qaoa = QAOA(problem, layers=2)
assert qaoa.parameter_names == ("gamma_0", "gamma_1", "beta_0", "beta_1")
assert isclose(qaoa.evaluate((0.0, 0.0, 0.0, 0.0)).energy, -0.5, abs_tol=1e-12)
result = qaoa.run(optimizer=OptimizerConfig(method="SPSA", max_iterations=1, seed=7),
initial_parameters=(0.1, 0.2, 0.3, 0.4), final_shots=16)
assert sum(result.final_result.counts.values()) == 16
assert result.optimality_claim == "not_claimed"
assert qaoa.build_circuit() is not qaoa.build_circuit()
运行入口使用本地 CPU 后端，backend=None 使用默认本地后端。含噪精确目标要求受支持的密度矩阵执行；此入口不提供有限采样目标配置。完整路线见优化课程。
返回投影后的 PauliHamiltonian，包括常数偏移和逻辑比特顺序。常数影响报告能量，不影响优化线路中的测量概率。
返回 gamma_0…gamma_(p-1)，随后 beta_0…beta_(p-1) 的元组，p 为层数；不是按每层交错排列。
返回新的参数化 Circuit：先对每个比特施加 H；每层单Z项使用 RZ(2coefficientgamma)，ZZ项分解为 CX–RZ–CX，再对每个比特施加 RX(2*beta)。返回线路没有末端测量。常数仅产生全局相位，因此不加入门序列。
返回门分解前的 QAOAAnsatzPlanIR，保留问题、哈密顿量、层次操作和参数，用于检查代价层结构。它不执行线路。
返回规范的 QAOALogicalScheduleResultIR，描述逻辑操作排布。它不是设备脉冲时序，也不表示已通过硬件编译或执行。
返回 AnsatzSpecIR，记录 QAOA 层数、逻辑比特顺序、参数名与构造元数据，用于结果来源核对。
从新建线路的声明返回 ParameterSchemaIR；读取 schema 不执行求值。
evaluate ¶
evaluate(
parameters: ParameterValues,
*,
backend: LocalBackend | None = None,
evaluation_index: int = 0,
algorithm_run_id: str | None = None,
seed: int | None = None,
noise: NoiseModel | None = None,
options: SimulationOptions | None = None,
) -> ObjectiveEvaluationIR
同步执行一个后端 Job，返回精确目标的 ObjectiveEvaluationIR。parameters 为完整映射或有序序列；energy 包含常数。evaluation_index 标识记录，algorithm_run_id 关联实验，seed/noise/options 传给受支持的执行路径。这里没有 measurement 参数，目标能量不是有限采样估计。
gradient ¶
gradient(
parameters: ParameterValues,
*,
backend: LocalBackend | None = None,
gradient_index: int = 0,
objective_evaluation_offset: int = 0,
max_backend_executions: int | None = None,
algorithm_run_id: str | None = None,
seed: int | None = None,
config: GradientConfig | None = None,
noise: NoiseModel | None = None,
options: SimulationOptions | None = None,
) -> ObjectiveGradientIR
返回参数移位 ObjectiveGradientIR，config=None 使用默认 GradientConfig。共享 gamma/beta 可能控制多个门，梯度按门级移位与链式法则合并，不应直接对整个共享参数套用两点公式。gradient_index、objective_evaluation_offset 用于编号，max_backend_executions 限制此次预算。此接口只提供精确目标梯度。
run ¶
run(
*,
backend: LocalBackend | None = None,
optimizer: OptimizerConfig | None = None,
initial_parameters: ParameterValues | None = None,
algorithm_run_id: str | None = None,
final_shots: int = 2048,
noise: NoiseModel | None = None,
options: SimulationOptions | None = None,
) -> VariationalResult
同步返回 VariationalResult，执行精确目标优化后，在 selected_evaluation 对应参数处做 final_shots 次计算基采样。optimizer=None 使用 OptimizerConfig()；initial_parameters 缺省时由配置生成。final_shots 不改变优化能量的估计方式。读取 termination 了解停止原因，候选质量可与问题基线比较，但达到迭代或预算上限不代表收敛。