uniqc.backend_adapter.region_selector module

RegionSelector: find optimal qubit regions on a quantum chip.

This module provides the RegionSelector class, which uses chip characterization data (per-qubit and per-pair calibration data) to find optimal physical qubit regions for executing quantum circuits.

Example

from uniqc.backend_adapter.task.adapters.originq_adapter import OriginQAdapter
from uniqc.backend_adapter.region_selector import RegionSelector

adapter = OriginQAdapter()
chip = adapter.get_chip_characterization("origin:wuyuan:d5")
selector = RegionSelector(chip)

# Find the best 5-qubit chain
chain_result = selector.find_best_1D_chain(5)
if chain_result.chain:
    print(f"Best chain: {chain_result.chain}")

# Find the best region for a circuit
region_result = selector.find_best_2D_from_circuit(circuit, min_qubits=4)
if region_result.qubits:
    print(f"Best region: {region_result.qubits}")
class uniqc.backend_adapter.region_selector.ChainSearchResult(chain, estimated_fidelity, num_swaps)[source]

Bases: object

Result of RegionSelector.find_best_1D_chain().

Variables:

  • chain (list[int] | None) – List of physical qubit indices forming the chain, or None if no valid chain of the requested length exists.

  • estimated_fidelity (float | None) – Estimated success probability of executing a single-layer circuit on this chain (product of edge fidelities), or None if no chain found.

  • num_swaps (int) – Number of SWAP gates that would be needed to realise this chain from the circuit’s natural qubit mapping (0 for an exact path match).

Parameters:

  • chain (list[int] | None)

  • estimated_fidelity (float | None)

  • num_swaps (int)

chain: list[int] | None
estimated_fidelity: float | None
num_swaps: int
class uniqc.backend_adapter.region_selector.RegionSearchResult(qubits, estimated_fidelity, region_shape)[source]

Bases: object

Result of RegionSelector.find_best_2D_from_circuit().

Variables:

  • qubits (set[int] | None) – Set of physical qubit indices forming the best region, or None if no region fits the circuit’s qubit requirements.

  • estimated_fidelity (float | None) – Estimated success probability of executing the full circuit on this region, or None if no region found.

  • region_shape (tuple[int, int] | None) – Approximate dimensions of the selected region as (rows, cols), or None.

Parameters:
estimated_fidelity: float | None
qubits: set[int] | None
region_shape: tuple[int, int] | None
class uniqc.backend_adapter.region_selector.RegionSelector(chip_characterization)[source]

Bases: object

Select optimal qubit regions from chip characterisation data.

Parameters:

chip_characterization (ChipCharacterization) – Complete chip characterisation data including connectivity and fidelity information, typically fetched via OriginQAdapter.get_chip_characterization() or the equivalent for other adapters.

estimate_circuit_fidelity(circuit, qubits=None)[source]

Estimate the success probability of executing a circuit on a qubit set.

Uses the product-of-fidelities formula:

P_success = product_{1Q gates} F_1q
          × product_{2Q gates} F_2q
          × product_{measured qubits} F_readout

Where gate error rates are derived from the chip characterisation:

  • Single-qubit gate fidelity: from SingleQubitData.single_gate_fidelity

  • Two-qubit gate fidelity: best fidelity among all gate types for that edge

  • Readout fidelity: from SingleQubitData.avg_readout_fidelity

If a qubit or edge is not in the characterisation data, a default fidelity of 0.99 (1% error rate) is used.

Parameters:

  • circuit (Circuit) – The circuit to estimate fidelity for.

  • qubits (set[int] | None) – The set of physical qubits to execute on. If None, uses all available qubits from the chip characterisation.

Returns:

Estimated success probability between 0.0 and 1.0.

Return type:

float

find_best_1D_chain(length, start=None, max_search_seconds=10.0)[source]

Find the highest-fidelity linear chain of connected qubits.

Algorithm:

  1. DFS phase. From each candidate starting qubit, run a DFS to find the lexicographically-first path of the requested length, pruning branches that cannot beat the current best.

  2. Backtracking phase. If no candidate produced an exact-length chain via DFS, run a deeper backtracking search.

  3. Pure-greedy fallback. If the time budget runs out (or DFS still did not find an exact-length chain), pick a chain by repeatedly extending into the highest-fidelity neighbour. This is O(length · degree) and always returns within the budget.

The fidelity of a chain q0-q1-…-q_{n-1} is:

F = product_{i=1}^{n-1} fidelity(q_{i-1}, q_i)
Parameters:

  • length (int) – Desired number of qubits in the chain. Must be >= 1.

  • start (int | None) – Physical qubit index to start the chain from. If None, the qubit with the highest single-gate fidelity is used.

  • max_search_seconds (float) – Total wall-clock budget for the DFS + backtracking phases. When the budget is exhausted, the search returns the best chain found via the pure-greedy fallback (never blocks beyond the budget). Default: 10 seconds.

Returns:

The best chain found, its estimated fidelity, and the number of SWAP gates needed (0 for an exact path match).

Return type:

ChainSearchResult

Raises:

ValueError – If length < 1.

find_best_2D_from_circuit(circuit, min_qubits=None, max_region_size=36, max_search_seconds=10.0, transpiler=None)[source]

Find the best 2D qubit region for executing a circuit.

Algorithm:

  1. Determine the circuit’s qubit requirements: min_qubits = max(circuit.max_qubit + 1, circuit.qubit_num).

  2. Enumerate candidate regions. The chip’s connectivity graph is searched for connected subgraphs of rectangular topology. Enumeration proceeds in order of increasing size until a feasible region is found, bounded by max_region_size.

    Heuristic: try rectangles of size 1×n, 2×n, 3×n, … up to the circuit’s qubit count. For each size, try all possible starting positions and orientations.

  3. For each candidate region, estimate circuit fidelity using estimate_circuit_fidelity(). If a custom transpiler is provided, call it instead for a more accurate estimate.

  4. Return the region with the highest estimated fidelity.

Parameters:

  • circuit (Circuit) – The circuit to find a region for.

  • min_qubits (int | None) – Override the minimum qubit count. If None, derived from the circuit’s max_qubit and qubit_num.

  • max_region_size (int) – Maximum number of qubits to search. Larger values increase search time but may find better regions. Default: 36.

  • max_search_seconds (float) – Time budget for the search. If exceeded, return the best result found so far. Default: 10 seconds.

  • transpiler (Callable[[Circuit, list[int]], float] | None) – Optional callable with signature (circuit, qubits: list[int]) -> float. If provided, used instead of the built-in fidelity estimator, enabling more accurate (but slower) estimates via the full Qiskit transpiler.

Returns:

The best region found, its estimated fidelity, and its shape.

Return type:

RegionSearchResult

classmethod from_backend(backend)[source]

Construct a RegionSelector from a backend identifier string.

This is a convenience wrapper that fetches the chip characterization for the named backend and feeds it to the constructor — equivalent to:

chip = OriginQAdapter().get_chip_characterization("WK_C180")
selector = RegionSelector(chip)
Parameters:

backend (str) – Backend identifier in the canonical "<platform>:<chip>" form, e.g. "originq:WK_C180" or "originq:wk_c180" (case-insensitive on the chip name). Bare "<chip>" is interpreted as "originq:<chip>" for convenience.

Returns:

Selector pre-populated with the chip’s connectivity and fidelity data.

Return type:

RegionSelector

Raises:

ValueError – If the backend string is malformed or the platform is unknown.

get_edge_rankings()[source]

Return all available edges ranked by two-qubit gate fidelity.

Return type:

list of ((qubit_u, qubit_v), fidelity) sorted by fidelity descending.

get_qubit_rankings()[source]

Return all available qubits ranked by single-gate fidelity.

Return type:

list of (qubit_id, fidelity) sorted by fidelity descending.