Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)
Python acoustic-geolocationads-baircraft-trackingairplaneaudio-forensicsdoppler-effectdoppler-shiftgeolocationosintsignal-processing
Add optional CUDA discovery median filter (#426)
Cinna Davis5c50f269a2fb
diff --git a/docs/PERFORMANCE.md b/docs/PERFORMANCE.mdindex 85873d8..b8f193c 100644--- a/docs/PERFORMANCE.md+++ b/docs/PERFORMANCE.md@@ -1,5 +1,33 @@# Measured pipeline performance+## Optional CUDA discovery filter++The default acoustic discovery path uses SciPy on the CPU. On a machine with a+compatible NVIDIA GPU and driver, an optional CuPy backend accelerates the+31-bin frequency-axis median filter. Install a CuPy wheel compatible with your+CUDA driver in the same Python environment as DOPPLERGEIST, then select it:++```sh+python -m pip install cupy-cuda12x+DOPPLERGEIST_MEDIAN_BACKEND=cuda dopplergeist discover recording.mp3 --output results/cuda-discovery+```++Set the variable for `analyze` or `serve` in the same way. This example assumes+the CUDA 12 CuPy wheel is compatible with the installed driver; consult the+[CuPy installation guide](https://docs.cupy.dev/en/stable/install.html) for+other configurations. CPU remains the default; set `DOPPLERGEIST_MEDIAN_BACKEND=cpu`+to select it explicitly. CUDA errors are reported instead of silently switching+backends. A CUDA audio checkpoint records the selected backend and CuPy version,+so resume requires the same selection and version.++On one 28-second real recording, a GTX 1080 Ti and its host produced identical+discovery JSON and 21 ridges on both backends. A single complete discovery run+took 5.01 s on CPU and 3.59 s with CUDA. For one 4096 × 221 float32 spectrogram,+the filter output was exactly equal and median warm filter time over three runs+was 350 ms on CPU versus 1.9 ms on CUDA including transfers. These measurements+are specific to that recording and machine; they do not establish a search or+localization speedup, GPU parity on every device, or localization accuracy.+## Integrated pipeline acceleration, 2026-11-03The integrated version reduces dense-search CPU time by **49.66%** and complete regional-upload elapsed time by **15.51%**.diff --git a/src/dopplergeist/advanced_discovery.py b/src/dopplergeist/advanced_discovery.pyindex 4ccc9c5..32d8a89 100644--- a/src/dopplergeist/advanced_discovery.py+++ b/src/dopplergeist/advanced_discovery.py@@ -1,5 +1,6 @@from collections import defaultdictimport hashlib+import osimport numpy as npfrom scipy.ndimage import median_filterfrom scipy import ndimage, signal, optimize@@ -7,6 +8,21 @@ from scipy.fft import rfftfrom scipy.interpolate import PchipInterpolatorfrom dopplergeist import discovery as baseline++def local_median(image):+ """Frequency-axis background filter, with an explicitly selected CUDA backend."""+ backend = os.environ.get('DOPPLERGEIST_MEDIAN_BACKEND', 'cpu')+ if backend == 'cpu':+ return median_filter(image, size=(31, 1), mode='nearest')+ if backend != 'cuda':+ raise ValueError('DOPPLERGEIST_MEDIAN_BACKEND must be cpu or cuda')+ try:+ import cupy as cp+ from cupyx.scipy.ndimage import median_filter as cuda_median_filter+ except ImportError as exc:+ raise RuntimeError('CUDA median backend requires a compatible CuPy installation') from exc+ return cp.asnumpy(cuda_median_filter(cp.asarray(image), size=(31, 1), mode='nearest'))+def canonical(members, event_id, basis):return dict(event_id=event_id, start_s=min((e['start_s'] for e in members)), end_s=max((e['end_s'] for e in members)), band_hz=[min((e['band_hz'][0] for e in members)), max((e['band_hz'][1] for e in members))], raw_event_ids=sorted((e['event_id'] for e in members)), grouping_basis=basis, source_identity='unknown', physical_source_multiplicity='unresolved')@@ -227,7 +243,7 @@ def dp_front(recording, variant):f = f[keep]db = 10 * np.log10(np.maximum(p[keep], 1e-30))t = t + start- local = db - median_filter(db, size=(31, 1), mode='nearest')+ local = db - local_median(db)for band, (low, high) in enumerate([(20.0, 1600.0), (1600.0, 8000.0)]):dense = variant.startswith(('ridge_dp_dense', 'ridge_dp_accel'))high_window = 0.5 if 'broad' in variant else 1.0diff --git a/src/dopplergeist/automatic.py b/src/dopplergeist/automatic.pyindex fb5009e..d35c237 100644--- a/src/dopplergeist/automatic.py+++ b/src/dopplergeist/automatic.py@@ -5,6 +5,7 @@ import hashlibfrom importlib.metadata import versionimport jsonimport math+import osfrom pathlib import Pathimport time@@ -20,10 +21,17 @@ def _digest(path):def _audio_identity(request, config):modules = ("intake.py", "discovery.py", "advanced_discovery.py", "audio.py", "contracts.py")- return {"request": request, "source_sha256": _digest(request["audio_path"]),+ identity = {"request": request, "source_sha256": _digest(request["audio_path"]),"discovery_settings": config.get("discovery", {}),"modules": {name: _digest(Path(__file__).parent / name) for name in modules},"packages": {name: version(name) for name in ("numpy", "scipy", "numba")}}+ backend = os.environ.get("DOPPLERGEIST_MEDIAN_BACKEND", "cpu")+ if backend != "cpu":+ identity["median_backend"] = backend+ if backend == "cuda":+ from cupy import __version__ as cupy_version+ identity["cupy_version"] = cupy_version+ return identitydef _save_audio_checkpoint(output, request, config):diff --git a/tests/test_real_cuda_median.py b/tests/test_real_cuda_median.pynew file mode 100644index 0000000..dc9a1b6--- /dev/null+++ b/tests/test_real_cuda_median.py@@ -0,0 +1,21 @@+"""Optional CPU/CUDA parity check on an existing recorded-audio spectrogram."""+import os++import numpy as np+import pytest+from scipy.ndimage import median_filter++from dopplergeist.advanced_discovery import local_median+++def test_recorded_spectrogram_median_parity(monkeypatch):+ path = os.environ.get("DOPPLERGEIST_REAL_SPECTROGRAM")+ if not path:+ pytest.skip("Set DOPPLERGEIST_REAL_SPECTROGRAM to a recorded-audio spectrogram")+ pytest.importorskip("cupy")+ image = np.load(path, allow_pickle=False)+ expected = median_filter(image, size=(31, 1), mode="nearest")+ monkeypatch.setenv("DOPPLERGEIST_MEDIAN_BACKEND", "cpu")+ np.testing.assert_array_equal(local_median(image), expected)+ monkeypatch.setenv("DOPPLERGEIST_MEDIAN_BACKEND", "cuda")+ np.testing.assert_array_equal(local_median(image), expected)