局域 Rabi 控制¶
先运行离线示例：
python3 examples/user/analog_local_rabi.py
每次调用 AHSProgram.local_rabi() 都会按声明顺序追加一条局域 Rabi amplitude、一个共享 phase 和一个 site-addressing 对象。重复调用得到相干 Hamiltonian 项，数值演化前会先叠加复振幅：
import math
from cascaqit import AHSProgram, AtomRegister, SitePattern, Waveform
program = AHSProgram(AtomRegister.line(count=2, spacing=5.0))
omega = program.parameter("omega", default=math.pi)
phi = program.parameter("phi", unit="rad", default=0.0)
weight = program.parameter(
"weight", unit=None, lower_bound=0.0, upper_bound=1.0, default=1.0
)
program.drive(
rabi=Waveform.constant(0.0, duration=1.0),
detuning=Waveform.constant(0.0, duration=1.0),
phase=0.0,
).local_rabi(
rabi=Waveform.constant(omega, duration=1.0),
phase=phi,
pattern=SitePattern.from_mapping({"q1": 1.0 - weight, "q0": weight}),
).measure()
result = program.bind({}).run(shots=64, seed=23, time_steps=400)
在一微秒时长下，omega = pi 且 weight = 1 时只翻转 q0，预期主要结果是 10。weight 可以是数值，也可以使用 canonical 无量纲 parameter/expression。mapping 输入顺序可以任意，但必须恰好覆盖每个 filled site；bind() 会检查 [0, 1] 范围和非全零约束，随后 IR 按 register 顺序保存数值 weights。
二进制寻址可使用 SiteMask.constant(("q0",), duration=1.0)，无需为 register 中的其他 site 手写零。SiteMask.piecewise() 接收帧起始时间，也允许中间出现 all-off 帧。Builder 会拒绝 unknown 或 vacant id，并在 validation、compile、visualization 和 simulation 前展开每一帧。analog_local_rabi.py 对比参数化 SitePattern 和 constant mask；time_dependent_site_addressing.py 展示动态形式。
需要为不同 site 设置独立 phase offset 时，使用 cascaqit.analog.SitePhasePattern。数值 offset 或 rad Parameter/Expression 会绑定到与 amplitude pattern 相同的 active-site order。Validation 会在离散化前后检查 local Target capability 和 phase range；reference compile、state-vector、subspace、density、trajectory、Hybrid 执行、Result 证据和标准报告消费同一份 typed IR。可运行的参数化示例见实验控制与原子阵列生命周期。
模拟器计算的横向项为：
该项会与 global drive、detuning、相互作用和可选 local-detuning 项相干叠加。它可在 scalable ideal、exact density 和 trajectory Hybrid engine 中执行，block 边界不会重置状态。
validation、discretization、pulse timeline visualization、resource estimate 和离线 CompilerPipeline lowering 都会保留局域 amplitude、phase、pattern、channel binding、source map 和 additive schedule。显式 local target 提供 rydberg.rabi.local；保守 target 会在执行前拒绝该 term；Pulser projection 也会明确拒绝。
当前支持按声明顺序相干叠加多个 local-Rabi term；每项拥有共享的数值或 waveform phase、覆盖每个 filled site 且位于 [0, 1] 的数值或参数化静态 weight、constant/piecewise 二进制 mask，以及数值或参数化的逐 site phase offset。动态 mask 和 phase pattern 已进入 ideal、subspace、density、trajectory 与 Hybrid 数值执行。连续 mask 插值、参数化帧拓扑、decorator/Pulser lowering、production channel allocation、hardware payload、云执行和网络提交仍不支持。