⚡ Bolt: Optimize topoplot grid interpolation

[suraj-ranganath]

⚡ Bolt Performance Boost: Topoplot Vectorization

💡 What

Optimized the griddata_v4 function in src/eegprep/functions/sigprocfunc/topoplot.py by replacing a double-nested Python loop over the query grid with vectorized NumPy operations.

🎯 Why

Topographic plotting is a frequent operation in EEG analysis. The previous implementation iterated over every pixel in the 67x67 grid, performing scalar distance calculations and dot products, which is a classic bottleneck in Python.

📊 Impact

• Speedup: ~3.8x to ~4.2x improvement in the griddata_v4 interpolation step.
• Latency: Reduced execution time for 10 grid evaluations from ~0.71s to ~0.17s on the benchmark environment.
• Scalability: The vectorized approach scales much better with higher grid resolutions or channel counts.

🔬 Measurement

Verified using a temporary benchmark script tools/benchmark_topoplot.py (since deleted) and by running the existing test suite:
uv run pytest tests/test_topoplot.py (26/26 non-MATLAB tests passed).

BOLT'S PHILOSOPHY

Speed is a feature. By vectorizing the core interpolation logic, we make the GUI and interactive plotting significantly more responsive for researchers.

---

PR created automatically by Jules for task 14794135948060669086 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 encountered an error after 0s —— View job

---

I'll analyze this and get back to you.

[claude]

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

---

Review: PR #284 — Topoplot grid interpolation vectorization

• Read PR diff
• Analyze correctness of vectorization
• Check EEGLAB parity concerns
• Check .jules/bolt.md addition

Verdict

The vectorization is mathematically equivalent to the original double loop and is a clean, idiomatic NumPy rewrite. Nice work — this is a legitimate hot path (topoplot runs on every interactive plot).

Correctness ✅

The transformation is sound:

• d = np.abs(xq_yq_complex[..., np.newaxis] - xy.ravel()) broadcasts (m, n, 1) against (num_electrodes,) → (m, n, num_electrodes), exactly reproducing the per-pixel np.abs(...) from the old loop.
• g @ weights contracts the last axis (m, n, num_electrodes) @ (num_electrodes,) → (m, n), which is np.dot(g, weights) applied per pixel.
• The g[d == 0] = 0 Green's-function guard is preserved and now applies element-wise across the full 3D array — same semantics.
• Dropping vq = np.zeros_like(xq) is fine: vq is now produced directly by the matmul (real-valued, since d is a magnitude).

One tidy-up detail: the old code reassigned xy = xy[:, None] before the loop and then called xy.ravel(); the new code skips that reassignment and calls xy.ravel() on the original 1-D xy. Equivalent result, and arguably cleaner. The .ravel() is now a redundant no-op (xy is already 1-D from line 26) — you could drop it, but it's harmless.

Minor considerations

1. Memory tradeoff (worth a mention, not a blocker): the new code materializes a full (m, n, num_electrodes) intermediate d/g. For the default 67×67 grid this is small even at high channel counts (67·67·256 ≈ 1.1M floats ≈ 9 MB), so it's fine. Just flagging that the speedup trades the old O(1)-extra-memory loop for an O(grid·channels) allocation — reasonable here, but the PR's "scales much better with higher grid resolutions" claim has a memory ceiling at very large grids.

2. .jules/bolt.md is committed to the repo. This agent scratch/learnings file is now tracked in git (.jules/bolt.md, not gitignored). Nothing here is harmful, but it's unrelated to the code change and adds an agent-workflow artifact to the source tree. Consider either gitignoring .jules/ or dropping this file from the PR to keep the diff scoped to the optimization. Your call — if the repo intends to keep Jules learnings, ignore this.

Testing

I couldn't execute pytest/Python in this environment (Bash calls were blocked by permissions), so I verified equivalence by code analysis rather than a live run. The PR notes tests/test_topoplot.py passes 26/26 non-MATLAB tests. If a MATLAB/Octave parity oracle is available, running tests/test_topoplot.py with the parity markers enabled would be the strongest confirmation that the biharmonic spline output matches EEGLAB's gdatav4 to tolerance.

Summary

Correct, well-commented, and a real speedup on a genuine hot path. Only non-code note is whether .jules/bolt.md belongs in the committed tree.

[suraj-ranganath]

🤖 Closing as a duplicate of #263. Both PRs replace the same griddata_v4 query-grid loop with the same broadcasted Green-function evaluation; #263 is already scoped to the source change, has been vetted, and does not include the unrelated .jules/bolt.md artifact. This PR adds no distinct behavior or coverage worth maintaining in parallel.