真机任务提交

compile() 只生成编译结果；submit() 会向量子硬件提供商实际提交任务，并可能消耗任务额度。提交前请确认 provider、机器、shots 和凭据。

提交前检查

在模拟器中验证线路和测量映射。
使用 compile() 检查目标门基、布局和生成的可执行内容。
确认提供商账户、目标机器、shots、费用或任务额度。
通过安全方式提供 token，再调用 submit()。


from unitarylab import Circuit
 
qc = Circuit(2)
qc.h(0)
qc.cx(0, 1)
 
hardware_result = qc.submit(
    provider="guodun",
    machine="gd_qc1",
    token="your-provider-token",
    shots=1024,
)

submit() 完成编译和提交并返回 HardwareResult。Guodun 和 Tianyan 适配器在省略 machine 时会查询机器列表并选择一个可用项；其余适配器应明确指定机器。凭据省略时，Guodun 和 Tianyan 可分别读取 GUODUN_LOGIN_KEY 和 TIANYAN_LOGIN_KEY。


submit(provider, machine=None, shots=1024, token=None)

provider 必须指向真实硬件适配器，不能使用 local。shots 应为正整数。省略 machine 时，实际目标取决于提交时返回的机器列表；要求固定目标时应明确指定机器。


from unitarylab import QCompiler
 
hardware_result = QCompiler().submit(
    circuit_or_qasm,
    provider="guodun",
    machine="gd_qc1",
    token="your-provider-token",
    shots=1024,
)

完整产物流为 raw_qasm -> optimized_qasm -> mapped_qcis -> hardware_result。LQCloud 需要 lqcloud SDK，QPanda3 需要 pyqpanda3，Quafu 需要 quarkstudio；缺少依赖时会在提交阶段报错。

HardwareResult

HardwareResult 统一保存以下信息：

字段或属性	说明
`provider` / `vendor`	提供商名称
`machine`、`status`、`submitted`	机器、任务状态和是否已提交
`query_ids` / `job_ids`	提供商任务标识
`layout`、`final_layout`	逻辑–物理量子比特映射
`raw_counts`、`raw_probabilities`	原始测量结果
`corrected_counts`、`corrected_probabilities`	读出缓解后的结果
`observed_counts`、`observed_probabilities`	根据缓解状态选择的推荐结果视图
`executable`、`executable_format`	实际提交的程序及格式
`stage_metadata`、`provider_result`	流水线元数据和提供商原始结果

可使用 to_dict() 生成可序列化摘要。不同提供商的任务状态和附加结果并不完全相同，应先检查 status，再读取 counts 或 provider_result。

提交成功只表示提供商已接受任务，不等于任务已经完成。网络超时后不要立即重复提交；应先使用提供商任务标识确认是否已经创建任务，避免重复消耗额度。

安全与限制

不要在 Notebook 输出、日志、截图或异常信息中打印 token。
真机结果受排队、校准、噪声和 shots 影响，与理想模拟结果不会完全一致。
提交前保存编译产物、机器名称和提交参数，便于复现实验。
第三方 SDK 的认证和网络错误由对应提供商处理，失败信息可能采用提供商自己的格式。

真机任务提交

提交前检查

HardwareResult

安全与限制

相关页面