⚡ Bolt: optimize covariance matrix powers and runica training loops

[suraj-ranganath]

💡 What: Optimized core numerical operations in covariance.py and runica.py.
🎯 Why: Stacks of covariance matrices and ICA training loops are performance bottlenecks.
📊 Impact: diag_nd is ~10x faster; runica training is ~3% faster.
🔬 Measurement: Verified with tools/benchmark_covariance_optimized.py and tools/benchmark_runica.py.

---

PR created automatically by Jules for task 10895161003436251304 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 48s —— View job

---

Code review

• Read PR diff against origin/develop
• Verify covariance.py broadcasting equivalence
• Verify runica.py mean-removal and bias broadcasting
• Check finite_matmul NaN-handling semantics
• Assess test coverage

Overall assessment: Safe to merge. The optimizations are mathematically equivalent to the originals.
Highest-risk area: covariance.py eigendecomposition reconstruction (V @ diag(d) @ V.T → V * d).
Merge recommendation: Safe to merge.

Blocking

None.

Important

None.

Nits

• .jules/bolt.md (new file) — This is a Jules agent scratch/learning note being committed into the repo. AGENTS.md says to "Touch only files you must"; an agent log isn't part of the library. The header date (2025-05-15) is also stale/incorrect. Suggest removing it from the PR or adding .jules/ to .gitignore so these notes don't land in the tree. Severity: nit.

Test gaps

None required. These are behavior-preserving optimizations, so the existing covariance/runica tests cover the changed paths. I confirmed the rewrites produce identical results (see parity notes), so no new tests are warranted.

EEGLAB parity notes

Verified the rewrites are equivalent, not just faster:

• covariance.py — cov_logm/expm/powm/sqrtm/rsqrtm/sqrtm2: V @ diag(d) @ V.T has (V @ diag(d))[i,j] = V[i,j]·d[j], which is exactly V * d[..., newaxis, :]. The new code is identical bit-for-bit in the normal (finite) case. Importantly, I checked finite_matmul (src/eegprep/functions/miscfunc/misc.py:42) — it only suppresses spurious RuntimeWarnings and does no nan_to_num cleaning, so collapsing the inner finite_matmul into element-wise scaling introduces no difference in NaN/Inf propagation. ✅
• covariance.py — diag_nd: vectorized res[..., i, i] = M matches the old np.diag-per-slice + reshape, and dtype=M.dtype preserves the original dtype. ✅
• runica.py — mean removal: data -= rowmeans[:, np.newaxis] is the in-place equivalent of the per-row loop. ✅
• runica.py — bias term: dropping onesrow and using + bias relies on (ncomps, 1) broadcasting across the block width, equal to bias @ onesrow. Blocks are uniformly sized (lastt = (datalength/block - 1)*block + 1, range(0, lastt, block)), and broadcasting is robust even for a short final block. The two remaining onesrow mentions are only in # MATLAB: comments, which is fine for parity documentation. ✅
  · bolt-covariance-runica-opt-10895161003436251304

[suraj-ranganath]

🤖 Closing this combined optimization. The covariance changes duplicate the retained #281, while the runica mean/bias changes overlap the retained #278. They are unrelated kernels with different numerical and performance risks and should not share a merge/revert unit. Keeping the focused candidates gives each change a clear test and review boundary.

[google-labs-jules]

🤖 Closing this combined optimization. The covariance changes duplicate the retained #281, while the runica mean/bias changes overlap the retained #278. They are unrelated kernels with different numerical and performance risks and should not share a merge/revert unit. Keeping the focused candidates gives each change a clear test and review boundary.

Understood. Acknowledging that this work is now obsolete and stopping work on this task as the optimizations are being handled in separate, more focused PRs (#281 and #278).