uniqc.compile.compiler module

Enhanced transpiler with chip-characterization-aware routing.

This module provides the canonical compile() entry point for chip-aware circuit transpilation in UnifiedQuantum. It wraps the existing Qiskit-based transpiler and adds fidelity-weighted routing, multiple output formats, and a typed configuration object.

class uniqc.compile.compiler.CompilationResult(output, fidelity_estimate, routing_overhead, transpiler_messages=<factory>)[source]

Bases: object

Result of a compile() call.

Variables:

  • output (Circuit | str) – Compiled circuit. Type depends on output_format passed to compile().

  • fidelity_estimate (float | None) – Estimated success probability of the compiled circuit on the target chip, computed from per-gate fidelities in the chip characterization. None if no chip_characterization was provided.

  • routing_overhead (int) – Number of SWAP gates inserted by the router. Zero if the circuit already fits the topology.

  • transpiler_messages (list[str]) – Informational messages from the transpiler.

Parameters:
fidelity_estimate: float | None
output: Circuit | str
routing_overhead: int
transpiler_messages: list[str]
class uniqc.compile.compiler.TranspilerConfig(type='qiskit', level=2, basis_gates=('cz', 'sx', 'rz'), chip_characterization=None)[source]

Bases: object

Configuration for the compile() function.

Parameters:

  • type (str) – Transpiler backend. Currently only "qiskit" is supported. The string is kept for future extensibility.

  • level (int) – Qiskit optimization level (0–3). Default: 2. 0 = no optimization, 1 = light, 2 = heavy, 3 = heaviest.

  • basis_gates (tuple[str, ...]) – Target basis gate set. Default: ("cz", "sx", "rz").

  • chip_characterization (ChipCharacterization | None) – Per-qubit and per-pair calibration data. When provided, the router prefers higher-fidelity qubits and edges during SWAP insertion and qubit routing. If None, routing uses only the connectivity graph.

basis_gates: tuple[str, ...] = ('cz', 'sx', 'rz')
chip_characterization: ChipCharacterization | None = None
level: int = 2
type: str = 'qiskit'
uniqc.compile.compiler.compile(circuit, backend_info=None, *, type='qiskit', level=2, basis_gates=None, chip_characterization=None, output_format='circuit', available_qubits=None)[source]

Compile a circuit for a specific backend using chip characterization data.

This is the canonical entry point for chip-aware transpilation in UnifiedQuantum. It supersedes transpile_originir by adding chip-characterization-aware routing, a typed configuration object, and a Circuit return type.

Important

compile (at every optimization level, including level=0) requires Qiskit, which is a core dependency installed by default with unified-quantum. If import qiskit fails, the install is broken — reinstall with pip install --upgrade unified-quantum. Without qiskit available every call raises CompilationFailedError. There is currently no pure-Python fallback path.

Parameters:

  • circuit (Any) – The input circuit. Accepts a uniqc.Circuit, an OriginIR string, an OpenQASM 2.0 string, or a qiskit.QuantumCircuit.

  • backend_info (BackendInfo | None) – Target backend descriptor. Supplies the topology coupling map. If omitted, the topology is taken from chip_characterization.

  • type (str) – Transpiler backend. Currently only "qiskit" is supported.

  • level (int) – Qiskit optimization level (0–3). Default: 2.

  • basis_gates (list[str] | None) – Target basis gate set. Default: ["cz", "sx", "rz"].

  • chip_characterization (ChipCharacterization | None) – Per-qubit and per-pair calibration data. When provided, the router prefers high-fidelity qubits and edges during SWAP insertion. If None, routing uses only the connectivity graph.

  • output_format (OutputFormat) – Return format. "circuit" (default) returns a new Circuit object; "originir" returns an OriginIR string; "qasm" returns a QASM2 string; "auto" matches the detected input format.

  • available_qubits (list[int] | tuple[int, ...] | None)

Returns:

The compiled circuit in the requested format.

Return type:

Circuit | str

Raises:

  • CompilationFailedError – If transpilation fails.

  • ValueError – If the transpiler type is unsupported, the optimization level is out of range, or no topology information is available.

  • TypeError – If the input type is not recognized.

Example

>>> from uniqc.circuit_builder import Circuit
>>> from uniqc.compile import compile
>>> circuit = Circuit()
>>> circuit.h(0); circuit.cnot(0, 1)
>>> compiled = compile(circuit, level=2)
>>> print(type(compiled).__name__)
Circuit
uniqc.compile.compiler.compile_full(circuit, backend_info=None, *, type='qiskit', level=2, basis_gates=None, chip_characterization=None, output_format='circuit', available_qubits=None)[source]

Full compile returning a CompilationResult with metadata.

Equivalent to compile() but also returns routing overhead, fidelity estimate, and informational messages.

Parameters:

  • circuit (Any) – The input circuit. Accepts a uniqc.Circuit, an OriginIR string, an OpenQASM 2.0 string, or a qiskit.QuantumCircuit.

  • backend_info (BackendInfo | None) – Target backend descriptor.

  • type (str)

  • level (int)

  • basis_gates (list[str] | None)

  • chip_characterization (ChipCharacterization | None)

  • output_format (OutputFormat)

  • available_qubits (list[int] | tuple[int, ...] | None)

Return type:

CompilationResult

:param : :param available_qubits: Same as compile().

Returns:

The compiled output plus metadata.

Return type:

CompilationResult

Parameters:

  • circuit (Any)

  • backend_info (BackendInfo | None)

  • type (str)

  • level (int)

  • basis_gates (list[str] | None)

  • chip_characterization (ChipCharacterization | None)

  • output_format (OutputFormat)

  • available_qubits (list[int] | tuple[int, ...] | None)

uniqc.compile.compiler.compile_with_config(circuit, backend_info, config, output_format, *, available_qubits=None)[source]

Internal compile implementation that accepts a TranspilerConfig.

Parameters:
Return type:

Circuit | str