BIPMapping

class qiskit.transpiler.passes.BIPMapping(*args, **kwargs)

Bases: TransformationPass

Map a DAGCircuit onto a given coupling_map, allocating qubits and adding swap gates.

The BIP mapper tries to find the best layout and routing at once by solving a BIP (binary integer programming) problem as described in [1].

The BIP problem represents the layer-by-layer mapping of 2-qubit gates, assuming all the gates in a layer can be run on the coupling_map. In the problem, the variables $w$ represent the layout of qubits for each layer and the variables $x$ represent which pair of qubits should be swapped in between layers. Based on the values in the solution of the BIP problem, the mapped circuit will be constructed.

The BIP mapper depends on docplex to represent the BIP problem and CPLEX (cplex) to solve it. Those packages can be installed with pip install qiskit-terra[bip-mapper]. Since the free version of CPLEX can solve only small BIP problems, i.e. mapping of circuits with less than about 5 qubits, the paid version of CPLEX may be needed to map larger circuits.

If you want to fix physical qubits to be used in the mapping (e.g. running Quantum Volume circuits), you need to supply qubit_subset, i.e. list of physical qubits to be used within the coupling_map. Please do not use initial_layout for that purpose because the BIP mapper gracefully ignores initial_layout (and tries to determines its best layout).

References:

[1] G. Nannicini et al. “Optimal qubit assignment and routing via integer programming.” arXiv:2106.06446

BIPMapping initializer.

Parameters

• coupling_map (Union[CouplingMap, Target]) – Directed graph represented a coupling map.

• qubit_subset (list[int]) – Sublist of physical qubits to be used in the mapping. If None, all qubits in the coupling_map will be considered.

• objective (str) –

  Type of objective function to be minimized:

  • 'gate_error': Approximate gate error of the circuit, which is given as the sum of

    negative logarithm of 2q-gate fidelities in the circuit. It takes into account only the 2q-gate (CNOT) errors reported in backend_prop and ignores the other errors in such as 1q-gates, SPAMs and idle times.

  • 'depth': Depth (number of 2q-gate layers) of the circuit.

  • 'balanced': [Default] Weighted sum of 'gate_error' and 'depth'

• backend_prop (BackendProperties) – Backend properties object containing 2q-gate gate errors, which are required in computing certain types of objective function such as 'gate_error' or 'balanced'. If this is not available, default_cx_error_rate is used instead.

• time_limit (float) – Time limit for solving BIP in seconds

• threads (int) – Number of threads to be allowed for CPLEX to solve BIP

• max_swaps_inbetween_layers (int) – Number of swaps allowed in between layers. If None, automatically set. Large value could decrease the probability to build infeasible BIP problem but also could reduce the chance of finding a feasible solution within the time_limit.

• depth_obj_weight (float) – Weight of depth objective in 'balanced' objective. The balanced objective is the sum of error_rate + depth_obj_weight * depth.

• default_cx_error_rate (float) – Default CX error rate to be used if backend_prop is not available.

Raises

• MissingOptionalLibraryError – if cplex or docplex are not installed.
• TranspilerError – if invalid options are specified.

Attributes

is_analysis_pass

is_transformation_pass

Methods

name

run