检查参考编译记录与缓存身份¶
对离散化后的 Analog 程序，使用固定的公开目标快照进行编译。查看各阶段记录、源码映射和缓存身份，再对相同输入编译一次。请先完成校验与离散化，使用安装好的环境。
先预测：相同输入应得到相同的编译内容。两次编译都不会向硬件发送脉冲，也不会取得私有校准。这条编译路径提供的是供检查与接入使用的公开参考信息。
从输入追踪到编译记录¶
"""检查 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()
python3 examples/user/tracks/compiler_engineer/05_expert_reference_compile_provenance_zh.py
目标快照记录使用了哪份公开规格。课程中固定的 effective_at 是示例元数据，不能证明设备曾在该时刻完成校准。CompilerPipeline.compile(...) 接收离散化程序和快照，返回范围为 public_reference 的产物。
{
"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"
}
按执行顺序阅读阶段记录：校验、离散化、目标绑定、Analog 表示转换、控制绑定、源码映射、资源估算和后端就绪检查。阶段名称说明它在公开编译流程中的职责；其中的后端就绪检查不会进行私有校准，也不代表获准提交硬件。
源码映射把全局驱动、测量等编译项关联回来源信息。某个编译项或诊断不符合预期时，可以从这里追查。同时还要保存原始和离散化程序；源码映射无法恢复全部编写意图，也不会判断控制修改是否符合实验要求。
target_hash_matches 将编译结果的目标引用与 snapshot.target_snapshot_hash 比较。这个字段标识快照内的目标规格，不等于对整个快照对象求哈希，后者还包含对象身份和元数据。检查各阶段引用时，必须比较同一类哈希。
有缓存键，不等于命中缓存¶
same_cache_key 和 same_compiled_hash 都应为 true。缓存键取决于程序输入、目标规格、编译器版本及选项、参数和位序约定；这些内容相同，身份就相同。
但报告中的缓存状态仍为 miss，filesystem_cache_used 为 false。本例生成了缓存元数据，没有提供已保存的条目，也不会写入磁盘缓存或在第二次调用时跳过编译。输出确定、缓存查找有效和实际复用工作，是三个不同的观察结果。
边界字段应显示：没有私有校准、没有硬件载荷、没有生产通道分配。这与公开参考范围一致。不能仅因为产物中出现通道、阶段记录或目标哈希，就称其为设备可执行程序。
检查有意引入的改动¶
- 将斜坡终点从
0.8改为0.9 rad/us，保持其他输入不变，与原运行比较缓存键。 - 相同输入编译两次，除缓存键外还要查看缓存报告。什么信息才能证明已保存条目确实被复用？
- 报告包含
backend_readiness阶段。如果要声称硬件已执行，还需要哪些证据？
波形变化会改变程序及缓存身份。键重复不足以证明命中，需要检查实际查找、匹配结果和复用行为。声称硬件执行，需要受支持的真实提交路径及实际执行结果，还要满足该路径要求的设备检查；这条公开参考编译流程不提供这些实时事实。