Transpiler

The Transpiler class maps a logical quantum program onto a target topology by combining layout, routing, gate decomposition, and optimization passes.

Construction

from pyqpanda3.transpilation import Transpiler

transpiler = Transpiler()

Transpile overloads

Edge-list overload

Transpiler.transpile(
    prog: QProg,
    chip_topology_edges: list[list[int]] = [],
    init_mapping: dict[int, int] = {},
    optimization_level: int = 2,
    basic_gates: list[str] = [],
) -> QProg

Use this overload when you want to pass topology edges and the target gate set explicitly.

Parameter	Type	Description
prog	QProg	Quantum program to transpile.
chip_topology_edges	list[list[int]]	Physical couplers, for example [[0, 1], [1, 2]].
init_mapping	dict[int, int]	Optional initial virtual-to-physical mapping.
optimization_level	int	Optimization level, typically 0, 1, or 2.
basic_gates	list[str]	Target gate set after decomposition, for example ["U3", "CZ"].

Backend overload

Transpiler.transpile(
    prog: QProg,
    backend: ChipBackend,
    init_mapping: dict[int, int] = {},
    optimization_level: int = 2,
) -> QProg

Use this overload when the target device is already described by a ChipBackend.

Backend + layout method overload

Transpiler.transpile(
    prog: QProg,
    backend: ChipBackend,
    init_mapping: dict[int, int] = {},
    optimization_level: int = 2,
    layout_method: str = "default",
) -> QProg

Parameter	Type	Description
layout_method	str	Layout strategy. Use "fidelity" to compute the initial mapping from backend topology and fidelity data.

virtual_z

virtual_z(prog: QProg) -> QProg

Converts a program decomposed to the X1 / RZ / CZ / RPhi family into an RPhi / CZ program while preserving measurements. This is the bridge used before instruction export when the backend expects virtual-Z phases to be represented inside RPhi gates.

fidelity_layout

fidelity_layout(
    prog: QProg,
    chip_topology_edges: list[list[int]],
    single_gate_fidelity: dict[int, float] = {},
    readout_fidelity: dict[int, float] = {},
    double_gate_fidelity: dict[tuple[int, int], float] = {},
    max_candidate_blocks: int = 32,
    max_mappings_per_block: int = 256,
    distance_penalty_weight: float = 1.0,
) -> dict[int, int]

Computes a virtual-to-physical initial mapping that prefers connected regions with better single-qubit, readout, and two-qubit fidelity.

Parameter	Type	Description
prog	QProg	Program whose two-qubit interactions drive the layout search.
chip_topology_edges	list[list[int]]	Physical couplers.
single_gate_fidelity	dict[int, float]	Single-qubit fidelity by physical qubit.
readout_fidelity	dict[int, float]	Readout fidelity by physical qubit.
double_gate_fidelity	dict[tuple[int, int], float]	Two-qubit fidelity by physical edge.
max_candidate_blocks	int	Maximum number of connected physical regions to score.
max_mappings_per_block	int	Maximum number of candidate mappings per region.
distance_penalty_weight	float	Penalty weight for non-adjacent interactions.

ChipBackend fidelity fields

When fidelity-aware layout is available, ChipBackend can carry the following calibration maps:

Field	Type	Description
single_gate_fidelity	dict[int, float]	Single-qubit gate fidelity by physical qubit.
readout_fidelity	dict[int, float]	Readout fidelity by physical qubit.
double_gate_fidelity	dict[tuple[int, int], float]	Two-qubit gate fidelity by physical coupler.
gate_fidelity	dict[tuple[str, tuple[int, ...]], float]	Per-instruction fidelity, keyed by (gate_name, ordered_qubit_tuple). transpilation_metrics() and the fidelity-driven approximation match this data first and take the exact branch on a hit. The setter validates the gate name and qubit arity of every key; any entry outside [0, 1] raises ValueError.

These fields can be filled manually or obtained from QCloud metadata through service.backend(...).chip_info().get_chip_backend() (cloud metadata populates gate_fidelity).

Runnable example

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

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}

mapping = fidelity_layout(
    prog,
    backend.chip_topology_edges,
    backend.single_gate_fidelity,
    backend.readout_fidelity,
    backend.double_gate_fidelity,
)

transpiled = Transpiler().transpile(
    prog,
    backend,
    {},
    1,
    "fidelity",
)

print(mapping)
print(len(transpiled.operations()) > 0)

See Also

• Topology utilities
• Gate decomposition
• QCloud service