Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)
Python acoustic-geolocationads-baircraft-trackingairplaneaudio-forensicsdoppler-effectdoppler-shiftgeolocationosintsignal-processing
"""Localized CPA checks on unchanged released ADS-B and measured audio inputs.
Receiver hypotheses and clock bounds are the existing development workload,
not microphone-location truth. No aircraft samples or audio are generated.
"""
from copy import deepcopy
import importlib.util
import json
import os
from pathlib import Path
import time
from unittest.mock import patch
import numpy as np
import pandas as pd
import pytest
from scipy.optimize import minimize_scalar
from dopplergeist.geometry import AcousticSupportError, Track, ecef
from dopplergeist.matching import prepare_events
from dopplergeist.search import _PreparedCPATrack, _ordered_cpa_rows, cpa_table_dense
from dopplergeist.tracks import load_tracks
ROOT = Path(__file__).resolve().parents[1]
@pytest.fixture(scope="module")
def real_intervals():
root = Path(os.environ.get("DOPPLERGEIST_REAL_REFERENCE_ROOT", ROOT))
source = root / "data/adsb/2026-09-08/reference-region.parquet"
if not source.is_file():
pytest.skip("restore the real reference archive or set DOPPLERGEIST_REAL_REFERENCE_ROOT")
workload = json.loads((ROOT / "tests/data/real-search-workloads.json").read_text())
tracks, _ = load_tracks(source)
cases = []
for name, case in workload["cases"].items():
points = pd.DataFrame([case["point"]])
observers = ecef(points.lat.to_numpy(), points.lon.to_numpy(), points.elev_m.to_numpy())
admitted, unknown = [], []
for track in tracks:
try:
if track.outside_observer_radius(observers, 20000., 343.):
continue
except AcousticSupportError:
pass
else:
continue
try:
prepared = _PreparedCPATrack(track, 343., 2., motion_observers=observers, max_distance=20000.)
except AcousticSupportError:
unknown.append(track)
else:
admitted.append(prepared)
assert admitted and unknown
cases.append((name, points, observers, admitted, unknown))
return workload, tracks, cases
def rows(prepared, observers):
return _ordered_cpa_rows(prepared.raw_rows(observers, np.arange(len(observers)), 20000.), 2.)
def test_real_local_cpa_preserves_original_lattice_and_every_proposal(real_intervals):
_, tracks, cases = real_intervals
summary = []
for name, _, observers, admitted, unknown in cases:
count = nonempty = multiple = 0
for prepared in admitted:
track = prepared.track
original_time = track.time.copy()
expected_lattice = np.unique(np.r_[np.arange(track.time[0], track.time[-1], 2.), track.time[-1]])
assert np.array_equal(prepared.time, expected_lattice)
actual = rows(prepared, observers)
# Diagnostic arithmetic reference only. The interval proof above,
# not bypassing this validator, supplies physical CPA support.
with patch.object(Track, "validate_motion_support", lambda *args: None):
previous = _PreparedCPATrack(track, 343., 2.)
expected = rows(previous, observers)
assert actual == expected
assert prepared.max_step == previous.max_step
assert np.array_equal(track.time, original_time)
count += len(actual)
nonempty += bool(actual)
multiple += len(prepared.motion_support["emission_intervals_s"]) > 1
assert count > 0 and nonempty > 0 and multiple > 0
summary.append({"case": name, "admitted": len(admitted), "unresolved": len(unknown),
"cpa_rows": count, "nonempty_tracks": nonempty})
# Clean sources keep the same path and do not acquire an exclusion receipt.
clean_checked = 0
for track in tracks:
try:
old = _PreparedCPATrack(track, 343., 2.)
except AcousticSupportError:
continue
expected = rows(old, cases[0][2])
if not expected:
continue
local = _PreparedCPATrack(track, 343., 2., motion_observers=cases[0][2], max_distance=20000.)
assert local.motion_support is None
assert rows(local, cases[0][2]) == expected
clean_checked += 1
if clean_checked == 5:
break
assert clean_checked == 5
print(json.dumps({"exact_sparse_cpa": summary, "clean_controls": clean_checked}))
def test_real_dense_comparison_keeps_existing_sampling_limits_visible(real_intervals):
_, _, cases = real_intervals
summary = []
for name, points, observers, admitted, _ in cases:
count = dense_count = fine_count = 0
largest_time = largest_range = 0.
for prepared in admitted:
actual = rows(prepared, observers)
with patch.object(Track, "validate_motion_support", lambda *args: None):
dense = cpa_table_dense([prepared.track], points, 20000., c=343., step_s=2.)
fine = prepared.track.closest_approaches(observers[0], max_distance=20000., c=343., step=.125)
count += len(actual)
dense_count += len(dense)
fine_count += len(fine)
for row in actual:
assert fine
closest = min(fine, key=lambda value: abs(value["emission_time"]-row[2]))
delta_time = abs(closest["emission_time"]-row[2])
delta_range = abs(closest["distance_m"]-row[4])
# Sparse CPA deliberately projects its two-second lattice.
# Compare with a finer continuous-spline solve without claiming
# that the existing finite proposer finds every narrow minimum.
assert delta_time < 2. * 1.1
assert delta_range < 343. * 2.
largest_time, largest_range = max(largest_time, delta_time), max(largest_range, delta_range)
assert count and dense_count and fine_count
summary.append({"case": name, "sparse_rows": count, "dense_2s_rows": dense_count,
"continuous_0_125s_minima": fine_count, "max_time_difference_s": largest_time,
"max_range_difference_m": largest_range})
print(json.dumps({"independent_dense_comparison": summary}))
def test_real_first_and_final_sample_intervals_remain_intact(real_intervals):
_, tracks, cases = real_intervals
# These complete observed tracks have endpoint-adjacent minima at the
# workload's existing receiver hypotheses. No trajectory is cut or shifted.
controls = (("previous-fit", "a46d03:38", False),
("previous-fit", "a740a3:3", True), ("offset", "ad6cf9:2", False))
for name, identity, final in controls:
observers = next(case[2] for case in cases if case[0] == name)
track = next(track for track in tracks if track.id == identity)
prepared = _PreparedCPATrack(track, 343., 2., motion_observers=observers, max_distance=20000.)
assert prepared.motion_support is None
lo, hi = prepared.time[-2:] if final else prepared.time[:2]
reference = minimize_scalar(lambda dt: np.sum((track.position(lo+dt)-observers[0])**2),
bounds=(0., hi-lo), method="bounded", options={"xatol": .0001})
assert reference.success and 0 < reference.x < hi-lo and reference.fun < 20000.**2
matches = [row for row in rows(prepared, observers) if lo < row[2] < hi]
assert len(matches) == 1
assert abs(matches[0][2]-(lo+reference.x)) < .001
assert abs(matches[0][4]-np.sqrt(reference.fun)) < .01
print(json.dumps({"observed_endpoint_controls": {"first": 2, "final": 1}}))
def test_real_unproven_boundaries_and_query_changes_fail_closed(real_intervals):
_, _, cases = real_intervals
for _, _, observers, admitted, unknown in cases:
for track in unknown:
with pytest.raises(AcousticSupportError) as original:
track.validate_motion_support(343.)
with pytest.raises(AcousticSupportError) as scoped:
_PreparedCPATrack(track, 343., 2., motion_observers=observers, max_distance=20000.)
assert vars(scoped.value) == vars(original.value)
prepared = admitted[0]
proof = prepared.motion_support
# Exercise equality at the outward-rounded hull bound using the same
# observed spline and receiver, not altered aircraft observations.
with pytest.raises(AcousticSupportError):
_PreparedCPATrack(prepared.track, 343., 2., motion_observers=observers,
max_distance=proof["hull_distance_lower_m"])
with pytest.raises(AcousticSupportError):
prepared.raw_rows(observers, np.array([0]), 20001.)
other = cases[1 if cases[0][2] is observers else 0][2]
with pytest.raises(AcousticSupportError):
prepared.raw_rows(other, np.array([0]), 20000.)
# Alternate sound speeds must recheck the native intervals.
changed = _PreparedCPATrack(prepared.track, 333.3, 2., motion_observers=observers, max_distance=20000.)
assert changed.motion_support["sound_speed_mps"] == 333.3
def test_real_acoustic_unknown_arrivals_survive_local_cpa_support(real_intervals):
_, _, cases = real_intervals
for _, _, observers, admitted, _ in cases:
prepared = admitted[0]
first, last = prepared.motion_support["emission_intervals_s"][0]
emission = first + (last-first)/2
receive = emission + np.linalg.norm(prepared.track.position(emission)-observers[0])/343.
with pytest.raises(AcousticSupportError) as supported:
prepared.track._check_motion_support(np.array([receive]), observers[0], 343.)
assert [first, last] in supported.value.emission_intervals_s
with pytest.raises(AcousticSupportError):
prepared.track.acoustic(np.array([receive]), observers[0], 343.)
with pytest.raises(AcousticSupportError):
prepared.track.validate_motion_support(343.)
def test_real_recovered_cpa_supports_acoustic_and_measured_hypotheses(real_intervals):
from dopplergeist.tiled_search import SearchBudget, _score
workload, _, cases = real_intervals
acoustic_counts = []
for name, _, observers, admitted, _ in cases:
count = 0
for prepared in admitted:
proposals = rows(prepared, observers)
if not proposals:
continue
receive = np.asarray([row[3] for row in proposals])
factor, emission, distance = prepared.track.acoustic(receive, observers[0], 343.)
assert np.isfinite([factor, emission, distance]).all()
residual = emission + np.linalg.norm(prepared.track.position(emission)-observers[0], axis=1)/343. - receive
assert np.all(np.abs(residual) <= np.maximum(1e-7, 4*np.abs(np.spacing(receive))))
count += len(proposals)
assert count
acoustic_counts.append({"case": name, "supported_cpa_arrivals": count})
# Use the very track recovered in the limited-clock regression below. The
# ordinary free-clock generator aligns unchanged measured ridges to its two
# actual CPA proposals. This component check supplies no recording-clock or
# location truth; the original limited-clock result remains separate.
_, points, _, admitted, _ = next(case for case in cases if case[0] == "offset")
track = next(prepared.track for prepared in admitted if prepared.track.id == "ad340b:8")
events, measurements = prepare_events(workload["events"])
args = (points, [track], events, measurements, SearchBudget(**workload["budget"]), workload["scoring"], {})
actual, counts = _score(*args)
assert actual and all(np.isfinite(row["score"]) and row["flight_ids"] == [track.id] for row in actual)
assert any(row["core_assessment_complete"] for row in actual)
assert counts["evaluated_trials"] > 0 and counts["unknown_trials"] > 0
assert counts["unclassified_candidate_assessments"]
assert [item["track_id"] for item in counts["interval_supported_cpa_tracks"]] == [track.id]
# Diagnostic comparison changes only the global CPA gate. Original acoustic
# motion/arrival guards still classify every clock trial on both paths.
with patch.object(Track, "validate_motion_support", lambda *args: None):
expected, expected_counts = _score(*args)
expected_counts["interval_supported_cpa_tracks"] = counts["interval_supported_cpa_tracks"]
assert actual == expected and counts == expected_counts
print(json.dumps({"recovered_acoustic_components": {"cpa_arrivals": acoustic_counts,
"free_clock_associations": counts["candidates"], "finite_hypotheses": len(actual),
"evaluated_trials": counts["evaluated_trials"], "rejected_trials": counts["rejected_trials"],
"unknown_trials": counts["unknown_trials"], "exact_diagnostic_parity": True}}))
def verifier():
spec = importlib.util.spec_from_file_location("verify_interval_cpa", ROOT / "scripts/verify_upload_http.py")
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
return module
def test_real_interval_receipts_reject_corrupted_inequalities(real_intervals):
workload, _, cases = real_intervals
check = verifier().valid_interval_cpa_support
events, _ = prepare_events(workload["events"])
config = {"events": events, "scoring": workload["scoring"], "budget": workload["budget"]}
for _, _, _, admitted, _ in cases:
for prepared in admitted:
proof = prepared.motion_support
assert check(proof, config)
for key, value in (("hull_distance_lower_m", proof["max_distance_m"]),
("edge_distance_lower_m", proof["query_radius_m"]),
("query_radius_m", proof["max_distance_m"]),
("sound_speed_mps", 333.3), ("sample_step_s", 3.),
("receiver_point_count", 0), ("emission_intervals_s", [])):
assert not check({**proof, key: value}, config)
damaged = deepcopy(proof)
damaged["observer_box_ecef_m"][0][0] = damaged["observer_box_ecef_m"][1][0] + 1
assert not check(damaged, config)
def test_real_interval_proof_overhead(real_intervals):
_, _, cases = real_intervals
comparisons = []
for name, _, observers, admitted, _ in cases:
original_times, local_times = [], []
for repetition in range(3):
for local in ((False, True) if repetition % 2 == 0 else (True, False)):
began = time.process_time()
for previous in admitted:
track = previous.track
if local:
prepared = _PreparedCPATrack(track, 343., 2., motion_observers=observers, max_distance=20000.)
else:
with patch.object(Track, "validate_motion_support", lambda *args: None):
prepared = _PreparedCPATrack(track, 343., 2.)
rows(prepared, observers)
(local_times if local else original_times).append(time.process_time()-began)
comparisons.append({"case": name, "track_receiver_pairs": len(admitted),
"original_diagnostic_cpu_s": float(np.median(original_times)),
"local_proof_cpu_s": float(np.median(local_times))})
print(json.dumps({"warm_cpa_overhead": comparisons}))
def test_real_measurements_preserve_nonempty_ranking_and_unknown_work(real_intervals, tmp_path):
from dopplergeist.data_access import FlightIndex
from dopplergeist.finite_search import RetentionLedger
from dopplergeist.tiled_search import SearchBudget, _record_support, _score
path = os.environ.get("DOPPLERGEIST_REAL_FLIGHT_INDEX")
if not path or not Path(path).is_file():
pytest.skip("set DOPPLERGEIST_REAL_FLIGHT_INDEX to the restored reference-region index")
workload, _, _ = real_intervals
case = workload["cases"]["offset"]
index = FlightIndex(path)
assert [{key: value[key] for key in ("sha256", "bytes")} for value in index.report["sources"]] == workload["index_identity"]["sources"]
tracks = list(index.query(case["query_bounds"], workload["query_time_s"]))
events, measurements = prepare_events(workload["events"])
points = pd.DataFrame([case["point"]])
args = (points, tracks, events, measurements, SearchBudget(**workload["budget"]),
workload["scoring"], {}, workload["recording_start_window_s"])
ledgers = {name: RetentionLedger(tmp_path / f"{name}.sqlite", "real-motion-interval-cpa",
"matched_group_support_minus_normalized_residual")
for name in ("actual", "baseline", "diagnostic")}
stage = "coarse:observed"
actual, counts = _score(*args, ledger=ledgers["actual"], stage=stage)
selected = {item["track_id"] for item in counts["interval_supported_cpa_tracks"]}
assert actual and selected and counts["unknown_trials"] > 0
with patch.object(Track, "_cpa_interval_exclusion", return_value=None):
old, old_counts = _score(*args, ledger=ledgers["baseline"], stage=stage)
assert actual == old
assert counts["cpa_rows"] > old_counts["cpa_rows"]
assert {item["track_id"] for item in old_counts["unsupported_cpa_tracks"]} == (
{item["track_id"] for item in counts["unsupported_cpa_tracks"]} | selected)
assert counts["unknown_trials"] == old_counts["unknown_trials"]
assert counts["unclassified_candidate_assessments"] == old_counts["unclassified_candidate_assessments"]
original = Track.validate_motion_support
def diagnostic_validate(track, c=343.):
if track.id not in selected:
original(track, c)
with patch.object(Track, "validate_motion_support", diagnostic_validate):
expected, expected_counts = _score(*args, ledger=ledgers["diagnostic"], stage=stage)
assert actual == expected
expected_counts["interval_supported_cpa_tracks"] = counts["interval_supported_cpa_tracks"]
assert counts == expected_counts
persisted = []
for ledger in ledgers.values():
checksum = ledger.checksum(stage)
assert checksum and ledger.stage_valid(stage, checksum)
with ledger.connect() as db:
persisted.append((db.execute("SELECT * FROM records ORDER BY stage,mode_id").fetchall(),
db.execute("SELECT * FROM bounds ORDER BY stage,bound_id").fetchall(),
db.execute("SELECT * FROM stages ORDER BY name").fetchall()))
assert persisted[0] == persisted[1] == persisted[2]
assert persisted[0][0] and persisted[0][1]
summary = dict.fromkeys(("unsupported_cpa_track_evaluations", "unclassified_score_candidates",
"bounded_score_candidates", "unbounded_score_candidates", "evaluated_trials", "rejected_trials",
"unknown_trials", "unreported_trial_envelopes"), 0)
_record_support(tmp_path, stage, counts, summary)
saved = json.loads((tmp_path / "support/coarse-observed.json").read_text())
assert saved["interval_supported_cpa_tracks"] == counts["interval_supported_cpa_tracks"]
assert summary["interval_supported_cpa_track_evaluations"] == len(selected)
config = {"events": events, "scoring": workload["scoring"], "budget": workload["budget"]}
assert all(verifier().valid_interval_cpa_support(item, config) for item in saved["interval_supported_cpa_tracks"])
print(json.dumps({"real_measured_scoring": {"tracks": len(tracks), "retained": len(actual),
"previous_cpa_rows": old_counts["cpa_rows"], "current_cpa_rows": counts["cpa_rows"],
"candidates": counts["candidates"], "remaining_unknown_trials": counts["unknown_trials"],
"interval_supported": len(selected), "retained_ledger_modes": len(persisted[0][0]),
"retained_unknown_bounds": len(persisted[0][1]), "exact_ranking_and_ledger": True}}))