Skip to content

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

Exclude unsupported tracks outside the bounded event clock (#297)

Cinna Davis0fcdcf6fdc25
diff --git a/docs/MODEL_SUPPORT_COVERAGE.md b/docs/MODEL_SUPPORT_COVERAGE.md
index 01800e9..dccdd2a 100644
--- a/docs/MODEL_SUPPORT_COVERAGE.md
+++ b/docs/MODEL_SUPPORT_COVERAGE.md
@@ -9,6 +9,20 @@ evaluated, rejected, or covered by a validated score bound. Unsupported CPA
trajectories, unreported clock trials, and unbounded alternatives keep the search
partial. A completed tile does not establish complete evidence.
+For robust-ridge subset association with a bounded recording-start window and no
+silence filter, an unsupported trajectory that starts strictly after every
+possible event CPA arrival cannot participate in an association. Those tracks
+are reported separately as `clock_excluded_unsupported_tracks` in stage
+diagnostics and counted in `clock_excluded_unsupported_track_evaluations`; their
+original motion failures and conservative clock bounds remain inspectable. The
+bound includes the configured clock sweep, CPA and association tolerances, and
+outward floating-point rounding. Overlap, missing or invalid clock information,
+fixed-clock mode, other scoring modes, and silence filtering retain the usual
+unsupported/partial behavior. This does not repair the source trajectory or
+establish geographic coverage. The HTTP evidence verifier checks the recorded
+inequality against the search clock and stage totals; it does not independently
+reload the original aircraft index to verify the recorded first emission time.
+
The additive `model_support` report contains these integer work counts:
- `unsupported_cpa_track_evaluations`: trajectory/stage CPA failures, including
diff --git a/scripts/verify_upload_http.py b/scripts/verify_upload_http.py
index 8287a2e..0f7ad1f 100644
--- a/scripts/verify_upload_http.py
+++ b/scripts/verify_upload_http.py
@@ -322,6 +322,48 @@ def model_assessment_accounted_for(search):
and finite["bounded_unknown_envelopes"] == support["bounded_score_candidates"])
+def valid_clock_exclusion(item, configuration):
+ """Check a recorded time bound, without reloading the source trajectory."""
+ from decimal import Decimal, localcontext
+
+ def number(value):
+ if type(value) not in (int, float) or not math.isfinite(value):
+ raise ValueError("invalid bound number")
+ return Decimal.from_float(float(value))
+
+ try:
+ scoring, filters = configuration["scoring"], configuration["filters"]
+ window = scoring["recording_start_window_s"]
+ if (not isinstance(item, dict) or not isinstance(item["track_id"], str) or not item["track_id"]
+ or not isinstance(item["reason"], str) or not item["reason"]
+ or not isinstance(item["reported_intervals"], dict)
+ or item["reported_intervals"].get("reason") != item["reason"]
+ or scoring.get("mode") != "robust_ridge" or scoring.get("time_origin") is not None
+ or filters.get("association", "subsets") != "subsets" or filters.get("silence")
+ or not isinstance(window, list) or len(window) != 2):
+ return False
+ with localcontext() as ctx:
+ # Enough digits to add arbitrary finite binary64 inputs without
+ # losing a very small operand next to a very large one.
+ ctx.prec = 1100
+ lo, hi = map(number, window)
+ sweep, offset = number(scoring.get("time_sweep_s", 5.0)), number(filters.get("offset_tolerance_s", 5.0))
+ c = number(scoring.get("c", 343.0))
+ if lo > hi or sweep < 0 or offset < 0 or c <= 0:
+ return False
+ bounds = []
+ for event in configuration["events"]:
+ event_tolerance = number(event.get("quality", {}).get("cpa_tolerance_s", 0))
+ if event_tolerance < 0:
+ return False
+ bounds.append(hi + sweep + offset / 2 + event_tolerance + number(event["cpa_receive_s"]))
+ saved = number(item["latest_event_receive_s"])
+ first = number(item["earliest_emission_s"])
+ return bool(bounds and saved >= max(bounds) and first > saved)
+ except (KeyError, TypeError, ValueError, OverflowError):
+ return False
+
+
def inspect_finite_search(artifact, read, search, configuration, refinement):
"""Audit recorded retention read-only; physical trials are not recomputed."""
import sqlite3
@@ -362,7 +404,7 @@ def inspect_finite_search(artifact, read, search, configuration, refinement):
totals, names, originals = {}, {}, {}
evaluated = discarded = coarse_unknown = 0
coarse_trials = dict(evaluated_trials=0, rejected_trials=0, unknown_trials=0, unreported_trial_envelopes=0)
- bounded_count = bounded_rejections = 0
+ bounded_count = bounded_rejections = clock_excluded = 0
bound = unknown_bound = None
bound_fields = ("bounded_unknown_envelopes", "bounded_unknown_rejections", "best_unknown_score_upper_bound")
bound_contract = any(name in finite for name in bound_fields) or "model_assessment_complete" in search
@@ -512,7 +554,7 @@ def inspect_finite_search(artifact, read, search, configuration, refinement):
coarse_unknown += unknown
if bound_contract and phase in {"coarse", "fine"}:
support_path = path.parent / "support" / (name.replace(":", "-") + ".json")
- details, unsupported = [], []
+ details, unsupported, excluded = [], [], []
if support_path.exists():
support_record = read("search/support/" + support_path.name)
details, unsupported = (support_record.get(key) for key in
@@ -520,6 +562,9 @@ def inspect_finite_search(artifact, read, search, configuration, refinement):
require(support_record.get("stage") == name and isinstance(details, list)
and all(isinstance(detail, dict) for detail in details) and isinstance(unsupported, list),
"Finite support artifact has invalid stage or candidate evidence")
+ excluded = support_record.get("clock_excluded_unsupported_tracks", [])
+ require(isinstance(excluded, list) and all(valid_clock_exclusion(item, configuration) for item in excluded),
+ "Invalid unsupported-track clock exclusion evidence")
certificates = {"bound-" + digest(detail): detail for detail in details
if bounded_finite_clock_assessment(detail, finite["max_event_groups"])}
require(stage_bounds == certificates, "Finite bound ledger omits or invents a recorded candidate assessment")
@@ -527,11 +572,13 @@ def inspect_finite_search(artifact, read, search, configuration, refinement):
counts = payload.get("counts", {})
require(counts.get("unclassified_candidate_assessments", []) == details
and counts.get("unsupported_cpa_tracks", []) == unsupported
+ and counts.get("clock_excluded_unsupported_tracks", []) == excluded
and counts.get("unclassified_score_candidates", 0) == len(details)
and counts.get("bounded_score_candidates", 0) == len(stage_bounds)
and counts.get("unbounded_score_candidates", 0) == len(details)-len(stage_bounds),
"Coarse support counts differ from persisted candidate assessments")
support_totals["unsupported_cpa_track_evaluations"] += len(unsupported)
+ clock_excluded += len(excluded)
support_totals["unclassified_score_candidates"] += len(details)
support_totals["bounded_score_candidates"] += len(stage_bounds)
support_totals["unbounded_score_candidates"] += len(details)-len(stage_bounds)
@@ -584,6 +631,8 @@ def inspect_finite_search(artifact, read, search, configuration, refinement):
for key, value in support_totals.items()) and unknown == support_totals["unclassified_score_candidates"]
and finite.get("unsupported_cpa_track_evaluations") == support_totals["unsupported_cpa_track_evaluations"],
"Finite model-support totals differ from persisted candidate assessments")
+ require(support.get("clock_excluded_unsupported_track_evaluations", 0) == clock_excluded,
+ "Clock-excluded unsupported-track totals differ from stage evidence")
require(all(type(support.get(key)) is int and support[key] >= value
for key, value in coarse_trials.items()),
"Search model-support totals omit recorded coarse clock trials")
diff --git a/src/dopplergeist/tiled_search.py b/src/dopplergeist/tiled_search.py
index 6441f5c..de3eb23 100644
--- a/src/dopplergeist/tiled_search.py
+++ b/src/dopplergeist/tiled_search.py
@@ -356,6 +356,42 @@ def _association_clock_window(start_window, sweep_s):
return center, tolerance
+def _latest_event_receive_time(events, parameters, filters, start_window):
+ """Conservatively bound matchable CPA arrivals for the shared-clock path.
+
+ None means that this optional exclusion is not justified. Silence filters
+ can use passages that match no event, so they cannot use this bound.
+ """
+ if (not start_window or parameters.get("mode") != "robust_ridge"
+ or parameters.get("time_origin") is not None
+ or filters.get("association", "subsets") != "subsets" or filters.get("silence")):
+ return None
+ try:
+ c = float(parameters.get("c", 343.0))
+ offset = float(filters.get("offset_tolerance_s", 5.0))
+ if not math.isfinite(c) or c <= 0 or not math.isfinite(offset) or offset < 0:
+ return None
+ center, clock_tolerance = _association_clock_window(start_window, parameters.get("time_sweep_s", 5.0))
+ upper = math.nextafter(center + clock_tolerance, math.inf)
+ latest = []
+ for event in events:
+ cpa = float(event["cpa_receive_s"])
+ event_tolerance = float(event.get("quality", {}).get("cpa_tolerance_s", 0))
+ if not math.isfinite(cpa) or not math.isfinite(event_tolerance) or event_tolerance < 0:
+ return None
+ margin = math.nextafter(event_tolerance + offset / 2, math.inf)
+ bound = math.nextafter(math.nextafter(upper + margin, math.inf) + cpa, math.inf)
+ # Association calculates receive_time - cpa before comparing clock
+ # intervals. Extra ULPs cover that inverse floating-point rounding.
+ bound += 4 * max(math.ulp(bound), math.ulp(center), math.ulp(cpa))
+ if not math.isfinite(bound):
+ return None
+ latest.append(bound)
+ return max(latest) if latest else None
+ except (KeyError, TypeError, ValueError, OverflowError):
+ return None
+
+
def _tile_anchor_window(tile_id, start_window, parameters, filters, events):
"""Recover a deterministic half-open anchor partition from its tile ID."""
path = [part for part in tile_id.split("~")[1:] if part.startswith("t")]
@@ -488,7 +524,8 @@ def _score(points, tracks, events, measurements, budget, parameters, filters, st
observers = ecef(points.lat.to_numpy(), points.lon.to_numpy(), points.elev_m.to_numpy())
point_ids = points.point_id.to_numpy(dtype=int)
cpa_batches, count = [], 0
- unsupported = []
+ unsupported, clock_excluded = [], []
+ latest_receive = _latest_event_receive_time(events, parameters, filters, start_window)
# Bound materialized CPA rows before pairing; one track at a time keeps the
# national traffic count out of the CPA tensor/list allocation.
for track in tracks:
@@ -514,6 +551,12 @@ def _score(points, tracks, events, measurements, budget, parameters, filters, st
track_batches.append(np.array(rows, dtype=_CPA_DTYPE))
del rows
except AcousticSupportError as error:
+ if latest_receive is not None and track.time[0] > latest_receive:
+ clock_excluded.append({"track_id": track.id, "reason": error.reason,
+ "reported_intervals": _support_error(error),
+ "earliest_emission_s": float(track.time[0]),
+ "latest_event_receive_s": latest_receive})
+ continue
# The typed failure does not identify an exact bad interval. Keep
# the entire track/stage as explicitly unassessed, and retain rows
# from other tracks. Never repair or clip the source payload here.
@@ -531,7 +574,8 @@ def _score(points, tracks, events, measurements, budget, parameters, filters, st
if not cpa_batches:
if ledger is not None:
ledger.record(stage, [], [], 0)
- return [], {"cpa_rows": 0, "candidates": 0, "unsupported_cpa_tracks": unsupported}
+ return [], {"cpa_rows": 0, "candidates": 0, "unsupported_cpa_tracks": unsupported,
+ "clock_excluded_unsupported_tracks": clock_excluded}
if parameters.get("mode") == "robust_ridge":
from .matching import _prepare_score_inputs
events, measurements = _prepare_score_inputs(events, measurements)
@@ -724,11 +768,16 @@ def _score(points, tracks, events, measurements, budget, parameters, filters, st
retention_score_pruned_candidates=retention_pruned,
bounded_score_candidates=len(bounds), unbounded_score_candidates=unclassified-len(bounds),
evaluated_rejections=rejected, unsupported_cpa_tracks=unsupported,
+ clock_excluded_unsupported_tracks=clock_excluded,
unclassified_candidate_assessments=unclassified_assessments, **trial_counts)
def _record_support(output, stage, counts, summary):
summary["unsupported_cpa_track_evaluations"] += len(counts.get("unsupported_cpa_tracks", []))
+ clock_excluded = len(counts.get("clock_excluded_unsupported_tracks", []))
+ if clock_excluded:
+ summary["clock_excluded_unsupported_track_evaluations"] = (
+ summary.get("clock_excluded_unsupported_track_evaluations", 0) + clock_excluded)
for key in ("unclassified_score_candidates", "bounded_score_candidates", "unbounded_score_candidates",
"evaluated_trials", "rejected_trials", "unknown_trials", "unreported_trial_envelopes"):
summary[key] += counts.get(key, 0)
@@ -743,10 +792,12 @@ def _record_support(output, stage, counts, summary):
(output / "support").mkdir(exist_ok=True)
write_json(output / "support" / (stage.replace(":", "-") + "-event-pair-screen.json"),
{"stage": stage, **pair_screen})
- if counts.get("unsupported_cpa_tracks") or counts.get("unclassified_candidate_assessments"):
+ if (counts.get("unsupported_cpa_tracks") or counts.get("unclassified_candidate_assessments")
+ or counts.get("clock_excluded_unsupported_tracks")):
(output / "support").mkdir(exist_ok=True)
write_json(output / "support" / (stage.replace(":", "-") + ".json"),
{"stage": stage, "unsupported_cpa_tracks": counts.get("unsupported_cpa_tracks", []),
+ "clock_excluded_unsupported_tracks": counts.get("clock_excluded_unsupported_tracks", []),
"unclassified_candidate_assessments": counts.get("unclassified_candidate_assessments", [])},
compact=True)
diff --git a/tests/test_real_unsupported_clock.py b/tests/test_real_unsupported_clock.py
new file mode 100644
index 0000000..63f8e8f
--- /dev/null
+++ b/tests/test_real_unsupported_clock.py
@@ -0,0 +1,140 @@
+"""Optional regression using an archived real audio/aircraft regional run."""
+import importlib.util
+import json
+import os
+from pathlib import Path
+
+import pytest
+
+from dopplergeist.data_access import CachedTerrain, FlightIndex
+from dopplergeist.matching import prepare_events
+from dopplergeist.tiled_search import (SearchBudget, _expanded_bounds, _latest_event_receive_time,
+ _score, _tracks_for_points, tile_points)
+
+
+def test_real_clock_excludes_late_unsupported_trajectories(tmp_path, monkeypatch):
+ value = os.environ.get("DOPPLERGEIST_REAL_CLOCK_JOB")
+ index_path = os.environ.get("DOPPLERGEIST_REAL_CLOCK_INDEX")
+ terrain_path = os.environ.get("DOPPLERGEIST_REAL_CLOCK_TERRAIN")
+ if not all((value, index_path, terrain_path)):
+ pytest.skip("set the archived real job, aircraft index and terrain cache paths")
+ job = Path(value)
+ config = json.loads((job / "search/manifest.json").read_text())["configuration"]
+ raw = json.loads((job / "discovery/discovery.json").read_text())["events"]
+ params = dict(config["scoring"])
+ window = params.pop("recording_start_window_s")
+ filters = config["filters"]
+ radius = max(event["slant_range_m"][1] for event in config["events"])
+ events, measurements = prepare_events(raw, c=params["c"], max_distance_m=radius)
+ assert events == config["events"]
+ budget = SearchBudget(**config["budget"])
+ terrain = CachedTerrain(terrain_path, offline=True)
+ index = FlightIndex(index_path)
+ spec = importlib.util.spec_from_file_location("verify_upload_http",
+ Path(__file__).parents[1] / "scripts/verify_upload_http.py")
+ verifier = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(verifier)
+ support_files = sorted((job / "search/support").glob("coarse-*.json"))
+ tested = 0
+ for support_path in support_files:
+ support = json.loads(support_path.read_text())
+ failures = support.get("unsupported_cpa_tracks", [])
+ if not failures:
+ continue
+ tile_id = support_path.stem.removeprefix("coarse-")
+ payload = json.loads((job / "search" / f"tile-{tile_id}.json").read_text())["payload"]
+ points = tile_points(payload["cells"], budget.spacing_m, config["bounds"], terrain, config["crs"])
+ tracks = list(index.lookup([item["track_id"] for item in failures]))
+ assert tracks
+ latest = _latest_event_receive_time(events, params, filters, window)
+ assert latest is not None and all(track.time[0] > latest for track in tracks)
+ rows, counts = _score(points, tracks, events, measurements, budget, params, filters, window)
+ assert rows == [] and not counts["unsupported_cpa_tracks"]
+ assert {item["track_id"] for item in counts["clock_excluded_unsupported_tracks"]} == {t.id for t in tracks}
+ for item in counts["clock_excluded_unsupported_tracks"]:
+ assert verifier.valid_clock_exclusion(item, config)
+ assert not verifier.valid_clock_exclusion({**item, "earliest_emission_s": item["latest_event_receive_s"]}, config)
+ assert not verifier.valid_clock_exclusion({**item, "latest_event_receive_s": item["latest_event_receive_s"] - 1}, config)
+ assert not verifier.valid_clock_exclusion(item, {**config, "filters": {**filters, "silence": {"edge_margin_s": 60}}})
+ # A clock that reaches the same unmodified flight must not suppress it.
+ shift = float(tracks[0].time[0] - latest + 1.0)
+ overlapping = [window[0] + shift, window[1] + shift]
+ _, unknown = _score(points, tracks, events, measurements, budget, params, filters, overlapping)
+ assert any(item["track_id"] == tracks[0].id for item in unknown["unsupported_cpa_tracks"])
+ assert _latest_event_receive_time(events, params, {**filters, "silence": {"edge_margin_s": 60}}, window) is None
+ assert _latest_event_receive_time(events, params, filters, None) is None
+ if not tested:
+ # Probe the actual track against clock windows on both sides of its
+ # first recorded emission, including the inclusive boundary.
+ boundary_shift = float(tracks[0].time[0] - latest)
+ before = [value + boundary_shift - 0.01 for value in window]
+ after = [value + boundary_shift + 0.01 for value in window]
+ assert tracks[0].time[0] > _latest_event_receive_time(events, params, filters, before)
+ assert tracks[0].time[0] <= _latest_event_receive_time(events, params, filters, after)
+ _, before_counts = _score(points, tracks, events, measurements, budget, params, filters, before)
+ _, after_counts = _score(points, tracks, events, measurements, budget, params, filters, after)
+ assert any(item["track_id"] == tracks[0].id for item in before_counts["clock_excluded_unsupported_tracks"])
+ assert any(item["track_id"] == tracks[0].id for item in after_counts["unsupported_cpa_tracks"])
+ tested += len(tracks)
+ assert tested == 12
+
+ # Compare full-tile scoring on original tracks and measurements with the
+ # old conservative exclusion; every actual retained candidate must agree.
+ supported_stages = [json.loads(path.read_text()) for path in support_files]
+ supported_stages = [value for value in supported_stages if value.get("unsupported_cpa_tracks")]
+ def ranked_count(value):
+ tile_name = value["stage"].removeprefix("coarse:")
+ return len(json.loads((job / "search" / f"tile-{tile_name}.json").read_text())["payload"]["ranked"])
+ support = max(supported_stages, key=ranked_count)
+ assert ranked_count(support) > 0
+ tile_id = support["stage"].removeprefix("coarse:")
+ cells = json.loads((job / "search" / f"tile-{tile_id}.json").read_text())["payload"]["cells"]
+ points = tile_points(cells, budget.spacing_m, config["bounds"], terrain, config["crs"])
+ tracks, points = _tracks_for_points([index], _expanded_bounds(cells, budget.spacing_m, radius, config["crs"]),
+ config["time_range_s"], budget, points, terrain, radius, params["c"])
+ import dopplergeist.tiled_search as tiled
+ with monkeypatch.context() as patch:
+ patch.setattr(tiled, "_latest_event_receive_time", lambda *args: None)
+ previous_rows, previous_counts = _score(points, tracks, events, measurements, budget, params, filters, window)
+ rows, counts = _score(points, tracks, events, measurements, budget, params, filters, window)
+ assert rows and counts["candidates"] > 0
+ assert rows == previous_rows
+ assert counts["cpa_rows"] == previous_counts["cpa_rows"]
+ assert counts["candidates"] == previous_counts["candidates"]
+ assert counts["unclassified_candidate_assessments"] == previous_counts["unclassified_candidate_assessments"]
+ assert len(previous_counts["unsupported_cpa_tracks"]) == len(counts["clock_excluded_unsupported_tracks"]) > 0
+ assert not counts["unsupported_cpa_tracks"]
+
+
+def test_real_clock_exclusion_evidence_rejects_tampering():
+ value = os.environ.get("DOPPLERGEIST_REAL_CLOCK_REPLAY_JOB")
+ if not value:
+ pytest.skip("set the completed real clock-exclusion upload job path")
+ job = Path(value)
+ spec = importlib.util.spec_from_file_location("verify_upload_clock_evidence",
+ Path(__file__).parents[1] / "scripts/verify_upload_http.py")
+ verifier = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(verifier)
+
+ def read(name):
+ return json.loads((job / name).read_text())
+
+ artifact = lambda name: job / name
+ search = read("search/search-report.json")
+ config = read("search/manifest.json")["configuration"]
+ refinement = read("refined-candidates.json")
+ assert search["model_support"]["clock_excluded_unsupported_track_evaluations"] > 0
+ report = verifier.inspect_finite_search(artifact, read, search, config, refinement)
+ assert report["complete"] is True
+ def read_with_damaged_bound(name):
+ data = read(name)
+ if name.startswith("search/support/") and data.get("clock_excluded_unsupported_tracks"):
+ item = data["clock_excluded_unsupported_tracks"][0]
+ item["earliest_emission_s"] = item["latest_event_receive_s"]
+ return data
+ with pytest.raises(ValueError, match="Invalid unsupported-track clock exclusion evidence"):
+ verifier.inspect_finite_search(artifact, read_with_damaged_bound, search, config, refinement)
+ changed = {**search, "model_support": {**search["model_support"],
+ "clock_excluded_unsupported_track_evaluations": search["model_support"]["clock_excluded_unsupported_track_evaluations"] + 1}}
+ with pytest.raises(ValueError, match="Clock-excluded unsupported-track totals"):
+ verifier.inspect_finite_search(artifact, read, changed, config, refinement)