校验 Analog 程序并生成参考编译记录¶
准备把 Analog 程序交给编译工具检查时，先用目标规格校验，再离散化，最后编译。这个流程返回公开参考产物，可用来查看控制映射、来源和资源估算；它不提交硬件任务。
- 调用
program.validate(target, shots=...)检查几何、波形、单位和目标约束。 - 对校验后的程序调用
discretize(target)，保留返回的程序与修改报告。检查时间点和控制值如何落到目标网格上。 - 用
target.to_snapshot(...)固定本次使用的目标规格，再将离散化程序传给CompilerPipeline.compile(...)。 - 阅读诊断、阶段记录和
source_map。保存原始程序、离散化程序与目标快照，便于解释控制修改。
一个可重复的参考编译¶
"""检查 reference compile 的 pass、source map、缓存标识和来源记录。
公开 compiler 会返回确定的 reference IR。本例查看 pass record、源码路径、
Target/Calibration hash 和 cache key，同时确认流程没有生成私有 payload 或生产调度。
"""
from __future__ import annotations
import json
from cascaqit import AHSProgram, AtomRegister, MockNeutralAtomTarget, Waveform
from cascaqit.compiler import CompilerPipeline
def main() -> None:
"""编译一个 global Analog 程序并检查 provenance 字段。"""
target = MockNeutralAtomTarget.v0_1()
program = (
AHSProgram(
AtomRegister.line(count=1, spacing=5.0),
program_id="lesson.compiler.reference",
)
.drive(
rabi=Waveform.linear(0.0, 0.8, duration=0.2),
detuning=Waveform.constant(-0.2, duration=0.2),
phase=0.0,
)
.measure()
)
validated = program.validate(target, shots=16)
discretized, _ = validated.discretize(target)
snapshot = target.to_snapshot(
snapshot_id="snapshot.lesson.compiler",
source="offline_lesson",
status="available",
effective_at="2026-07-20T00:00:00Z",
)
compiled = CompilerPipeline().compile(
discretized.program_ir,
target_snapshot=snapshot,
)
repeated = CompilerPipeline().compile(
discretized.program_ir, target_snapshot=snapshot
)
cache_report = compiled.metadata["compile_cache_report"]
contract = compiled.metadata["compiler_pipeline_contract"]
pass_pipeline = compiled.metadata["compiler_pass_pipeline"]
payload = {
"track": "compiler_engineer",
"level": "expert",
"lesson": "reference_compile_provenance",
"facts": {
"pass_names": [item["pass_name"] for item in pass_pipeline["records"]],
"source_map_keys": sorted(compiled.source_map),
"same_cache_key": repeated.compile_cache_key == compiled.compile_cache_key,
"same_compiled_hash": repeated.stable_hash() == compiled.stable_hash(),
"target_hash_matches": compiled.target_snapshot_hash
== snapshot.target_snapshot_hash,
"cache_status": cache_report["status"],
"filesystem_cache_used": cache_report["filesystem_cache_used"],
"cache_key_present": len(compiled.compile_cache_key) == 64,
"target_hash_present": bool(compiled.target_snapshot_hash),
"compilation_scope": compiled.compilation_scope,
"private_calibration_present": "calibration_snapshot_hash"
in compiled.to_dict(),
"hardware_payload_emitted": contract["hardware_payload_emitted"],
"production_scheduling_performed": compiled.channel_schedule[
"production_channel_allocation_performed"
],
},
"boundaries": {
"hardware_execution": False,
"cloud_execution": False,
"network_accessed": False,
"credentials_loaded": False,
},
}
print(json.dumps(payload, sort_keys=True))
if __name__ == "__main__":
main()
python examples/user/tracks/compiler_engineer/05_expert_reference_compile_provenance_zh.py
{
"boundaries": {
"cloud_execution": false,
"credentials_loaded": false,
"hardware_execution": false,
"network_accessed": false
},
"facts": {
"cache_key_present": true,
"cache_status": "miss",
"compilation_scope": "public_reference",
"filesystem_cache_used": false,
"hardware_payload_emitted": false,
"pass_names": [
"validation",
"discretization",
"target_binding",
"analog_lowering",
"control_binding",
"source_map",
"resource_estimate",
"backend_readiness"
],
"private_calibration_present": false,
"production_scheduling_performed": false,
"same_cache_key": true,
"same_compiled_hash": true,
"source_map_keys": [
"channel.global",
"control_system",
"measurements",
"op.global_rydberg_drive"
],
"target_hash_matches": true,
"target_hash_present": true
},
"lesson": "reference_compile_provenance",
"level": "expert",
"track": "compiler_engineer"
}
输出中的 compilation_scope 应为 public_reference，两次相同输入的 same_cache_key 和 same_compiled_hash 应为 true。target_hash_matches 比较的是目标规格的哈希，与整个快照对象的哈希不是同一回事。
本例的 cache_status 仍为 miss，filesystem_cache_used 为 false。生成相同缓存键不表示已经查找或复用了磁盘缓存。快照时间也是示例元数据，不能证明设备完成过校准。
控制被修改或编译失败时¶
先看诊断指向的波形、位点或参数，再比较离散化报告。不要为了通过目标检查而直接删除控制项；先确认改动是否保留实验需要的物理条件。离散化后应重新检查你关心的观测量。
hardware_payload_emitted 和 production_scheduling_performed 在本例中均为 false。公开目标能够描述约束，不代表已经提供生产设备、私有校准或真实执行通道。若只需要本地实验，可沿用 AHSProgram 与 LocalBackend 的运行路径。
继续学习见校验与离散化和参考编译课程。Problem 编译从优化问题生成原生程序，与这里检查已编写 Analog 程序的任务不同。