Pauli iter all

doc/python_api_reference_vDev.md

@@ -227,11 +227,17 @@ API references for stable versions are kept on the [stim github wiki](https://gi
     - [`stim.PauliString.copy`](#stim.PauliString.copy)
     - [`stim.PauliString.from_numpy`](#stim.PauliString.from_numpy)
     - [`stim.PauliString.from_unitary_matrix`](#stim.PauliString.from_unitary_matrix)
+    - [`stim.PauliString.iter_all`](#stim.PauliString.iter_all)
     - [`stim.PauliString.random`](#stim.PauliString.random)
     - [`stim.PauliString.sign`](#stim.PauliString.sign)
     - [`stim.PauliString.to_numpy`](#stim.PauliString.to_numpy)
     - [`stim.PauliString.to_tableau`](#stim.PauliString.to_tableau)
     - [`stim.PauliString.to_unitary_matrix`](#stim.PauliString.to_unitary_matrix)
+- [`stim.PauliStringIterator`](#stim.PauliStringIterator)
+    - [`stim.PauliStringIterator.__iter__`](#stim.PauliStringIterator.__iter__)
+    - [`stim.PauliStringIterator.__next__`](#stim.PauliStringIterator.__next__)
+    - [`stim.PauliStringIterator.next_qubit_permutation`](#stim.PauliStringIterator.next_qubit_permutation)
+    - [`stim.PauliStringIterator.seed_iterator`](#stim.PauliStringIterator.seed_iterator)
 - [`stim.Tableau`](#stim.Tableau)
     - [`stim.Tableau.__add__`](#stim.Tableau.__add__)
     - [`stim.Tableau.__call__`](#stim.Tableau.__call__)
@@ -7586,6 +7592,45 @@ def from_unitary_matrix(
     """
 ```
 
+<a name="stim.PauliString.iter_all"></a>
+```python
+# stim.PauliString.iter_all
+
+# (in class stim.PauliString)
+@staticmethod
+def iter_all(
+    num_qubits: int,
+    *,
+    min_weight: Optional[int] = None,
+    max_weight: Optional[int] = None,
+) -> stim.PauliStringIterator:
+    """Returns an iterator that iterates over all PauliStrings.
+
+    The length of PauliString and its weight (the number of
+    non-identity terms) are controlled by num_qubits and
+    min_/max_weight.
+
+    Args:
+        num_qubits: The number of qubits the Pauli string acts on.
+        min_weight: The minimum weight PauliString to consider. If None
+            min_weight is set to zero and the identity string is included.
+        max_weight: The maximum weight PauliString to consider. If None
+            then max_weight is set to num_qubits.
+
+    Returns:
+        An Iterable[stim.PauliString] that yields the requested PauliStrings.
+
+    Examples:
+        >>> import stim
+        >>> pauli_iter = stim.PauliString.iter_all(10, min_weight=2, max_weight=3)
+        >>> n = 0
+        >>> for pauli_string in pauli_iter:
+        ...     n += 1
+        >>> n
+        3645
+    """
+```
+
 <a name="stim.PauliString.random"></a>
 ```python
 # stim.PauliString.random
@@ -7793,6 +7838,101 @@ def to_unitary_matrix(
     """
 ```
 
+<a name="stim.PauliStringIterator"></a>
+```python
+# stim.PauliStringIterator
+
+# (at top-level in the stim module)
+class PauliStringIterator:
+    """Iterates over all possible pauli_strings of weight specfied by
+    min_weight and max_weight.
+
+    Returns:
+        An Iterable[stim.PauliString] that yields the requested Pauli
+            string.
+
+    Examples:
+        >>> import stim
+        >>> pauli_iter = stim.PauliString.iter_all(10, min_weight=2, max_weight=3)
+        >>> n = 0
+        >>> for pauli_string in pauli_iter:
+        ...     n += 1
+        >>> n
+        3645
+    """
+```
+
+<a name="stim.PauliStringIterator.__iter__"></a>
+```python
+# stim.PauliStringIterator.__iter__
+
+# (in class stim.PauliStringIterator)
+def __iter__(
+    self,
+) -> stim.PauliStringIterator:
+    """Returns an independent copy of the pauli string iterator.
+    """
+```
+
+<a name="stim.PauliStringIterator.__next__"></a>
+```python
+# stim.PauliStringIterator.__next__
+
+# (in class stim.PauliStringIterator)
+def __next__(
+    self,
+) -> stim.PauliString:
+    """Returns the next iterated pauli string.
+    """
+```
+
+<a name="stim.PauliStringIterator.next_qubit_permutation"></a>
+```python
+# stim.PauliStringIterator.next_qubit_permutation
+
+# (in class stim.PauliStringIterator)
+def next_qubit_permutation(
+    self,
+) -> object:
+    """Get the next permutation of qubit labels.
+
+    It's alot easier to test more complicated edge cases in python
+    which largely arise due to the algorithm for generating the next
+    permutation. The user should probably not interact with this function.
+
+    Returns:
+        next_perm: numpy boolean array which represents the next qubit permutation
+
+    Examples:
+        >>> import stim
+        >>> pauli_iter = stim.PauliString.iter_all(5, min_weight=3, max_weight=5)
+        >>> pauli_iter.next_qubit_permutation()
+        array([ True,  True, False,  True, False])
+    """
+```
+
+<a name="stim.PauliStringIterator.seed_iterator"></a>
+```python
+# stim.PauliStringIterator.seed_iterator
+
+# (in class stim.PauliStringIterator)
+def seed_iterator(
+    self,
+    arg0: object,
+) -> None:
+    """Seed the iterator with a given qubit pattern.
+
+    Examples:
+        >>> import stim
+        >>> import numpy as np
+        >>> pauli_iter = stim.PauliString.iter_all(4, min_weight=2, max_weight=2)
+        >>> seed = np.array([False, True, True, False])
+        >>> pauli_iter.seed_iterator(seed)
+        >>> pauli_iter.next_qubit_permutation()
+        array([ True, False, False,  True])
+    """
+```
+
 <a name="stim.Tableau"></a>
 ```python
 # stim.Tableau

doc/stim.pyi

@@ -5805,6 +5805,38 @@ class PauliString:
             stim.PauliString("+XZ")
         """
     @staticmethod
+    def iter_all(
+        num_qubits: int,
+        *,
+        min_weight: Optional[int] = None,
+        max_weight: Optional[int] = None,
+    ) -> stim.PauliStringIterator:
+        """Returns an iterator that iterates over all PauliStrings.
+
+        The length of PauliString and its weight (the number of
+        non-identity terms) are controlled by num_qubits and
+        min_/max_weight.
+
+        Args:
+            num_qubits: The number of qubits the Pauli string acts on.
+            min_weight: The minimum weight PauliString to consider. If None
+                min_weight is set to zero and the identity string is included.
+            max_weight: The maximum weight PauliString to consider. If None
+                then max_weight is set to num_qubits.
+
+        Returns:
+            An Iterable[stim.PauliString] that yields the requested PauliStrings.
+
+        Examples:
+            >>> import stim
+            >>> pauli_iter = stim.PauliString.iter_all(10, min_weight=2, max_weight=3)
+            >>> n = 0
+            >>> for pauli_string in pauli_iter:
+            ...     n += 1
+            >>> n
+            3645
+        """
+    @staticmethod
     def random(
         num_qubits: int,
         *,
@@ -5976,6 +6008,66 @@ class PauliString:
                    [0.+0.j, 0.+0.j, 0.+0.j, 0.-1.j],
                    [0.+0.j, 0.+0.j, 0.+1.j, 0.+0.j]], dtype=complex64)
         """
+class PauliStringIterator:
+    """Iterates over all possible pauli_strings of weight specfied by
+    min_weight and max_weight.
+
+    Returns:
+        An Iterable[stim.PauliString] that yields the requested Pauli
+            string.
+
+    Examples:
+        >>> import stim
+        >>> pauli_iter = stim.PauliString.iter_all(10, min_weight=2, max_weight=3)
+        >>> n = 0
+        >>> for pauli_string in pauli_iter:
+        ...     n += 1
+        >>> n
+        3645
+    """
+    def __iter__(
+        self,
+    ) -> stim.PauliStringIterator:
+        """Returns an independent copy of the pauli string iterator.
+        """
+    def __next__(
+        self,
+    ) -> stim.PauliString:
+        """Returns the next iterated pauli string.
+        """
+    def next_qubit_permutation(
+        self,
+    ) -> object:
+        """Get the next permutation of qubit labels.
+
+        It's alot easier to test more complicated edge cases in python
+        which largely arise due to the algorithm for generating the next
+        permutation. The user should probably not interact with this function.
+
+        Returns:
+            next_perm: numpy boolean array which represents the next qubit permutation
+
+        Examples:
+            >>> import stim
+            >>> pauli_iter = stim.PauliString.iter_all(5, min_weight=3, max_weight=5)
+            >>> pauli_iter.next_qubit_permutation()
+            array([ True,  True, False,  True, False])
+        """
+    def seed_iterator(
+        self,
+        arg0: object,
+    ) -> None:
+        """Seed the iterator with a given qubit pattern.
+
+        Examples:
+            >>> import stim
+            >>> import numpy as np
+            >>> pauli_iter = stim.PauliString.iter_all(4, min_weight=2, max_weight=2)
+            >>> seed = np.array([False, True, True, False])
+            >>> pauli_iter.seed_iterator(seed)
+            >>> pauli_iter.next_qubit_permutation()
+            array([ True, False, False,  True])
+        """
 class Tableau:
     """A stabilizer tableau.
 

file_lists/benchmark_files

@@ -15,5 +15,6 @@ src/stim/simulators/error_analyzer.perf.cc
 src/stim/simulators/frame_simulator.perf.cc
 src/stim/simulators/tableau_simulator.perf.cc
 src/stim/stabilizers/pauli_string.perf.cc
+src/stim/stabilizers/pauli_string_iter.perf.cc
 src/stim/stabilizers/tableau.perf.cc
 src/stim/stabilizers/tableau_iter.perf.cc

file_lists/python_api_files

@@ -20,5 +20,6 @@ src/stim/simulators/matched_error.pybind.cc
 src/stim/simulators/measurements_to_detection_events.pybind.cc
 src/stim/simulators/tableau_simulator.pybind.cc
 src/stim/stabilizers/pauli_string.pybind.cc
+src/stim/stabilizers/pauli_string_iter.pybind.cc
 src/stim/stabilizers/tableau.pybind.cc
 src/stim/stabilizers/tableau_iter.pybind.cc

file_lists/test_files

@@ -68,6 +68,7 @@ src/stim/simulators/transform_without_feedback.test.cc
 src/stim/simulators/vector_simulator.test.cc
 src/stim/stabilizers/conversions.test.cc
 src/stim/stabilizers/pauli_string.test.cc
+src/stim/stabilizers/pauli_string_iter.test.cc
 src/stim/stabilizers/tableau.test.cc
 src/stim/stabilizers/tableau_iter.test.cc
 src/stim/str_util.test.cc

glue/python/src/stim/__init__.pyi

@@ -5805,6 +5805,38 @@ class PauliString:
             stim.PauliString("+XZ")
         """
     @staticmethod
+    def iter_all(
+        num_qubits: int,
+        *,
+        min_weight: Optional[int] = None,
+        max_weight: Optional[int] = None,
+    ) -> stim.PauliStringIterator:
+        """Returns an iterator that iterates over all PauliStrings.
+
+        The length of PauliString and its weight (the number of
+        non-identity terms) are controlled by num_qubits and
+        min_/max_weight.
+
+        Args:
+            num_qubits: The number of qubits the Pauli string acts on.
+            min_weight: The minimum weight PauliString to consider. If None
+                min_weight is set to zero and the identity string is included.
+            max_weight: The maximum weight PauliString to consider. If None
+                then max_weight is set to num_qubits.
+
+        Returns:
+            An Iterable[stim.PauliString] that yields the requested PauliStrings.
+
+        Examples:
+            >>> import stim
+            >>> pauli_iter = stim.PauliString.iter_all(10, min_weight=2, max_weight=3)
+            >>> n = 0
+            >>> for pauli_string in pauli_iter:
+            ...     n += 1
+            >>> n
+            3645
+        """
+    @staticmethod
     def random(
         num_qubits: int,
         *,
@@ -5976,6 +6008,66 @@ class PauliString:
                    [0.+0.j, 0.+0.j, 0.+0.j, 0.-1.j],
                    [0.+0.j, 0.+0.j, 0.+1.j, 0.+0.j]], dtype=complex64)
         """
+class PauliStringIterator:
+    """Iterates over all possible pauli_strings of weight specfied by
+    min_weight and max_weight.
+
+    Returns:
+        An Iterable[stim.PauliString] that yields the requested Pauli
+            string.
+
+    Examples:
+        >>> import stim
+        >>> pauli_iter = stim.PauliString.iter_all(10, min_weight=2, max_weight=3)
+        >>> n = 0
+        >>> for pauli_string in pauli_iter:
+        ...     n += 1
+        >>> n
+        3645
+    """
+    def __iter__(
+        self,
+    ) -> stim.PauliStringIterator:
+        """Returns an independent copy of the pauli string iterator.
+        """
+    def __next__(
+        self,
+    ) -> stim.PauliString:
+        """Returns the next iterated pauli string.
+        """
+    def next_qubit_permutation(
+        self,
+    ) -> object:
+        """Get the next permutation of qubit labels.
+
+        It's alot easier to test more complicated edge cases in python
+        which largely arise due to the algorithm for generating the next
+        permutation. The user should probably not interact with this function.
+
+        Returns:
+            next_perm: numpy boolean array which represents the next qubit permutation
+
+        Examples:
+            >>> import stim
+            >>> pauli_iter = stim.PauliString.iter_all(5, min_weight=3, max_weight=5)
+            >>> pauli_iter.next_qubit_permutation()
+            array([ True,  True, False,  True, False])
+        """
+    def seed_iterator(
+        self,
+        arg0: object,
+    ) -> None:
+        """Seed the iterator with a given qubit pattern.
+
+        Examples:
+            >>> import stim
+            >>> import numpy as np
+            >>> pauli_iter = stim.PauliString.iter_all(4, min_weight=2, max_weight=2)
+            >>> seed = np.array([False, True, True, False])
+            >>> pauli_iter.seed_iterator(seed)
+            >>> pauli_iter.next_qubit_permutation()
+            array([ True, False, False,  True])
+        """
 class Tableau:
     """A stabilizer tableau.