Skip to content

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

Report unreconciled discovery groups as inconclusive (#425)

Cinna Davis89aaa7d78ce5
diff --git a/src/dopplergeist/automatic.py b/src/dopplergeist/automatic.py
index c6e73ed..fb5009e 100644
--- a/src/dopplergeist/automatic.py
+++ b/src/dopplergeist/automatic.py
@@ -215,6 +215,9 @@ def analyze(request, output_dir, config=None, progress=lambda *args, **kwargs: N
except MissingData as exc:
state["coverage"]["limitations"].append(str(exc))
return finish("inconclusive", "data_unavailable", str(exc))
+ except UnreconciledDiscovery as exc:
+ state["coverage"]["limitations"].append(str(exc))
+ return finish("inconclusive", "unreconciled_discovery_group", str(exc))
except DataUnavailable as exc:
state["coverage"]["limitations"].append(str(exc))
return finish("failed", "data_unavailable", str(exc))
@@ -248,6 +251,10 @@ class MissingData(ValueError):
pass
+class UnreconciledDiscovery(ValueError):
+ pass
+
+
# Display-only progress bands. Fractions never affect scoring or rankings.
_DISCOVERY_PHASES = {
"tracking_ridges": (0.25, "Discovery: tracking Doppler ridges across the recording."),
@@ -356,12 +363,18 @@ def _latest_emission(hi, duration, events, filters):
def _search(request, recording, events, output, config, search_progress, acquisition_progress=None):
from .data_access import FlightIndex, acquire_inputs
from .geography import profile_for_search, receiver_mask_for_search
- from .matching import prepare_events
+ from .matching import prepare_events, UnreconciledHarmonicGroup
from .terrain import Terrain
from .tiled_search import SearchBudget, search_national
c = float(config.get("sound_speed_mps", 343.0))
max_distance = float(config.get("max_distance_m", 20000.0))
- prepared, measurements = prepare_events(events, c=c, max_distance_m=max_distance)
+ try:
+ prepared, measurements = prepare_events(events, c=c, max_distance_m=max_distance)
+ except UnreconciledHarmonicGroup as exc:
+ raise UnreconciledDiscovery(
+ f"Acoustic proposals could not be reconciled for matching: {exc}. "
+ "The saved discovery diagnostics retain all detected ridges; no location search was performed."
+ ) from exc
window = recording.metadata["time_window"]
lo, hi = (utc_timestamp(window[name]).timestamp() for name in ("start_utc", "end_utc"))
filters = {"association": "subsets", **config.get("filters", {})}
diff --git a/src/dopplergeist/matching.py b/src/dopplergeist/matching.py
index 7edc542..e41add0 100644
--- a/src/dopplergeist/matching.py
+++ b/src/dopplergeist/matching.py
@@ -19,6 +19,11 @@ from scipy.optimize import minimize
from .geometry import Track, _EMISSION_ITERATION_TOLERANCE_S, ecef
+
+class UnreconciledHarmonicGroup(ValueError):
+ """Discovery supplied a group without a usable shared frequency scale."""
+
+
_ridge_backend_choice = os.environ.get("DOPPLERGEIST_RIDGE_BACKEND", "auto")
if _ridge_backend_choice not in {"auto", "python"}:
raise ValueError("DOPPLERGEIST_RIDGE_BACKEND must be 'auto' or 'python'")
@@ -496,11 +501,11 @@ def prepare_events(detected_events, c=343.0, max_distance_m=20000.0):
base = np.column_stack((reference_time, reference_frequency))
shared = _overlap(base, np.column_stack((t, f)))
if shared is None or len(shared[0]) * 0.5 < 0.6 * min(np.ptp(reference_time), np.ptp(t)):
- raise ValueError("Harmonic-group ridges lack sufficient shared observations")
+ raise UnreconciledHarmonicGroup(f"Harmonic group {group_id}: ridges lack sufficient shared observations")
ratio = shared[2] / shared[1]
harmonic = min([1.0, *_HARMONIC_RATIOS], key=lambda value: abs(value - np.median(ratio)))
if np.quantile(np.abs(ratio - harmonic) / harmonic, 0.9) >= 0.008:
- raise ValueError("Harmonic group does not have a consistent supported frequency ratio")
+ raise UnreconciledHarmonicGroup(f"Harmonic group {group_id}: inconsistent supported frequency ratio")
times.extend(t)
frequencies.extend(f / harmonic)
# Equal aggregate weight per ridge prevents duplicated harmonics
diff --git a/tests/test_real_unreconciled_discovery.py b/tests/test_real_unreconciled_discovery.py
new file mode 100644
index 0000000..70a7993
--- /dev/null
+++ b/tests/test_real_unreconciled_discovery.py
@@ -0,0 +1,38 @@
+"""Opt-in regression using an existing real discovery checkpoint, not audio synthesis."""
+import json
+import os
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+from dopplergeist import automatic
+from dopplergeist.matching import UnreconciledHarmonicGroup, prepare_events
+
+
+def test_unreconciled_real_group_is_inconclusive(tmp_path, monkeypatch):
+ checkpoint = os.environ.get("DOPPLERGEIST_UNRECONCILED_CHECKPOINT")
+ if not checkpoint:
+ pytest.skip("Set DOPPLERGEIST_UNRECONCILED_CHECKPOINT to a real saved job")
+ checkpoint = Path(checkpoint)
+ request = json.loads((checkpoint / "request.json").read_text())
+ metadata = json.loads((checkpoint / "intake/recording.json").read_text())
+ discovery = (checkpoint / "discovery/discovery.json").read_bytes()
+ events = json.loads(discovery)["events"]
+ with pytest.raises(UnreconciledHarmonicGroup):
+ prepare_events(events)
+
+ # Exercise the orchestration path using the saved measured ridges. The
+ # bypassed clock gate is a software control; no flight search is performed.
+ recording = SimpleNamespace(metadata=metadata, time_status="ready")
+ monkeypatch.setattr(automatic, "_load_audio_checkpoint", lambda *args: (recording, events))
+ (tmp_path / "discovery").mkdir()
+ (tmp_path / "discovery/discovery.json").write_bytes(discovery)
+ result = automatic.analyze(request, tmp_path, resume=True)
+ assert result["status"] == "inconclusive"
+ assert result["reason_code"] == "unreconciled_discovery_group"
+ assert "no location search was performed" in result["message"]
+ assert result["events"] == events
+ assert result["coverage"]["search_complete"] is False
+ assert (tmp_path / result["artifacts"]["discovery"]).read_bytes() == discovery
+ assert not (tmp_path / "search").exists()