Transpilation Options & Metrics

TranspilationOptions, TranspilationResult, the related enums, and transpilation_metrics() are the strongly-typed transpilation entry points introduced in 0.4.1. They upgrade the 0.4.0 positional-argument style into structured objects and recover compile timing and fidelity metrics.

When to use

• When you need to explicitly choose layout / routing / optimization strategies, or want to enable LightSABRE routing.
• When you want fidelity-driven approximate two-qubit gate synthesis (approximation_degree).
• When you want compile time, two-qubit gate count, depth, and log-expected-fidelity metrics back.

If you only need a single default transpilation against a topology or ChipBackend, the 0.4.0 positional-argument overloads still work — see Transpiler.

Enums

LayoutMethod

Member	Description
DEFAULT	The default layout strategy.
FIDELITY	Fidelity-aware layout that uses single_gate_fidelity / readout_fidelity / double_gate_fidelity to compute the initial mapping (equivalent to 0.4.0's layout_method="fidelity").

RoutingMethod

Member	Description
AUTO	Let the transpiler choose (default).
DEFAULT	The default routing strategy.
BASIC	Basic greedy routing.
LOOKAHEAD	Lookahead routing.
DECAY	Sabre routing with decay.
LIGHT_SABRE	Layered-lookahead routing (new in 0.4.1); usually reduces two-qubit gate insertion and swap depth.

OptimizationMethod

Member	Description
DEFAULT	The default optimization strategy.

TranspilationOptions

from pyqpanda3.transpilation import TranspilationOptions

options = TranspilationOptions()

TranspilationOptions() takes no arguments; every field is readable and writable after construction.

Attribute	Type	Default	Description
optimization_level	int	2	Optimization level (0, 1, 2). level 0 forces exact synthesis; at level >= 1, approximation_degree decides whether ORACLE KAK synthesis is exact or approximate. level 1 runs unitary_synthesis once, while level 2 iterates unitary_synthesis to a fixed point.
layout_method	LayoutMethod	DEFAULT	Layout strategy. Set to FIDELITY to compute the initial mapping from the backend fidelity maps.
routing_method	RoutingMethod	AUTO	Routing strategy. Set to LIGHT_SABRE to enable layered-lookahead routing.
optimization_method	OptimizationMethod	DEFAULT	Optimization strategy.
init_mapping	dict[int, int]	{}	Initial virtual-to-physical mapping; an empty dict means auto-assign.
execution	TranspilationExecutionConfig	see below	Parallelism and determinism controls.
approximation_degree	float or None	1.0	Fidelity-driven approximation strength. 1.0 means exact synthesis; None means use the target two-qubit gate error rate; a finite value in [0, 1] scales the approximation. Non-finite or out-of-range values raise ValueError.

TranspilationExecutionConfig

from pyqpanda3.transpilation import TranspilationExecutionConfig

config = TranspilationExecutionConfig()

Attribute	Type	Default	Description
max_threads	int	4	Maximum number of threads for parallel transpilation; 0 means decide from hardware concurrency.
routing_trials	int	0	Number of routing trials; 0 means automatic. Larger values are more likely to find a better route but take longer.
seed	int or None	None	Random seed; setting it makes transpilation reproducible.
compile_time_budget_ms	int	0	Compile wall-clock budget in milliseconds; 0 means unlimited.

TranspilationResult

The strongly-typed overload Transpiler().transpile(prog, backend, options) returns a TranspilationResult.

Attribute	Type	Description
program	QProg	The transpiled quantum program.
compile_time_ns	int	The compile time of this transpilation, in nanoseconds.
metrics	dict	Metrics of the transpiled program, same shape as transpilation_metrics().

transpilation_metrics

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

Evaluates metrics for an already-transpiled program against a backend. The returned dict contains:

Field	Type	Description
two_qubit_gate_count	int	Number of two-qubit gates in the transpiled program.
depth	int	Gate depth of the transpiled program.
log_expected_fidelity	float or None	Logarithm of the expected fidelity, accumulated as log(1 - error) over every gate plus one readout per measured qubit; None when any gate or readout fidelity is unknown.
fidelity_exact	int	Number of gates whose fidelity data was matched exactly.
fidelity_fallback	int	Number of gates that fell back to an aggregate estimate.
fidelity_unknown	int	Number of gates with no fidelity data at all.

Raises ValueError if any gate_fidelity entry is outside [0, 1].

Advanced transpile overloads

Besides the strongly-typed entry, Transpiler.transpile() provides the following advanced positional-argument overloads (full signatures in Transpiler):

# Topology edges + execution config
Transpiler.transpile(
    prog, chip_topology_edges, init_mapping={}, optimization_level=2,
    basic_gates=[], execution_config,
) -> QProg

# Topology edges + routing/optimization methods (approximation_degree is keyword-only)
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 + layout/routing/optimization methods
Transpiler.transpile(
    prog, backend, init_mapping={}, optimization_level=2,
    layout_method, routing_method, optimization_method,
    execution_config=TranspilationExecutionConfig(), *, approximation_degree=1.0,
) -> QProg

# Strongly-typed entry
Transpiler.transpile(prog, backend, options) -> TranspilationResult

In these transpile() overloads, routing_method and optimization_method accept only strings (lowercase, e.g. "light_sabre", "default"); passing enum members raises a TypeError. To configure them via enums, use the strongly-typed TranspilationOptions entry instead. In overload 4 above, execution_config is a required positional parameter (no default); in overloads 5 and 6, execution_config has a default and may be passed positionally or by keyword, while approximation_degree is keyword-only.

0.5.0 engine notes: the layout and routing stack was rebuilt around a shared LightSABRE engine (bidirectional SABRE layout search with a balanced layout-routing objective, VF2 completion for embeddable subgraphs, ring-neighborhood candidates, and a work-budget circuit breaker). The Python entry points are unchanged. Transpilation is deterministic when execution.seed is fixed: repeated transpile() calls on the same program produce identical output. execution.max_threads, execution.routing_trials, and execution.compile_time_budget_ms bound the thread pool, layout-search trials, and wall-clock budget respectively.

Runnable example

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

# The same metrics can be recomputed for any transpiled program with the standalone function
m = transpilation_metrics(result.program, backend)
print(m == result.metrics)

Example output shape:

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

Related pages

• Transpiler
• Topology
• Decompose
• 0.4.1 release notes