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)

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 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.

Results

• Returns a new Circuit with all gates retargeted to physical qubits.

• 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

topology: rustworkx.PyGraph[int, None]

num_trials

seed = None

lookahead_size = 10

beta

decay_delta

decay_lambda

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.

Tipus de retorn:

Circuit

Llença:

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