QCut

QCut#

Init circuit knitting.

QCut.transpile_experiments(cut_experiment: CutExperiment, backend, optimization_level: int = 0, transpile_options: dict | None = None) → CutExperiment[source]#

Transpile experiment circuits. Transpiles all generated experiment circuits for a given backend. Most often one should use transpile_subcircuits instead, as that only transpiles subcircuits before experiment generation which is a lot more efficient. This function is mainly provided for special cases where one needs/wants extra control over the transpilation of experiment circuits.

Parameters:

  • cut_experiment – (CutExperiment): Experiment circuits to be transpiled.

  • backend (str) – Backend to transpile to.

  • optimization_level (int) – Optimization level for transpilation (0-3).

  • transpile_options (dict) – Arguments passed to qiskit transpile function.

Returns:

Transpiled experiment circuits wrapped in CutExperiment class.

Return type:

CutExperiment

QCut.transpile_subcircuits(cut_circuit: CutCircuit, backend, optimization_level: int = 0, transpile_options: dict | None = None) → CutCircuit[source]#

Transpile subcircuits for a given backend. More efficient than transpiling experiment circuits as it only transpiles each subcircuit once instead of each experiment circuit. However, may lead to suboptimal transpilation results as the tranpiler cannot use the backend object directly due to need to retain some placeholder gates for cuts and observables. transpile_options can be used to pass additional options to the transpiler. For more control over transpilation of experiment circuits, use transpile_experiments or manually transpile them.

Parameters:

  • subcircuits (list[QuantumCircuit]) – List of subcircuits to be transpiled.

  • backend – Backend to transpile to.

  • optimization_level (int) – Optimization level for transpilation (0-3).

  • transpile_options (dict) – Arguments passed to qiskit transpile function.

Returns:

Transpiled subcircuits wrapped in CutCircuit class.

Return type:

CutCircuit

QCut.estimate_expectation_values(results: list[list[TotalResult]], expv_data: dict) → list[float][source]#

Calculate the estimated expectation values.

Loop through processed results. For each result group generate all products of different measurements from different subcircuits of the group. For each result from qpd measurements calculate qpd coefficient and from counts calculate weight. Get results for qubits corresponding to the observables. If multiqubit observable multiply individual qubit eigenvalues and multiply by (-1)^(m+1) where m is number of qubits in the observable. Multiply by weight and add to sub expectation value. Once all results iterated over move to next circuit group. Lastly multiply by total cut cost and divide by number of samples.

Parameters:

  • results (list[TotalResult]) – results from experiment circuits

  • coefficients (list[int]) – list of coefficients for each subcircuit group

  • cut_locations (np.ndarray[CutLocation]) – cut locations

  • observables (list[int | list[int]]) – observables to calculate expectation values for

Returns:

expectation values as a list of floats

Return type:

list[float]

QCut.get_experiment_circuits(cut_circuit: CutCircuit, observables: SparsePauliOp) → CutExperiment[source]#

Generate experiment circuits by inserting QPD operations on measure/initialize/cutCZ nodes.

Parameters:

  • subcircuits (list[QuantumCircuit]) – subcircuits with measure/initialize nodes.

  • cut_locations (np.ndarray[CutLocation]) – cut locations.

Returns:

A tuple containing:

  • CutCircuit: A CutCircuit object containing the experiment circuits.

  • list[int]: A list of coefficients for each circuit.

  • list[tuple[int, int, int]]:

    A list of index pointers to results that need additional post-processing due to identity basis measurement.

Return type:

tuple

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

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 necesary to manually specify this parameter.

Returns:

A tuple containing:

  • list[SingleQubitCutLocation]: Locations of the cuts as a list

  • list[QuantumCircuit]: Subcircuits with placeholder operations

  • dict[int:int]: map of subcircuit qubit indices to original circuit

    qubit indices

Return type:

tuple

QCut.run(circuit: QuantumCircuit, observables: SparsePauliOp, backend=AerSimulator('aer_simulator')) → list[float][source]#

Run the whole circuit knitting sequence with one function call.

Parameters:

  • circuit (QuantumCircuit) – circuit with cut experiments

  • observables (list[int | list[int]]) – list of observbles in the form of qubit indices (Z-obsevable).

  • backend – backend to use for running experiment circuits (optional)

Returns:

a list of expectation values

Return type:

list

QCut.run_cut_circuit(cut_circuit: CutCircuit, observables: SparsePauliOp, backend=AerSimulator('aer_simulator')) → list[float][source]#

After splitting the circuit run the rest of the circuit knitting sequence.

Parameters:

  • subcircuits (list[QuantumCircuit]) – subcircuits containing the placeholder operations

  • cut_locations (np.ndarray[CutLocation]) – list of cut locations

  • observables (list[int | list[int]]) – list of observables as qubit indices (Z observable)

  • backend – backend to use for running experiment circuits (optional)

Returns:

a list of expectation values

Return type:

list

QCut.run_experiments(cut_experiment: CutExperiment, shots: int = 4096, backend=None) → list[list[TotalResult]][source]#

Run experiment circuits.

Loop through experiment circuits and then loop through circuit group and run each circuit. Store results as [group0, group1, …] where group is [res0, res1, …]. where res is “xxx yy”: count xxx are the measurements from the end of circuit measurements on the meas classical register and yy are the qpd basis measurement results from the qpd_meas class register.

Parameters:

  • experiment_circuits (CutCircuit) – experiment circuits

  • cut_locations (np.ndarray[CutLocation]) – list of cut locations

  • shots (int) – number of shots per circuit run (optional)

  • backend – backend used for running the circuits (optional)

Returns:

list of transformed results

Return type:

list[TotalResult]

QCut.cut() → QuantumCircuit | Instruction[source]#

Return a single qubit wire cut instruction.

QCut.cutCZ() → QuantumCircuit | Instruction[source]#

Return a two qubit cutCZ gate instruction.

QCut.cutGate(gate: Gate, control: int, target: int) → dict[source]#

Return a cutCZ circuit with the same parameters as the input gate.

QCut.find_cuts(circuit, num_partitions: int | None = None, max_qubits=None, cuts='both', more_data=False)[source]#

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.

  • num_partitions (int, optional) – Number of partitions to create. If None, determined from max_qubits.

  • max_qubits (list[int], optional) – Maximum number of qubits allowed in each partition. If specified, must match num_partitions.

  • cuts (str, optional) – Type of cuts to insert. Can be “both”, “gate”, or “wire”. Defaults to “both”.

  • more_data (bool, optional) – If True, returns additional data for debugging and analysis. Defaults to False.

Returns:

If more_data is False, returns:

  • list[list[int]]: Qubit locations for each subcircuit.

  • list[QuantumCircuit]: List of subcircuits after cuts.

  • list[dict]: Mapping of qubits for each subcircuit.

If more_data is True, returns:

  • list[list[int]]: Qubit locations for each subcircuit.

  • list[QuantumCircuit]: List of subcircuits after cuts.

  • list[dict]: Mapping of qubits for each subcircuit.

  • QuantumCircuit: The circuit with cuts inserted.

  • list: Data describing the cuts.

  • list: Additional cut data for testing.

  • dict: Partition labels for each node.

  • rustworkx.PyGraph: The graph representation of the circuit.

  • dict: Mapping of nodes to qubits.

Return type:

tuple

Contents