From f0fbfda64ef7ad6c76b26e5ac7b5eca845857721 Mon Sep 17 00:00:00 2001
From: Craig Gidney <craiggidney@google.com>
Date: Sat, 25 Nov 2023 16:01:22 -0800
Subject: [PATCH] Add additional tests of has_flow

---
 doc/python_api_reference_vDev.md         | 20 ++++--
 doc/stim.pyi                             | 20 ++++--
 glue/python/src/stim/__init__.pyi        | 20 ++++--
 src/stim/circuit/circuit.pybind.cc       | 20 ++++--
 src/stim/circuit/circuit_pybind_test.py  | 90 ++++++++++++++++++++++++
 src/stim/circuit/stabilizer_flow.inl     | 21 +++---
 src/stim/circuit/stabilizer_flow.test.cc | 14 ++++
 7 files changed, 177 insertions(+), 28 deletions(-)

diff --git a/doc/python_api_reference_vDev.md b/doc/python_api_reference_vDev.md
index a27e89e30..e263f9d15 100644
--- a/doc/python_api_reference_vDev.md
+++ b/doc/python_api_reference_vDev.md
@@ -1892,7 +1892,7 @@ def has_flow(
     *,
     start: Optional[stim.PauliString] = None,
     end: Optional[stim.PauliString] = None,
-    measurements: Iterable[Union[int, stim.GateTarget]] = (),
+    measurements: Optional[Iterable[Union[int, stim.GateTarget]]] = None,
     unsigned: bool = False,
 ) -> bool:
     """Determines if the circuit has a stabilizer flow or not.
@@ -1908,10 +1908,6 @@ def has_flow(
     A flow like P -> IDENTITY means that the circuit measures P.
     A flow like IDENTITY -> IDENTITY means that the circuit contains a detector.
 
-    Stim's gate documentation includes the stabilizer flows of each gate.
-    See Appendix A of https://arxiv.org/abs/2302.02192 for more information on how
-    flows are defined.
-
     Args:
         start: The input into the flow at the start of the circuit. Defaults to None
             (the identity Pauli string).
@@ -1930,6 +1926,13 @@ def has_flow(
     Returns:
         True if the circuit has the given flow; False otherwise.
 
+    References:
+        Stim's gate documentation includes the stabilizer flows of each gate.
+
+        Appendix A of https://arxiv.org/abs/2302.02192 describes how flows are
+        defined and provides a circuit construction for experimentally verifying
+        their presence.
+
     Examples:
         >>> import stim
 
@@ -1976,6 +1979,13 @@ def has_flow(
         ...     unsigned=True,
         ... )
         True
+
+    Caveats:
+        Currently, the unsigned=False version of this method is implemented by
+        performing 256 randomized tests. Each test has a 50% chance of a false
+        positive, and a 0% chance of a false negative. So, when the method returns
+        True, there is technically still a 2^-256 chance the circuit doesn't have
+        the flow. This is lower than the chance of a cosmic ray flipping the result.
     """
 ```
 
diff --git a/doc/stim.pyi b/doc/stim.pyi
index d7afb4204..291954718 100644
--- a/doc/stim.pyi
+++ b/doc/stim.pyi
@@ -1316,7 +1316,7 @@ class Circuit:
         *,
         start: Optional[stim.PauliString] = None,
         end: Optional[stim.PauliString] = None,
-        measurements: Iterable[Union[int, stim.GateTarget]] = (),
+        measurements: Optional[Iterable[Union[int, stim.GateTarget]]] = None,
         unsigned: bool = False,
     ) -> bool:
         """Determines if the circuit has a stabilizer flow or not.
@@ -1332,10 +1332,6 @@ class Circuit:
         A flow like P -> IDENTITY means that the circuit measures P.
         A flow like IDENTITY -> IDENTITY means that the circuit contains a detector.
 
-        Stim's gate documentation includes the stabilizer flows of each gate.
-        See Appendix A of https://arxiv.org/abs/2302.02192 for more information on how
-        flows are defined.
-
         Args:
             start: The input into the flow at the start of the circuit. Defaults to None
                 (the identity Pauli string).
@@ -1354,6 +1350,13 @@ class Circuit:
         Returns:
             True if the circuit has the given flow; False otherwise.
 
+        References:
+            Stim's gate documentation includes the stabilizer flows of each gate.
+
+            Appendix A of https://arxiv.org/abs/2302.02192 describes how flows are
+            defined and provides a circuit construction for experimentally verifying
+            their presence.
+
         Examples:
             >>> import stim
 
@@ -1400,6 +1403,13 @@ class Circuit:
             ...     unsigned=True,
             ... )
             True
+
+        Caveats:
+            Currently, the unsigned=False version of this method is implemented by
+            performing 256 randomized tests. Each test has a 50% chance of a false
+            positive, and a 0% chance of a false negative. So, when the method returns
+            True, there is technically still a 2^-256 chance the circuit doesn't have
+            the flow. This is lower than the chance of a cosmic ray flipping the result.
         """
     def inverse(
         self,
diff --git a/glue/python/src/stim/__init__.pyi b/glue/python/src/stim/__init__.pyi
index d7afb4204..291954718 100644
--- a/glue/python/src/stim/__init__.pyi
+++ b/glue/python/src/stim/__init__.pyi
@@ -1316,7 +1316,7 @@ class Circuit:
         *,
         start: Optional[stim.PauliString] = None,
         end: Optional[stim.PauliString] = None,
-        measurements: Iterable[Union[int, stim.GateTarget]] = (),
+        measurements: Optional[Iterable[Union[int, stim.GateTarget]]] = None,
         unsigned: bool = False,
     ) -> bool:
         """Determines if the circuit has a stabilizer flow or not.
@@ -1332,10 +1332,6 @@ class Circuit:
         A flow like P -> IDENTITY means that the circuit measures P.
         A flow like IDENTITY -> IDENTITY means that the circuit contains a detector.
 
-        Stim's gate documentation includes the stabilizer flows of each gate.
-        See Appendix A of https://arxiv.org/abs/2302.02192 for more information on how
-        flows are defined.
-
         Args:
             start: The input into the flow at the start of the circuit. Defaults to None
                 (the identity Pauli string).
@@ -1354,6 +1350,13 @@ class Circuit:
         Returns:
             True if the circuit has the given flow; False otherwise.
 
+        References:
+            Stim's gate documentation includes the stabilizer flows of each gate.
+
+            Appendix A of https://arxiv.org/abs/2302.02192 describes how flows are
+            defined and provides a circuit construction for experimentally verifying
+            their presence.
+
         Examples:
             >>> import stim
 
@@ -1400,6 +1403,13 @@ class Circuit:
             ...     unsigned=True,
             ... )
             True
+
+        Caveats:
+            Currently, the unsigned=False version of this method is implemented by
+            performing 256 randomized tests. Each test has a 50% chance of a false
+            positive, and a 0% chance of a false negative. So, when the method returns
+            True, there is technically still a 2^-256 chance the circuit doesn't have
+            the flow. This is lower than the chance of a cosmic ray flipping the result.
         """
     def inverse(
         self,
diff --git a/src/stim/circuit/circuit.pybind.cc b/src/stim/circuit/circuit.pybind.cc
index 3c2ec87c4..4382ed526 100644
--- a/src/stim/circuit/circuit.pybind.cc
+++ b/src/stim/circuit/circuit.pybind.cc
@@ -2276,7 +2276,7 @@ void stim_pybind::pybind_circuit_methods(pybind11::module &, pybind11::class_<Ci
         pybind11::arg("measurements") = pybind11::none(),
         pybind11::arg("unsigned") = false,
         clean_doc_string(R"DOC(
-            @signature def has_flow(self, *, start: Optional[stim.PauliString] = None, end: Optional[stim.PauliString] = None, measurements: Iterable[Union[int, stim.GateTarget]] = (), unsigned: bool = False) -> bool:
+            @signature def has_flow(self, *, start: Optional[stim.PauliString] = None, end: Optional[stim.PauliString] = None, measurements: Optional[Iterable[Union[int, stim.GateTarget]]] = None, unsigned: bool = False) -> bool:
             Determines if the circuit has a stabilizer flow or not.
 
             A circuit has a stabilizer flow P -> Q if it maps the instantaneous stabilizer
@@ -2290,10 +2290,6 @@ void stim_pybind::pybind_circuit_methods(pybind11::module &, pybind11::class_<Ci
             A flow like P -> IDENTITY means that the circuit measures P.
             A flow like IDENTITY -> IDENTITY means that the circuit contains a detector.
 
-            Stim's gate documentation includes the stabilizer flows of each gate.
-            See Appendix A of https://arxiv.org/abs/2302.02192 for more information on how
-            flows are defined.
-
             Args:
                 start: The input into the flow at the start of the circuit. Defaults to None
                     (the identity Pauli string).
@@ -2312,6 +2308,13 @@ void stim_pybind::pybind_circuit_methods(pybind11::module &, pybind11::class_<Ci
             Returns:
                 True if the circuit has the given flow; False otherwise.
 
+            References:
+                Stim's gate documentation includes the stabilizer flows of each gate.
+
+                Appendix A of https://arxiv.org/abs/2302.02192 describes how flows are
+                defined and provides a circuit construction for experimentally verifying
+                their presence.
+
             Examples:
                 >>> import stim
 
@@ -2358,6 +2361,13 @@ void stim_pybind::pybind_circuit_methods(pybind11::module &, pybind11::class_<Ci
                 ...     unsigned=True,
                 ... )
                 True
+
+            Caveats:
+                Currently, the unsigned=False version of this method is implemented by
+                performing 256 randomized tests. Each test has a 50% chance of a false
+                positive, and a 0% chance of a false negative. So, when the method returns
+                True, there is technically still a 2^-256 chance the circuit doesn't have
+                the flow. This is lower than the chance of a cosmic ray flipping the result.
         )DOC")
             .data());
 
diff --git a/src/stim/circuit/circuit_pybind_test.py b/src/stim/circuit/circuit_pybind_test.py
index 70772b4cc..a4cc62ed1 100644
--- a/src/stim/circuit/circuit_pybind_test.py
+++ b/src/stim/circuit/circuit_pybind_test.py
@@ -1573,3 +1573,93 @@ def test_detslice_filter_coords_flexibility():
     assert str(d1) == str(d3)
     assert str(d1) == str(d4)
     assert str(d1) == str(d5)
+
+
+def test_has_flow_ry():
+    c = stim.Circuit("""
+        RY 0
+    """)
+    assert c.has_flow(end=stim.PauliString("Y"))
+    assert not c.has_flow(end=stim.PauliString("-Y"))
+    assert not c.has_flow(end=stim.PauliString("X"))
+    assert c.has_flow(end=stim.PauliString("Y"), unsigned=True)
+    assert not c.has_flow(end=stim.PauliString("X"), unsigned=True)
+    assert c.has_flow(end=stim.PauliString("-Y"), unsigned=True)
+
+
+def test_has_flow_cxs():
+    c = stim.Circuit("""
+        CX 0 1
+        S 0
+    """)
+
+    assert c.has_flow(start=stim.PauliString("X_"), end=stim.PauliString("YX"))
+    assert c.has_flow(start=stim.PauliString("Y_"), end=stim.PauliString("-XX"))
+    assert not c.has_flow(start=stim.PauliString("X_"), end=stim.PauliString("XX"))
+    assert not c.has_flow(start=stim.PauliString("X_"), end=stim.PauliString("-XX"))
+
+    assert c.has_flow(start=stim.PauliString("X_"), end=stim.PauliString("YX"), unsigned=True)
+    assert c.has_flow(start=stim.PauliString("Y_"), end=stim.PauliString("-XX"), unsigned=True)
+    assert not c.has_flow(start=stim.PauliString("X_"), end=stim.PauliString("XX"), unsigned=True)
+    assert not c.has_flow(start=stim.PauliString("X_"), end=stim.PauliString("-XX"), unsigned=True)
+
+
+def test_has_flow_cxm():
+    c = stim.Circuit("""
+        CX 0 1
+        M 1
+    """)
+    assert c.has_flow(end=stim.PauliString("_Z"), measurements=[0])
+    assert c.has_flow(start=stim.PauliString("ZZ"), measurements=[0])
+    assert c.has_flow(start=stim.PauliString("ZZ"), end=stim.PauliString("_Z"))
+    assert c.has_flow(start=stim.PauliString("XX"), end=stim.PauliString("X_"))
+    assert c.has_flow(end=stim.PauliString("_Z"), measurements=[0], unsigned=True)
+    assert c.has_flow(start=stim.PauliString("ZZ"), measurements=[0], unsigned=True)
+    assert c.has_flow(start=stim.PauliString("ZZ"), end=stim.PauliString("_Z"), unsigned=True)
+    assert c.has_flow(start=stim.PauliString("XX"), end=stim.PauliString("X_"), unsigned=True)
+
+
+def test_has_flow_lattice_surgery():
+    c = stim.Circuit("""
+        # Lattice surgery CNOT with feedback.
+        RX 2
+        MZZ 2 0
+        MXX 2 1
+        MZ 2
+        CX rec[-1] 1 rec[-3] 1
+        CZ rec[-2] 0
+
+        S 0
+    """)
+    assert c.has_flow(start=stim.PauliString("X_"), end=stim.PauliString("YX"))
+    assert c.has_flow(start=stim.PauliString("Z_"), end=stim.PauliString("Z_"))
+    assert c.has_flow(start=stim.PauliString("_X"), end=stim.PauliString("_X"))
+    assert c.has_flow(start=stim.PauliString("_Z"), end=stim.PauliString("ZZ"))
+    assert not c.has_flow(start=stim.PauliString("X_"), end=stim.PauliString("XX"))
+
+    assert not c.has_flow(start=stim.PauliString("X_"), end=stim.PauliString("XX"))
+    assert not c.has_flow(start=stim.PauliString("X_"), end=stim.PauliString("-YX"))
+    assert not c.has_flow(start=stim.PauliString("X_"), end=stim.PauliString("XX"), unsigned=True)
+    assert c.has_flow(start=stim.PauliString("X_"), end=stim.PauliString("-YX"), unsigned=True)
+
+
+def test_has_flow_lattice_surgery_without_feedback():
+    c = stim.Circuit("""
+        # Lattice surgery CNOT without feedback.
+        RX 2
+        MZZ 2 0
+        MXX 2 1
+        MZ 2
+
+        S 0
+    """)
+    assert c.has_flow(start=stim.PauliString("X_"), end=stim.PauliString("YX"), measurements=[1])
+    assert c.has_flow(start=stim.PauliString("Z_"), end=stim.PauliString("Z_"))
+    assert c.has_flow(start=stim.PauliString("_X"), end=stim.PauliString("_X"))
+    assert c.has_flow(start=stim.PauliString("_Z"), end=stim.PauliString("ZZ"), measurements=[0, 2])
+    assert not c.has_flow(start=stim.PauliString("X_"), end=stim.PauliString("XX"))
+
+    assert not c.has_flow(start=stim.PauliString("X_"), end=stim.PauliString("XX"))
+    assert not c.has_flow(start=stim.PauliString("X_"), end=stim.PauliString("-YX"))
+    assert not c.has_flow(start=stim.PauliString("X_"), end=stim.PauliString("XX"), unsigned=True)
+    assert c.has_flow(start=stim.PauliString("X_"), end=stim.PauliString("-YX"), unsigned=True, measurements=[1])
diff --git a/src/stim/circuit/stabilizer_flow.inl b/src/stim/circuit/stabilizer_flow.inl
index 65c824d9b..8e7c627c3 100644
--- a/src/stim/circuit/stabilizer_flow.inl
+++ b/src/stim/circuit/stabilizer_flow.inl
@@ -170,16 +170,21 @@ std::ostream &operator<<(std::ostream &out, const StabilizerFlow<W> &flow) {
 template <size_t W>
 std::vector<bool> check_if_circuit_has_unsigned_stabilizer_flows(const Circuit &circuit, SpanRef<const StabilizerFlow<W>> flows) {
     auto stats = circuit.compute_stats();
-    SparseUnsignedRevFrameTracker rev(stats.num_qubits, stats.num_measurements, flows.size(), false);
+    size_t num_qubits = stats.num_qubits;
+    for (const auto &flow : flows) {
+        num_qubits = std::max(num_qubits, flow.input.num_qubits);
+        num_qubits = std::max(num_qubits, flow.output.num_qubits);
+    }
+    SparseUnsignedRevFrameTracker rev(num_qubits, stats.num_measurements, flows.size(), false);
 
     // Add end of flows into frames.
     for (size_t f = 0; f < flows.size(); f++) {
         const auto &flow = flows[f];
-        for (size_t q = 0; q < flow.input.num_qubits; q++) {
-            if (flow.input.xs[q]) {
+        for (size_t q = 0; q < flow.output.num_qubits; q++) {
+            if (flow.output.xs[q]) {
                 rev.xs[q].xor_item(DemTarget::relative_detector_id(f));
             }
-            if (flow.input.zs[q]) {
+            if (flow.output.zs[q]) {
                 rev.zs[q].xor_item(DemTarget::relative_detector_id(f));
             }
         }
@@ -205,11 +210,11 @@ std::vector<bool> check_if_circuit_has_unsigned_stabilizer_flows(const Circuit &
     // Remove start of flows from frames.
     for (size_t f = 0; f < flows.size(); f++) {
         const auto &flow = flows[f];
-        for (size_t q = 0; q < flow.output.num_qubits; q++) {
-            if (flow.output.xs[q]) {
+        for (size_t q = 0; q < flow.input.num_qubits; q++) {
+            if (flow.input.xs[q]) {
                 rev.xs[q].xor_item(DemTarget::relative_detector_id(f));
             }
-            if (flow.output.zs[q]) {
+            if (flow.input.zs[q]) {
                 rev.zs[q].xor_item(DemTarget::relative_detector_id(f));
             }
         }
@@ -222,7 +227,7 @@ std::vector<bool> check_if_circuit_has_unsigned_stabilizer_flows(const Circuit &
             result[t.val()] = false;
         }
     }
-    for (const auto &zs : rev.xs) {
+    for (const auto &zs : rev.zs) {
         for (const auto &t : zs) {
             result[t.val()] = false;
         }
diff --git a/src/stim/circuit/stabilizer_flow.test.cc b/src/stim/circuit/stabilizer_flow.test.cc
index 2e0c15290..887249abb 100644
--- a/src/stim/circuit/stabilizer_flow.test.cc
+++ b/src/stim/circuit/stabilizer_flow.test.cc
@@ -93,4 +93,18 @@ TEST_EACH_WORD_SIZE_W(stabilizer_flow, check_if_circuit_has_unsigned_stabilizer_
             StabilizerFlow<W>::from_str("-___Z -> +___Z"),
         });
     ASSERT_EQ(results, (std::vector<bool>{1, 1, 1, 1, 1, 1, 1, 0, 1, 1, 1, 1}));
+});
+
+TEST_EACH_WORD_SIZE_W(stabilizer_flow, check_if_circuit_has_unsigned_stabilizer_flows_historical_failure, {
+    auto results = check_if_circuit_has_unsigned_stabilizer_flows<W>(
+        Circuit(R"CIRCUIT(
+            CX 0 1
+            S 0
+        )CIRCUIT"),
+        std::vector<StabilizerFlow<W>>{
+            StabilizerFlow<W>::from_str("X_ -> YX"),
+            StabilizerFlow<W>::from_str("Y_ -> XX"),
+            StabilizerFlow<W>::from_str("X_ -> XX"),
+        });
+    ASSERT_EQ(results, (std::vector<bool>{1, 1, 0}));
 })