Analog Walkthrough¶
本文解释 examples/release/minimal_analog_quickstart.py 这个短 analog 示例。如果你是第一次学习 SDK，请先运行 examples/learning/analog_first_run.py；需要逐行理解更短脚本时，再读这一页。整个流程只使用本地 SDK 路径。
这个示例会构建一个很小的 AHS 程序，使用 mock neutral-atom target 做校验，按目标网格离散化，运行本地模拟，然后打印一个简短摘要。它不会提交到汉原硬件，也不会调用 CASCAQit Cloud。
运行示例¶
在仓库根目录运行：
python3 examples/release/minimal_analog_quickstart.py
预期输出：
{'program_type': 'analog', 'counts_total': 16, 'validation_errors': [], 'diagnostic_codes': ['SIMULATION_COMPLETED'], 'mean_excitation': 0.210409, 'hardware_execution': False, 'cloud_execution': False}
这些字段刻意保持很少。它们告诉你：程序类型是 analog，本地模拟器产生了 16 shots，校验没有错误，模拟完成，并且没有使用硬件或云路径。
导入¶
示例使用顶层公开导入路径：
from cascaqit import (
AHSProgram,
AtomRegister,
LocalAhsSimulator,
MockNeutralAtomTarget,
Waveform,
)
第一次写程序时建议使用这些导入。from cascaqit.analog import AHSProgram 这类包级导入也可用，但顶层导入更适合快速示例。
Target 和 Register¶
示例先创建 mock target 和两个点位的原子阵列：
target = MockNeutralAtomTarget.v0_1()
register = AtomRegister.line(count=2, spacing=5.0)
MockNeutralAtomTarget.v0_1() 提供本地校验和离散化使用的约束。它不是到真实设备的连接。
AtomRegister.line(count=2, spacing=5.0) 创建一维两原子阵列。这里的 spacing 满足 mock target 约束，因此校验不应产生原子间距错误。
Program 和 Drive¶
Analog 程序从 register 构建：
program = AHSProgram(
register,
program_id="program.example.minimal_analog_quickstart",
)
drive 定义随时间变化的控制场：
program.drive(
rabi=Waveform.linear(0.0, 2.0, duration=1.0, waveform_id="rabi"),
detuning=Waveform.piecewise_linear(
times=[0.0, 0.5, 1.0],
values=[-4.0, 0.0, 4.0],
waveform_id="detuning",
),
phase=0.0,
)
program.measure()
rabi 表示驱动强度。detuning 通过三个时间点变化。这个示例中的 phase 是常量。program.measure() 添加末端测量，这样模拟器可以返回 bitstring counts。
Validate 和 Discretize¶
模拟前，示例先做校验和离散化：
validated = program.validate(target, shots=128)
discretized, _report = validated.discretize(target, policy="nearest")
校验会根据 Target 约束检查原子间距、波形形状、持续时间和 shots 设置。这个示例有效，因此 validation_errors 应为空列表。
Discretization 会把连续的程序值映射到目标网格。"nearest" policy 表示需要量化时选择最接近的可表示值。示例没有打印 report，是为了让终端输出保持短小；调试更大程序时，report 会很有用。
本地模拟¶
示例运行本地 analog simulator：
result = LocalAhsSimulator(target=target, seed=1234).run(discretized, shots=16)
seed 让示例结果足够稳定，便于文档和快速检查使用。返回结果是结构化的 ResultIR 风格对象，包含 counts、observables、diagnostics 和 metadata。
范德瓦尔斯相互作用¶
需要让阵列按有限两体项演化时，使用 VanDerWaalsInteraction：
from cascaqit import LocalBackend, VanDerWaalsInteraction
register = AtomRegister.custom(
((0.0, 0.0), (5.0, 0.0), (2.0, 5.0), (8.0, 4.0))
)
program = AHSProgram(
register,
interaction=VanDerWaalsInteraction(
c6=15_625.0,
cutoff_radius=5.0,
enabled=True,
),
)
program.drive(
rabi=Waveform.constant(1.0, duration=0.2),
detuning=Waveform.constant(0.0, duration=0.2),
phase=0.0,
).measure()
result = LocalBackend(seed=31).run(program, shots=32).result()
interaction = result.interaction_report()
模拟器对欧氏距离小于或等于截断半径的每个活动原子对应用
C6 的单位是 rad*um^6/us，坐标和截断半径的单位是 um。一维直线阵列和任意二维阵列共用同一个几何模型。设置 enabled=False 会把配置保留在 Program 中，但不贡献原子对能量。
对于这个独立程序，interaction_report() 返回实际执行的 coherent + crosstalk + number_number 证据。包含多个 Analog block 的 Hybrid 结果应改用 interaction_reports()。该相互作用不是 coherent XX crosstalk 噪声通道，有限相互作用也不会启用 hard-blockade subspace。运行 python3 examples/user/van_der_waals_interaction.py 可查看完整、确定性的示例。位置噪声 realization 目前仅是内部扩展点，尚无面向用户的配置 API。
理解输出¶
打印的字典是 result 的紧凑视图：
program_type：应为analog。counts_total：应等于请求的本地模拟 shots。validation_errors：这个有效示例中应为空。diagnostic_codes：应包含SIMULATION_COMPLETED。mean_excitation：来自本地模拟输出的一个小型 observable。hardware_execution：本示例中始终为False。cloud_execution：本示例中始终为False。
编写更大工具时，应把 ResultIR 和 ProgramIR 作为源记录。打印字典、报告和可视化对象都是用于查看的派生视图。
可复用参数与 Waveform¶
需要复用声明时，从 program 创建参数，再把返回值传给 waveform：
omega = program.parameter("omega", unit="rad/us", default=1.0)
delta = program.parameter("delta", unit="rad/us")
rabi = Waveform.constant(omega, duration=0.25).concat(
Waveform.constant(omega / 2, duration=0.25)
)
program.drive(
rabi=rabi,
detuning=Waveform.constant(delta, duration=0.5),
phase=0.0,
).measure()
bound = program.bind({"delta": 0.4})
result = bound.run(shots=16, seed=17)
参数使用 rad/us 或 rad 单位；加减要求单位相同，乘除只接收有限标量。concat() 只组合兼容的 constant family 或 linear family 片段，不修改源 waveform。typed program 必须完全绑定后才能导出 IR、校验、离散化、运行 Local AHS 或构造 Local Hybrid payload。
运行 python3 examples/user/analog_program_ergonomics.py 可查看完整离线工作流。
这个示例不做什么¶
本文不会使用真实汉原2号执行、真实硬件执行、CASCAQit Cloud 执行、网络端点访问、凭证加载、对象存储访问、artifact 字节读取、发布包上传或 release signing。
mock target、validation、discretization 和 local simulator 足以帮助你理解 analog 编程形态，但它们不是硬件执行已经就绪的证明。