转译选项与指标

TranspilationOptions、TranspilationResult 和相关的枚举、transpilation_metrics() 是 0.4.1 引入的强类型转译入口。它们把 0.4.0 的位置参数风格升级为结构化对象，并提供编译耗时和保真度指标回收。

何时使用

• 需要显式选择布局/路由/优化策略，或想启用 LightSABRE 路由。
• 需要根据后端保真度做近似双比特门合成（approximation_degree）。
• 需要拿到编译耗时、双比特门数量、深度和对数期望保真度等指标。

如果只需要按拓扑或 ChipBackend 做一次默认转译，0.4.0 的位置参数重载仍然可用，参见 Transpiler。

枚举

LayoutMethod

成员	说明
DEFAULT	默认布局策略。
FIDELITY	保真度感知布局，使用 single_gate_fidelity / readout_fidelity / double_gate_fidelity 计算初始映射（等价于 0.4.0 的 layout_method="fidelity"）。

RoutingMethod

成员	说明
AUTO	由转译器自动选择（默认）。
DEFAULT	默认路由策略。
BASIC	基础贪心路由。
LOOKAHEAD	前瞻路由。
DECAY	带衰减的 Sabre 路由。
LIGHT_SABRE	分层前瞻路由（0.4.1 新增），通常能减少双比特门插入与交换深度。

OptimizationMethod

成员	说明
DEFAULT	默认优化策略。

TranspilationOptions

from pyqpanda3.transpilation import TranspilationOptions

options = TranspilationOptions()

TranspilationOptions() 无参构造，所有字段都可在构造后读写。

属性	类型	默认值	说明
optimization_level	int	2	优化等级（0、1、2）。level 0 强制精确合成；level >= 1 时由 approximation_degree 决定 ORACLE KAK 是精确还是近似合成。level 1 只跑一次 unitary_synthesis，level 2 在此基础上迭代 unitary_synthesis 到不动点。
layout_method	LayoutMethod	DEFAULT	布局策略。设为 FIDELITY 时根据后端保真度映射计算初始布局。
routing_method	RoutingMethod	AUTO	路由策略。设为 LIGHT_SABRE 启用分层前瞻路由。
optimization_method	OptimizationMethod	DEFAULT	优化策略。
init_mapping	dict[int, int]	{}	初始虚拟到物理映射；空字典表示自动分配。
execution	TranspilationExecutionConfig	见下	并行与确定性执行控制。
approximation_degree	float 或 None	1.0	保真度驱动近似强度。1.0 表示精确合成；None 表示使用目标双比特门错误率；[0, 1] 内的有限值用于缩放近似强度。非有限值或越界值会抛出 ValueError。

TranspilationExecutionConfig

from pyqpanda3.transpilation import TranspilationExecutionConfig

config = TranspilationExecutionConfig()

属性	类型	默认值	说明
max_threads	int	4	并行转译使用的最大线程数；0 表示按硬件并发度自动决定。
routing_trials	int	0	路由尝试次数，0 表示自动。值越大越可能找到更优路由，但耗时增加。
seed	int 或 None	None	随机种子，设置后可复现转译结果。
compile_time_budget_ms	int	0	编译墙钟时间预算（毫秒），0 表示不限制。

TranspilationResult

Transpiler().transpile(prog, backend, options) 的强类型重载返回 TranspilationResult。

属性	类型	说明
program	QProg	转译后的量子程序。
compile_time_ns	int	本次转译的编译耗时（纳秒）。
metrics	dict	转译后程序的指标，结构同 transpilation_metrics()。

transpilation_metrics

transpilation_metrics(prog: QProg, backend: ChipBackend) -> dict

针对一个已经转译的程序和后端评估指标，返回的字典包含：

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

任何 gate_fidelity 条目超出 [0, 1] 时抛出 ValueError。

transpile 高级重载

强类型入口之外，Transpiler.transpile() 还提供以下高级位置参数重载（完整签名见 Transpiler）：

# 拓扑边 + 执行配置
Transpiler.transpile(
    prog, chip_topology_edges, init_mapping={}, optimization_level=2,
    basic_gates=[], execution_config,
) -> QProg

# 拓扑边 + 路由/优化方法（approximation_degree 为关键字参数）
Transpiler.transpile(
    prog, chip_topology_edges, init_mapping={}, optimization_level=2,
    basic_gates=[], routing_method, optimization_method,
    execution_config=TranspilationExecutionConfig(), *, approximation_degree=1.0,
) -> QProg

# ChipBackend + 布局/路由/优化方法
Transpiler.transpile(
    prog, backend, init_mapping={}, optimization_level=2,
    layout_method, routing_method, optimization_method,
    execution_config=TranspilationExecutionConfig(), *, approximation_degree=1.0,
) -> QProg

# 强类型入口
Transpiler.transpile(prog, backend, options) -> TranspilationResult

在这些 transpile() 重载中，routing_method 与 optimization_method 仅接受字符串（小写形式，如 "light_sabre"、"default"），传枚举成员会抛出 TypeError；如需以枚举方式配置，请使用强类型入口 TranspilationOptions。上面第 4 个重载中 execution_config 是必填位置参数（无默认值）；第 5、6 个重载中 execution_config 有默认值、可按位置或关键字传入，而 approximation_degree 是仅限关键字参数。

0.5.0 引擎说明：布局与路由栈已围绕共享的 LightSABRE 引擎重建（带均衡布局-路由目标函数的双向 SABRE 布局搜索、面向可嵌入子图的 VF2 补全、环形邻域候选与工作量熔断器）。Python 入口保持不变。固定 execution.seed 后转译是确定性的：对同一程序重复调用 transpile() 产生完全相同的输出。execution.max_threads、execution.routing_trials 与 execution.compile_time_budget_ms 分别约束线程池、布局搜索试验数与墙钟预算。

可运行示例

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

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()))

# 同样的指标可以用独立函数对任意已转译程序重新计算
m = transpilation_metrics(result.program, backend)
print(m == result.metrics)

示例输出形态：

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

相关页面

• Transpiler
• 拓扑工具
• 门分解
• 0.4.1 发布说明