Merge branch 'main' into sinter-correlated-pymatching

Author: inmzhang

.github/workflows/ci.yml

@@ -126,9 +126,7 @@ jobs:
           {os: windows-2025, dist: cp310-win_amd64},
           {os: windows-2025, dist: cp311-win_amd64},
           {os: windows-2025, dist: cp312-win_amd64},
-
-          # (April 2024) disabled because numpy fails to build. Unsure why it's not using a prebuilt wheel.
-          # {os: windows-2025, dist: cp313-win_amd64},
+          {os: windows-2025, dist: cp313-win_amd64},
 
           {os: windows-2025, dist: cp36-win32},
           {os: windows-2025, dist: cp37-win32},

doc/circuit_data_references.md

@@ -33,6 +33,7 @@
 - [arXiv:2408.00758](https://arxiv.org/abs/2408.00758) → [Stim circuits for ``To reset, or not to reset -- that is the question" manuscript](https://zenodo.org/records/13152440)
 - [arXiv:2408.11894](https://arxiv.org/abs/2408.11894) → [Stim circuits for 'Automated Synthesis of Fault-Tolerant State Preparation Circuits for Quantum Error Correction Codes'](https://github.com/cda-tum/mqt-qecc/tree/main/src/mqt/qecc/ft_stateprep/eval/circuits)
 - [arXiv:2408.13687](https://arxiv.org/abs/2408.13687) → [Data for "Quantum error correction below the surface code threshold"](https://zenodo.org/records/13273331)
+- [arXiv:2409.04628](https://arxiv.org/abs/2409.04628) → [Stim implementation of the [[16,4,4]] Tesseract Code](https://github.com/DeDuckProject/tesseract-code-stim) (circuits are in the stim_circuits/ directory)
 - [arXiv:2409.17595](https://arxiv.org/abs/2409.17595) → [Data for "Magic state cultivation: growing T states as cheap as CNOT gates"](https://zenodo.org/records/13777072)
 - [arXiv:2412.01391](https://arxiv.org/abs/2412.01391) → [GitHub repo for "Transversal Logical Clifford gates on rotated surface codes with reconfigurable neutral atom arrays"](https://github.com/Zihan-Chen-PhMA/Dynamical-S-gate-decoding/) (circuits are in the circuit_garage/ directory)
 - [arXiv:2412.14256](https://arxiv.org/abs/2412.14256) → [Data for "Scaling and logic in the color code on a superconducting quantum processor"](https://zenodo.org/records/14238944)

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
@@ -10911,6 +11086,14 @@ def __init__(
             Iterable: initializes by interpreting each item as a Pauli.
                 Each item can be a single-qubit Pauli string (like "X"),
                 or an integer. Integers use the convention 0=I, 1=X, 2=Y, 3=Z.
+            Dict[int, Union[int, str]]: initializes by interpreting keys as
+                the qubit index and values as the Pauli for that index.
+                Each value can be a single-qubit Pauli string (like "X"),
+                or an integer. Integers use the convention 0=I, 1=X, 2=Y, 3=Z.
+            Dict[Union[int, str], Iterable[int]]: initializes by interpreting keys
+                as Pauli operators and values as the qubit indices for that Pauli.
+                Each key can be a single-qubit Pauli string (like "X"),
+                or an integer. Integers use the convention 0=I, 1=X, 2=Y, 3=Z.
 
     Examples:
         >>> import stim
@@ -10938,6 +11121,15 @@ def __init__(
 
         >>> stim.PauliString("X6*Y6")
         stim.PauliString("+i______Z")
+
+        >>> stim.PauliString({0: "X", 2: "Y", 3: "X"})
+        stim.PauliString("+X_YX")
+
+        >>> stim.PauliString({0: "X", 2: 2, 3: 1})
+        stim.PauliString("+X_YX")
+
+        >>> stim.PauliString({"X": [1], 2: [4], "Z": [0, 3]})
+        stim.PauliString("+ZX_ZY")
     """
 ```