qalgora-Q Docs Hub量子文档 ✦ Ask AI✦ 问问文档
/

Optimizers & Gradients

◐ Design-level API
This page documents qalgora-Q API design, architecture, or adaptation workflows. Code examples illustrate intended usage and are not guaranteed to run in the current reference implementation.

Variational algorithms pair a quantum cost function with a classical optimizer. The qalgora-Q specification defines gradient-free and gradient-based optimizer interfaces; the open reference build does not bundle them yet. Today, build the cost function from qalgora.observe and drive it with a third-party optimizer (SciPy, NLopt, scikit-optimize).

Optimizer / gradient API — spec interface (规范接口·暂未实现)
Everything under qalgora.optimizers.* and qalgora.gradients.* is a documented specification interface; the open reference build does not include it. To run code today, see the third-party optimizers section below — that is the current recommended path.

Gradient-free optimizers (spec interface)

Need only the cost value — robust when gradients are noisy or unavailable. The qalgora.optimizers interface below is specification-only; it is illustrative and not runnable on the reference build.

# Spec interface — qalgora.optimizers is not in the reference build. Illustrative:
# opt = COBYLA()
# opt.max_iterations = 100
# opt.initial_parameters = [0.1, 0.1]
# energy, params = opt.optimize(dimensions=2, function=cost)
Specification API — not in the open reference build yet
This example shows a qalgora-Q specification API (or a third-party library) that the open reference build does not bundle today. It documents the intended interface; to run code now, use the reference build’s supported core API.

Gradient-based optimizers (spec interface)

Converge faster when a gradient is available. Pair an optimizer with a gradient strategy. The qalgora.optimizers / qalgora.gradients interfaces below are specification-only.

# Spec interface — qalgora.optimizers / qalgora.gradients are not in the reference build:
# opt  = LBFGS()
# grad = ParameterShift()
# energy, params = opt.optimize(dimensions=4, function=cost, gradient=grad)
Specification API — not in the open reference build yet
This example shows a qalgora-Q specification API (or a third-party library) that the open reference build does not bundle today. It documents the intended interface; to run code now, use the reference build’s supported core API.

Specified optimizers & gradients (planned)

OptimizerType
COBYLA, NelderMeadGradient-free
LBFGS, GradientDescent, Adam, SGDGradient-based
SPSAStochastic perturbation — noise-robust, cheap
GradientMethod
ParameterShiftExact analytic gradient via shifted evaluations
CentralDifference / ForwardDifferenceFinite-difference approximations

Parallel parameter-shift (planned)

The parameter-shift rule evaluates the circuit at ±π/2-shifted angles. Those evaluations are independent, so on a planned multi-QPU target they could run in parallel — one gradient costing little more than one cost evaluation. The multi-QPU backend below is planned (规划中) and not in the CPU reference build.

# Planned multi-QPU backend — not in the CPU reference build:
# qalgora.set_target("gpu", option="mqpu")     # shard shifted evaluations
# grad = ParameterShift()                       # spec gradient interface

Third-party optimizers (recommended today)

The cost function is plain Python, so any external optimizer (SciPy, NLopt, scikit-optimize) works — just hand it cost. This is the recommended path on the reference build today.

from scipy.optimize import minimize
result = minimize(cost, x0=[0.1, 0.1], method="COBYLA")
Parameter shift
The parameter-shift rule yields exact analytic gradients for gates whose generator has two distinct eigenvalues — i.e. gates satisfying the shift condition (the standard rotations rx/ry/rz), not arbitrary gates. For those it evaluates the circuit at shifted angles with no finite-difference truncation error.

优化器与梯度

◐ 设计接口
本页描述的是 qalgora-Q 的接口设计、架构设计或适配工作流。相关代码用于说明预期用法，当前参考实现不保证可以直接运行。

变分算法将量子代价函数与经典优化器结合。qalgora-Q 规范设计了无梯度/基于梯度优化器接口；开放参考实现暂未内置；当前可用 SciPy 等第三方优化器 + qalgora.observe 构造代价函数。

优化器 / 梯度 接口 — 规范接口·暂未实现
qalgora.optimizers.* 与 qalgora.gradients.* 下的所有内容均属规范中的接口，开放参考实现并未包含。如需立即运行，请见下方第三方优化器一节——这是当前推荐路径。

无梯度优化器（规范接口）

只看代价函数的取值即可——梯度噪声大或者拿不到梯度时，这类方法更稳。下面的 qalgora.optimizers 接口仅为规范，参考实现上无法运行。

# 规范接口——qalgora.optimizers 未包含于参考实现，仅作说明：
# opt = COBYLA()
# opt.max_iterations = 100
# opt.initial_parameters = [0.1, 0.1]
# energy, params = opt.optimize(dimensions=2, function=cost)
规范接口 · 参考实现暂未包含
此示例展示的是 qalgora-Q 规范中的接口（或第三方库），开放参考实现目前尚未内置，仅用于说明预期用法；如需立即运行，请使用参考实现已支持的核心 API。

基于梯度的优化器（规范接口）

有梯度可用时收敛更快。把优化器和某种梯度策略搭配起来用即可。下面的 qalgora.optimizers / qalgora.gradients 接口仅为规范。

# 规范接口——qalgora.optimizers / qalgora.gradients 未包含于参考实现：
# opt  = LBFGS()
# grad = ParameterShift()
# energy, params = opt.optimize(dimensions=4, function=cost, gradient=grad)
规范接口 · 参考实现暂未包含
此示例展示的是 qalgora-Q 规范中的接口（或第三方库），开放参考实现目前尚未内置，仅用于说明预期用法；如需立即运行，请使用参考实现已支持的核心 API。

规范的优化器与梯度（规划中）

优化器类型
COBYLA, NelderMead无梯度
LBFGS, GradientDescent, Adam, SGD基于梯度
SPSA随机扰动——抗噪，计算开销小
梯度方法
ParameterShift通过移位求值得到精确解析梯度
CentralDifference / ForwardDifference有限差分近似

并行参数移位（规划中）

参数移位规则在 ±π/2 移位角度处对线路求值，这些求值相互独立，因此在规划中的多 QPU 目标上可并行执行——一次梯度计算的开销几乎不超过一次代价函数求值。下面的多 QPU 后端属规划中（规划中），CPU 参考实现并不包含。

# 规划中的多 QPU 后端——CPU 参考实现暂未包含：
# qalgora.set_target("gpu", option="mqpu")     # 分片移位求值
# grad = ParameterShift()                       # 规范梯度接口

第三方优化器（当前推荐）

代价函数是纯 Python 函数，因此任何外部优化器（SciPy、NLopt、scikit-optimize）均可直接使用——只需将 cost 传入即可。这是当前在参考实现上推荐的路径。

from scipy.optimize import minimize
result = minimize(cost, x0=[0.1, 0.1], method="COBYLA")
参数移位
参数移位规则仅适用于生成元具有两个不同本征值、满足移位条件的门（例如标准旋转门 rx/ry/rz），并非任意门。对这类门，它通过在移位角度处对线路求值得到精确解析梯度，无有限差分截断误差。