Feature/20260421 bbrzycki accelerate voltage experiments

[bbrzycki]

Summary

This PR accelerates setigen.voltage workflows by adding exact selected-channel computation, direct voltage-to-spectrogram generation, and centralized NumPy/CuPy backend control.

Key changes:

• Add stg.voltage.set_backend("cupy" | "numpy" | "auto") for explicit backend selection.
• Keep SETIGEN_ENABLE_GPU=1 as a legacy fallback.
• Add selected-bin coarse PFB channelization to avoid full coarse FFTs for small channel selections.
• Add selected fine-channel DFT reduction for targeted final-frequency regions.
• Add RawVoltageBackend.to_spectrogram(...) to generate spectrograms directly without writing and rereading RAW files.
• Add frequency_range, coarse_method, and fine_method options to reduction specs.
• Add CLI flags for --frequency-range and --fine-method.
• Update docs and voltage notebooks to prefer stg.voltage.set_backend("cupy").

Usage

Enable GPU acceleration before constructing voltage objects:

import os
os.environ["CUDA_VISIBLE_DEVICES"] = "0"

import setigen as stg
stg.voltage.set_backend("cupy")

Force CPU execution:

stg.voltage.set_backend("numpy")

Generate a spectrogram directly from a voltage backend:

spec = stg.voltage.VoltageSpectrogramSpec(
    fftlength=1024,
    integration_factor=4,
    pol_mode=stg.voltage.PolarizationMode.TOTAL_POWER,
    coarse_method="auto",
    fine_method="auto",
)

result = rvb.to_spectrogram(
    spec,
    num_blocks=1,
    length_mode="num_blocks",
    verbose=False,
)

frame = result.to_frame()

Reduce only a final-frequency region:

spec = stg.voltage.RawReductionSpec(
    fftlength=1024,
    integration_factor=4,
    pol_mode=stg.voltage.PolarizationMode.TOTAL_POWER,
    output_format="fil",
    frequency_range=(6001.0e6, 6001.5e6),
    backend="cupy",
    fine_method="selected",
)

stg.voltage.reduce_raw(raw_stem, "roi.fil", spec, overwrite=True)

CLI equivalent:

setigen-raw-reduce input.raw roi.fil \
  --fftlength 1024 \
  --integration-factor 4 \
  --frequency-range 6001000000 6001500000 \
  --backend cupy \
  --fine-method selected \
  --overwrite

Notes

• The new selected-channel paths preserve exact FFT/DFT semantics.
• accuracy="approx_zoom" is reserved but not implemented; only accuracy="exact" is currently supported.
• coarse_method="auto" and fine_method="auto" use selected-bin computation only for small selections and fall back to full FFT otherwise.
• The tap-vectorized PFB frontend is available for experiments via filterbank.frontend_method = "vectorized", but remains off by default because it can increase temporary memory use.

[codecov]

Codecov Report

❌ Patch coverage is 99.73190% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 94.27%. Comparing base (4cfaf00) to head (1972475).
⚠️ Report is 7 commits behind head on main.

Files with missing lines	Patch %	Lines
setigen/voltage/_array_backend.py	98.33%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #44      +/-   ##
==========================================
+ Coverage   92.22%   94.27%   +2.04%     
==========================================
  Files          54       56       +2     
  Lines        3189     3491     +302     
==========================================
+ Hits         2941     3291     +350     
+ Misses        248      200      -48     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.