QCloudService

QCloudService 是连接 OriginQ 云后端的入口。

QCloudService

QCloudService(api_key: str)
QCloudService(api_key: str, url: str)

• 单参构造从新格式 API key 中解析服务域名；旧格式 key 不携带域名，使用历史默认云端端点。
• 两参构造的 url 显式覆盖 key 中编码的域名，用于测试或私有部署；0.5.1 绑定中 url 已无默认值。

方法

方法	签名	说明
setup_logging	setup_logging(output: LogOutput = LogOutput.CONSOLE, file_path: str = "") -> None	配置客户端日志。
backends	backends() -> dict[str, bool]	列出后端名称及可用性。
best_qubit_blocks	best_qubit_blocks(chip_id: str, qubit_num: int, label: int = 1, qubit_block_num: int = 1) -> BestQubitBlocks	查询芯片的最优比特块。
backend	backend(backend_name: str) -> QCloudBackend	按名称打开一个后端。

BestQubitBlocks

BestQubitBlocks 存储云端最优比特块查询结果。返回的块按质量排序，可直接用于 QCloudOptions.set_specified_block(...)。

属性 / 方法	类型	说明
chip_id	str	查询所用的芯片标识。
qubit_num	int	每个块请求的量子比特数。
label	int	块选择的优化标签。
qubit_block_num	int	请求的块数量。
qubit_blocks	list[list[int]]	选出的比特块，每个块是一组物理比特索引。
size()	int	选中的块数量（等价于 len(blocks)）。
empty()	bool	是否未选出任何块。
block(index: int)	list[int]	按索引获取一个块。越界抛出 IndexError。

BestQubitBlocks 支持 __getitem__ / __len__ / __repr__。

from pyqpanda3.qcloud import QCloudService

service = QCloudService("your_api_key")
blocks = service.best_qubit_blocks("WK_C180_2", qubit_num=2, label=1, qubit_block_num=2)

print(blocks.chip_id)        # "WK_C180_2"
print(blocks.qubit_blocks)   # [[59, 69], [99, 108]]
print(blocks.size())         # 2
print(blocks.block(0))       # [59, 69]
print(blocks[0])             # [59, 69]
print(len(blocks))           # 2

QCloudBackend

QCloudBackend 表示一个已选定的云后端。

QCloudBackend(backend_name: str)

常用执行重载

run(
    prog: QProg,
    shots: int,
    model: QCloudNoiseModel = QCloudNoiseModel(),
    batch_id: str = "",
    task_form: int = 4,
) -> QCloudJob

run(
    prog: QProg,
    shots: int,
    options: QCloudOptions,
    enable_binary_encoding: bool = False,
    batch_id: str = "",
    task_form: int = 4,
) -> QCloudJob

run(
    progs: list[QProg],
    shots: int,
    options: QCloudOptions,
    enable_binary_encoding: bool = False,
    batch_id: str = "",
    task_form: int = 4,
) -> QCloudJob

源码还支持这些额外形式：

• run(prog, qubits=[...])
• run(prog, amplitudes=[...])
• run(prog, amplitude="0101")
• run_quantum_state_tomography(prog, shots, options=QCloudOptions())

run_instruction

run_instruction(
    instruction: str | list[str],
    shots: int,
    options: QCloudOptions,
    batch_id: str = "",
    task_form: int = 4,
) -> QCloudJob

直接提交指令 JSON，而不是发送 QProg。

芯片与布局辅助接口

方法	签名	说明
chip_info	chip_info() -> ChipInfo	原始芯片元数据。
chip_backend	chip_backend(qubits: list[int] = []) -> ChipBackend	chip_info().get_chip_backend() 的便捷包装。
best_qubit_blocks	best_qubit_blocks(qubit_num: int, label: int = 1, qubit_block_num: int = 1) -> BestQubitBlocks	查询此后端的最优比特块。
name	name() -> str	后端名称。

NOTE

真实 QPU 限制

chip_info() 和 chip_backend() 只适用于真实 QPU 后端。对 full_amplitude、partial_amplitude、single_amplitude 等云模拟器调用会抛出 RuntimeError: This function is only for real QPU backend. 自 0.5.0 起 chip_info() 可无参调用（带 options 的重载仍然可用）。

期望值接口

expval_hamiltonian(
    prog: QProg,
    hamiltonian: Hamiltonian,
    shots: int = 1000,
    noise_model: QCloudNoiseModel = QCloudNoiseModel(),
) -> float

expval_hamiltonian(
    prog: QProg,
    hamiltonian: Hamiltonian,
    options: QCloudOptions,
) -> float

expval_pauli_operator(...) 也有对应的等价重载。

ChipInfo

ChipInfo 提供硬件标定数据，并且可以直接物化成 ChipBackend。

方法	说明
qubits_num()	量子比特总数。
chip_id()	芯片标识。
available_qubits()	当前可用的物理量子比特。
high_frequency_qubits()	高频量子比特列表。
single_qubit_info()	单比特读出与相干信息。
double_qubits_info()	双比特保真度信息。
get_basic_gates()	原生门集。
get_compensate_angle_map()	CZ 补偿角映射。
get_double_gate_timing()	双比特门时序值。
get_single_gate_timing()	单比特门时序值。
get_chip_topology(qubits=[])	耦合图。
get_chip_backend(qubits=[])	构造带有时序、拓扑和保真度映射的 ChipBackend。

QCloudOptions

QCloudOptions 控制云端提交时的编译、映射、纠错与输出选项。

QCloudOptions(
    amend_flag: int = 1,
    use_cz_pattern: bool = False,
    mapping: bool = True,
    optimization: bool = True,
    point_label: int = 1,
    is_prob_counts: bool = True,
    specified_block: list[int] = [],
)

方法	签名	说明
set_amend_flag	set_amend_flag(amend_flag: int) -> None	0 关闭纠错，1 全局采样纠错，3 局部实时纠错。
amend_flag	amend_flag() -> int	返回纠错模式。
set_use_cz_pattern	set_use_cz_pattern(use_cz_pattern: bool) -> None	设置串扰噪声抑制。
use_cz_pattern	use_cz_pattern() -> bool	查询串扰噪声抑制。

原有的 set_amend、set_mapping、set_optimization、set_point_label、set_specified_block、set_is_prob_counts 与 set_custom_option 仍然可用。

QCloudOptions.print() 输出当前设置：

is_prob_counts: true
amend_flag: 1
use_cz_pattern: false
mapping: true
optimization: true
point_label: 1

示例

import os

from pyqpanda3.core import CZ, H, QProg, measure
from pyqpanda3.qcloud import QCloudOptions, QCloudService
from pyqpanda3.transpilation import Transpiler, decompose
from pyqpanda3.visualization import draw_time_scheduling

service = QCloudService(os.environ["QPANDA_QCLOUD_API_KEY"])
backend = service.backend(os.environ.get("QPANDA_QCLOUD_BACKEND", "WK_C180_2"))

chip_info = backend.chip_info()
chip_backend = backend.chip_backend([0, 10])

prog = QProg()
prog << H(0) << CZ(0, 1) << measure(0, 0) << measure(1, 1)

decomposed = decompose(prog, ["U3", "CZ"])
transpiled = Transpiler().transpile(decomposed, chip_backend, {}, 2, "fidelity")
instruction = transpiled.to_instruction(
    chip_backend,
    offset=1,
    is_scheduling=True,
    compensate_pulse=False,
)
figures = draw_time_scheduling(instruction, backend=chip_backend, output="plotly")

options = QCloudOptions()
options.set_mapping(False)
options.set_optimization(False)
options.set_amend(False)
options.set_specified_block([0, 10])

job = backend.run_instruction([instruction], 1000, options)
print(chip_backend.basic_gates)
print(chip_backend.single_gate_timing, chip_backend.double_gate_timing)
print(type(figures).__name__)
print(job.job_id())

示例输出形态：

['RPhi', 'CZ']
25 40
Figure
JOB_ID

说明

• chip_info().get_chip_backend() 是从云端标定数据进入本地 transpiler API 的显式路径。返回的 ChipBackend 同时携带拓扑、保真度、补偿角和时序数据，可继续用于 transpile()、to_instruction(is_scheduling=True) 与时序可视化。
• options=None / 默认 QPU 选项这类 run() 便捷重载属于当前 0.4.0 源码绑定中整理出的 QCloud 工作流。
• pyqpanda3 0.4.0 源码中，QCloudOptions() 默认 mapping=True、optimization=True、amend=True、prob_counts=True、point_label=1、specified_block=[]。
• 自 0.5.0 起，QCloudOptions.get_custom_option(name) 返回存储值的真实类型（int/float/str/bool）；此前 Python 侧只有 int 重载可达。各 setter（set_amend、set_mapping、set_optimization、set_point_label、set_specified_block、set_is_prob_counts、set_custom_option）与 has_custom_option 与 0.4.x 相同。
• 自 0.5.1 起，QCloudOptions 支持关键字构造，新增 amend_flag（0/1/3）与 use_cz_pattern；print() 输出 amend_flag / use_cz_pattern，不再输出 amend。
• QCloudService.best_qubit_blocks(chip_id, qubit_num, label=1, qubit_block_num=1) 和 QCloudBackend.best_qubit_blocks(qubit_num, label=1, qubit_block_num=1) 都在 0.4.0 源码中暴露。如需手动固定物理比特，请使用 QCloudOptions.set_specified_block([...])，并先检查 ChipInfo.available_qubits() 与 ChipInfo.get_chip_topology()。

另见

• QCloudJob
• QCloudResult
• Transpiler API