Troubleshooting¶
本页整理用户在本地试用 CASCAQit 时常见的问题，重点覆盖 learning 示例、release smoke 示例和当前 Alpha SDK 行为。
安装¶
请使用 Python 3.9 至 3.13，并在仓库根目录安装：
python3 -m pip install -e ".[dev]"
如果安装后 import 失败，先确认命令是在仓库根目录执行的，并且运行示例时使用的是同一个 Python 解释器：
python3 -c "import cascaqit; print(cascaqit.__version__)"
先运行 learning 示例¶
首次检查请运行 learning 示例：
python3 examples/learning/analog_first_run.py
python3 examples/learning/digital_first_run.py
python3 examples/learning/result_diagnostics_first_run.py
python3 examples/learning/visualization_metadata_first_run.py
如果只需要更短的发布包烟测，再运行 release 示例：
python3 examples/release/minimal_analog_quickstart.py
python3 examples/release/minimal_digital_quickstart.py
python3 examples/release/minimal_result_view.py
python3 examples/release/minimal_structured_error.py
这两组示例都预期不需要硬件、云服务、凭证或网络访问。
看到 hardware_execution: False 或 cloud_execution: False¶
这是预期行为。当前发布示例使用本地 SDK 路径。hardware_execution: False 和 cloud_execution: False 是刻意打印出来的边界字段。
当前版本不支持真实汉原2号执行、真实硬件执行、CASCAQit Cloud 执行或云端编译。
Analog 示例报告 validation errors¶
发布版 analog 示例应打印空的 validation_errors。如果你自己写的程序出现 validation errors，请检查：
- atom spacing 和坐标单位；
- waveform duration 和 waveform shape；
MockNeutralAtomTarget.v0_1()提供的 target constraints；- 传给
program.validate(...)的 shots 设置。
Validation errors 的作用是在程序进入 compilation 或任何 backend handoff 前阻止无效程序。
Digital 示例的 bitstring 看起来不符合预期¶
解释 bitstring 前先查看 bit_order。发布版 digital 示例会打印：
['q0', 'q1']
这表示 bitstring 按 q0、再 q1 的顺序解释。编写分析代码时，应把这份 metadata 和 counts、probabilities 一起保留。
Result view 没有渲染图表¶
这是预期行为。minimal_result_view.py 构建只读取元数据的 result view 和 histogram descriptor。它保持示例可以在普通 Python 环境运行，不直接渲染 chart。
需要可视化输入时，使用 build_counts_histogram(result) 生成可供渲染的 metadata，再交给 notebook、web UI 或报告工具渲染。
Structured error 里有 suggestion¶
应把 suggestion 看作恢复建议，而不是自动修复。面向工具的稳定字段是 code、object_path、reason_category 和 category。
我需要硬件或云执行¶
当前 Alpha 候选版本是本地 SDK 预览。硬件和云相关路径是准备界面：它们描述 payload、metadata、diagnostics 和 planning details，但不代表真实服务已经接通。
不要期待当前版本会加载凭证、探测网络端点、读取对象存储、签发 signed URL、上传发布包或执行 release signing。
下一步阅读¶
- Fresh Checkout 学习路径：
docs/zh/user-guide/learning-path.md - 快速开始烟测：
docs/zh/getting-started/quickstart.md - Analog walkthrough：
docs/zh/user-guide/analog-walkthrough.md - Digital walkthrough：
docs/zh/user-guide/digital-walkthrough.md - 结果和诊断：
docs/zh/user-guide/result-diagnostics-visualization.md - 当前限制：
docs/zh/limitations.md