文档版本

校验目标，再检查参考编译结果¶

让带局域失谐的双原子程序依次经过校验、离散化和公开参考编译。辨认每一步新增的信息，再尝试越界幅度和网格外数值。先完成局域失谐和局域 Rabi 控制。本例只做本地编译，不执行量子演化，也不向硬件提交。

校验检查声明的程序是否符合目标能力与范围；离散化把支持的数值投影到目标网格；参考编译产生可检查的操作、逻辑调度片段和源映射。任一步骤都不能单独视为硬件提交。

使用明确的目标快照¶

"""检查带类型的 local control 如何进行离线 reference compile。

公开编译器根据 mock Target 和 Calibration snapshot 生成 native operation、候选
schedule、源码路径和资源信息。输出不包含私有硬件 payload，也不会分配生产资源。
"""

from __future__ import annotations

import json

from cascaqit import (
    AHSProgram,
    AtomRegister,
    MockNeutralAtomTarget,
    SitePattern,
    Waveform,
)
from cascaqit.compiler import CompilerPipeline


def main() -> None:
    """编译一个 local-detuning 程序，并检查用户可见 projection。"""
    target = MockNeutralAtomTarget.local_ahs_v0_1()
    program = (
        AHSProgram(
            AtomRegister.line(count=2, spacing=5.0),
            program_id="lesson.experimentalist.reference_compile",
        )
        .drive(
            rabi=Waveform.constant(0.6, duration=0.2),
            detuning=Waveform.constant(0.0, duration=0.2),
            phase=0.0,
        )
        .local_detuning(
            waveform=Waveform.constant(0.4, duration=0.2),
            pattern=SitePattern.from_mapping({"q0": 1.0, "q1": 0.25}),
        )
        .measure()
    )
    validated = program.validate(target, shots=16)
    discretized, _ = validated.discretize(target)
    snapshot = target.to_snapshot(
        snapshot_id="snapshot.lesson.experimentalist",
        source="offline_lesson",
        status="available",
        effective_at="2026-07-20T00:00:00Z",
    )
    compiled = CompilerPipeline().compile(
        discretized.program_ir,
        target_snapshot=snapshot,
    )
    contract = compiled.metadata["compiler_pipeline_contract"]

    payload = {
        "track": "quantum_experimentalist",
        "level": "expert",
        "lesson": "reference_compile",
        "facts": {
            "native_operations": [
                item["operation_type"] for item in compiled.native_operation_set
            ],
            "schedule_segments": [
                item["segment_id"] for item in compiled.compiled_schedule["segments"]
            ],
            "local_source_paths": sorted(
                key for key in compiled.source_map if "local_detuning" in key
            ),
            "compiled_hash_present": len(compiled.stable_hash()) == 64,
            "hardware_payload_emitted": contract["hardware_payload_emitted"],
            "compiled_ir_only": True,
        },
        "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/quantum_experimentalist/05_expert_reference_compile_zh.py

支持局域控制的模拟目标允许这组带空间权重的失谐。to_snapshot() 保存传给编译器的目标描述。代码中的固定日期和 offline_lesson 标记用于识别教学快照，不能证明某台设备在那个时间做过校准。

{
  "boundaries": {
    "cloud_execution": false,
    "credentials_loaded": false,
    "hardware_execution": false,
    "network_accessed": false
  },
  "facts": {
    "compiled_hash_present": true,
    "compiled_ir_only": true,
    "hardware_payload_emitted": false,
    "local_source_paths": [
      "channel.local_detuning",
      "op.local_detuning.0"
    ],
    "native_operations": [
      "global_rydberg_drive",
      "local_detuning"
    ],
    "schedule_segments": [
      "segment.global_rydberg_drive.0",
      "segment.local_detuning.0"
    ]
  },
  "lesson": "reference_compile",
  "level": "expert",
  "track": "quantum_experimentalist"
}

输出包含全局 Rydberg 驱动、局域失谐操作，以及对应调度片段。局域源路径可把编译项追溯到原控制。compiled_hash_present 标识编译记录；hardware_payload_emitted = false、compiled_ir_only = true 说明输出范围。存在片段列表，不代表已经分配生产控制通道。

分清三种检查¶

阶段	查看什么	不能据此确定什么
校验	诊断级别、错误码和对象路径	数值收敛性或实验精度
离散化	调整字段、新数值和报告诊断	原始未修改程序已经按新数值运行
参考编译	操作类型、调度项、映射和来源	私有设备载荷或真机执行成功

发现错误时，先检查再继续。示例默认数值已经被目标接受，因此不需要修复。

制造并修复三个问题¶

将全局 Rabi 幅度改为 100 rad/us。先调用 validate() 查看错误，定位无效字段后恢复 0.6，再考虑编译。
将局域失谐改为 0.4004 rad/us，比较 discretize(target, policy="nearest") 与 policy="strict"，同时查看返回波形和报告诊断。
把 MockNeutralAtomTarget.local_ahs_v0_1() 换成保守目标 v0_1()。解释为什么在前一个目标上可用的程序，在这里仍可能被拒绝。

核对思路

过大的幅度会在 Rabi 数值处产生 WAVEFORM_VALUE_OUT_OF_RANGE。对于当前网格，最近投影把 0.4004 改为 0.4；严格策略保留输入值，但报告 DISCRETIZATION_STRICT_GRID_MISMATCH。所以返回了对象，不代表严格检查已经通过。保守目标会报告 LOCAL_DETUNING_CAPABILITY_UNSUPPORTED。更换为支持该控制的模拟目标，只是选择另一种本地模型，不能通过改一个标志就启用真机。

保存练习时，将源程序和目标快照与编译对象放在一起；仅凭内容标识无法重建丢失的目标描述。接着做 Rabi 振荡与相互作用数值实验，或阅读校验与离散化的一般规则。