提交任务到量子云平台 {#guide-submit-task}¶

什么时候进入本页 {#guide-submit-task-when-to-read}¶

当你已经完成本地线路构建，并且已经通过快速上手或本地模拟跑通了最小示例，接下来如果你希望：

把线路提交到云平台或真机执行
查询远端任务状态与执行结果
比较不同平台的接入方式与适用场景

就应该进入本页。

本页讨论的是远端任务提交路径，它解决的是”如何把已经在本地验证过的线路交给外部平台执行”的问题，而不是”如何在本地验证线路是否正确”。

本页解决的问题 {#guide-submit-task-problems}¶

什么时候应从本地模拟切换到提交任务路径
提交到云平台前需要准备哪些配置
不同平台各自适合什么场景
如何提交任务、查询状态并获取结果
使用远端平台前需要先了解哪些边界与限制

前置条件¶

阅读本页前，默认你已经完成以下至少一项：

已经完成快速上手中的最小示例
已经会使用 Circuit 构建线路，并能导出 originir 或 qasm
已经通过本地模拟对线路做过基本验证

如果你还不确定线路是否正确、输出是否合理，建议先留在本地模拟路径，不要直接进入远端提交。

通用流程 {#guide-submit-task-flow}¶

无论选择哪个平台，远端任务提交通常都遵循以下流程：

准备线路 —— 确认你已经有可提交的 Circuit 对象
选择平台 —— 根据目标平台、依赖、成熟度与接入条件决定使用哪个后端
准备配置 —— 通过环境变量配置 Token
提交任务 —— 调用 submit_task() 提交任务
查询结果 —— 通过 wait_for_result() 或 query_task() 获取结果

与本地模拟相比，这条路径多出了平台账号、配置文件、网络访问、任务排队与远端状态查询等因素。

统一云平台接口 {#guide-submit-task-unified-api}¶

UnifiedQuantum 提供统一的云平台接入层，通过一致的接口操作 OriginQ、IBM 和 Quark 等平台。

配置方式¶

云平台 API key 统一通过 ~/.uniqc/config.yaml 配置：

uniqc config set originq.token "your-originq-token"
uniqc config set ibm.token "your-ibm-token"

对应的 YAML 配置文件结构如下：

active_profile: default
default:
  originq:
    token: "your-originq-token"
  ibm:
    token: "your-ibm-token"
    proxy:
      http: "http://proxy:8080"
      https: "https://proxy:8080"

基本用法¶

完整 API 文档与所有可选参数（local_compile、cloud_compile、skip_validation、options=、backend_name=、chip_id= 等）见 uniqc.backend_adapter.task_manager.submit_task。同时也可以在交互环境中执行 help(submit_task) 查看完整 docstring。

from uniqc import Circuit, submit_task, wait_for_result, query_task, poll_result, get_result

# 1. 创建电路
circuit = Circuit()
circuit.h(0)
circuit.cnot(0, 1)
circuit.measure(0, 1)

# 2. 提交任务
#
# backend 参数必须使用 'provider:chip-name' 的规范格式。仅传 'originq'
# （或其它平台名）会报错并提示当前缓存中的 chip 列表。可用的 chip 列表
# 通过 `uniqc backend list -p originq` 或 `uniqc.list_backends()` 查询。
#
# 默认 local_compile=1：UnifiedQuantum 会先做离线 compatibility 检查，
# 若使用了非 basis 门（如 H/CNOT），会自动 transpile 到目标芯片的 basis
# 门集（CZ/SX/RZ）和拓扑后再提交，因此你不需要手动 compile() 才能提交。
task_id = submit_task(circuit, backend='originq:WK_C180', shots=1000)
print(f"Task ID: {task_id}")

# 3. 等待结果（返回 UnifiedResult；超时抛 TaskTimeoutError，失败抛 TaskFailedError）
result = wait_for_result(task_id, timeout=300)
print(f"Counts: {result.counts}")          # {'00': 512, '11': 488}
print(f"Probabilities: {result.probabilities}")

# 4. 查询任务状态
info = query_task(task_id)
print(info.status)  # TaskStatus.RUNNING / SUCCESS / FAILED

关于 backend 字符串的强校验（自 0.0.12 起）：submit_task() / submit_batch() 要求 backend 满足 provider:chip-name 规范格式（如 originq:WK_C180、ibm:ibm_brisbane）。仅传裸平台名（'originq'）会被拒绝，错误信息会列出本地缓存里能用的 chip。需要先通过 uniqc auth login / uniqc config set <provider>.token … 配好 API key，然后用 uniqc backend list -p originq 拉一遍 backend 列表，再选一个 chip 提交。

旧的 submit_task(circuit, backend='originq', backend_name='WK_C180') 写法仍可工作（会被自动归一为 originq:WK_C180），但新代码请直接用规范格式。

平台选择¶

切换不同平台只需更改 backend 参数（保持 provider:chip-name 规范格式）：

# OriginQ Cloud
task_id = submit_task(circuit, backend='originq:WK_C180', shots=1000)

# IBM Quantum（qiskit 已是核心依赖，无需额外安装）
task_id = submit_task(circuit, backend='ibm:ibm_brisbane', shots=1000)

# QuarkStudio / Quark（需要 pip install unified-quantum[quark]，Python ≥ 3.12）
task_id = submit_task(circuit, backend='quark:<chip>', shots=1000)

任务管理¶

from uniqc import list_tasks, get_task, clear_completed_tasks, clear_cache

# 查看所有缓存的任务
tasks = list_tasks()
for task in tasks:
    print(f"{task.task_id}: {task.status}")

# 获取特定任务信息
task_info = get_task(task_id)

# 清理已完成的任务
cleared = clear_completed_tasks()
print(f"Cleared {cleared} tasks")

# 清空所有缓存
clear_cache()

后端信息¶

from uniqc import backend

# 列出所有已注册后端名称
names = backend.list_backends()  # ['dummy', 'ibm', 'originq', 'quark']

# 获取详细状态信息
backends = backend.list_backends_by_platform()
for name, info in backends.items():
    print(f"{name}: available={info['available']}")

# 获取特定后端实例
originq_backend = backend.get_backend('originq')
print(f"OriginQ available: {originq_backend.is_available()}")

后端命名规则 {#guide-submit-task-backend-naming}¶

submit_task() 和 CLI 的 --backend 参数均使用统一的后端标识符格式。

格式说明¶

云平台后端：provider:chip-name（如 originq:WK_C180）
本地 dummy 后端：以 dummy 开头（如 dummy:local:simulator）

命名规则与典型示例¶

后端 ID	含义
`originq:WK_C180`	OriginQ 180 比特真机
`originq:full_amplitude`	OriginQ 全振幅模拟器
`ibm:ibm_brisbane`	IBM Brisbane 真机
`dummy` 或 `dummy:local:simulator`	无约束、无噪声本地模拟器
`dummy:local:virtual-line-N`	N 比特线性拓扑，无噪声
`dummy:local:virtual-grid-RxC`	R×C 网格拓扑，无噪声
`dummy:local:mps-linear-N`	N 比特 MPS 模拟器（线性链）
`dummy:<platform>:<backend>`	复用真实 backend 拓扑和标定数据的本地含噪模拟

dummy:<platform>:<backend> 是规则型写法，不需要提前注册，也不会出现在 uniqc backend list 的列表中。运行时会解析真实 backend 的拓扑和标定数据，先 compile/transpile，再在本地执行含噪模拟。

MPS 隐式参数¶

MPS（Matrix Product State）模拟器支持通过后缀传递隐式参数，格式为：

dummy:local:mps-linear-N:chi=<bond_dim>:cutoff=<threshold>

参数	含义	默认值
`chi`	MPS bond dimension（键维度）	取决于电路规模
`cutoff`	SVD 截断阈值	`1e-10`

这些参数可选，省略时使用默认值。

from uniqc import submit_task

# 使用默认参数
task_id = submit_task(circuit, backend='dummy:local:mps-linear-32')

# 指定 bond dimension 和截断阈值
task_id = submit_task(circuit, backend='dummy:local:mps-linear-32:chi=64:cutoff=1e-10')

CLI 中同样适用：

uniqc submit circuit.ir --backend dummy:local:mps-linear-32:chi=64:cutoff=1e-10

Dummy 模式（本地模拟） {#guide-submit-task-dummy}¶

Dummy 模式允许在不连接真实云平台的情况下测试任务提交流程。通过 backend 名称前缀 dummy 激活。

启用方式¶

from uniqc import submit_task, wait_for_result

# 默认 dummy 模拟
task_id = submit_task(circuit, backend='dummy:local:simulator')
result = wait_for_result(task_id)

# 带 chip 特征的 dummy 模拟
task_id = submit_task(circuit, backend='dummy:originq:WK_C180')

# 线性拓扑 dummy
line_task = submit_task(circuit, backend='dummy:local:virtual-line-3')
grid_task = submit_task(circuit, backend='dummy:local:virtual-grid-2x2')  # 2x2 网格、无噪声
noisy_task = submit_task(circuit, backend='dummy:originq:WK_C180')  # 真实 backend compile/transpile + 本地含噪执行

注意：backend='dummy:*' 系列以及 dummy=True 的提交不会触发”必须带 chip” 的规范格式校验——dummy 路径只用于本地验证，由 dummy 适配器自行处理子标识符。

弃用警告：dummy=True 参数已弃用，请改用 backend='dummy:local:simulator'。如果你想模拟某个真实芯片，请使用 backend='dummy:<platform>:<backend>'，例如 backend='dummy:originq:WK_C180'。这一类 chip-backed dummy 是规则型写法，不会出现在 backend 列表中。

Dummy 模式适用场景¶

开发阶段验证提交/查询调用链路
本地测试任务提交流程
在不具备真实平台访问条件时完成联调
在提交到真实硬件前，用 dummy:virtual-* 或 dummy:<platform>:<backend> 验证拓扑、compile/transpile 与任务展示链路

批量提交¶

from uniqc import submit_batch

# 构建多个电路
circuits = []
for i in range(10):
    c = Circuit()
    c.h(0)
    c.rx(1, i * 0.1)
    c.cnot(0, 1)
    c.measure(0, 1)
    circuits.append(c)

# 批量提交
task_ids = submit_batch(circuits, backend='originq:WK_C180', shots=1000)
print(f"Submitted {len(task_ids)} tasks")

多种输入格式 {#guide-submit-task-input-formats}¶

submit_task() 和 submit_batch() 支持以下输入类型，提交时会自动检测并转换为内部 Circuit 对象：

uniqc.Circuit（推荐）—— 直接传入
OriginIR 字符串 —— 以 QINIT 开头的 OriginIR 文本
OpenQASM 2.0 字符串 —— 以 OPENQASM 开头的 QASM 文本
qiskit.QuantumCircuit —— 自动转为 QASM 后再导入

from uniqc import Circuit, submit_task

# 方式 1: Circuit 对象（推荐）
circuit = Circuit(2)
circuit.h(0)
circuit.cnot(0, 1)
circuit.measure(0, 1)
task_id = submit_task(circuit, backend='originq:WK_C180', shots=1000)

# 方式 2: OriginIR 字符串
task_id = submit_task(
    "QINIT 2\nCREG 2\nH q[0]\nCNOT q[0], q[1]\n"
    "MEASURE q[0], c[0]\nMEASURE q[1], c[1]\n",
    backend='originq:WK_C180', shots=1000,
)

# 方式 3: OpenQASM 2.0 字符串
task_id = submit_task(
    'OPENQASM 2.0;\ninclude "qelib1.inc";\n'
    'qreg q[2];\ncreg c[2];\nh q[0];\ncx q[0],q[1];\n'
    'measure q[0] -> c[0];\nmeasure q[1] -> c[1];\n',
    backend='originq:WK_C180', shots=1000,
)

# 方式 4: Qiskit QuantumCircuit
from qiskit import QuantumCircuit as QiskitQC
qc = QiskitQC(2, 2)
qc.h(0); qc.cx(0, 1); qc.measure([0, 1], [0, 1])
task_id = submit_task(qc, backend='ibm:ibm_brisbane', shots=1000)

如果字符串格式无法识别，会抛出 TypeError。

结果处理¶

Bitstring 约定（永久不变）{#guide-submit-task-bitstring-convention}¶

uniqc 在所有平台（OriginQ / IBM-Qiskit / Quark / Dummy / 本地仿真）返回的 result.counts / result.probabilities 字典 key 都满足 同一条永久约定：

c[0] 始终是 bitstring 的最右侧字符（LSB），c[N-1] 是最左侧字符。

c[i] 记录的是 第 i 次 调用 circuit.measure(q) 的比特，与 qubit 索引解耦。如果你按 circuit.measure(0); circuit.measure(1) 的顺序写测量，那么 c[0] 对应 q[0] 的结果，c[1] 对应 q[1]。

最简自检脚本（在任何后端都应给出 '01' 占绝对多数）：

from uniqc.circuit_builder import Circuit
from uniqc.backend_adapter.task_manager import submit_batch, wait_for_result

c = Circuit(2)
c.x(0)
c.measure(0)        # -> c[0]
c.measure(1)        # -> c[1]

uid = submit_batch([c], backend='dummy:local:virtual-line-2', shots=1024)
print(wait_for_result(uid)[0].counts)   # -> {'01': 1024}

x(0) 把 q[0] 翻成 |1⟩，q[0]→c[0]→1，所以读到的 bitstring 是 '01' （左边是 c[1]=0，右边是 c[0]=1）。这一约定由 uniqc/test/test_endianness_convention.py 在每次发布前对所有平台 adapter 强制校验，不会再改变。

任何平台原生 SDK 的差异（IBM 默认 little-endian、Quark 取决于固件）都已经在 adapter 内部统一翻译为以上约定；下游代码不必再做 [::-1] 之类的手工翻转。

返回值结构¶

wait_for_result(task_id, ...) 返回 :class:UnifiedResult（dict-like，统一接口）；原生批量任务（submit_batch(..., native_batch=True)）返回 list[UnifiedResult]。

result = wait_for_result(task_id)

# 访问测量结果
print(result.counts)         # {'00': 512, '11': 488}
print(result.probabilities)  # {'00': 0.512, '11': 0.488}
print(result['00'])          # dict-like 访问也可
print(result.raw())          # 原始平台 payload

# 计算期望值
from uniqc import calculate_expectation
exp_zz = calculate_expectation(result.probabilities, 'ZZ')
print(f"<ZZ> = {exp_zz}")

非阻塞查询 {#guide-submit-task-polling}¶

所有任务提交都是异步的——submit_task() 立即返回 task_id，不会阻塞等待云端结果。你可以选择阻塞或非阻塞方式获取结果：

from uniqc import submit_task, get_result, poll_result, TaskStatus

task_id = submit_task(circuit, backend='originq:WK_C180', shots=1000)

# 方式 1: 非阻塞轮询（立即返回当前状态）
info = poll_result(task_id)
print(info.status)  # TaskStatus.RUNNING / SUCCESS / FAILED

# 方式 2: 阻塞等待（等任务完成或超时）
result = get_result(task_id, timeout=300, poll_interval=5)

# 方式 3: 经典阻塞等待（get_result 的等价接口）
from uniqc import wait_for_result
result = wait_for_result(task_id, timeout=300)

典型轮询模式：

import time
while True:
    info = poll_result(task_id)
    if info.status in (TaskStatus.SUCCESS, TaskStatus.FAILED):
        break
    time.sleep(2)

平台特定后端参数¶

# OriginQ: 指定芯片和优化选项
task_id = submit_task(circuit, backend='originq:WK_C180', circuit_optimize=True)

平台选择说明 {#guide-submit-task-platform-selection}¶

平台	定位	适用场景	额外依赖
OriginQ Cloud	主生产路径	生产环境、真实量子计算	无额外依赖
QuarkStudio / Quark	第三方云平台	国内 QuarkStudio 生态 / 自建 Quark 集群	`pip install unified-quantum[quark]`（要求 Python ≥ 3.12）
IBM Quantum	第三方云平台	IBM Quantum 生态	qiskit 已是核心依赖，无需额外安装
Dummy	本地模拟	开发测试、联调	`pip install unified-quantum[simulation]`

平台边界与限制¶

在进入远端提交路径前，建议先确认以下几点：

本地模拟 != 远端提交：本地模拟解决的是线路验证问题；远端提交解决的是平台接入与任务执行问题。
配置是前置条件：不同平台需要配置相应的环境变量。
网络与账号会影响可用性：远端平台可能受网络环境、认证状态、平台可用性和排队情况影响。
额外依赖：IBM/Qiskit 已并入核心依赖，无需额外安装；Quark 需要 pip install unified-quantum[quark]（Python ≥ 3.12）。

如果你还在反复修改线路结构、量子门或输出解释，说明你仍处于本地验证阶段，建议先回到本地模拟。

下一步与参考¶

如果你还没有完成线路验证，先回到本地模拟
如果你还不清楚线路如何构建，先阅读构建量子线路
API 参考：

完整 API 参考 {#guide-submit-task-api-reference}¶

下面把 submit_task 的完整签名 / 默认参数 / 隐藏 kwargs 全部展开列出，避免你必须跳到独立 API 文档去查。submit_batch 接受同样的 kwargs，只是把 circuit 换成 circuits: list[Circuit]，并返回 list[str]。

uniqc.backend_adapter.task_manager.submit_task(circuit, backend, shots=1000, metadata=None, options=None, *, local_compile=1, cloud_compile=1, backend_name=None, chip_id=None, **kwargs)[source]

Submit a single circuit to a quantum backend.

This function performs IR-language validation, optionally rewrites the circuit through a local qiskit transpile pass, then ships the result to the backend’s native API.

Parameters:

circuit (Circuit | str) – The UnifiedQuantum Circuit to submit.
backend (str) – Backend identifier in the canonical 'provider:chip-name' format (e.g. 'originq:WK_C180', 'quafu:ScQ-P10', 'ibm:ibm_brisbane'). Cloud submissions reject the bare 'provider' form (e.g. 'originq') and surface the list of cached chips for that provider — call uniqc.list_backends() or run uniqc backend list -p originq to discover available chips. Dummy backends use 'dummy' or 'dummy:<provider>:<chip>' and are exempt from the strict format check.
shots (int) – Number of measurement shots.
metadata (dict | None) – Optional metadata to store with the task.
options (BackendOptions | UnifiedOptions | dict | None) – Optional typed backend options. Accepts a BackendOptions instance, a UnifiedOptions instance (auto-translated to the platform’s specific options with cross-platform semantics for optimize_level / error_mitigation / auto_mapping), a plain dict (treated as **kwargs), or None for platform defaults.
local_compile (int) –
Local qiskit transpile pass strength.
- 0 — no local transpile. The circuit is shipped as-authored (after IR-language validation). Use this when you have hand-tuned the circuit or want to delegate everything to the cloud transpiler.
- 1 (default) — light qiskit transpile to the chip’s basis gates and topology when validation fails.
- 2 / 3 — heavier qiskit optimization. Slower but yields shorter / higher-fidelity circuits.
See docs/source/compile/compile_levels.md for details on what each level does.
cloud_compile (int) – Cloud-side compile request strength forwarded to the adapter. 0 disables cloud compile (e.g. OriginQAdapter receives circuit_optimize=False); any value > 0 enables it (boolean cloud APIs see True). Adapters with finer control may interpret 1/2/3 directly.
backend_name (str | None) – OriginQ chip name (e.g. 'WK_C180'). Optional when backend already encodes the chip as 'originq:<chip>'.
chip_id (str | None) – Quafu / IBM chip ID. Required for full validation on those platforms.
**kwargs (Any) –
Additional backend-specific parameters passed through to the underlying adapter. Common implicit / hidden defaults:
- skip_validation (default False): bypass the offline IR-language compatibility check. Use sparingly — most validation failures are real bugs.
- For Quafu: chip_id, auto_mapping
- For OriginQ: backend_name (e.g. 'WK_C180'), measurement_amend
- For dummy: chip_characterization, noise_model, available_qubits, available_topology

Returns:

The task ID assigned by the backend.

Raises:

BackendNotFoundError – If the backend identifier is missing a chip name (bare 'provider') or is otherwise unrecognised.
BackendNotAvailableError – If the backend is not available.
UnsupportedGateError – If the circuit uses gates that cannot be expressed in the backend’s IR language and cannot be auto-decomposed (hard block — most OriginIR-native gates such as RPhi/PHASE2Q/UU15 are auto-rewritten via uniqc.compile.decompose before this check; only controlled wrappings or unrecognised gates fall through).
AuthenticationError – If authentication fails.
InsufficientCreditsError – If account has insufficient credits.
QuotaExceededError – If usage quota is exceeded.
NetworkError – If a network error occurs.

Return type:

str

Example

>>> circuit = Circuit()
>>> circuit.h(0)
>>> circuit.cnot(0, 1)
>>> circuit.measure(0, 1)
>>> # Canonical form (preferred):
>>> task_id = submit_task(circuit, backend='originq:WK_C180', shots=1000)
>>> # Legacy form (still accepted, normalised internally):
>>> task_id = submit_task(circuit, backend='originq', backend_name='WK_C180', shots=1000)
>>> # Heavier local compile, no cloud-side recompile:
>>> task_id = submit_task(
...     circuit, backend='originq:WK_C180', shots=1000,
...     local_compile=3, cloud_compile=0,
... )
>>> # Local noisy simulation using chip characterization:
>>> from uniqc.backend_adapter.task.adapters.originq_adapter import OriginQAdapter
>>> chip = OriginQAdapter().get_chip_characterization("WK_C180")
>>> task_id = submit_task(circuit, backend='dummy:local:simulator', chip_characterization=chip)

uniqc.backend_adapter.task_manager.submit_batch(circuits, backend, shots=1000, options=None, *, local_compile=1, cloud_compile=1, backend_name=None, chip_id=None, native_batch=True, return_platform_ids=False, **kwargs)[source]

Submit multiple circuits as a batch and return a single uniqc task id.

uniqc maintains an internal mapping from one uqt_* task id to one or more platform-issued task ids. The user manages exactly one handle, regardless of the underlying platform’s batch capabilities:

For platforms with native batch (OriginQ, IBM) — circuits are packed into one platform job per shard. uniqc auto-shards if the batch exceeds the adapter’s max_native_batch_size (e.g. OriginQ task_group_size 200, IBM 100).
For platforms without native batch (Quafu, Quark, Dummy) — max_native_batch_size = 1: uniqc loops one platform job per circuit, but the user still receives a single uqt_* id and wait_for_result() returns the per-circuit results in submission order.

Parameters:

circuits (list[Circuit | str]) – List of UnifiedQuantum Circuits to submit.
backend (str) – The backend name.
shots (int) – Number of measurement shots per circuit.
options (BackendOptions | UnifiedOptions | dict | None) – Optional typed backend options. Same as in submit_task().
local_compile (int) – Local qiskit transpile pass strength. See submit_task() for the full semantics. Default 1.
cloud_compile (int) – Cloud-side compile request strength. See submit_task(). Default 1.
backend_name (str | None) – OriginQ chip name (optional when backend already encodes the chip).
chip_id (str | None) – Quafu / IBM chip ID.
native_batch (bool) – When True (default), shards use the platform’s native grouped-submission API (one platform job per shard). When False, every circuit is submitted as a separate platform job (one shard per circuit). Useful when you need to retry/cancel individual circuits but do not need per-circuit task ids returned.
return_platform_ids (bool) – When True, returns the list of platform-issued task ids (one per shard, NOT one per circuit). Provided only for legacy code paths and debugging; new code should always use the single returned uqt_* id and call get_platform_task_ids() if it needs the mapping.
**kwargs (Any) – Additional backend-specific parameters.

Returns:

The uniqc task id uqt_* for this batch, or a list of platform task ids when return_platform_ids=True.

Return type:

str | list[str]

Example

>>> circuits = [build(i) for i in range(400)]
>>> uid = submit_batch(circuits, 'originq', shots=1000,
...                    backend_name='WK_C180')
>>> # `uid` is one ``uqt_*`` covering up to ``ceil(400/200) = 2`` shards
>>> results = wait_for_result(uid)         # list[UnifiedResult] len=400
>>> shards  = get_platform_task_ids(uid)   # 2 shard rows

uniqc.backend_adapter.task_manager.wait_for_result(task_id, timeout=300.0, poll_interval=5.0, raise_on_failure=True)[source]

Wait for a task to complete and return its result.

This function polls the task status until it completes, fails, or the timeout is reached. The backend is auto-resolved from the cached TaskInfo — task IDs are unique, so explicit backend= is no longer needed.

Parameters:

task_id (str) – The task identifier.
timeout (float) – Maximum time to wait in seconds.
poll_interval (float) – Time between status checks in seconds.
raise_on_failure (bool) – If True, raises TaskFailedError on task failure.

Returns:

Single-circuit submissions return a UnifiedResult.

Native batch submissions (one cloud task ID covering many circuits, as produced by submit_batch() with native_batch=True) return a list[UnifiedResult] — one entry per circuit, in the order they were submitted.

Returns None if the task failed and raise_on_failure=False.

The UnifiedResult object is dict-like (result["00"], len(result), iteration, equality with a plain counts dict all work). Use UnifiedResult.raw() to access the original platform-specific payload.

Raises:

TaskTimeoutError – If the timeout is reached before completion.
TaskFailedError – If the task fails and raise_on_failure is True.
TaskNotFoundError – If the task is not found.
NetworkError – If a network error occurs.

Return type:

UnifiedResult | list[UnifiedResult] | None

Example

>>> result = wait_for_result('task-123', timeout=300)
>>> print(result.counts)        # unified accessor
{'00': 512, '11': 488}
>>> result['00']                # dict-like access still works
512
>>> result.raw()                # original adapter payload
{'result': {'00': 512, '11': 488}, ...}

Native batch result:

>>> task_ids = submit_batch([c1, c2, c3], backend='originq:WK_C180')
>>> results = wait_for_result(task_ids[0])
>>> for r in results:
...     print(r.counts)

uniqc.backend_adapter.task_manager.get_result(task_id, timeout=300.0, poll_interval=5.0, raise_on_failure=True)[source]

Blocking retrieval: wait until task completes or timeout.

This is a convenience alias for wait_for_result(). The name get_result emphasises the “I want the answer” pattern, while wait_for_result emphasises the blocking behaviour.

Parameters:

task_id (str) – The task identifier.
timeout (float) – Maximum time to wait in seconds (default 300).
poll_interval (float) – Seconds between status checks (default 5).
raise_on_failure (bool) – If True (default), raise TaskFailedError when the task fails. If False, return None on failure.

Returns:

UnifiedResult for single-circuit tasks, or list[UnifiedResult] for native batch submissions. Returns None if the task failed and raise_on_failure is False.

Raises:

TaskTimeoutError – If timeout is exceeded.
TaskFailedError – If the task fails and raise_on_failure is True.

Return type:

UnifiedResult | list[UnifiedResult] | None

uniqc.backend_adapter.task_manager.poll_result(task_id)[source]

Non-blocking status check: return current task status/result without waiting.

Unlike wait_for_result(), this returns immediately with the latest cached status. Call it in a loop if you want to poll without blocking.

Parameters:: task_id (str) – The task identifier (uqt_* or platform id).
Returns:: TaskInfo with current status. Check .status for TaskStatus.SUCCESS, TaskStatus.FAILED, TaskStatus.RUNNING, etc. If the task has completed, .result will be populated.
Return type:: TaskInfo

Example

>>> task_id = submit_task(circuit, backend='originq:WK_C180')
>>> while True:
...     info = poll_result(task_id)
...     if info.status in (TaskStatus.SUCCESS, TaskStatus.FAILED):
...         break
...     time.sleep(2)

uniqc.backend_adapter.task_manager.query_task(task_id, backend=None)[source]

Query the status of a task.

For uniqc-managed task ids, refreshes each shard’s status from its backend (best-effort), then denormalises the aggregate status onto the parent tasks row. The returned TaskInfo therefore reflects the freshest known state.

For legacy platform task ids (pre-v4 cache rows or rows without shards), falls back to the historical direct-query path.

Parameters:

task_id (str) – The task identifier. Accepts a uniqc id (uqt_*) or, with a deprecation warning, a raw platform id.
backend (str | None) – Ignored when the task is found in cache (the backend is resolved from the stored shards). Only used for legacy direct-query fallback.

Returns:

TaskInfo with current aggregated status.

Return type:

TaskInfo

关键隐式参数速查¶

参数 / 环境变量	默认值	作用
`local_compile` (kwarg)	`1`	本地 qiskit transpile 强度。`0` 完全关闭本地编译；`1` 在校验失败时做轻量 transpile 到 basis/拓扑；`2`/`3` 走更重的优化（更慢但更短/更高保真度的线路）。详情见 `docs/source/compile/compile_levels.md`。
`cloud_compile` (kwarg)	`1`	转发给适配器的云端编译强度。`0` 关闭云端编译（如 OriginQ 适配器会收到 `circuit_optimize=False`），`>0` 开启；支持精细控制的适配器可直接读取 1/2/3。
`skip_validation` (kwarg)	`False`	完全跳过离线 compatibility 检查（不推荐，会让已知会被云端拒绝的线路也走到网络层）。
`options` (kwarg)	`None`	平台专属的强类型选项对象（`OriginQOptions` / `IBMOptions` 等）。
`metadata` (kwarg)	`None`	写入本地 task 缓存的附加元数据；后续可通过 `query_task(...).metadata` 取回。
`backend_name` / `chip_id` (kwarg)	—	旧式写法，把 chip 名以独立 kwarg 形式传入。新代码直接写在 `backend='provider:chip'` 即可，旧写法会被自动归一。

文档版本与代码同步保证：基本用法示例由 uniqc/test/cloud/test_doc_basic_usage.py 自动跑测，文档写错或代码行为漂移时 CI 会失败；如果你发现新的 doc 示例无法运行，请同步加一条对应测试。