Add optional seed parameter to stim.Tableau.random()

Fixes #974

Author: xguot

glue/python/src/stim/__init__.pyi

@@ -9987,6 +9987,7 @@ class PauliString:
         num_qubits: int,
         *,
         allow_imaginary: bool = False,
+        seed: int | None = None,
     ) -> stim.PauliString:
         """Samples a uniformly random Hermitian Pauli string.
 
@@ -9995,6 +9996,28 @@ class PauliString:
             allow_imaginary: Defaults to False. If True, the sign of the result may be
                 1j or -1j in addition to +1 or -1. In other words, setting this to True
                 allows the result to be non-Hermitian.
+            seed: PARTIALLY determines the sampled Pauli string by deterministically
+                seeding the random number generator.
+
+                Must be None or an integer in range(2**64).
+
+                Defaults to None. When None, the prng is seeded from system entropy.
+
+                When set to an integer, making the exact same series calls on the exact
+                same machine with the exact same version of Stim will produce the exact
+                same Pauli string.
+
+                CAUTION: the Pauli string produced by a specific seed *WILL NOT* be
+                consistent between versions of Stim. This restriction is present to
+                make it possible to have future optimizations to the random sampling,
+                and is enforced by introducing intentional differences in the seeding
+                strategy from version to version.
+
+                CAUTION: the Pauli string produced by a specific seed *MAY NOT* be
+                consistent across machines that differ in the width of supported SIMD
+                instructions. For example, using the same seed on a machine that
+                supports AVX instructions and one that only supports SSE instructions
+                may produce different Pauli strings.
 
         Examples:
             >>> import stim
@@ -11212,11 +11235,35 @@ class Tableau:
     @staticmethod
     def random(
         num_qubits: int,
+        *,
+        seed: int | None = None
     ) -> stim.Tableau:
         """Samples a uniformly random Clifford operation and returns its tableau.
 
         Args:
             num_qubits: The number of qubits the tableau should act on.
+            seed: PARTIALLY determines the sampled tableau by deterministically
+                seeding the random number generator.
+
+                Must be None or an integer in range(2**64).
+
+                Defaults to None. When None, the prng is seeded from system entropy.
+
+                When set to an integer, making the exact same series calls on the exact
+                same machine with the exact same version of Stim will produce the exact
+                same tableau.
+
+                CAUTION: the tableau produced by a specific seed *WILL NOT* be
+                consistent between versions of Stim. This restriction is present to
+                make it possible to have future optimizations to the random sampling,
+                and is enforced by introducing intentional differences in the seeding
+                strategy from version to version.
+
+                CAUTION: the tableau produced by a specific seed *MAY NOT* be
+                consistent across machines that differ in the width of supported SIMD
+                instructions. For example, using the same seed on a machine that
+                supports AVX instructions and one that only supports SSE instructions
+                may produce different tableaus.
 
         Returns:
             The sampled tableau.

src/stim/stabilizers/pauli_string.pybind.cc

@@ -635,14 +635,15 @@ void stim_pybind::pybind_pauli_string_methods(pybind11::module &m, pybind11::cla
 
     c.def_static(
         "random",
-        [](size_t num_qubits, bool allow_imaginary) {
-            auto rng = make_py_seeded_rng(pybind11::none());
+        [](size_t num_qubits, bool allow_imaginary, pybind11::object seed_obj) {
+            auto rng = make_py_seeded_rng(seed_obj);
             return FlexPauliString(
                 PauliString<MAX_BITWORD_WIDTH>::random(num_qubits, rng), allow_imaginary ? (rng() & 1) : false);
         },
         pybind11::arg("num_qubits"),
         pybind11::kw_only(),
         pybind11::arg("allow_imaginary") = false,
+        pybind11::arg("seed") = pybind11::none(),
         clean_doc_string(R"DOC(
             Samples a uniformly random Hermitian Pauli string.
 
@@ -651,6 +652,7 @@ void stim_pybind::pybind_pauli_string_methods(pybind11::module &m, pybind11::cla
                 allow_imaginary: Defaults to False. If True, the sign of the result may be
                     1j or -1j in addition to +1 or -1. In other words, setting this to True
                     allows the result to be non-Hermitian.
+                seed: Optional. An integer to seed the random number generator.
 
             Examples:
                 >>> import stim

src/stim/stabilizers/tableau.pybind.cc

@@ -180,16 +180,18 @@ void stim_pybind::pybind_tableau_methods(pybind11::module &m, pybind11::class_<T
 
     c.def_static(
         "random",
-        [](size_t num_qubits) {
-            auto rng = make_py_seeded_rng(pybind11::none());
+        [](size_t num_qubits, pybind11::object seed_obj) {
+            auto rng = make_py_seeded_rng(seed_obj);
             return Tableau<MAX_BITWORD_WIDTH>::random(num_qubits, rng);
         },
         pybind11::arg("num_qubits"),
+        pybind11::arg("seed") = pybind11::none(),
         clean_doc_string(R"DOC(
             Samples a uniformly random Clifford operation and returns its tableau.
 
             Args:
                 num_qubits: The number of qubits the tableau should act on.
+                seed: Optional. An integer to seed the random number generator.
 
             Returns:
                 The sampled tableau.

src/stim/stabilizers/tableau_pybind_test.py

@@ -111,6 +111,23 @@ def test_random():
     assert t != stim.Tableau.random(10)
 
 
+def test_random_seed():
+    t1 = stim.Tableau.random(4, seed=12345)
+    t2 = stim.Tableau.random(4, seed=12345)
+    assert t1 == t2
+
+    t3 = stim.Tableau.random(4, seed=54321)
+    assert t1 != t3
+
+    t4 = stim.Tableau.random(4, seed=None)
+    t5 = stim.Tableau.random(4, seed=None)
+    assert t4 != t5
+
+    t6 = stim.Tableau.random(num_qubits=2, seed=999)
+    t7 = stim.Tableau.random(num_qubits=2, seed=999)
+    assert t6 == t7
+
+
 def test_str():
     assert str(stim.Tableau.from_named_gate("cnot")).strip() == """
 +-xz-xz-