当前限制¶
本页说明程序构建、模拟、编译和结果分析中的具体约束。设计实验时，请结合所用接口、参数单位和运行配置阅读。
Analog 参数明确使用 rad/us 或 rad 单位；表达式支持同单位加减以及与有限标量的乘除，不做单位换算，也不执行任意 Python 表达式。Waveform.interpolated() 固定使用保形 PCHIP。Waveform.concat() 只能在 constant 或 linear 类型内组合非插值串行片段，结果最多 1024 个点；不能混合类型、重叠片段或调度并行通道。AHSProgram.run() 是离线 Local AHS 便捷入口，不是远程后端或硬件 Job API。它的可选 O1 只删除严格为零的 local control term，不重写 global control，也不做 target-specific compilation。
Circuit.run()、AHSProgram.run() 和单次绑定的 HybridProgram.run() 支持 optimization_level=0 | 1。O1 是执行前的精确 Canonical IR 重写，证据记录在 ResultIR.metadata；它不是 Target lowering、routing、scheduling 或 Physical compilation。Hybrid O1 当前不支持参数 sweep。
当前支持的本地 SDK 路径：
- 原生 Analog AHS 程序构建、校验、离散化和本地模拟。
- 实验性的有序局域失谐项：支持静态加权模式或 constant/piecewise 二进制 mask、本地 Target 校验与离散化，以及 Local AHS 或 Hybrid 模拟。
- 实验性的相干局域 Rabi 项：支持静态加权模式或 constant/piecewise 二进制 mask、振幅与共享相位，以及理想态/密度矩阵/轨迹的 Local AHS 或 Hybrid 模拟。
- line、square、rectangular、triangular 与 custom 阵列几何；不可变的 filled/vacant/defect/loading-failed 快照；通过哈希连接的生命周期校验；模拟、测量、结果和报告共用同一活动位点顺序。
- 数值或参数化的逐位点局域 Rabi 相位偏移。校验、离散化、参考编译、各类本地模拟内核、结果和标准报告都使用这组偏移。
- 根据程序生成公开控制计划，并依据本地 Target 中的已声明数据检查并发、互斥、带宽、变化率和串扰策略。
- 指定本地 Target 后，可对带类型的局域失谐和局域 Rabi 做离线参考编译，输出逻辑操作、计划、通道、来源和资源投影。
- 根据受支持的 Digital/Analog 参考编译构建带校验和的公开
HardwareSubmissionIR，并用仓库内确定性的 mock Compiler Service、Gateway 和结果清洗流程验证数据约定。 - 原生 Digital 量子门程序构建和本地状态向量模拟。
- 版本化 Digital Operation Definition/Application/Catalog、类型化参数规范化、标准 derived facade 与 modifier、内置 QFT/H-layer/GHZ-preparation Composite 的确定性 normalization、带 lineage 的 modifier-safe 精确相邻 O1 重写、带确定性逻辑调度的 QAOA Domain Plan，以及只读 Source/Canonical/Native/Physical 线路可视化快照。
- 供 Digital 与 Analog 纯态连续演化使用的实验性内部共享状态内核。
- 实验性的
cascaqit.syntax装饰器、Syntax AST、Semantic HIR、源码映射和执行前诊断。 - 显式启用后，可把白名单内的 Digital 与全局 Analog 装饰器函数体声明降低为原生
Circuit或AHSProgram，且不执行用户函数。 - 实验性的用户级
HybridProgram、带类型的 Block DAG 和确定性本地计划编译。 - 实验性的
ParameterManager、安全表达式、明确的 Digital/Analog 目标、确定性扫描和参数投影。 - 实验性的统一
LocalBackend.run()，为 Circuit、AHSProgram 和带类型的HybridProgram提供惰性、可缓存 Job，并支持单组参数和受限扫描。 - 显式启用的 SQLite 本地重试、跨实例或进程恢复、逐扫描项恢复，以及使用校验和旁路文件的可筛选不可变 Job 历史。
- 正式的 NumPy/SciPy 运行时依赖、不可变的状态向量/密度矩阵/轨迹/子空间数组约定，以及创建 Job 或分配大数组前的资源规划。
- Analog/Hybrid 状态向量、blockade 子空间和密度矩阵可使用分段 DOP853 自适应积分；结果记录求解器实际工作量，并统一保存 Digital/Analog/Hybrid 状态转换。
- 单 Digital、单 Analog 和 D-A-D Hybrid 可执行规范的物理
NoiseChannel/NoiseModel，覆盖八类噪声通道、自动选择密度矩阵或轨迹方法，并生成有序NoiseReport。 - 实验性的
LocalHybridExecutionBuilder，支持原生用户对象、参数工厂、严格串行的遇错停止扫描，以及在参考/可扩展理想引擎上受内存限制的并行继续扫描。 - 可选的 Pulser 参考 Backend/Job：支持单个 filled 位点、全局 Rydberg 驱动、受支持波形、精确
ResultIR、带类型运行记录、状态保真度和 Z 值比较。 - 用于打包、追踪和结果查看的 mock 运行时与后端接口约定。
- 结构化的
ResultIR、DiagnosticsIR、运行记录、结果视图和可视化派生视图。 - 面向 Digital、Analog、Hybrid、精确密度矩阵、轨迹和逐扫描项结果的带类型 Pauli Observable 批量求值，保留估计器与来源证据。
- 固定参数点 VQE，以及 standalone 或 Unified Problem Digital VQE 的 sampled SPSA，可按稳定 QWC 规则分组，显式执行 X/Y/Z 基变换，每组调用一次理想本地 Digital Backend，并给出考虑协方差的误差、固定或按标准误有界自适应的目标 repeats、可选的 learning-rate scale 校准、候选独立确认和标准报告。
- 支持把 Graph、MIS、MWIS、QUBO 和 Ising 按 Target 统一编译成 Digital QAOA/VQE、多层 Hybrid D-A-D QAOA 或完整可表达的 Analog QAA，并共用本地执行、解码、参数点评估和 Problem 报告。
- 面向受支持本地 Digital 子集的受限 OpenQASM 互操作。
日常使用建议先从 examples/learning/ 开始，再阅读 examples/user/ 中的完整示例；examples/release/ 主要用于发布复核或安装检查。
当前版本不支持：
- 完整 OpenQASM 语法、defcal、时序或动态控制。
- 部分参数绑定、任意 Python 表达式、可调用参数、复数或
std中的通用符号值。可执行梯度只覆盖受支持的 RX/RY/RZ 仿射表达式。 - 面向用户的
CircuitBuilder 暂不支持中途测量、reset、经典条件、反馈或动态控制。 - 通用 unitary synthesis、ancilla allocation 或 approximate controlled synthesis。线路级 control 已覆盖内置静态 Circuit 门集，包括 H、参数化旋转和 nested control，但不证明硬件 Target 支持。
- 通用自定义 Composite factory 或 template 解释、Operation Palette、自动 decomposition rule 选择、routing 或 provider-native 矩阵/校准扩展。内置 QFT、H-layer 和 GHZ-preparation normalization 已可执行，但不是通用用户自定义 Composite lowering engine。
- 只从 Canonical
DigitalProgramIR恢复 facade 拼写。Source label 需要原始Circuit或显式匹配的ProgramSourceMapIR；否则可视化使用 Canonical label 并报告 evidence unavailable。Source Map 只用于展示，不能驱动执行。 - 带真实 start time、duration、channel 或 calibration 的 Digital Physical Schedule。Physical 线路视图明确保持
not_bound；standalone 与标准报告线路 renderer 不提供交互式阶段 tabs、Composite 展开或长线路虚拟化。 - 连续或参数化的 mask 时间/拓扑、生产环境局域调度、私有或硬件 lowering，以及局域控制装饰器或 Pulser lowering。当前 piecewise mask 使用数值帧时间和
step插值；公开控制计划不分配生产通道，也不绑定私有校准。 - Hybrid 硬件执行、并行程序块、动态控制、反馈或中途测量。
- Hybrid 硬件提交。Raman 通道明确不支持，DMM 通道仅支持 IR；两者都没有调度器或数值运行时使用方。
- 自适应轨迹跳变时间和 GPU/MPS；轨迹演化当前固定使用定步长。
- 通用符号微分、反向模式、adjoint、Analog 或 Hybrid 梯度。occurrence-level parameter-shift 支持 Digital RX/RY/RZ 仿射参数。QAOA 可计算理想或精确密度矩阵带噪梯度；VQE 还支持理想、带噪和读出缓解后的有限 shots 梯度。当前不支持 sampled QAOA 和参数相关噪声梯度。
- 持久化参数扫描不提供远程 Job 取回、跨主机调度或硬件、云执行；带噪轨迹扫描会避免嵌套 worker 池。
- 两个及以上位点、Hybrid 状态交接、局域寻址、噪声、参数扫描、采样 counts 或通用第三方后端的 Pulser 参考验证。
- 一般对易组的 Clifford 对角化或中途 Observable 采集。有限 shots VQE 使用显式局部基变换的 QWC 分组，支持理想或带噪 Digital 执行、原生 SPSA 或 Adam、uniform、coefficient-L1、pilot-variance，以及显式 tensor-product 读出缓解。SPSA 支持多方向和固定或按标准误有界追加的目标 repeats；Adam 支持完整梯度的固定或有界自适应 repeats、QWC 级池化，以及可选的更新模长与梯度不确定度双条件停止。暂不支持逐 occurrence 自适应分配。
- 通用 Problem minor embedding、gadget 或 quantum-wire 构造、自动布局搜索、其他 Hybrid 拓扑、非对易 Trotter 拆分、Analog/Hybrid 带噪 Problem 优化、trajectory/shot-noise 目标函数或全局最优保证。
Hybrid 前端默认只读取函数签名。设置 lower_body=True 后，它可以静态捕获白名单声明并降低为原生程序；整个过程不会执行被装饰函数，也不会求值任意 Python。当前子集不支持赋值、返回值、条件分支、模式匹配、循环、异常处理、上下文管理器、import、lambda、推导式、任意属性或任意可调用对象。REPL、标准输入、生成代码或动态执行代码可能无法提供源码，此时应改用原生 Builder API。Analog 函数体 lowering 仅支持全局控制，要求明确声明阵列、恰好一次驱动和末端测量，不支持局域控制或批量执行。
所有静态 LocalExecutionPlan 都保持 execution_ready=False，因为程序内容和参数绑定由 HybridProgram 与执行构建器管理。带类型的 HybridProgram 可通过 LocalBackend.run() 执行；HybridProgramIR 和执行计划不能直接传给后端。理想扫描的参数点数和 worker 数由资源预算决定；遇错停止模式严格串行执行，遇错继续模式使用有界并行批次。配置 store= 后，已完成的扫描项会保存并在本地恢复时复用；不配置时，扫描结果只存在于当前进程。
持久化执行仅限本地。SQLite 只协调同一主机上的单个活动执行权，不是分布式调度器，也不承诺跨主机只执行一次。执行超时只用于协作式状态记录，不能强制终止 NumPy、SciPy 或原生代码。History 不读取 Result 正文，Job 不会自动过期，也没有清理 API；SQLite 文件和对应的制品目录应同时保留或删除。
LocalBackend 根据可用资源规划，不设置固定的位点上限。Apple M4 上已验证 24-qubit Digital、18-site 理想 Analog/Hybrid、10-site 精确密度矩阵退相位和 16-site、256 条轨迹的带噪 Hybrid。LocalBackend(kernel_threads=N) 可用受限 CPU 线程池拆分理想定步长 Krylov 的矩阵向量乘，但扫描和带噪执行会拒绝该配置。连续 Hybrid 多起点优化可使用 parallel_workers 并行相互独立的起点；它要求内存 Backend，不能同时启用内核线程，也不会并行单个优化起点。进程数受有效 CPU 和可用内存约束，macOS 与 Windows 使用可安全启动的 worker。这些配置只优化本地 CPU 执行，不是分布式能力，也不承诺所有程序或主机都能获得相同加速。
QAOA 和 VQE 只做本地同步执行。Standalone 与 Unified Digital 支持理想目标和确定性的精确密度矩阵带噪目标。VQE 还可以在理想执行或 preparation、gate、idle、crosstalk、readout 噪声下，用有限 shots QWC 测量估计能量和完整 parameter-shift 梯度；带噪 sampled 执行支持 auto、density-matrix 和 trajectory 规划。Standalone 与 Unified Problem Digital VQE 都可以把该估计器交给原生 SPSA 或 Adam，并在末端采样前独立确认候选。所有 QWC 分组、候选确认、层数实验和 final sampling 使用同一个运行级 NoiseModel 与 SimulationOptions，每个 Job 分别保存 seed、counts、执行计划、噪声报告和 identity。调用方提供逐量子位校准后可使用 tensor-product linear-inverse 读出缓解，原始整数 counts 不会被覆盖；校准不会从 NoiseModel 自动推断。SPSA 支持多方向和固定或按标准误有界追加的目标 repeats。Adam 每轮使用一次完整 sampled parameter-shift 梯度并保存协方差，但不重复梯度 shift 点，也不能按梯度不确定度阈值停止。目标求值、候选确认、shots、分组 Job、梯度回调、shift Job、优化器更新、trajectory 数和 final sampling 分别统计。当前不支持化学积分、费米子映射、稠密矩阵 Hamiltonian、通用自动微分、trajectory 精确目标、SPSA 与 Adam 之外的采样优化器、自动获取读出校准、SPSA 方向或 parameter-shift 并行、更广泛的误差缓解、Analog/Hybrid 带噪优化、分布式执行或优化历史持久化，也不保证找到全局最优。本地 NoiseModel 是数值模型，不能证明结果与真实设备一致。hardware-efficient 与固定基数两种内置 VQE Definition 支持自动层迁移，custom Circuit 仍按固定深度运行。固定基数 VQE 只保持调用方声明的分组 Hamming weight，不推断业务约束，带噪执行也可能离开子空间。经典穷举基准最多支持 20 个变量；该限制不影响量子模拟规模。
VQE.benchmark_sampling() 在配对初值、seed 和目标求值上限下比较精确、单次采样、固定 repeats 与自适应 repeats。三种采样策略共用 QWC 测量和候选确认，每个采样策略选中的参数都会额外执行一次独立精确复测。该复测能区分估计误差与相对配对精确参考的参数质量差距，但不能证明基态、全局最优或量子优势。诊断用精确 Job 不进入优化预算，并单独统计。基准仍只支持理想 Digital、本地同步执行和 SPSA。
VariationalResult.diagnose_stability() 只读取已经完成的精确、理想 sampled 或带噪 sampled 原生 SPSA VQE。它分别检查每个 start，并根据末端目标范围、更新模长、梯度模长和采样标准误阈值返回 stable、unstable 或 insufficient_evidence。单次 sampled evaluation 没有重复标准误，因此证据不足。诊断不会校正噪声偏差、改变优化器停止规则，也不证明基态、全局最优、严格收敛或量子优势；SciPy 优化器和真实硬件结果暂不支持。
原生 SPSA 也可以在优化过程中使用 SPSAStoppingConfig。它检查 final 之前的完整迭代窗口，并可能以 stability_reached 结束；最终中心仍会执行。按方向标准误停止要求每轮至少两个方向，按采样标准误停止要求理想或带噪 sampled objective 至少执行两个 repeats。预算无法达到 min_iterations 时，会在执行前报错。阈值不会自动校准，也不会消除噪声偏差；窗口通过不代表基态、全局最优、严格收敛或量子优势。方向并行和真实硬件仍不支持。
原生 SPSA 目前只自动校准 learning-rate scale，依据是初始点的完整正负方向。固定 gain 与校准 gain 不能同时设置。精确、精确密度矩阵、理想 sampled 和带噪 sampled VQE 都可使用校准，其成本进入目标求值与 Backend 预算。校准不会调整 perturbation、调度指数、方向数、repeats、停止阈值或 Ansatz；局部梯度低于配置下限时会直接失败，不会生成无限大的 gain。目标更新 RMS 只是局部尺度选择，不是收敛或最优证据。
ProblemCompiler 当前接受 digital + qaoa、digital + vqe、hybrid + qaoa 和 analog + qaa。内置 VQE Definition 支持自动层迁移，custom VQE Circuit 只能按固定深度运行。Unified Digital VQE 可用原生 SPSA 或 Adam 运行理想或带噪的有限 shots QWC 目标，并支持可选读出缓解，以及固定或顺序候选确认。SPSA 支持固定或有界自适应的目标 repeats；Adam 支持完整梯度的固定或有界自适应 repeats，以及可选的不确定度工程停止。优化、确认和末端采样成本分别记录。采样优化不支持 SciPy 优化器或 parameter_sets。
ProblemCompiler.optimize_layers() 对连续的 Digital QAOA/VQE 或 Hybrid QAOA 层数各执行一次优化。采样路径只接受理想或带噪 Digital VQE、SPSA 或 Adam、正数末端 shots 和独立候选确认；选层使用确认能量，下一层继承确认参数。这仍是固定预算规则，不是统计检验。ProblemCompiler.optimize_layers_repeated() 与 standalone VQE.optimize_layers_repeated() 对每层执行至少两次完整优化，并依据配对 Student-t 改善下置信界选层。采样重复实验同样要求独立确认。repeats 不等于 starts、shots 或 trajectories；重复入口要求 optimizer.seed=None，并从根 seed 派生每个 run seed。所有层数实验都不支持 Analog QAA、custom VQE、跨维度固定 bounds、逐层 optimizer 配置、全局最优声明、自适应重复次数、bootstrap 区间或多重比较校正。
MIS 与 MWIS 提供显式罚项充分性和能量分解，MWIS 还保留带权目标指标。普通 QUBO/Ising 不标记来源约束，因此完整规范化目标都记为业务能量。Hybrid 每层要求 Analog contribution 非空且 gamma 严格为正。Analog 只有在 Target 能于容差内完整表达 Hamiltonian 时才编译成功。本地参考映射不代表生产布局、校准、调度或硬件可执行性。小样本置信结论只覆盖当前配置下保存的本地运行；Problem 对比也不会归一化优化预算、shots、主机负载或路线资源单位。优化仍不支持历史持久化或分布式执行。
启用 sampled_selection 后，运行时会独立确认一组不同的优化参数点，并按最低确认均值选择 final sampling 参数。把 max_repeats_per_candidate 设得高于初始重复次数后，程序会顺序复测当前均值最低的候选，以及与它的能量差下置信界最低的另一个候选，直到校正后的置信区间分离、达到重复上限或确认预算不足。best_evaluation 仍表示优化历史中的最低池化估计，selected_evaluation 才是最终参数来源。separated 或 inconclusive 只描述当前正态近似流程下已保存候选之间的关系。确认不会改变优化器已经做出的 repeat 决策，不计入优化器 nfev，也不证明全局最优或量子优势。
Standalone VQE 重复层数报告会用选中层内目标值最低的 repeat 展示详细生命周期。这只是展示选择，不会改变统计选层规则，也不会从报告中删除其他运行。
当前硬件和云相关代码只包括公开接口约定和仓库内离线 mock。mock Compiler Service 与 Gateway 不进入公开 wheel 或源码包，其 counts 来自固定测试数据，不是模拟或硬件测量。上述路径都不执行真实任务。
Pulser 位于可选依赖组 reference-pulser 中，默认导入、测试和示例不会加载第三方运行时。PulserReferenceBackend 使用公共的惰性 Job 接口，但只支持精确的单个位点 Analog 结果，不支持 Hybrid 或扫描。真实参考检查只做本地同步执行；基准测试只报告当前机器各阶段耗时的中位数，不比较性能比例。详见 Pulser 参考验证。
评估硬件或云端接入时，当前 API 只能用于准备程序内容、诊断信息、清单和结果数据约定，不能证明真实服务已经兼容。
ProgramIR、ResultIR 和 ProblemExecutionContextIR 保存的源记录仍是事实源。可视化元数据、报告、结果视图和就绪摘要都由它们派生。
关于本地安装、示例输出、诊断和边界问题，请阅读 docs/zh/user-guide/troubleshooting.md。