Add some circuit and flip sim utility methods (#991)

- Add `stim.Circuit.missing_detectors`
- Add `unknown_input=False` argument to
`stim.Circuit.count_determined_measurements`
- Add `stim.FlipSimulator.append_measurement_flips`

Fixes #973

Fixes #981

Fixes #987

Author: Strilanc

doc/file_format_stim_circuit.md

@@ -25,7 +25,8 @@ and annotations for tasks such as detection event sampling and drawing the circu
 ## Encoding
 
 Stim circuit files are always encoded using UTF-8.
-Furthermore, the only place in the file where non-ASCII characters are permitted is inside of comments.
+
+(Also, the only place in the file where non-ASCII characters can validly appear is inside of comments and tags.)
 
 ## Syntax
 

doc/gates.md

@@ -1784,7 +1784,7 @@ Example:
     # Apply Y to qubit 5 controlled by qubit 2.
     CY 2 5
 
-    # Perform CY 2 5 then CX 4 2.
+    # Perform CY 2 5 then CY 4 2.
     CY 2 5 4 2
 
     # Apply Y to qubit 6 if the most recent measurement result was TRUE.

doc/python_api_reference_vDev.md

@@ -43,6 +43,7 @@ API references for stable versions are kept on the [stim github wiki](https://gi
     - [`stim.Circuit.insert`](#stim.Circuit.insert)
     - [`stim.Circuit.inverse`](#stim.Circuit.inverse)
     - [`stim.Circuit.likeliest_error_sat_problem`](#stim.Circuit.likeliest_error_sat_problem)
+    - [`stim.Circuit.missing_detectors`](#stim.Circuit.missing_detectors)
     - [`stim.Circuit.num_detectors`](#stim.Circuit.num_detectors)
     - [`stim.Circuit.num_measurements`](#stim.Circuit.num_measurements)
     - [`stim.Circuit.num_observables`](#stim.Circuit.num_observables)
@@ -197,6 +198,7 @@ API references for stable versions are kept on the [stim github wiki](https://gi
     - [`stim.ExplainedError.dem_error_terms`](#stim.ExplainedError.dem_error_terms)
 - [`stim.FlipSimulator`](#stim.FlipSimulator)
     - [`stim.FlipSimulator.__init__`](#stim.FlipSimulator.__init__)
+    - [`stim.FlipSimulator.append_measurement_flips`](#stim.FlipSimulator.append_measurement_flips)
     - [`stim.FlipSimulator.batch_size`](#stim.FlipSimulator.batch_size)
     - [`stim.FlipSimulator.broadcast_pauli_errors`](#stim.FlipSimulator.broadcast_pauli_errors)
     - [`stim.FlipSimulator.clear`](#stim.FlipSimulator.clear)
@@ -1249,6 +1251,8 @@ def copy(
 # (in class stim.Circuit)
 def count_determined_measurements(
     self,
+    *,
+    unknown_input: bool = False,
 ) -> int:
     """Counts the number of predictable measurements in the circuit.
 
@@ -1280,6 +1284,13 @@ def count_determined_measurements(
     the Z basis. Typically this relationship is not declared as a detector, because
     it's not local, or as an observable, because it doesn't store a qubit.
 
+    Args:
+        unknown_input: Defaults to False (inputs assumed to be in the |0> state).
+            When set to True, the inputs are instead treated as being in unknown
+            random states. For example, this means that Z-basis measurements at
+            the very beginning of the circuit will be considered random rather
+            than determined.
+
     Returns:
         The number of measurements that were predictable.
 
@@ -1299,6 +1310,24 @@ def count_determined_measurements(
         ... ''').count_determined_measurements()
         0
 
+        >>> stim.Circuit('''
+        ...     M 0
+        ... ''').count_determined_measurements()
+        1
+
+        >>> stim.Circuit('''
+        ...     M 0
+        ... ''').count_determined_measurements(unknown_input=True)
+        0
+
+        >>> stim.Circuit('''
+        ...     M 0
+        ...     M 0 1
+        ...     M 0 1 2
+        ...     M 0 1 2 3
+        ... ''').count_determined_measurements(unknown_input=True)
+        6
+
         >>> stim.Circuit('''
         ...     R 0 1
         ...     MZZ 0 1
@@ -2542,6 +2571,72 @@ def likeliest_error_sat_problem(
     """
 ```
 
+<a name="stim.Circuit.missing_detectors"></a>
+```python
+# stim.Circuit.missing_detectors
+
+# (in class stim.Circuit)
+def missing_detectors(
+    self,
+    *,
+    unknown_input: bool = False,
+) -> int:
+    """Finds deterministic measurements independent of declared detectors/observables.
+
+    This method is useful for debugging missing detectors in a circuit, because it
+    identifies generators for uncovered degrees of freedom.
+
+    It's not recommended to use this method to solve for the detectors of a circuit.
+    The returned detectors are not guaranteed to be stable across versions, and
+    aren't optimized to be "good" (e.g. form a low weight basis or be matchable
+    if possible). It will also identify things that are technically determined
+    but that the user may not want to use as a detector, such as the fact that
+    in the first round after transversal Z basis initialization of a toric code
+    the product of all X stabilizer measurements is deterministic even though the
+    individual measurements are all random.
+
+    Args:
+        unknown_input: Defaults to False (inputs assumed to be in the |0> state).
+            When set to True, the inputs are instead treated as being in unknown
+            random states. For example, this means that Z-basis measurements at
+            the very beginning of the circuit will be considered random rather
+            than determined.
+
+    Returns:
+        A circuit containing DETECTOR instructions that specify the uncovered
+        degrees of freedom in the deterministic measurement sets of the input
+        circuit. The returned circuit can be appended to the input circuit to
+        get a circuit with no missing detectors.
+
+    Examples:
+        >>> import stim
+
+        >>> stim.Circuit('''
+        ...     R 0
+        ...     M 0
+        ... ''').missing_detectors()
+        stim.Circuit('''
+            DETECTOR rec[-1]
+        ''')
+
+        >>> stim.Circuit('''
+        ...     MZZ 0 1
+        ...     MYY 0 1
+        ...     MXX 0 1
+        ...     DEPOLARIZE1(0.1) 0 1
+        ...     MZZ 0 1
+        ...     MYY 0 1
+        ...     MXX 0 1
+        ...     DETECTOR rec[-1] rec[-4]
+        ...     DETECTOR rec[-2] rec[-5]
+        ...     DETECTOR rec[-3] rec[-6]
+        ... ''').missing_detectors(unknown_input=True)
+        stim.Circuit('''
+            DETECTOR rec[-3] rec[-2] rec[-1]
+        ''')
+    """
+```
+
 <a name="stim.Circuit.num_detectors"></a>
 ```python
 # stim.Circuit.num_detectors
@@ -8050,6 +8145,86 @@ def __init__(
     """
 ```
 
+<a name="stim.FlipSimulator.append_measurement_flips"></a>
+```python
+# stim.FlipSimulator.append_measurement_flips
+
+# (in class stim.FlipSimulator)
+def append_measurement_flips(
+    self,
+    measurement_flip_data: np.ndarray,
+) -> None:
+    """Appends measurement flip data to the simulator's measurement record.
+
+    Args:
+        measurement_flip_data: The flip data to append. The following shape/dtype
+            combinations are supported.
+
+            Single measurement without bit packing:
+                shape=(self.batch_size,)
+                dtype=np.bool_
+
+            Single measurement with bit packing:
+                shape=(math.ceil(self.batch_size / 8),)
+                dtype=np.uint8
+
+            Multiple measurements without bit packing:
+                shape=(num_measurements, self.batch_size)
+                dtype=np.bool_
+
+            Multiple measurements with bit packing:
+                shape=(num_measurements, math.ceil(self.batch_size / 8))
+                dtype=np.uint8
+
+    Examples:
+        >>> import stim
+        >>> import numpy as np
+        >>> sim = stim.FlipSimulator(batch_size=9)
+        >>> sim.append_measurement_flips(np.array(
+        ...     [0, 1, 0, 0, 1, 0, 0, 1, 1],
+        ...     dtype=np.bool_,
+        ... ))
+
+        >>> sim.get_measurement_flips()
+        array([[False,  True, False, False,  True, False, False,  True,  True]])
+
+        >>> sim.append_measurement_flips(np.array(
+        ...     [0b11001001, 0],
+        ...     dtype=np.uint8,
+        ... ))
+
+        >>> sim.get_measurement_flips()
+        array([[False,  True, False, False,  True, False, False,  True,  True],
+               [ True, False, False,  True, False, False,  True,  True, False]])
+
+        >>> sim.append_measurement_flips(np.array(
+        ...     [[0b11111111, 0b1], [0b00000000, 0b0], [0b11111111, 0b1]],
+        ...     dtype=np.uint8,
+        ... ))
+
+        >>> sim.get_measurement_flips()
+        array([[False,  True, False, False,  True, False, False,  True,  True],
+               [ True, False, False,  True, False, False,  True,  True, False],
+               [ True,  True,  True,  True,  True,  True,  True,  True,  True],
+               [False, False, False, False, False, False, False, False, False],
+               [ True,  True,  True,  True,  True,  True,  True,  True,  True]])
+
+        >>> sim.append_measurement_flips(np.array(
+        ...     [[1, 0, 1, 0, 1, 0, 1, 0, 1], [0, 1, 0, 1, 0, 1, 0, 1, 0]],
+        ...     dtype=np.bool_,
+        ... ))
+
+        >>> sim.get_measurement_flips()
+        array([[False,  True, False, False,  True, False, False,  True,  True],
+               [ True, False, False,  True, False, False,  True,  True, False],
+               [ True,  True,  True,  True,  True,  True,  True,  True,  True],
+               [False, False, False, False, False, False, False, False, False],
+               [ True,  True,  True,  True,  True,  True,  True,  True,  True],
+               [ True, False,  True, False,  True, False,  True, False,  True],
+               [False,  True, False,  True, False,  True, False,  True, False]])
+    """
+```
+
 <a name="stim.FlipSimulator.batch_size"></a>
 ```python
 # stim.FlipSimulator.batch_size