qilisdk.digital.circuit_transpiler_passes.sabre_layout_pass

Classes

SabreLayoutPass

A SABRE-style initial layout pass (no SWAP insertion).

Module Contents

class SabreLayoutPass(topology: qilisdk.digital.types.Topology, *, num_trials: int = 8, seed: int | None = None, lookahead_size: int = 10, beta: float = 0.5, decay_delta: float = 0.001, decay_lambda: float = 0.99, apply_layout: bool = True)

Bases: qilisdk.digital.circuit_transpiler_passes.circuit_transpiler_pass.CircuitTranspilerPass

A SABRE-style initial layout pass (no SWAP insertion). It computes a good logical→physical qubit mapping for a given coupling graph and, unless apply_layout is False, returns a new Circuit with all gates retargeted to the chosen physical qubits.

Key features

• Accepts either a topology edge list or a rustworkx PyGraph and normalizes it to an undirected coupling graph internally.

• Implements SABRE’s heuristic:

  • Front layer (first unscheduled 2Q gates on each qubit).

  • Extended look-ahead set of upcoming 2Q gates.

  • Cost = sum distances(front) + beta * sum distances(lookahead), with a light decay penalty on recently swapped physical qubits.

• Runs several randomized trials and keeps the best layout.

Parameters

topologyTopology

Coupling map provided either as an edge list or as an undirected PyGraph whose node indices represent physical qubits.

num_trialsint

Number of random initializations to try (keeps the best).

seedint | None

RNG seed for reproducibility (affects initial layout and tie breaks).

lookahead_sizeint

Max size of the extended set (SABRE «E»).

betafloat

Weight for the extended set in the cost function.

decay_deltafloat

Increment added to the decay penalty for the two physical qubits whenever a swap would be applied during simulation.

decay_lambdafloat

Decay multiplier applied each iteration to gradually forget old penalties.

apply_layoutbool

Whether to return the circuit retargeted onto the chosen physical qubits. When False the pass only records the layout and returns the input circuit untouched, leaving it to a following router such as SabreSwapPass to apply the mapping. Use False when this pass is paired with a router that reads context.initial_layout, otherwise the layout is applied twice.

Results

• Returns a new Circuit with all gates retargeted to physical qubits, unless apply_layout is False.

• Exposes last_layout (list[int]) mapping logical → physical. Also last_score as a diagnostic (lower is better).

Notes

• This pass performs layout only. Routing/SWAP insertion should be done by a separate pass.

• If the coupling graph has more physical qubits than the input circuit, the returned circuit’s nqubits will be enlarged as needed so that physical indices are in range.

Initialize a SABRE layout pass.

param topology:

Coupling map as an edge list or PyGraph.

type topology:

Topology

param num_trials:

Number of randomized layout trials.

type num_trials:

int

param seed:

RNG seed for reproducible trials.

type seed:

int | None

param lookahead_size:

Maximum number of gates in the look-ahead set.

type lookahead_size:

int

param beta:

Weight assigned to look-ahead cost.

type beta:

float

param decay_delta:

Increment applied to decay on selected swap endpoints.

type decay_delta:

float

param decay_lambda:

Per-iteration decay factor for penalties.

type decay_lambda:

float

param apply_layout:

Whether to retarget the circuit onto the chosen physical qubits. Set to False when a following router applies context.initial_layout itself.

type apply_layout:

bool

topology: rustworkx.PyGraph[int, None]

num_trials

seed = None

lookahead_size = 10

beta

decay_delta

decay_lambda

apply_layout = True

last_layout: list[int] | None = None

last_score: float | None = None

run(circuit: qilisdk.digital.Circuit) → qilisdk.digital.Circuit

Compute a layout and return a retargeted copy of the circuit.

Paràmetres:

circuit (Circuit) – Logical circuit to place onto physical qubits.

Retorna:

New circuit retargeted according to the selected layout, or circuit unchanged when apply_layout is False.

Tipus de retorn:

Circuit

Llença:

ValueError – If the topology is empty or has fewer physical qubits than required by circuit.