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

Numerical Integrators

◐ 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.

Choose how the Schrödinger or master equation is integrated in time — trading accuracy against cost.

Reference implementation scope
The fixed-step and SciPy CPU integrators are supported in the public reference build. The TorchDiffEq family (Dopri5/Dopri8/Bosh3/AdaptiveHeun/RK4/Euler/Midpoint/Adams) and every GPU/differentiable integrator are specification interfaces — not yet included in the reference implementation.

Selecting an integrator

The snippets below are illustrative; construct the Hamiltonian and initial state for your own model.

import qalgora
from qalgora.dynamics import integrators
import numpy as np

psi0 = np.array([1.0, 0.0], dtype=complex)
result = qalgora.evolve(
    hamiltonian, dimensions={0: 2},
    schedule=qalgora.Schedule(steps=np.linspace(0, 1, 200), parameters=["t"]),
    initial_state=qalgora.State.from_data(psi0),
    integrator=integrators.RungeKutta(order=4, max_step=1e-3),
)

Available integrators

Fixed-step solvers are cheapest and predictable; adaptive solvers control local error automatically; the differentiable Torch family lets gradients flow through the whole trajectory for optimal-control and machine-learning loops.

IntegratorFamilyUse caseStatus
RungeKutta(order=1|2|4)fixed stepgeneral-purpose, default order 4reference impl
Euler / Midpointfixed stepcheap, low-order baselinesreference impl
CrankNicolsonfixed step, implicitstable for stiff master equationsreference impl
MagnusExpansionfixed step, geometricstrongly time-dependent drives, stays unitaryreference impl
ScipyZvodeadaptive, CPUstiff systems, tight tolerancesreference impl
TorchDiffEqDopri5 / Dopri8adaptive, GPU, differentiablehigh-accuracy GPU runs, gradientsspec — not in reference impl
TorchDiffEqBosh3 / AdaptiveHeunadaptive, GPU, differentiablelower-order adaptive GPU steppingspec — not in reference impl
TorchDiffEqRK4 / Euler / Midpointfixed, GPU, differentiablefixed-step on GPU with autodiffspec — not in reference impl
TorchDiffEqExplicitAdams / ImplicitAdamsmultistep, GPU, differentiablesmooth long-time evolutionsspec — not in reference impl

Tolerances and step control

Adaptive integrators take relative and absolute tolerances; fixed-step ones take a step size.

from qalgora.dynamics import integrators

# adaptive: control error, let the solver pick the step
integ = integrators.TorchDiffEqDopri5(atol=1e-8, rtol=1e-6)

# fixed: you set the step explicitly
integ = integrators.RungeKutta(order=4, max_step=1e-3)
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.

Differentiable evolution for control

Specification — not in the reference implementation
Differentiable (Torch) integrators are a specification interface; the example below documents the intended autodiff API and does not run on the CPU reference build.

A Torch-based integrator keeps the trajectory in the autograd graph, so you can differentiate a final-state cost with respect to pulse parameters and optimise a control directly.

import torch

amp = torch.tensor(0.5, requires_grad=True)        # a control knob

def cost(amp):
    H = operators.spin.z(0) + operators.scalar(lambda t: amp) * operators.spin.x(0)
    r = qalgora.evolve(H, dimensions={0: 2}, schedule=schedule, initial_state=psi0,
                       integrator=integrators.TorchDiffEqDopri5(),
                       observables=[operators.spin.z(0)])
    # expectation_values() has shape [n_observables, n_steps];
    # [0] selects the first observable, [-1] its value at the final time
    return r.expectation_values()[0][-1]           # final <Z>

cost(amp).backward()                                # gradient flows back to amp
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.
Step size
Too large a step silently loses accuracy. For fixed-step solvers, tighten max_step until the expectation values stop changing, then back off slightly for speed; for adaptive solvers, tighten atol/rtol instead.

数值积分器

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

选择薛定谔方程或主方程的时间积分方式，在精度与开销之间取舍。

参考实现范围
定步长求解器与 SciPy CPU 积分器在公开参考实现中受支持。TorchDiffEq 系列（Dopri5/Dopri8/Bosh3/AdaptiveHeun/RK4/Euler/Midpoint/Adams）以及所有 GPU/可微积分器均为规范接口·参考实现暂未包含。

选择积分器

以下为片段示例，哈密顿量/初态需按模型自行构造。

import qalgora
from qalgora.dynamics import integrators
import numpy as np

psi0 = np.array([1.0, 0.0], dtype=complex)
result = qalgora.evolve(
    hamiltonian, dimensions={0: 2},
    schedule=qalgora.Schedule(steps=np.linspace(0, 1, 200), parameters=["t"]),
    initial_state=qalgora.State.from_data(psi0),
    integrator=integrators.RungeKutta(order=4, max_step=1e-3),
)

可用积分器

定步长求解器开销最小、行为可预测；自适应求解器会自动控制局部误差；可微的 Torch 系列让梯度贯穿整条轨迹，专为最优控制与机器学习回路而设。

积分器类别适用状态
RungeKutta(order=1|2|4)定步长通用，默认四阶参考实现已支持
Euler / Midpoint定步长低阶廉价基线参考实现已支持
CrankNicolson定步长，隐式刚性主方程下稳定参考实现已支持
MagnusExpansion定步长，几何强含时驱动，保持幺正性参考实现已支持
ScipyZvode自适应，CPU刚性系统，严格容差参考实现已支持
TorchDiffEqDopri5 / Dopri8自适应，GPU，可微GPU 上的高精度求解与梯度规范接口·参考实现暂未包含
TorchDiffEqBosh3 / AdaptiveHeun自适应，GPU，可微GPU 上的低阶自适应步进规范接口·参考实现暂未包含
TorchDiffEqRK4 / Euler / Midpoint定步长，GPU，可微GPU 上的定步长，带自动微分规范接口·参考实现暂未包含
TorchDiffEqExplicitAdams / ImplicitAdams多步，GPU，可微平滑的长时演化规范接口·参考实现暂未包含

容差与步长控制

自适应积分器接收相对容差和绝对容差，定步长积分器则接收步长。

from qalgora.dynamics import integrators

# 自适应 控制误差 由求解器自行选步
integ = integrators.TorchDiffEqDopri5(atol=1e-8, rtol=1e-6)

# 定步长 你显式设定步长
integ = integrators.RungeKutta(order=4, max_step=1e-3)
规范接口 · 参考实现暂未包含
此示例展示的是 qalgora-Q 规范中的接口（或第三方库），开放参考实现目前尚未内置，仅用于说明预期用法；如需立即运行，请使用参考实现已支持的核心 API。

用于控制的可微演化

规范接口·参考实现暂未包含
可微（Torch）积分器是规范接口；下面的示例描述的是预期的自动微分 API，不会在 CPU 参考实现上运行。

基于 Torch 的积分器会把整条轨迹保留在自动微分图中，于是你可以对脉冲参数求终态代价的梯度，直接优化一段控制。

import torch

amp = torch.tensor(0.5, requires_grad=True)        # 一个控制旋钮

def cost(amp):
    H = operators.spin.z(0) + operators.scalar(lambda t: amp) * operators.spin.x(0)
    r = qalgora.evolve(H, dimensions={0: 2}, schedule=schedule, initial_state=psi0,
                       integrator=integrators.TorchDiffEqDopri5(),
                       observables=[operators.spin.z(0)])
    # expectation_values() 形状为 [n_observables, n_steps]
    # [0] 选第一个可观测量 [-1] 取其终时刻的值
    return r.expectation_values()[0][-1]           # 终态 <Z>

cost(amp).backward()                                # 梯度回流到 amp
规范接口 · 参考实现暂未包含
此示例展示的是 qalgora-Q 规范中的接口（或第三方库），开放参考实现目前尚未内置，仅用于说明预期用法；如需立即运行，请使用参考实现已支持的核心 API。
步长
步长过大会悄无声息地损失精度。对定步长求解器，不断收紧 max_step 直到期望值不再变化，再略微放宽以提速；对自适应求解器，则改为收紧 atol/rtol。