pyqpanda3 文档

简体中文

English
English

简体中文

English
English

Appearance

0.4.1 ​

pyqpanda3 0.4.1 是 0.4.0 硬件工作流的延续与深化。本版本的焦点是：把保真度数据真正贯穿到转译决策里（保真度驱动近似分解、LightSABRE 路由、可回收的转译指标），同时补齐两类长期缺失的模拟器——矩阵乘积态（MPS）模拟器与海森堡绘景期望模拟器。

1. 强类型转译选项与指标回收 ​

0.4.0 的 transpile() 使用位置参数控制优化等级与布局策略。0.4.1 新增 TranspilationOptions，把所有可调项集中到一个对象里，并配套 TranspilationResult 一次性返回转译后的程序、编译耗时和指标。

python
from pyqpanda3.core import QProg, H, CZ, measure
from pyqpanda3.transpilation import (
    ChipBackend,
    LayoutMethod,
    RoutingMethod,
    Transpiler,
    TranspilationOptions,
)

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

backend = ChipBackend()
backend.chip_topology_edges = [[0, 1], [1, 2]]
backend.basic_gates = ["RPhi", "CZ"]
backend.single_gate_fidelity = {0: 0.99, 1: 0.99, 2: 0.99}
backend.readout_fidelity = {0: 0.90, 1: 0.90, 2: 0.99}
backend.double_gate_fidelity = {(0, 1): 0.90, (1, 2): 0.99}

options = TranspilationOptions()
options.optimization_level = 2
options.layout_method = LayoutMethod.FIDELITY
options.routing_method = RoutingMethod.LIGHT_SABRE
options.approximation_degree = 0.99
options.execution.routing_trials = 8
options.execution.seed = 42

result = Transpiler().transpile(prog, backend, options)

print(type(result).__name__)
print(result.compile_time_ns > 0)
print(sorted(result.metrics.keys()))
print(len(result.program.operations()) > 0)

示例输出形态：

text
TranspilationResult
True
['depth', 'fidelity_exact', 'fidelity_fallback', 'fidelity_unknown', 'log_expected_fidelity', 'two_qubit_gate_count']
True

result.metrics 与独立函数 transpilation_metrics(prog, backend) 返回的字典结构一致，包含：

字段类型说明
two_qubit_gate_countint转译后程序中的双比特门数量。
depthint转译后程序的门深度。
log_expected_fidelityfloat 或 None对每个门（以及每个被测比特一次读出）累加 log(1 - error) 得到的对数期望保真度；任何门或读出保真度未知时为 None。
fidelity_exactint保真度数据精确命中的门数。
fidelity_fallbackint回退到聚合估计的门数。
fidelity_unknownint完全没有保真度数据的门数。

2. LightSABRE 路由 ​

RoutingMethod.LIGHT_SABRE（字符串 "light_sabre"）启用新的分层前瞻路由器。它在路由时按层扩展交互图，能减少双比特门插入与交换深度，适合耦合度受限或线路较深的后端。

除强类型入口外，也可以直接通过位置参数重载启用：

python
from pyqpanda3.core import QProg, H, CZ, measure
from pyqpanda3.transpilation import ChipBackend, Transpiler

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

backend = ChipBackend()
backend.chip_topology_edges = [[0, 1], [1, 2]]
backend.basic_gates = ["RPhi", "CZ"]

transpiled = Transpiler().transpile(
    prog,
    backend,
    {},
    2,
    "fidelity",
    "light_sabre",
    "default",
    approximation_degree=0.99,
)

print(type(transpiled).__name__)
print(len(transpiled.operations()) > 0)

输出：

text
QProg
True

3. 海森堡绘景期望模拟器 ​

SparseHeisenbergSimulator 用稀疏海森堡绘景算法计算泡利哈密顿量的期望值。它不是基于采样的 QVM，也不返回态矢量；适合门集受支持、初态为直积态时快速估算 <H>。当算符项数膨胀时，可用 max_terms 与 truncation_norm 截断。

python
from pyqpanda3.core import QProg, CZ, SparseHeisenbergSimulator

zero = (1 + 0j, 0 + 0j)  # 每个比特的 (|0> 振幅, |1> 振幅)

prog = QProg() << CZ(0, 1)  # |00> 不变

sim = SparseHeisenbergSimulator(num_qubits=2)
sim.set_initial_product_state([zero, zero])
sim.add_observable("ZZ", 1.0)
sim.evolve_backward(prog)

print(round(sim.expectation(), 6))

输出：

text
1.0

自由函数 sparse_heisenberg_expectation(prog, hamiltonian, initial_product_state=...) 等价于上面的流程，一步完成：

python
from pyqpanda3.core import QProg, CZ, sparse_heisenberg_expectation
from pyqpanda3.hamiltonian import Hamiltonian

zero = (1 + 0j, 0 + 0j)
prog = QProg() << CZ(0, 1)
ham = Hamiltonian({"Z0 Z1": 1.0})

print(round(sparse_heisenberg_expectation(prog, ham, initial_product_state=[zero, zero]), 6))

输出：

text
1.0

4. 矩阵乘积态（MPS）模拟器 ​

MPSQVM 用矩阵乘积态后端运行量子程序，对纠缠较弱的线路在比特数较大时仍保持较低内存占用。运行后通过 result() 取测量结果。

python
from pyqpanda3.core import H, MPSQVM, QProg, measure

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

qvm = MPSQVM()
qvm.run(prog, 1000)
result = qvm.result()

print(type(result).__name__)
print(sum(result.get_counts().values()) == 1000)

示例输出形态：

text
QResult
True

5. 初态设置：CPUQVM.init_state ​

0.4.1 在 CPUQVM 上新增 init_state()，可在运行前设置模拟器的初始量子态。模拟器会在每次 run()（以及每次 evolve()）之前重置为该初始态；无参调用则恢复默认的 |0...0> 初态。

python
import numpy as np
from pyqpanda3.core import CPUQVM, QProg, measure

qvm = CPUQVM()
qvm.init_state([1 / np.sqrt(2), 0, 0, 1 / np.sqrt(2)])

prog = QProg() << measure([0, 1], [0, 1])
qvm.run(prog, 1000)
print(qvm.result().get_counts())

qvm.init_state()  # 恢复默认 |0...0>
qvm.run(prog, 1000)
print(qvm.result().get_counts())

运行结果（计数随随机采样略有波动）：

text
{'00': 524, '11': 476}
{'00': 1000}

说明：MPSQVM 的 C++ init_state 未在 Python 绑定中暴露（0.4.1），Python 侧请使用 CPUQVM.init_state。

6. 云端任务取消 ​

QCloudJob 新增取消能力，可主动取消已提交的云端任务：

python
QCloudJob.cancel(self) -> bool
QCloudJob.cancel_task(task_id: str) -> bool

cancel() 取消当前任务；静态方法 cancel_task(task_id) 按任务 id 取消指定任务。两者返回 True 表示云服务接受了取消请求，False 表示服务端响应任务无法取消。

取消任务需要云端凭据与真实任务，无法本地执行：

python
from pyqpanda3.qcloud import QCloudJob, QCloudService

# 需云端凭据与真实任务，无法本地执行
service = QCloudService("your_api_key")
job = QCloudJob("your_job_id")

print(job.cancel())                          # 取消当前任务
print(QCloudJob.cancel_task("your_task_id"))  # 按任务 id 取消（静态方法）

API 变化 ​

Released under the MIT License.

Copyright 2024-present Origin Quantum