在创建任务前拒绝不支持的请求¶
读取 Backend 的能力声明，再请求本地模拟器尚不支持的 GPU 设备。请先完成任务恢复与资源规划，使用安装好的环境。
先预测：调用应在返回 Job 之前报错。静默改用 CPU 会改变请求的执行条件；应用若提供替代方案，应明确让使用者知道这项选择。
读取声明，再检查具体请求¶
"""检查 Backend capability 和结构化的 fail-fast 错误。
Local Backend 会明确列出可执行 method。示例主动请求当前不可用的 GPU device，
并在创建 Job 或分配大型状态数组之前捕获拒绝原因，不会自动回退到其他设备。
"""
from __future__ import annotations
import json
from cascaqit import CapabilityError, Circuit, LocalBackend
from cascaqit.simulators import SimulationOptions
def main() -> None:
"""读取 capability，并捕获一个 unsupported-device diagnostic。"""
backend = LocalBackend(seed=405)
capability = backend.capability
error_code = None
error_stage = None
error_path = None
gpu_job = None
try:
gpu_job = backend.run(
Circuit(1, program_id="lesson.platform.capability").h(0),
shots=8,
options=SimulationOptions(device="gpu"),
)
except CapabilityError as error:
error_code = error.code
error_stage = error.stage
error_path = error.object_path
payload = {
"track": "sdk_platform_engineer",
"level": "expert",
"lesson": "capability_boundaries",
"facts": {
"backend_id": capability.backend_id,
"methods": list(capability.executable_simulation_methods),
"scan_supported": capability.unified_scan_supported,
"noise_supported": capability.noise_supported,
"gpu_error_code": error_code,
"gpu_error_stage": error_stage,
"gpu_error_path": error_path,
"job_created_for_gpu": gpu_job is not None,
},
"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/sdk_platform_engineer/05_expert_capability_boundaries_zh.py
能力对象列出支持的模拟方法，并说明是否支持扫描和噪声。这些信息表示有哪些功能，并不保证程序、方法、噪声模型与设备的任意组合都有效。例如，子空间执行需要适用的基；一般 Hybrid 线路不会自动投影到更小的空间。
{
"boundaries": {
"cloud_execution": false,
"credentials_loaded": false,
"hardware_execution": false,
"network_accessed": false
},
"facts": {
"backend_id": "local.simulator",
"gpu_error_code": "SIMULATION_DEVICE_UNAVAILABLE",
"gpu_error_path": "simulation_options.device",
"gpu_error_stage": "simulation",
"job_created_for_gpu": false,
"methods": [
"state_vector",
"subspace",
"density_matrix",
"trajectory"
],
"noise_supported": true,
"scan_supported": true
},
"lesson": "capability_boundaries",
"level": "expert",
"track": "sdk_platform_engineer"
}
GPU 请求应抛出 CapabilityError，代码为 SIMULATION_DEVICE_UNAVAILABLE，阶段为 simulation，对象路径为 simulation_options.device。job_created_for_gpu 根据调用是否真正返回句柄计算，预期为 false。脚本捕获这个预期错误，是为了打印诊断，不表示 GPU 任务执行成功。
应用可以根据稳定的错误代码决定处理方式，并在有消息和建议时展示给使用者。不要捕获全部异常后统一返回空结果：无效输入、不支持的能力和运行失败需要分别处理。被拒绝的请求没有可导出的测量数据。
区分能力声明与执行证据¶
| 已知事实 | 能说明什么 |
|---|---|
| 能力列表中包含某方法 | 后端为满足条件的任务实现了这种方法。 |
| 规划器接受当前请求 | 程序、选项和估算资源通过了执行前检查。 |
| Job 返回已完成结果 | 这次提交的任务实际执行了。 |
| 结果符合独立预测 | 在相应假设下，已检查的计算与预测一致。 |
这些结论需要依次检查，前一项不能替代后一项。类似地，源码哈希或演练用的提交包也不能证明硬件已执行。SDK 的公开 Backend 路径运行本地模拟；Cloud 与 Hanyuan 材料仅涉及文档说明的离线接口、回放或演练。
尝试支持的设备与不适用的方法¶
- 在副本中请求
device='cpu'，先检查返回的 Job，再调用result()。数值工作在哪一步发生？ - 对同一个程序请求
method='density_matrix'，但不提供噪声模型。为什么方法列在能力表中，这次仍可能不接受？ - 能力检查拒绝请求后，将完全相同的请求重试三次有帮助吗？
CPU 请求会返回排队中的 Job，调用 result() 才执行。没有噪声模型时，显式密度矩阵请求不满足条件，会在规划阶段被拒绝。重复提交同一个不支持的请求不会增加能力，应明确调整请求条件或选择兼容的后端。
方法适用条件见本地模拟算法，硬件边界见当前限制。现在可以从输入检查一路追踪到执行、结果保存和恢复，并区分离线产物与真实运行。