Cutting

Marking cuts

QCut.cut() → QuantumCircuit | Instruction

Return a single qubit wire cut instruction.

QCut.cutGate(gate: Gate, control: int | list[int], target: int | list[int], single_qubit_basis: list[str] | None = None) → dict

Return a CutGate circuit decomposing the input gate with QPD cut markers.

control and target together define the ordered physical qubit mapping for gate inputs 0..n-1: gate input i maps to physical qubit (controls + targets)[i].

A two-qubit gate becomes a single CutTwoQubitGate marker, so its QPD is generated from its matrix at expansion time. Larger gates are still transpiled into the {u, cz, swap, iswap} basis first, which turns them into several cuts.

Parameters:

• gate (Gate) – the gate to cut.

• control (int | list[int]) – qubit, or qubits, the gate’s first inputs map to.

• target (int | list[int]) – qubit, or qubits, its remaining inputs map to.

• single_qubit_basis (list[str]) – basis the single-qubit parts are translated into, if the default is not wanted (optional).

Returns:

keyword arguments for QuantumCircuit.append, so the call site reads circuit.append(**cutGate(...)).

Return type:

dict

QCut.cutCZ() → QuantumCircuit | Instruction

Return a two qubit cutCZ gate instruction.

QCut.cutSWAP() → QuantumCircuit | Instruction

Return a two qubit cutSWAP gate instruction.

QCut.cutISWAP() → QuantumCircuit | Instruction

Return a two qubit cutISWAP gate instruction.

Splitting

QCut.get_locations_and_subcircuits(circuit: QuantumCircuit, max_qubits: list[int] | None = None, options: CutOptions | None = None) → CutCircuit

Get cut locations and subcircuits with placeholder operations.

Parameters:

• circuit (QuantumCircuit) – circuit with cuts inserted

• max_qubits (list[int], optional) – list of maximum qubits per subcircuit when using automatic cut finding. If None, no constraint is used. Defaults to None. In general it is not necessary to manually specify this parameter.

• options (CutOptions, optional) – configuration for the run. Defaults to QCut.options.DEFAULT_OPTIONS.

Returns:

the subcircuits, the cut locations, and the map of subcircuit qubit indices to original circuit qubit indices.

Return type:

CutCircuit

Finding cuts

QCut.find_cuts(circuit, options: CutOptions | None = None)

Partition a quantum circuit into subcircuits by inserting cut operations.

Converts the input circuit into a graph representation and partitions it into the specified number of subcircuits using METIS partitioning. Optionally refines the partitioning to respect maximum qubit constraints per subcircuit. Cut operations are inserted at the partition boundaries, and the resulting subcircuits and their mappings are returned.

Parameters:

• circuit (QuantumCircuit) – The input quantum circuit to partition.

• options (CutOptions, optional) – configuration for the run. Defaults to QCut.options.DEFAULT_OPTIONS.

Returns:

A circuit with cut operations inserted, ready for decomposition into subcircuits.

Return type:

CutCircuit

QCut.consolidate_two_qubit_blocks(circuit: QuantumCircuit, restrict_to: set[frozenset] | None = None) → QuantumCircuit

Merge runs of gates acting on the same qubit pair into single unitaries.

Parameters:

• circuit – circuit to rewrite. Two-qubit cut markers are unwrapped, merged and marked again. Wire cut markers end a run and are left in place.

• restrict_to – if given, only these qubit pairs are considered. Pass the marked pairs to leave gates alone that were never going to be cut.

Returns:

An equivalent circuit. Returns the input unchanged if nothing was worth merging.