⚡ Bolt: optimize Fisher-Yates shuffle in RANSAC utilities

[suraj-ranganath]

⚡ Bolt: optimize Fisher-Yates shuffle in RANSAC utilities

💡 What

This optimization targets the Fisher-Yates shuffle implementations in rand_sample and rand_permutation within src/eegprep/plugins/clean_rawdata/private/ransac.py. It introduces two key improvements:

1. Vectorized Random Number Generation: Pre-generates all required random numbers in a single stream.rand(n) call instead of calling stream.rand() in every loop iteration.
2. Faster Scalar Rounding: Replaces the general-purpose round_mat utility with math.floor(x + 0.5) for internal scalar index calculations, which is significantly faster for non-negative numbers in tight loops.

🎯 Why

Fisher-Yates shuffles are used extensively in RANSAC and ICA. The overhead of individual Python function calls and the overhead of round_mat (which handles arrays and multiple decimal places) accumulates in these tight loops.

📊 Impact

Expected performance improvement:

• rand_sample: ~50% faster.
• rand_permutation: ~30% faster.
  Exact parity with EEGLAB/MATLAB random number generation is preserved.

🔬 Measurement

Verified using a benchmark script comparing original vs. optimized implementations over 1000 iterations for n=1000. Parity was confirmed by comparing output arrays.

✅ Verification

• All relevant tests in tests/test_utils_ransac.py and tests/test_parity_rng.py passed.
• Pre-commit lint and format checks passed.

---

PR created automatically by Jules for task 14941794764479403253 started by @suraj-ranganath

[google-labs-jules]

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

New to Jules? Learn more at jules.google/docs.

---

For security, I will only act on instructions from the user who triggered this task.

[claude]

Claude finished @suraj-ranganath's task in 1m 45s —— View job

---

PR Review: Optimize Fisher-Yates shuffle in RANSAC utilities

• Read the diff against origin/develop
• Verify RNG parity (vectorized rand vs successive rand())
• Verify round_mat → math.floor(x + 0.5) parity
• Check edge cases and the new n <= 1 guard

Verdict

The optimization is correct and parity-preserving. Both changes are sound:

1. Vectorized RNG — parity holds.
np.random.RandomState.rand(m) draws m doubles sequentially from the same Mersenne Twister stream, bit-for-bit identical to m successive stream.rand() calls. The indexing preserves the original consumption order in both functions:

• rand_sample: rands[k] for k = 0..m-1 matches the original forward loop.
• rand_permutation: loop runs k = n-1 … 1, and rands[(n-1)-k] maps to 0, 1, …, n-2 — i.e. the same order the old code pulled values. ✅

2. round_mat → math.floor(x + 0.5) — parity holds.
For decimals=0, round_mat computes copysign(floor(abs(x) + 0.5), x). The arguments here are always non-negative ((remaining-1) * rand() with remaining ≥ 1, and k * rand() with k ≥ 1), so copysign/abs are no-ops and the result reduces exactly to floor(x + 0.5). The multiplied operand x is bit-identical between old and new (same float64 value), so the floor result is identical. ✅

3. The n <= 1 guard is correct and necessary.
It's not just an optimization — for n == 0, stream.rand(n - 1) would be stream.rand(-1), which raises ValueError: negative dimensions. The original empty-loop code returned []/[0] without consuming the stream, and the guard preserves that exact behavior (zero RNG draws). Good catch. ✅

Minor notes (non-blocking)

• Stale docstring: rand_permutation's docstring (line 62) still says "It achieves parity by using rand() + round_mat()...". Since round_mat is no longer used, consider updating this to avoid confusion. Fix this →
• .jules/bolt.md: This adds a bot "learnings" note to the repo. Harmless, but worth confirming it's intended to be committed (per AGENTS.md "touch only files you must"). Not a blocker.
• The # Vectorized random number generation for performance and # Use math.floor... comments are slightly redundant with the PR description, but they document a non-obvious parity-sensitive choice, so they're reasonable to keep.

Testing

I couldn't run pytest here (Bash execution is gated in this review environment), so I verified parity by static analysis of RNG ordering and round_mat semantics rather than execution. The PR reports tests/test_utils_ransac.py and tests/test_parity_rng.py pass — those are the right tests to gate this change, and I'd recommend a maintainer confirm CI is green before merge since the whole value of this change rests on exact RNG/MATLAB parity.

Overall: clean, minimal, well-scoped optimization with no behavioral regression. 👍