AHSProgram¶
from cascaqit import AHSProgram
AHSProgram ¶
AHSProgram(
register: AtomRegister,
*,
program_id: str = "program",
interaction: VanDerWaalsInteraction | None = None,
)
用原子阵列、驱动波形和测量声明一个模拟量子程序。register 决定几何位置与逻辑顺序；interaction 可显式指定范德瓦耳斯相互作用。直接调用 run() 在本机计算，返回 ResultIR。
时间用 us，Rabi 频率和失谐用 rad/us，相位用 rad，坐标用 um。先调用 drive()，独立执行前再调用 measure()；含符号参数时先 bind()。drive()、局域控制和测量方法修改当前程序并返回它，适合连续调用；bind() 返回独立程序。
完整例子见波形设计和局域 Rabi 控制。需要噪声、执行规划或任务记录时使用 LocalBackend。
控制与测量¶
设置全局 rabi、detuning 和 phase。再次调用会替换此前的全局驱动。前两项必须是 Waveform；相位可用数值、已声明参数、表达式或相位波形。波形参数必须属于当前程序且单位匹配。类型不符会抛出 TypeError，参数归属或单位问题会触发校验错误。
追加局域失谐项。waveform 给出时间变化，pattern 用 SitePattern 权重或 SiteMask 二值选择站点。多次调用按声明顺序保留，贡献相加。导出时会将寻址映射到有原子的目标站点；稠密权重必须覆盖这些站点，动态掩码的时长必须与控制一致。
local_rabi ¶
local_rabi(
*,
rabi: Waveform,
phase: AnalogPhaseValue,
pattern: SiteAddressing,
phase_pattern: SitePhasePattern | None = None,
) -> AHSProgram
追加局域 Rabi 驱动。rabi 为幅度，phase 为共享相位，pattern 为权重或掩码。可选 phase_pattern 来自 cascaqit.analog.SitePhasePattern，提供各站点的相位偏移。多项驱动相干叠加，不能把幅度简单当成概率相加。控制是否可执行仍取决于目标支持的通道和约束。
追加末端测量声明并返回当前程序。默认基为 ground_rydberg，结果中的 0/1 对应基态/Rydberg 态。给测量设置可识别的 measurement_id；声明测量本身不会启动模拟。
参数与导出¶
parameter ¶
parameter(
name: str,
*,
unit: str | None = "rad/us",
lower_bound: float | None = None,
upper_bound: float | None = None,
default: float | None = None,
) -> Parameter
声明当前程序拥有的浮点参数并返回 Parameter。unit 默认 rad/us；相位用 rad，无量纲权重用 None。lower_bound、upper_bound 和 default 约束可绑定的值。重复名称或不合法声明会抛出 ProgramValidationError。
按声明顺序返回参数元组，供界面、扫描或检查使用。
返回控制值是否都已解析为数值。它检查参数状态；即使为 True，仍需检查驱动、测量和目标限制。
按名称绑定 values，返回独立的 AHSProgram。被引用但未提供的参数使用声明的默认值；没有默认值时必须提供。未知名称、缺失值、非有限数或越界值会抛出 ProgramValidationError。即使每个参数都有默认值，也应显式调用 bind({}) 完成数值化。
返回数值 ProgramIR。缺少全局驱动、缺少独立程序的末端测量，或仍有未绑定的类型化参数时会抛出 ProgramValidationError。导出不执行目标校验、离散化或模拟。
返回 bind(values).to_ir() 的结果，类型为 ProgramIR。需要继续操作程序时用 bind()。
校验与执行¶
按 target 和 shots 校验数值程序，返回 ValidatedAHSProgram，其中保存程序和诊断。先检查 diagnostics 中是否有 error；包装对象本身不代表校验已通过。导出阶段的缺失声明等问题也可能抛出错误。确认诊断后可调用 discretize(target)，返回离散化程序与报告二元组。这里返回的不是数字线路 validate() 所用的诊断元组。
run ¶
run(
*,
shots: int = 1000,
seed: int | None = None,
target: TargetSpec | None = None,
time_steps: int = 400,
return_probabilities: bool = True,
optimization_level: int = 0,
) -> ResultIR
在本地执行并返回 ResultIR。shots 控制末端采样次数，seed 控制随机采样，time_steps 控制积分离散精度；增加 shots 不会减小积分误差。return_probabilities=True 请求状态概率。target 指定本地模拟所检查的目标规格；使用局域控制时应传入支持它的目标，例如 MockNeutralAtomTarget.local_ahs_v0_1()。
optimization_level 当前支持 0 和 1，后者执行保持语义的程序化简。程序、目标或配置不合法时执行失败；不要把对象构造成功当作执行校验通过。研究结果应另做步数收敛检查，并区分状态概率与有限采样计数。