Fix seed correlation

crates/ppvm-python-native/Cargo.toml

@@ -25,3 +25,4 @@ pyo3 = { version = "0.29.0", features = [
     "multiple-pymethods",
     "abi3-py310",
 ] }
+rand = "0.10.3"

crates/ppvm-python-native/src/interface_tableau.rs

@@ -6,6 +6,7 @@ use paste::paste;
 use ppvm_tableau::prelude::*;
 use pyo3::prelude::*;
 use pyo3::types::{PyByteArray, PyComplex, PyDict};
+use rand::{RngExt, SeedableRng, rngs::SmallRng};
 
 pub(crate) fn measurement_to_u8(m: Option<bool>) -> u8 {
     match m {
@@ -317,10 +318,12 @@ macro_rules! create_interface {
             /// Multi-shot sampling: builds a fresh tableau per shot.
             ///
             /// Shots run in parallel on rayon's global thread pool (GIL
-            /// released), falling back to serial for small batches. Shot `i`
-            /// is seeded with `seed.wrapping_add(i)` when `seed` is given
-            /// (wrapping mod 2⁶⁴), so results are reproducible and
-            /// independent of the thread count; set the `RAYON_NUM_THREADS`
+            /// released), falling back to serial for small batches. When
+            /// `seed` is given, it is first scrambled into a base seed
+            /// (`SmallRng::seed_from_u64(seed).random::<u64>()`) and shot `i`
+            /// is seeded with `base.wrapping_add(i)`. Results are reproducible
+            /// and independent of the thread count, and nearby seeds (`s`,
+            /// `s + 1`, ...) give unrelated shots. Set the `RAYON_NUM_THREADS`
             /// environment variable to control the pool size.
             ///
             /// Returns the outcome codes (0/1/2 = zero/one/lost) as one flat,
@@ -346,7 +349,9 @@ macro_rules! create_interface {
                             Some(s) => GeneralizedTableau::<$type, $indexType>::new_with_seed(
                                 n_qubits,
                                 min_abs_coeff,
-                                s.wrapping_add(i as u64),
+                                SmallRng::seed_from_u64(s)
+                                    .random::<u64>()
+                                    .wrapping_add(i as u64),
                             ),
                             None => GeneralizedTableau::<$type, $indexType>::new(
                                 n_qubits,

crates/ppvm-stim/src/executor.rs

@@ -157,7 +157,9 @@ where
 /// `make_tableau(i)`.
 ///
 /// The shot index lets callers derive a deterministic per-shot seed (e.g.
-/// `seed + i`) so results are independent of evaluation order — the same
+/// `base.wrapping_add(i)` with `base = SmallRng::seed_from_u64(seed).random()`;
+/// don't use `seed + i` directly, or calls with seeds `s` and `s + 1` share
+/// almost all shots) so results are independent of evaluation order — the same
 /// factory then yields identical results from `sample_parallel` (when the `rayon` feature is enabled).
 pub fn sample_serial<T, I, C, F>(
     program: &ExtendedProgram,

crates/ppvm-vihaco/Cargo.toml

@@ -25,3 +25,4 @@ vihaco-parser = "0.4.1"
 vihaco-parser-derive = "0.4.1"
 vihaco-circuit-isa = { version = "0.1.0", path = "../vihaco-circuit-isa" }
 ppvm-pauli-sum = { version = "0.1.0", path = "../ppvm-pauli-sum" }
+rand = "0.10.3"

crates/ppvm-vihaco/src/shots.rs

@@ -12,6 +12,7 @@
 use crate::PPVMModule;
 use crate::composite::PPVM;
 use crate::measurements::MeasurementResult;
+use rand::{RngExt, SeedableRng, rngs::SmallRng};
 
 /// One shot's full output: the measurement record and the trace-instruction
 /// record. Either may be empty depending on what the program emits.
@@ -27,10 +28,18 @@ pub const PARALLEL_SHOT_THRESHOLD: usize = 128;
 
 /// Per-shot seed derived from the base seed and the shot index, so every shot
 /// gets a distinct RNG stream (a shared seed would make all shots identical).
-/// Depends only on `(base, index)`, so serial and parallel runs are bit-for-bit
-/// identical for a given seed regardless of thread count.
+/// The base seed is scrambled through a `SmallRng` before the index is added,
+/// so nearby base seeds (`s`, `s + 1`, ...) give unrelated shots rather than
+/// the same shots shifted by one (issue #228). Depends only on
+/// `(base, index)`, so serial and parallel runs are bit-for-bit identical for
+/// a given seed regardless of thread count.
+#[inline]
 fn shot_seed(base: Option<u64>, index: usize) -> Option<u64> {
-    base.map(|b| b.wrapping_add(index as u64))
+    base.map(|b| {
+        SmallRng::seed_from_u64(b)
+            .random::<u64>()
+            .wrapping_add(index as u64)
+    })
 }
 
 /// Run a single shot on a fresh machine and return both records.
@@ -178,6 +187,21 @@ mod tests {
         );
     }
 
+    #[test]
+    fn nearby_seeds_do_not_share_shots() {
+        // Regression test for #228: with `seed + i` per-shot seeds, the run
+        // with seed 8 was the run with seed 7 shifted by one shot. Each shot is
+        // one random bit, so a chance match of 127 bits is ~2^-127.
+        let m = module(RANDOM);
+        let a = run_shots_serial(&m, 128, Some(7)).unwrap();
+        let b = run_shots_serial(&m, 128, Some(8)).unwrap();
+        assert_ne!(
+            a[1..],
+            b[..127],
+            "seed 8 reproduced seed 7's shots shifted by one"
+        );
+    }
+
     #[cfg(feature = "rayon")]
     #[test]
     fn serial_and_parallel_match_for_same_seed() {

ppvm-python/src/ppvm/generalized_tableau.py

@@ -439,9 +439,10 @@ def sample(
 
         Shots run in parallel across CPU cores (the GIL is released during
         sampling), with a serial fallback for small batches. When ``seed`` is
-        given (it must fit in an unsigned 64-bit integer), shot ``i`` uses
-        ``(seed + i) % 2**64`` (wrapping ``u64`` arithmetic), so results are
-        reproducible and independent of the number of threads. Set the
+        given (it must fit in an unsigned 64-bit integer), each shot's seed is
+        derived deterministically from ``seed`` and the shot index, so results
+        are reproducible and independent of the number of threads, and nearby
+        seeds (``seed`` and ``seed + 1``) give unrelated shots. Set the
         ``RAYON_NUM_THREADS`` environment variable before the first call to
         control the pool size (it defaults to the number of logical cores).
 

ppvm-python/test/generalized_tableau/test_stim.py

@@ -255,6 +255,24 @@ def test_generalized_tableau_sample_classmethod_equivalent():
     assert a == b
 
 
+def test_sample_nearby_seeds_do_not_share_shots():
+    # Regression test for #228: with `seed + i` per-shot seeds, the batch for
+    # seed 8 was the batch for seed 7 shifted by one shot (999 of 1000 shared).
+    n = 32
+    qubits = " ".join(map(str, range(n)))
+    prog = StimProgram.parse(f"H {qubits}\nM {qubits}")
+
+    def shots(seed):
+        res = sample_stim(prog, n_qubits=n, num_shots=1000, seed=seed)
+        return [tuple(int(v) for v in shot) for shot in res]
+
+    a, b = shots(7), shots(8)
+    assert b[:-1] != a[1:]
+    # 32 random bits per shot: a chance collision between the two batches is
+    # ~1000^2 / 2^32 ≈ 2e-4, so allow a handful.
+    assert len(set(a) & set(b)) < 5
+
+
 def test_sample_stim_zero_shots_returns_empty():
     prog = StimProgram.parse("X 0\nM 0")
     assert sample_stim(prog, n_qubits=1, num_shots=0) == []

skills/ppvm-usage/SKILL.md

@@ -224,7 +224,10 @@ let prog = parse_extended(stim_src)?;
 
 // Multi-shot: pass a factory closure to `sample` — it reuses the parsed
 // program. The closure receives the shot index `i`; derive a per-shot seed
-// from it (e.g. `new_with_seed(.., base.wrapping_add(i as u64))`) for reproducible runs.
+// from it for reproducible runs. Scramble the user seed first
+// (`let base = SmallRng::seed_from_u64(seed).random::<u64>();`), then use
+// `new_with_seed(.., base.wrapping_add(i as u64))`. Plain `seed + i` makes calls
+// with seeds `s` and `s + 1` share almost all their shots.
 let shots = sample(&prog, 10_000, |_i| {
     GeneralizedTableau::<_, usize, _>::new(n_qubits, 1e-10)
 })?;