VQE¶
from cascaqit import VQE
VQE ¶
VQE(
operator: VQEInput,
layers: int = 1,
ansatz: HardwareEfficientAnsatz
| CardinalityPreservingAnsatz
| Circuit
| None = None,
algorithm_id: str | None = None,
)
为 PauliHamiltonian、QUBOProblemIR 或 IsingModelIR 构造变分量子本征求解器。QUBO 与 Ising 输入先转换成 Pauli 哈密顿量；layers 必须为正整数。ansatz=None 时，每层依次执行 RY、RZ 旋转，再沿逻辑比特顺序施加线性 CX 纠缠。可从 cascaqit.algorithms 导入 HardwareEfficientAnsatz 或 CardinalityPreservingAnsatz 改变结构。
显式 Circuit 的比特及顺序必须与哈密顿量一致，不能含末端测量，必须含未绑定且全部被引用的参数。构造器保存线路快照；layers 不会把自定义线路自动重复，也不支持为它执行自动增层实验。algorithm_id 缺省由哈密顿量标识生成。
求值接受名称完全匹配的映射，或按 parameter_names 排列的数值序列。值必须是有限实数，不能为布尔值。backend=None 使用本地后端；这些接口执行本地 CPU 模拟。含噪精确目标要求密度矩阵路径，有限采样目标可使用受支持的密度矩阵或轨迹路径，具体配置仍需通过执行前检查。
单比特例子用 cos(theta) 和解析导数核对求值与梯度：
from math import cos, sin, isclose
from cascaqit import HamiltonianTerm, PauliHamiltonian, PauliZ, VQE
vqe = VQE(PauliHamiltonian("z", (HamiltonianTerm("z", 1.0, PauliZ("q0")),),
logical_order=("q0",)))
point = (0.4, 0.2)
evaluation = vqe.evaluate(point)
assert isclose(evaluation.energy, cos(point[0]), abs_tol=1e-12)
gradient = vqe.gradient(point)
assert isclose(gradient.gradient[vqe.parameter_names[0]], -sin(point[0]), abs_tol=1e-12)
assert abs(gradient.gradient[vqe.parameter_names[1]]) < 1e-12
assert vqe.build_circuit() is not vqe.build_circuit()
有限采样优化应分别设置目标测量次数、候选确认次数和最终采样次数：
from cascaqit import OptimizerConfig, PauliMeasurementConfig, SampledSelectionConfig
result = vqe.run(
optimizer=OptimizerConfig(method="SPSA", max_iterations=1, seed=7),
initial_parameters=point,
measurement=PauliMeasurementConfig(shots_per_group=32),
sampled_selection=SampledSelectionConfig(candidate_count=2, repeats_per_candidate=2),
final_shots=16,
)
assert result.sampled_selection is not None
assert sum(result.final_result.counts.values()) == 16
assert result.optimality_claim == "not_claimed"
完整实验见有限采样 VQE。结果字段见 VariationalResult。
返回实际求值的 PauliHamiltonian，包含输入转换后的常数与逻辑比特顺序。读取属性不执行模拟。
返回线路声明顺序下的参数名元组。使用位置序列时按此顺序赋值，自定义线路的顺序也以此为准。
返回独立的参数化 Circuit 快照。修改返回线路不会改变后续构建的线路；这里只构造，不绑定参数或求值。
返回 AnsatzSpecIR，记录结构、层数、逻辑顺序、参数、所需门及来源。它描述构造方案，不包含优化结果。
返回 ParameterSchemaIR，保留参数的顺序、类型、单位及边界，用于绑定与结果核对。
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
同步返回一次精确目标求值的 ObjectiveEvaluationIR；energy 含哈密顿量常数。内部执行一个后端 Job，未对能量做有限次数采样。evaluation_index 标识该记录，algorithm_run_id 关联实验，seed 传给执行路径。noise/options 决定受支持的含噪方法；含噪精确目标仍来自密度矩阵期望值。
evaluate_sampled ¶
evaluate_sampled(
parameters: ParameterValues,
*,
measurement: PauliMeasurementConfig | None = None,
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,
) -> SampledObjectiveEvaluationIR
按 Pauli 测量分组执行有限采样，返回 SampledObjectiveEvaluationIR，包含能量估计、标准误差、分组计数与成本。measurement=None 使用 PauliMeasurementConfig()。一次方法调用可执行多个后端 Job；使用返回记录中的成本，不按调用次数估算 shots。
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,
measurement: PauliMeasurementConfig | None = None,
noise: NoiseModel | None = None,
options: SimulationOptions | None = None,
) -> ObjectiveGradientIR
用参数移位规则返回 ObjectiveGradientIR。config=None 使用默认 GradientConfig；measurement 决定精确或有限采样梯度。共享参数可能出现在多个门中，调用成本由移位计划决定，不能一律按每参数两次求值计算。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,
measurement: None = None,
sampled_selection: None = None,
) -> VariationalResult[ObjectiveEvaluationIR]
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,
measurement: PauliMeasurementConfig,
sampled_selection: SampledSelectionConfig | None = None,
) -> VariationalResult[SampledObjectiveEvaluationIR]
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,
measurement: PauliMeasurementConfig | None = None,
sampled_selection: SampledSelectionConfig | None = None,
) -> VariationalResult[
Union[
ObjectiveEvaluationIR, SampledObjectiveEvaluationIR
]
]
同步执行优化与最终计算基采样，返回 VariationalResult。optimizer=None 使用 OptimizerConfig()；initial_parameters 提供显式初值，否则按优化配置生成。measurement=None 为精确目标；有限采样只支持 SPSA 或 ADAM。sampled_selection 可在优化后独立确认候选，必须同时提供 measurement。final_shots 只控制最终计算基采样。最终点读取 selected_evaluation；停止原因和成本应分别读取，不能仅凭 success 声称收敛或全局最优。
benchmark_sampling ¶
benchmark_sampling(
config: VQESamplingBenchmarkConfig,
*,
backend: LocalBackend | None = None,
) -> VQESamplingBenchmarkResult
按 VQESamplingBenchmarkConfig 比较 exact、sampled_single、sampled_fixed、sampled_adaptive 四策略，返回 VQESamplingBenchmarkResult。同次重复共享初值与种子；预算约束目标求值，确认及最终采样成本另计。参考值来自同次 exact 策略选点，不是真实基态。详细配置限制见对应配置页；此方法没有 noise/options 参数。
optimize_layers_repeated ¶
optimize_layers_repeated(
*,
max_layers: int,
repeats: int,
optimizer: OptimizerConfig | None = None,
confidence_level: float = 0.95,
min_improvement: float = 0.0,
patience: int = 1,
final_shots: int = 2048,
seed: int = 0,
backend: LocalBackend | None = None,
noise: NoiseModel | None = None,
options: SimulationOptions | None = None,
measurement: PauliMeasurementConfig | None = None,
sampled_selection: SampledSelectionConfig | None = None,
) -> VQERepeatedLayerExperimentResult
返回 VQERepeatedLayerExperimentResult。每次从1层开始，最多到 max_layers，与当前对象的 layers 起点无关；每层 repeats 次，repeats 至少为2。仅支持内置 ansatz，optimizer 必须采用 random 初始化、seed=None 且不带 bounds。高层继承同一重复编号上一层的 selected_evaluation 参数。用当前层相对已选层的配对能量改善量计算单侧 Student-t 下界；下界大于1e-12且不低于 min_improvement 才更新所选层，否则累计无改善次数，达到 patience 后停止。confidence_level 在(0.5,1)，min_improvement 非负，patience 为正整数。有限采样须同时给 measurement 和 sampled_selection，优化器限 SPSA/ADAM。独立 seed 派生各次实验种子；增层选择不证明全局最优。