Provide options in the cut-finder API to turn LO gate and wire cut finding off or on, expose min-reached flag.

circuit_knitting/cutting/automated_cut_finding.py

@@ -63,6 +63,8 @@ def find_cuts(
         seed=optimization.seed,
         max_gamma=optimization.max_gamma,
         max_backjumps=optimization.max_backjumps,
+        gate_lo=optimization.gate_lo,
+        wire_lo=optimization.wire_lo,
     )
 
     # Hard-code the optimizer to an LO-only optimizer
@@ -106,7 +108,7 @@ def find_cuts(
         )
         counter += 1
 
-        if action.action.get_name() == "CutBothWires":  # pragma: no cover
+        if action.action.get_name() == "CutBothWires":
             # There should be two wires specified in the action in this case
             assert len(action.args) == 2
             qubit_id2 = action.args[1][0] - 1
@@ -137,6 +139,8 @@ class OptimizationParameters:
     seed: int | None = OptimizationSettings().seed
     max_gamma: float = OptimizationSettings().max_gamma
     max_backjumps: None | int = OptimizationSettings().max_backjumps
+    gate_lo: bool = OptimizationSettings().gate_lo
+    wire_lo: bool = OptimizationSettings().wire_lo
 
 
 @dataclass

circuit_knitting/cutting/cut_finding/cut_optimization.py

@@ -60,11 +60,16 @@ def cut_optimization_cost_func(
 
 
 def cut_optimization_upper_bound_cost_func(
-    goal_state, func_args: CutOptimizationFuncArgs
+    goal_state: DisjointSubcircuitsState, func_args: CutOptimizationFuncArgs
 ) -> tuple[float, float]:
     """Return the value of :math:`gamma` computed assuming all LO cuts."""
     # pylint: disable=unused-argument
-    return (goal_state.upper_bound_gamma(), np.inf)
+    if goal_state is not None:
+        return (goal_state.upper_bound_gamma(), np.inf)
+    else:
+        raise ValueError(
+            "None state encountered: no cut state satisfying the specified constraints and settings could be found."
+        )
 
 
 def cut_optimization_min_cost_bound_func(
@@ -125,7 +130,7 @@ def cut_optimization_goal_state_func(
 # Global variable that holds the search-space functions for generating
 # the cut optimization search space.
 cut_optimization_search_funcs = SearchFunctions(
-    cost_func=cut_optimization_cost_func,
+    cost_func=cut_optimization_upper_bound_cost_func,  # valid choice when considering only LO cuts.
     upperbound_cost_func=cut_optimization_upper_bound_cost_func,
     next_state_func=cut_optimization_next_state_func,
     goal_state_func=cut_optimization_goal_state_func,

circuit_knitting/cutting/cut_finding/disjoint_subcircuits_state.py

@@ -40,16 +40,20 @@ class Action(NamedTuple):
     args: list | tuple
 
 
-class GateCutLocation(NamedTuple):
-    """Named tuple for specification of gate cut location."""
+class CutLocation(NamedTuple):
+    """Named tuple for specifying cut locations.
+
+    This is used to specify instances of both :class:`CutTwoQubitGate` and :class:`CutBothWires`.
+    Both of these instances are fully specified by a gate reference.
+    """
 
     instruction_id: int
     gate_name: str
     qubits: Sequence
 
 
 class WireCutLocation(NamedTuple):
-    """Named tuple for specification of wire cut location.
+    """Named tuple for specification of (single) wire cut locations.
 
     Wire cuts are identified through the gates whose input wires are cut.
     """
@@ -64,10 +68,10 @@ class CutIdentifier(NamedTuple):
     """Named tuple for specification of location of :class:`CutTwoQubitGate` or :class:`CutBothWires` instances."""
 
     cut_action: DisjointSearchAction
-    gate_cut_location: GateCutLocation
+    cut_location: CutLocation
 
 
-class OneWireCutIdentifier(NamedTuple):
+class SingleWireCutIdentifier(NamedTuple):
     """Named tuple for specification of location of :class:`CutLeftWire` or :class:`CutRightWire` instances."""
 
     cut_action: DisjointSearchAction
@@ -130,15 +134,13 @@ def __init__(self, num_qubits: int | None = None, max_wire_cuts: int | None = No
         if not (
             num_qubits is None or (isinstance(num_qubits, int) and num_qubits >= 0)
         ):
-            raise ValueError("num_qubits must be either be None or a positive integer.")
+            raise ValueError("num_qubits must either be None or a positive integer.")
 
         if not (
             max_wire_cuts is None
             or (isinstance(max_wire_cuts, int) and max_wire_cuts >= 0)
         ):
-            raise ValueError(
-                "max_wire_cuts must be either be None or a positive integer."
-            )
+            raise ValueError("max_wire_cuts must either be None or a positive integer.")
 
         if num_qubits is None or max_wire_cuts is None:
             self.wiremap: NDArray[np.int_] | None = None
@@ -213,7 +215,7 @@ def cut_actions_sublist(self) -> list[NamedTuple]:
         for i in range(len(cut_actions)):
             if cut_actions[i].action.get_name() in ("CutLeftWire", "CutRightWire"):
                 self.cut_actions_list.append(
-                    OneWireCutIdentifier(
+                    SingleWireCutIdentifier(
                         cut_actions[i].action.get_name(),
                         WireCutLocation(
                             cut_actions[i].gate_spec.instruction_id,
@@ -231,7 +233,7 @@ def cut_actions_sublist(self) -> list[NamedTuple]:
                 self.cut_actions_list.append(
                     CutIdentifier(
                         cut_actions[i].action.get_name(),
-                        GateCutLocation(
+                        CutLocation(
                             cut_actions[i].gate_spec.instruction_id,
                             cut_actions[i].gate_spec.gate.name,
                             cut_actions[i].gate_spec.gate.qubits,

circuit_knitting/cutting/cut_finding/optimization_settings.py

@@ -38,16 +38,18 @@ class OptimizationSettings:
     If None is used as the random seed, then a seed is obtained using an
     operating-system call to achieve an unrepeatable randomized initialization.
 
-    NOTE: The current release only supports LO gate and wire cuts. LOCC
+    NOTE: The current release only supports LO gate and wire cuts. locc
     flags have been incorporated with an eye towards future releases.
     """
 
     max_gamma: float = 1024
     max_backjumps: None | int = 10000
     seed: int | None = None
-    LO: bool = True
-    LOCC_ancillas: bool = False
-    LOCC_no_ancillas: bool = False
+    gate_lo: bool = True
+    wire_lo: bool = True
+    gate_locc_ancillas: bool = False
+    wire_locc_ancillas: bool = False
+    wire_locc_no_ancillas: bool = False
     engine_selections: dict[str, str] | None = None
 
     def __post_init__(self):
@@ -57,12 +59,12 @@ def __post_init__(self):
         if self.max_backjumps is not None and self.max_backjumps < 0:
             raise ValueError("max_backjumps must be a positive semi-definite integer.")
 
-        self.gate_cut_LO = self.LO
-        self.gate_cut_LOCC_with_ancillas = self.LOCC_ancillas
+        self.gate_cut_lo = self.gate_lo
+        self.gate_cut_locc_with_ancillas = self.gate_locc_ancillas
 
-        self.wire_cut_LO = self.LO
-        self.wire_cut_LOCC_with_ancillas = self.LOCC_ancillas
-        self.wire_cut_LOCC_no_ancillas = self.LOCC_no_ancillas
+        self.wire_cut_lo = self.wire_lo
+        self.wire_cut_locc_with_ancillas = self.wire_locc_ancillas
+        self.wire_cut_locc_no_ancillas = self.wire_locc_no_ancillas
         if self.engine_selections is None:
             self.engine_selections = {"CutOptimization": "BestFirst"}
 
@@ -102,31 +104,31 @@ def set_gate_cut_types(self) -> None:
         The default is to only include LO gate cuts, which are the
         only cut types supported in this release.
         """
-        self.gate_cut_LO = self.LO
-        self.gate_cut_LOCC_with_ancillas = self.LOCC_ancillas
+        self.gate_cut_lo = self.gate_lo
+        self.gate_cut_locc_with_ancillas = self.gate_locc_ancillas
 
     def set_wire_cut_types(self) -> None:
         """Select which wire-cut types to include in the optimization.
 
         The default is to only include LO wire cuts, which are the
         only cut types supported in this release.
         """
-        self.wire_cut_LO = self.LO
-        self.wire_cut_LOCC_with_ancillas = self.LOCC_ancillas
-        self.wire_cut_LOCC_no_ancillas = self.LOCC_no_ancillas
+        self.wire_cut_lo = self.wire_lo
+        self.wire_cut_locc_with_ancillas = self.wire_locc_ancillas
+        self.wire_cut_locc_no_ancillas = self.wire_locc_no_ancillas
 
     def get_cut_search_groups(self) -> list[None | str]:
         """Return a list of action groups to include in the optimization."""
         out: list
         out = [None]
 
-        if self.gate_cut_LO or self.gate_cut_LOCC_with_ancillas:
+        if self.gate_cut_lo or self.gate_cut_locc_with_ancillas:
             out.append("GateCut")
 
         if (
-            self.wire_cut_LO
-            or self.wire_cut_LOCC_with_ancillas
-            or self.wire_cut_LOCC_no_ancillas
+            self.wire_cut_lo
+            or self.wire_cut_locc_with_ancillas
+            or self.wire_cut_locc_no_ancillas
         ):
             out.append("WireCut")
 

docs/circuit_cutting/tutorials/01_gate_cutting_to_reduce_circuit_width.ipynb

@@ -413,7 +413,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.0"
+   "version": "3.9.6"
   }
  },
  "nbformat": 4,

releasenotes/notes/new-flags-to-control-cut-finder-search-e499e1ea49abb0bc.yaml

@@ -0,0 +1,6 @@
+---
+features:
+  - |
+    When specifying instances of :class:`~OptimizationParameters` that are inputted to :meth:`circuit_knitting.cutting.find_cuts()`, the user can now control whether the 
+    cut-finder looks only for gate cuts, only for wire cuts, or both, by setting the bools ``gate_lo`` and ``wire_lo`` appropriately. The default value
+    of both of these is set to `True` and so the default search considers the possibility of both gate and wire cuts.

test/cutting/cut_finding/test_best_first_search.py

@@ -93,10 +93,11 @@ def test_best_first_search(test_circuit: SimpleGateList):
 
     out, _ = op.optimization_pass()
 
+    print(get_actions_list(out.actions))
     assert op.search_engine.get_stats(penultimate=True) is not None
     assert op.search_engine.get_stats() is not None
     assert op.get_upperbound_cost() == (27, inf)
-    assert op.minimum_reached() is False
+    assert op.minimum_reached() is True
     assert out is not None
     assert (out.lower_bound_gamma(), out.gamma_UB, out.get_max_width()) == (
         27,