⚡ Bolt: vectorize griddata_v4 in topoplot

[suraj-ranganath]

💡 What:

Vectorized the griddata_v4 function in src/eegprep/functions/sigprocfunc/topoplot.py.

🎯 Why:

The previous implementation used a double-nested Python loop to evaluate the biharmonic spline at each query point on the grid. This is a classic NumPy anti-pattern that causes significant overhead for high-resolution topographic maps.

📊 Impact:

• Speedup: ~5.3x faster for a standard 67x67 grid.
• Baseline: 0.0694s
• Optimized: 0.0132s
• Memory: Introduces a small intermediate 3D array (grid x grid x channels), which is negligible for typical EEG data sizes (e.g., < 20MB for 128x128 grid and 128 channels).

🔬 Measurement:

Verified using a temporary benchmark script tools/benchmark_topoplot.py that measures the execution time of griddata_v4 on a 67x67 grid with 128 channels. Correctness was verified by running tests/test_topoplot.py.

---

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

---

Code review

• Overall assessment: Safe to merge — the vectorization is numerically equivalent to the prior loop.
• Highest-risk area: Broadcasting semantics of the removed xy column-vector reassignment.
• Merge recommendation: Safe to merge (one nit below).

I verified the change by tracing the math and shapes rather than running the suite (the CI sandbox here blocked uv run pytest/python3, so I could not execute tests/test_topoplot.py directly — please rely on your local run).

Correctness ✅

The vectorization is faithful to the original nested loop:

• The old code reassigned xy = xy[:, None] then used xy.ravel() per point. The new code correctly drops that reassignment and broadcasts the original 1-D xy (x + 1j*y, shape (channels,)) against the query grid:
  • (xq + 1j*yq)[..., None] → (grid, grid, 1)
  • xy[None, None, :] → (1, 1, channels)
  • d → (grid, grid, channels), real (via np.abs), matching the per-point np.abs(xq[i,j] + 1j*yq[i,j] - xy.ravel()).
• Green's function (d**2)*(log(d)-1) and the zero-distance guard g[d == 0] = 0 are preserved, so query points landing exactly on an electrode stay finite (covered by test_zero_distance_handling).
• vq = g @ weights reduces over the channel axis, equivalent to np.dot(g, weights) at each (i, j).

Existing tests (test_basic_interpolation, test_collinear_points, test_single_point_interpolation, test_zero_distance_handling, plus the MATLAB parity tests) already exercise these paths, so no new test is needed for this behavior-preserving change.

Blocking

None.

Important

None.

Nits

• .jules/bolt.md (added): This looks like an agent scratch/learning note rather than a code artifact, and it carries an incorrect date (## 2025-05-15 — today is 2026-07-03). AGENTS.md asks to touch only files the change requires and not to commit AI-tooling artifacts. Consider dropping this file from the PR unless the repo intentionally tracks .jules/ notes.
• vq dtype (nit): The old vq = np.zeros_like(xq) inherited xq's dtype; vq = g @ weights is always float64. Harmless for the float64 grids topoplot generates — noting only for completeness.

Test gaps

None. The change is behavior-preserving and the existing TestGriddataV4 cases cover the affected paths.

EEGLAB parity notes

None. This mirrors MATLAB's gdatav4 biharmonic-spline evaluation; only the Python evaluation loop was vectorized, and the parity tests (test_parity_*) guard the output against EEGLAB.