qilisdk.digital.circuit_transpiler_passes.custom_layout_pass

Classes

CustomLayoutPass

Apply a user-specified initial layout (logical→physical mapping) and retarget

Module Contents

class CustomLayoutPass(topology: qilisdk.digital.types.Topology, layout: qilisdk.digital.types.LayoutMap)[source]

Bases: qilisdk.digital.circuit_transpiler_passes.circuit_transpiler_pass.CircuitTranspilerPass

Apply a user-specified initial layout (logical→physical mapping) and retarget all gates accordingly. The returned circuit is resized to the device size (i.e., the number of qubits of the coupling graph).

Parameters

topologyTopology

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

mappingLayoutMap

Logical→physical mapping provided by the user. For example, for a 2-qubit circuit: {0: 5, 1: 2} means logical q0→phys 5, logical q1→phys 2.

Behavior

  • Validates that mapping covers every logical qubit in the input circuit, is injective (no repeated physical indices), and only references physical qubits that exist in topology.

  • Stores the user-requested layout in context.initial_layout (same field set by SabreLayoutPass).

  • Inserts SWAPs (with corresponding un-swaps) along shortest paths of the coupling graph when a user-requested 2Q interaction would otherwise violate connectivity, keeping logical qubits on their requested physical nodes for subsequent operations.

  • Returns a new Circuit whose nqubits equals the chip size (len of topology’s qubits) and whose gates are retargeted to the mapped physical qubits.

  • Exposes last_layout (list[int]) for diagnostics, mirroring SabreLayout.

Notes

  • SWAPs are emitted eagerly using shortest paths whenever a 2Q gate is not locally executable on the chosen mapping, and are undone immediately so the mapping remains stable for subsequent operations.

  • last_layout matches the user-provided mapping; the same list is stored in context.initial_layout for diagnostics.

Initialize the pass with a fixed logical-to-physical layout.

param topology:

Coupling map as an edge list or PyGraph.

type topology:

Topology

param layout:

User-specified layout logical -> physical.

type layout:

LayoutMap

topology: rustworkx.PyGraph[int, None][source]
run(circuit: qilisdk.digital.Circuit) → qilisdk.digital.Circuit[source]

Retarget a circuit using the user layout, inserting temporary SWAPs when needed.

Parameters:

circuit (Circuit) – Logical circuit to retarget.

Returns:

New circuit in physical qubit indices sized to the topology.

Return type:

Circuit

Raises:

  • ValueError – If the topology is empty, mapping coverage is invalid, mapping is not injective, mapping targets unknown physical qubits, or a two-qubit interaction is unroutable.

  • NotImplementedError – If a gate with arity greater than two is encountered.

  • RuntimeError – If routing swaps fail to make a two-qubit gate adjacent.