局域失谐¶
先运行完整的离线示例：
python3 examples/user/analog_local_detuning.py
每次调用 AHSProgram.local_detuning() 都会追加一条对角 Hamiltonian 项；重复调用按声明顺序保留，并在状态演化时相加。
局域失谐将随时间变化的 detuning waveform 与静态 site weight 或二进制寻址时间表组合起来：
from cascaqit import AHSProgram, AtomRegister, MockNeutralAtomTarget
from cascaqit import SitePattern, Waveform
target = MockNeutralAtomTarget.local_ahs_v0_1()
program = AHSProgram(AtomRegister.line(count=2, spacing=5.0))
local_delta = program.parameter("local_delta", default=0.8004)
local_weight = program.parameter(
"local_weight", unit=None, lower_bound=0.0, upper_bound=1.0, default=0.25
)
program.drive(
rabi=Waveform.constant(1.2, duration=0.6),
detuning=Waveform.constant(0.1, duration=0.6),
phase=0.0,
).local_detuning(
waveform=Waveform.constant(local_delta, duration=0.6),
pattern=SitePattern.from_mapping({"q1": local_weight, "q0": 1.0}),
).measure()
bound = program.bind({})
validated = bound.validate(target, shots=32)
discretized, report = validated.discretize(target, policy="nearest")
result = bound.run(shots=32, seed=13, time_steps=800)
SitePattern 必须恰好覆盖 register 中的每个 filled site。weight 可以是数值，也可以是用 unit=None 声明的 canonical 无量纲 Parameter 或无量纲 Expression。mapping 输入的键顺序可以不同，但绑定后的 site_ids 和数值 weights 会按 register 顺序投影。缺少、多出或重复 site 仍会产生 validation error。
二进制稀疏控制使用 SiteMask：
from cascaqit import SiteMask
mask = SiteMask.constant(("q0",), duration=0.6)
program.local_detuning(
waveform=Waveform.constant(0.4, duration=0.6),
pattern=mask,
)
SiteMask.constant() 在整段控制时间内保持同一组 site。Builder 会将它展开为按 register 排序的二进制 SiteAddressingIR；unknown 或 vacant id 会被拒绝。
需要在 pulse 中途切换 site 时，使用 SiteMask.piecewise()：
mask = SiteMask.piecewise(
duration=0.6,
frames=((0.0, ("q0",)), (0.3, ("q1",))),
)
每一帧从声明时间开始生效，直到下一帧；空帧会暂时关闭该局部控制。duration、帧时间和 site id 目前必须是数值静态配置，插值固定为 step。
local waveform 和 site pattern 都可以引用参数，但必须在 validation 前完成全部绑定。绑定后的 weight 必须位于 [0, 1]，且每个 pattern 至少包含一个非零 weight。validation 和 discretization 使用 MockNeutralAtomTarget.local_ahs_v0_1()。local target 会报告每个被调整的字段路径，因此调用方可以区分绑定参数值和离散后的 waveform 值。typed local-detuning term 存在时，AHSProgram.run() 和 LocalAhsSimulator() 会自动选择支持局域失谐的本地 target；用户显式传入的保守 target 不会被替换。
本地模拟器计算：
其中权重与 filled-site register order 对齐。该项也可在受限的 Local Hybrid shared-state 路径中运行。
Public Reference Compile¶
运行 python3 examples/user/analog_local_reference_compile.py 可查看 build、bind、validate、discretize、compile 和 local run 的完整路径。直接编译时，将离散化后的 ProgramIR、显式 local target snapshot 和匹配的 local mock calibration 传给 CompilerPipeline.compile()。
生成的 ReferenceCompiledProgramIR 为每条控制项包含一个带索引的 op.local_detuning.N，并包含 additive logical segment、patterned local channel reference、source mapping 和 resource count。这是确定性的离线 public contract：它不会创建 ExecutionPackage、分配 production channel、生成 private/hardware payload、调用 backend，也不会访问 cloud、network 或 credentials。保守的 MockNeutralAtomTarget.v0_1() 仍保持 blocked。
此能力仍是实验性功能。当前支持按声明顺序相加多个 local-detuning term、数值或参数化静态 weight，以及 constant/piecewise 二进制 mask。动态 mask 已进入 ideal、density、trajectory 和 Hybrid 数值引擎，并显示在标准实验报告中。连续 mask 插值、参数化帧拓扑、production scheduler、decorator 或 Pulser lowering、硬件执行、云执行和网络提交仍不支持。局部横向控制见局域 Rabi 控制；3x3 Hybrid 示例运行 python3 examples/user/time_dependent_site_addressing.py。