Return more info about circuit separation during partitioning

circuit_knitting/cutting/__init__.py

@@ -34,6 +34,7 @@
     :template: autosummary/class_no_inherited_members.rst
 
     PartitionedCuttingProblem
+    CutInfo
     CuttingExperimentResults
 
 Quasi-Probability Decomposition (QPD)
@@ -80,6 +81,7 @@
     cut_gates,
     decompose_gates,
     PartitionedCuttingProblem,
+    CutInfo,
 )
 from .cutting_evaluation import execute_experiments, CuttingExperimentResults
 from .cutting_reconstruction import reconstruct_expectation_values
@@ -92,5 +94,6 @@
     "execute_experiments",
     "reconstruct_expectation_values",
     "PartitionedCuttingProblem",
+    "CutInfo",
     "CuttingExperimentResults",
 ]

circuit_knitting/cutting/cutting_decomposition.py

@@ -28,15 +28,34 @@
 from ..utils.observable_grouping import observables_restricted_to_subsystem
 from ..utils.transforms import separate_circuit
 from .qpd.qpd_basis import QPDBasis
-from .qpd.instructions import TwoQubitQPDGate
+from .qpd.instructions import BaseQPDGate, SingleQubitQPDGate, TwoQubitQPDGate
 
 
 class PartitionedCuttingProblem(NamedTuple):
     """The result of decomposing and separating a circuit and observable(s)."""
 
-    subcircuits: dict[str | int, QuantumCircuit]
-    bases: list[QPDBasis]
-    subobservables: dict[str | int, QuantumCircuit] | None = None
+    subcircuits: dict[Hashable, QuantumCircuit]
+    cuts: list[CutInfo]
+    subobservables: dict[Hashable, QuantumCircuit] | None = None
+
+
+class CutInfo(NamedTuple):
+    """
+    The decomposition and circuit index information associated with one cut.
+
+    If the cut is associated with more than one subcircuit, the ``gates`` field should
+    be represented as a list of length-2 tuples containing the partition labels and
+    subcircuit instruction indices to the associated gates.
+
+    If the cut is associated with more than one :class:`~circuit_knitting.cutting.qpd.SingleQubitQPDGate` in an unseparated
+    circuit, the ``gates`` may be specified as a list of circuit indices to those gates.
+
+    If the cut is associated with a single :class:`~circuit_knitting.cutting.qpd.BaseQPDGate` instance in an unseparated circuit, the ``gates``
+    may be specified by a single index to the gate.
+    """
+
+    basis: QPDBasis
+    gates: list[tuple[Hashable, int]] | list[int] | int
 
 
 def partition_circuit_qubits(
@@ -195,6 +214,7 @@ def partition_problem(
         ValueError: An input observable acts on a different number of qubits than the input circuit.
         ValueError: An input observable has a phase not equal to 1.
         ValueError: The input circuit should contain no classical bits or registers.
+        ValueError: The input circuit should contain no :class:`~circuit_knitting.cutting.qpd.SingleQubitQPDGate` instances.
     """
     if len(partition_labels) != circuit.num_qubits:
         raise ValueError(
@@ -221,14 +241,28 @@ def partition_problem(
     bases = []
     i = 0
     for inst in qpd_circuit.data:
+        if isinstance(inst.operation, SingleQubitQPDGate):
+            raise ValueError(
+                "Input circuit may not contain SingleQubitQPDGate instances."
+            )
         if isinstance(inst.operation, TwoQubitQPDGate):
             bases.append(inst.operation.basis)
             inst.operation.label = inst.operation.label + f"_{i}"
             i += 1
 
     # Separate the decomposed circuit into its subcircuits
     qpd_circuit_dx = qpd_circuit.decompose(TwoQubitQPDGate)
-    separated_circs = separate_circuit(qpd_circuit_dx, partition_labels)
+    subcircuits = separate_circuit(qpd_circuit_dx, partition_labels).subcircuits
+
+    # Gather the basis and location information for the cuts
+    cuts_dict = defaultdict(list)
+    for label in subcircuits.keys():
+        circuit = subcircuits[label]
+        for i, inst in enumerate(circuit.data):
+            if isinstance(inst.operation, BaseQPDGate):
+                cut_num = int(inst.operation.label.split("_")[-1])
+                cuts_dict[cut_num].append((label, i))
+    cuts = [CutInfo(basis, cuts_dict[cut_num]) for cut_num, basis in enumerate(bases)]
 
     # Decompose the observables, if provided
     subobservables_by_subsystem = None
@@ -238,15 +272,15 @@ def partition_problem(
         )
 
     return PartitionedCuttingProblem(
-        separated_circs.subcircuits,  # type: ignore
-        bases,
+        subcircuits,
+        cuts,
         subobservables=subobservables_by_subsystem,
     )
 
 
 def decompose_observables(
-    observables: PauliList, partition_labels: Sequence[str | int]
-) -> dict[str | int, PauliList]:
+    observables: PauliList, partition_labels: Sequence[Hashable]
+) -> dict[Hashable, PauliList]:
     """
     Decompose a list of observables with respect to some qubit partition labels.
 

circuit_knitting/cutting/cutting_reconstruction.py

@@ -72,7 +72,7 @@ def reconstruct_expectation_values(
         for label, subobservable in observables.items():
             if any(obs.phase != 0 for obs in subobservable):
                 raise ValueError("An input observable has a phase not equal to 1.")
-        subobservables_by_subsystem = observables
+        subobservables_by_subsystem = observables  # type: ignore
         expvals = np.zeros(len(list(observables.values())[0]))
 
     subsystem_observables = {

releasenotes/notes/cut-info-49e59b465b64d48f.yaml

@@ -0,0 +1,6 @@
+---
+upgrade:
+  - |
+    Introduction of `~circuit_knitting.cutting.CutInfo` class, which contains the decomposition and gate index information for a single cut.
+
+    Removed the ``bases`` field from the :class:`~circuit_knitting.cutting.PartitionedCuttingProblem` class in favor of a ``cuts`` field. Users may now extract the :class:`~circuit_knitting.cutting.qpd.QPDBasis` instances from the ``basis`` field of each `~circuit_knitting.cutting.CutInfo` instance in ``cuts``.

test/cutting/test_backwards_compatibility.py

@@ -51,9 +51,10 @@ def test_v0_2_cutting_width_workflow():
     circuit = EfficientSU2(4, entanglement="linear", reps=2).decompose()
     circuit.assign_parameters([0.8] * len(circuit.parameters), inplace=True)
     observables = PauliList(["ZZII", "IZZI", "IIZZ", "XIXI", "ZIZZ", "IXIX"])
-    subcircuits, bases, subobservables = partition_problem(
+    subcircuits, cuts, subobservables = partition_problem(
         circuit=circuit, partition_labels="AABB", observables=observables
     )
+    bases = [cut_info.basis for cut_info in cuts]
     assert np.prod([basis.overhead for basis in bases]) == pytest.approx(81)
 
     samplers = {

test/cutting/test_cutting_decomposition.py

@@ -28,6 +28,7 @@
 )
 from circuit_knitting.cutting.qpd import (
     QPDBasis,
+    SingleQubitQPDGate,
     TwoQubitQPDGate,
     BaseQPDGate,
 )
@@ -170,7 +171,22 @@ def test_partition_problem(self):
             compare_obs = {"A": PauliList(["XX"]), "B": PauliList(["ZZ"])}
 
             self.assertEqual(subobservables, compare_obs)
-
+        with self.subTest("test single qubit qpd gate input"):
+            # Split 4q HWEA in middle of qubits
+            partition_labels = "AABB"
+            circuit = self.circuit.copy()
+            circuit.data.append(
+                CircuitInstruction(
+                    SingleQubitQPDGate(QPDBasis.from_gate(CXGate()), qubit_id=0),
+                    qubits=[0],
+                )
+            )
+            with pytest.raises(ValueError) as e_info:
+                partition_problem(circuit, partition_labels)
+            assert (
+                e_info.value.args[0]
+                == "Input circuit may not contain SingleQubitQPDGate instances."
+            )
         with self.subTest("test mismatching inputs"):
             # Split 4q HWEA in middle of qubits
             partition_labels = "AB"