Skip to content

Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)

Add optional CUDA discovery median filter (#426)

Cinna Davis5c50f269a2fb
diff --git a/docs/PERFORMANCE.md b/docs/PERFORMANCE.md
index 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-03
The 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.py
index 4ccc9c5..32d8a89 100644
--- a/src/dopplergeist/advanced_discovery.py
+++ b/src/dopplergeist/advanced_discovery.py
@@ -1,5 +1,6 @@
from collections import defaultdict
import hashlib
+import os
import numpy as np
from scipy.ndimage import median_filter
from scipy import ndimage, signal, optimize
@@ -7,6 +8,21 @@ from scipy.fft import rfft
from scipy.interpolate import PchipInterpolator
from 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.0
diff --git a/src/dopplergeist/automatic.py b/src/dopplergeist/automatic.py
index fb5009e..d35c237 100644
--- a/src/dopplergeist/automatic.py
+++ b/src/dopplergeist/automatic.py
@@ -5,6 +5,7 @@ import hashlib
from importlib.metadata import version
import json
import math
+import os
from pathlib import Path
import 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 identity
def _save_audio_checkpoint(output, request, config):
diff --git a/tests/test_real_cuda_median.py b/tests/test_real_cuda_median.py
new file mode 100644
index 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)