Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)
Python acoustic-geolocationads-baircraft-trackingairplaneaudio-forensicsdoppler-effectdoppler-shiftgeolocationosintsignal-processing
Record exact real-input parity and 30.88 percent lower upload elapsed time
Cinna Davisb9e2887acacf
diff --git a/README.md b/README.mdindex 8edae87..4db28e4 100644--- a/README.md+++ b/README.md@@ -92,13 +92,15 @@ Recording-time evidence matters: audio-relative seconds do not identify which daThe automatic search uses conservative score ceilings before completing every fit: incompatible residuals and an established Top-K cutoff can stop further group fitting at a shared clock. It batches eligible clock fits, reuses exact acoustic calculations in dense tiles, and divides overloaded areas or single-cell clock ranges into checkpointed pieces. [Search screening and real-data timing](docs/DATA_AND_SCALE.md#search) describe the bounds and their measured limits.+The integrated implementation [`66146714`](https://github.com/1337isnot1337/DOPPLERGEIST/commit/66146714c6c22a448a7a54830a82d31034c2be44) completed a fresh bounded HTTP comparison in **78.38 → 54.18 wall seconds**, an observed **1.45×** speedup over baseline `aa3dff6`. This is **30.88% less elapsed time** in one sequential pair on the same CI runner. Both arms used one shared fresh encoding of the complete published recording, with the same flight data, terrain, and budgets. Both returned 16 event records and 23 candidates with `inconclusive / search_incomplete`. Scientific JSON, the logical retention ledger, decoded audio, CSV values, and PNG pixels matched exactly after the declared metadata normalization. All **38 selected real-input tests passed**, with no skips; standard Python 3.11 and 3.14 CI also passed. The [integrated measurement record](benchmarks/results/integrated-http-20261103.json) and [performance report](docs/PERFORMANCE.md#integration-with-main-verified) preserve the source pins, runtime, scope, and comparisons.+The original PR225 comparison used source `5699a657` against baseline `aa3dff6`. Median scoring time at one source-informed receiver point fell from **28.80 to 15.57 CPU seconds**, a **1.85×** speedup. A narrower clock workload improved from **4.39 to 2.21 CPU seconds**, or **1.98×**. Each comparison used three alternating pairs on actual recorded ridges and observed flight trajectories. All 3,905 broad-window associations and 1,055 narrow-window associations matched exactly across 16 independent groups, including diagnostics and retention records.That recorded implementation used a 32 MiB object cache and avoided decoding unrelated finalist trajectories. Separate measurements cover refinement, optional plots, and compact checkpoint encoding. The [performance report](docs/PERFORMANCE.md) gives the methodology, reproduction commands, memory tradeoff, and earlier historical results. Point timings use NumPy 2.5.4, while complete HTTP checks use NumPy 2.3.5. The full CONUS baseline reached its runtime limit, so these measurements do not establish nationwide completion time or independent location accuracy.A separate bounded HTTP pair compared the same two source revisions. It processed the complete original recording in **264.81 → 188.32 wall seconds**, an observed **1.41×** speedup. Both runs passed the full-pipeline checks and returned 23 candidates with `inconclusive / search_incomplete`. Scientific outputs, the retention ledger, decoded audio, and diagnostics matched without numerical tolerance after the declared run-metadata normalization. This is one sequential pair on a shared host, with source-informed regional bounds and a fitted recording clock. The [HTTP measurement record](benchmarks/results/bounded-http-20261103.json) preserves the settings and equality checks.-Main `21262e0` includes PR222's overlapping cache improvements, merged at `0d6a923`, and later checkpoint compatibility changes. The combined implementation selects its serialized cache, whose **4 MiB cap covers digest keys and serialized payloads**. Python object headers and dictionary bookkeeping require additional memory. One instrumented broad-clock pair used **13.08% less CPU** than the 32 MiB object-cache variant, with all 3,905 associations and retention outputs equal. This cache-selection comparison uses otherwise identical main-based code and NumPy 2.3.5. Fresh integrated HTTP validation remains pending. The earlier speedups do not measure an incremental gain over `21262e0`; see [integration scope and cache selection](docs/PERFORMANCE.md#integration-with-main-pending).+Main `b7be433` includes PR222's overlapping cache improvements, merged at `0d6a923`, and checkpoint compatibility changes from `21262e0`. The combined implementation selects its serialized cache, whose **4 MiB cap covers digest keys and serialized payloads**. Python object headers and dictionary bookkeeping require additional memory. One instrumented broad-clock pair used **13.08% less CPU** than the 32 MiB object-cache variant, with all 3,905 associations and retention outputs equal. This cache-selection comparison uses otherwise identical main-based code and NumPy 2.3.5. The fresh [CI verification](https://github.com/1337isnot1337/DOPPLERGEIST/actions/runs/41678922355) passed for frozen integrated source `66146714`. The HTTP comparisons measure the combined changes since `aa3dff6`; an incremental timing comparison against `b7be433` remains unmeasured. See [integration scope and cache selection](docs/PERFORMANCE.md#integration-with-main-verified).Recent search work makes omitted alternatives and failed model evaluations visible. For more detail see [finite-search evidence](docs/FINITE_SEARCH_PRODUCER.md) and [clock-trial accounting](docs/SCORING_ASSESSMENT.md).diff --git a/benchmarks/results/cache-integration-20261103.json b/benchmarks/results/cache-integration-20261103.jsonindex 483cda7..00fb8f4 100644--- a/benchmarks/results/cache-integration-20261103.json+++ b/benchmarks/results/cache-integration-20261103.json@@ -73,7 +73,15 @@"integration_followup": {"main_revision": "b7be4330c37eb9ec2bfca23a55d840bf9bb3acab","note": "The timed pair tested 0d6a923 only. The later legacy-arithmetic API and uncached kernel are preserved unchanged, with strict custom-input bypass and fitter-identity clearing added around the single serialized cache.",- "local_validation": "All changed Python files compile. The uncached fitter AST is identical to public blob 4250d9800747805f376c51206f771c1d8bfcb640. Runtime checks await CI because the reset runner lacks required dependencies.",- "fitting_source_revision": "21262e031388b3a5a8dd75979b2dc851608499b2"+ "local_validation": "All changed Python files compiled before CI. The uncached fitter AST was identical to public blob 4250d9800747805f376c51206f771c1d8bfcb640; local runtime checks were unavailable after the runner reset.",+ "fitting_source_revision": "21262e031388b3a5a8dd75979b2dc851608499b2",+ "frozen_combined_source": "66146714c6c22a448a7a54830a82d31034c2be44",+ "runtime_validation": {+ "ci_run": "https://github.com/1337isnot1337/DOPPLERGEIST/actions/runs/41678922355",+ "recorded_input_tests_passed": 38,+ "skipped_tests": 0,+ "fresh_http_scientific_and_array_parity": true,+ "result_record": "integrated-http-20261103.json"+ }}}diff --git a/benchmarks/results/integrated-http-20261103.json b/benchmarks/results/integrated-http-20261103.jsonnew file mode 100644index 0000000..067d3a4--- /dev/null+++ b/benchmarks/results/integrated-http-20261103.json@@ -0,0 +1,234 @@+{+ "ci": {+ "repository": "1337isnot1337/DOPPLERGEIST",+ "workflow": "Real performance comparison",+ "run_id": 41678922355,+ "job_id": 126066992758,+ "run_url": "https://github.com/1337isnot1337/DOPPLERGEIST/actions/runs/41678922355",+ "job_conclusion": "success",+ "artifact_id": 13250983862,+ "artifact_name": "bounded-http-comparison"+ },+ "real_tests": {+ "selected_real_tests": 38,+ "skipped": []+ },+ "elapsed_reduction_percent": 30.878286063153183,+ "both_parity_checks_passed": true,+ "matched_pair_wall_speedup": 1.4467233855249189,+ "scientific_comparison": {+ "passed": true,+ "scientific_payloads_exact": true,+ "run_kinds": {+ "baseline": "fresh_http",+ "current": "fresh_http"+ },+ "full_pipeline_verified": {+ "baseline": true,+ "current": true+ },+ "checked_artifacts": {+ "json": 17,+ "sqlite": 1,+ "root_json": 3+ },+ "retention_ledgers": {+ "search/retention.sqlite": {+ "baseline_rows": {+ "bounds": 16894,+ "records": 706,+ "run": 1,+ "stages": 6+ },+ "current_rows": {+ "bounds": 16894,+ "records": 706,+ "run": 1,+ "stages": 6+ }+ }+ },+ "outcomes": {+ "baseline": {+ "status": "inconclusive",+ "reason_code": "search_incomplete",+ "candidate_count": 23,+ "event_count": 16+ },+ "current": {+ "status": "inconclusive",+ "reason_code": "search_incomplete",+ "candidate_count": 23,+ "event_count": 16+ }+ },+ "differences": {+ "count": 0,+ "changed_artifact_count": 0,+ "counts_by_artifact": {},+ "numeric_difference_count": 0,+ "maximum_absolute_numeric_difference": 0,+ "examples": [],+ "examples_truncated": false+ }+ },+ "intake_array_comparison": {+ "passed": true,+ "checked": {+ "intake_diagnostics": 1,+ "decoded_pcm": 1,+ "csv": 16,+ "npz": 0,+ "npz_arrays": 0,+ "png": 1+ },+ "manifest_verified_artifacts": {+ "baseline": 19,+ "current": 19+ },+ "difference_count": 0,+ "differences": []+ },+ "http_receipts": {+ "baseline": {+ "verification_passed": true,+ "implementation_unchanged": true,+ "full_pipeline_observed": true,+ "full_pipeline_requirements_met": true,+ "elapsed_s": 78.37902887000001,+ "status": "inconclusive",+ "reason_code": "search_incomplete",+ "event_count": 16,+ "candidate_count": 23,+ "source_sha256": "811a61eea5d21b5a99f008b499d399de9a20e475aaa0fc23cc233c7560605523",+ "source_bytes": 43202924,+ "service": {+ "shutdown_signal": "SIGINT",+ "forced_kill": false,+ "returncode": 0,+ "command": [+ "/opt/hostedtoolcache/Python/3.12.15/x64/bin/python",+ "-m",+ "dopplergeist.cli",+ "serve",+ "--port",+ "0",+ "--jobs",+ "/home/runner/work/DOPPLERGEIST/DOPPLERGEIST/results/http-baseline/jobs",+ "--config",+ "/home/runner/work/DOPPLERGEIST/DOPPLERGEIST/results/http-baseline/operator.json",+ "--max-runtime",+ "900.0"+ ],+ "pid": 3347,+ "port": 45545,+ "shutdown_requested_utc": "2026-11-03T16:57:55.805480Z",+ "stopped_utc": "2026-11-03T16:57:55.820901Z"+ }+ },+ "current": {+ "verification_passed": true,+ "implementation_unchanged": true,+ "full_pipeline_observed": true,+ "full_pipeline_requirements_met": true,+ "elapsed_s": 54.17692812199999,+ "status": "inconclusive",+ "reason_code": "search_incomplete",+ "event_count": 16,+ "candidate_count": 23,+ "source_sha256": "811a61eea5d21b5a99f008b499d399de9a20e475aaa0fc23cc233c7560605523",+ "source_bytes": 43202924,+ "service": {+ "shutdown_signal": "SIGINT",+ "forced_kill": false,+ "returncode": 0,+ "command": [+ "/opt/hostedtoolcache/Python/3.12.15/x64/bin/python",+ "-m",+ "dopplergeist.cli",+ "serve",+ "--port",+ "0",+ "--jobs",+ "/home/runner/work/DOPPLERGEIST/DOPPLERGEIST/results/http-current/jobs",+ "--config",+ "/home/runner/work/DOPPLERGEIST/DOPPLERGEIST/results/http-current/operator.json",+ "--max-runtime",+ "900.0"+ ],+ "pid": 3470,+ "port": 46579,+ "shutdown_requested_utc": "2026-11-03T16:58:50.220522Z",+ "stopped_utc": "2026-11-03T16:58:50.235906Z"+ }+ }+ },+ "context": {+ "scope": "One fresh sequential matched HTTP pair on a new MP3 encoding of the public real WAV. Timings and event counts do not inherit the earlier original-MP3 measurements. Source-informed region/time; not independent location accuracy.",+ "baseline": "aa3dff686c989524daa20c081a816b792d9c8890",+ "current": "66146714c6c22a448a7a54830a82d31034c2be44",+ "python": "3.12.15",+ "packages": {+ "numpy": "2.3.5",+ "scipy": "1.17.0",+ "pandas": "2.2.3",+ "pyarrow": "26.0.1",+ "pyproj": "3.8.0",+ "rasterio": "1.5.2",+ "matplotlib": "3.10.8"+ },+ "ffmpeg": "ffmpeg version 8.0.1-3ubuntu2 Copyright (c) 2000-2025 the FFmpeg developers",+ "encoding": {+ "codec": "libmp3lame",+ "bitrate": "96k",+ "sample_rate_hz": 48000,+ "channels": 1+ },+ "source_sha256": "811a61eea5d21b5a99f008b499d399de9a20e475aaa0fc23cc233c7560605523",+ "source_bytes": 43202924,+ "request": {+ "schema_version": 1,+ "search": {+ "coverage": "conus",+ "bounds_wsen": [+ -73.545,+ 40.865,+ -73.505,+ 40.895+ ]+ },+ "time_window": {+ "start_utc": "2026-09-08T20:17:20Z",+ "end_utc": "2026-09-08T20:17:40Z",+ "source": "user",+ "source_detail": "Source-informed integration replay around the historical fitted recording start and benchmark receiver region; not independently measured recording time or a location-accuracy evaluation."+ }+ },+ "operator": {+ "flight_indexes": [+ "/home/runner/work/DOPPLERGEIST/DOPPLERGEIST/benchmark-http-inputs/reference-region.sqlite"+ ],+ "offline": true,+ "terrain": {+ "rasters": [+ "/home/runner/work/DOPPLERGEIST/DOPPLERGEIST/data/terrain/Copernicus_DSM_COG_10_N40_00_W074_00_DEM.tif"+ ],+ "geoid_raster": "/home/runner/work/DOPPLERGEIST/DOPPLERGEIST/data/terrain/us_nga_egm96_15.tif"+ },+ "search_budget": {+ "spacing_m": 2000,+ "tile_cells": 16,+ "top_k": 20,+ "refine_spacing_m": 500,+ "refine_finalists": 3+ },+ "refine_finalists": 3,+ "search_workers": 1+ }+ },+ "discovery_event_groups": {+ "baseline": 14,+ "current": 14,+ "source": "http-baseline/pipeline-evidence.json and http-current/pipeline-evidence.json: discovery_counts.event_groups"+ }+}diff --git a/docs/PERFORMANCE.md b/docs/PERFORMANCE.mdindex 2087c8b..ca3b24d 100644--- a/docs/PERFORMANCE.md+++ b/docs/PERFORMANCE.md@@ -1,5 +1,9 @@# Measured pipeline performance+The integrated implementation completed the fresh bounded HTTP workflow in **54.176928122 seconds**, compared with **78.379028870 seconds** for baseline `aa3dff6`.+That is an observed **1.44672×** speedup and **30.88%** less elapsed time in one sequential pair on the same CI runner.+The [integrated measurement record](../benchmarks/results/integrated-http-20261103.json) preserves exact output comparisons and the measured source pins.+The original PR225 point and HTTP comparisons use baseline `aa3dff686c989524daa20c081a816b792d9c8890` and the implementation published at `5699a657d57dc4f66b74ef000e20d3ba88f84704`.The integration section separates validation of the combined implementation from these original comparisons.@@ -12,29 +16,75 @@ These are incremental improvements over an already optimized baseline.The earlier **2.69×** scorer result appears in the [historical comparison](#historical-scorer-comparison-2026-11-03).The measurements cover different stages and environments, so their speedups do not combine into a complete-pipeline ratio.-## Integration with main: pending+## Integration with main: verifiedMain commit [`0d6a92377af0f00b84dff9fa7966326d0014c20c`](https://github.com/1337isnot1337/DOPPLERGEIST/commit/0d6a92377af0f00b84dff9fa7966326d0014c20c) merged [PR222](https://github.com/1337isnot1337/DOPPLERGEIST/pull/222).That work independently adds batch-fit reuse and improvements to audio, terrain, trajectory decoding, and retention transactions.Some changes overlap the original PR225 implementation.The [PR222 report](PIPELINE_PERFORMANCE_2026-11-03.md) preserves its separate measurements.-The combined implementation also includes main commit [`21262e031388b3a5a8dd75979b2dc851608499b2`](https://github.com/1337isnot1337/DOPPLERGEIST/commit/21262e031388b3a5a8dd75979b2dc851608499b2) and its checkpoint compatibility changes.--The earlier PR225 timings do not isolate an incremental gain over `0d6a923` or `21262e0`.-A fresh comparison will validate the frozen combined implementation separately.-Results against `aa3dff6` describe the combined changes.-Results against `0d6a923` describe the additional changes after PR222.-Results against `21262e0` describe the additional changes after that later main revision.+The combined implementation includes main commit [`b7be4330c37eb9ec2bfca23a55d840bf9bb3acab`](https://github.com/1337isnot1337/DOPPLERGEIST/commit/b7be4330c37eb9ec2bfca23a55d840bf9bb3acab).+Its fitting source is unchanged from [`21262e031388b3a5a8dd75979b2dc851608499b2`](https://github.com/1337isnot1337/DOPPLERGEIST/commit/21262e031388b3a5a8dd75979b2dc851608499b2), which added checkpoint compatibility changes.-<!-- PERFORMANCE_INTEGRATION_PENDING: fill after source freeze and the fresh HTTP comparison. -->+The earlier PR225 timings do not isolate an incremental gain over `0d6a923`, `21262e0`, or `b7be433`.+The fresh comparison below validates the frozen combined implementation against `aa3dff6`.+It measures the combined changes since that baseline.+An incremental HTTP timing comparison against the integrated main revision `b7be433` remains unmeasured.| Integration item | Status || --- | --- |-| Integrated main source | `21262e031388b3a5a8dd75979b2dc851608499b2` |-| Frozen combined source | Pending |+| Integrated main source | `b7be4330c37eb9ec2bfca23a55d840bf9bb3acab` |+| Frozen combined source | [`66146714c6c22a448a7a54830a82d31034c2be44`](https://github.com/1337isnot1337/DOPPLERGEIST/commit/66146714c6c22a448a7a54830a82d31034c2be44) || Batch-cache selection | Serialized cache from main; 4 MiB digest-key and payload cap |-| Fresh bounded HTTP result and baseline | Pending |-| Exact JSON, SQLite, and array comparison | Pending |+| Fresh CI verification | [Run 41678922355](https://github.com/1337isnot1337/DOPPLERGEIST/actions/runs/41678922355); passed |+| HTTP baseline source | `aa3dff686c989524daa20c081a816b792d9c8890` |+| Fresh bounded HTTP elapsed time | 78.379028870 → 54.176928122 seconds; one sequential pair |+| Exact JSON, SQLite, and array comparison | Passed; zero differences after declared metadata normalization |++### Fresh integrated HTTP comparison++Both arms used the same fresh MP3 encoding of the complete published real recording, restored observed flight data, and terrain.+The baseline ran first, followed by the integrated source on the same CI runner.+The request, operator settings, and search budgets were identical between arms.+Each numerical library used one thread.+The request used bounds `[-73.545, 40.865, -73.505, 40.895]` and recording-start window `2026-09-08T20:17:20Z` through `20:17:40Z`.+It used one search worker, 2 km coarse spacing, 500 m refinement spacing, a top-K limit of 20, and three refinement finalists.++| Measurement | Baseline `aa3dff6` | Integrated `66146714` |+| --- | ---: | ---: |+| HTTP verification elapsed wall time | 78.379028870 s | 54.176928122 s |+| Event records | 16 | 16 |+| Returned candidates | 23 | 23 |+| HTTP and full-pipeline verification | Passed | Passed |+| Decision | `inconclusive / search_incomplete` | `inconclusive / search_incomplete` |++The measured wall-time ratio is **1.4467233855×**, with a **30.87828606%** elapsed-time reduction.+This is one sequential pair, without a repeated-run estimate or a process CPU measurement.+The source-informed regional request and recording clock make this a controlled integration workload.+It does not establish nationwide completion time or independent location accuracy.++The scientific comparison checked **17 job JSON files, three root JSON files, and one logical SQLite ledger**.+The ledger contained 16,894 bounds, 706 records, one run, and six stages in each arm.+It found zero differences after the declared run-identity, path, timing, and other metadata normalization.+The comparison retains exact decoded scientific values, numeric types, and signed zeros, with no numerical tolerance.++A separate comparison checked one intake diagnostic, one decoded PCM artifact, 16 CSV files, and the decoded pixels of one PNG.+All comparisons passed, and the manifest check covered **19 artifacts per arm**.+This workload contained no NPZ artifact.+The [integrated record](../benchmarks/results/integrated-http-20261103.json) preserves the verification results and comparison scope.++The fresh MP3 contains **43,202,924 bytes** and has SHA-256 `811a61eea5d21b5a99f008b499d399de9a20e475aaa0fc23cc233c7560605523`.+It is a new encoding of the published WAV, distinct from the original MP3 used for the earlier PR225 HTTP pair.+Both arms used this same file.+The old and new pairs have different encodings and execution environments, so their absolute times must remain separate.++The fresh runtime used Python 3.12.15, **NumPy 2.3.5**, SciPy 1.17.0, pandas 2.2.3, pyarrow 26.0.1, and pyproj 3.8.0.+It also used rasterio 1.5.2, Matplotlib 3.10.8, and FFmpeg 8.0.1-3ubuntu2.+All **38 selected real-input tests passed in 19.20 seconds**, with no skips.+The standard Python **3.11 and 3.14** CI jobs also passed.+The [successful verification run](https://github.com/1337isnot1337/DOPPLERGEIST/actions/runs/41678922355) records the setup, test gate, sequential HTTP runs, and comparisons.+The [workflow at the measured commit](https://github.com/1337isnot1337/DOPPLERGEIST/blob/66146714c6c22a448a7a54830a82d31034c2be44/.github/workflows/real-performance.yml) preserves the exact replay commands in its fresh-HTTP job.+Reproduction must use the recorded baseline and current source pins, with one shared recording file for both arms.+A new encoding requires a new input hash and fresh results.### Cache selection for the combined implementation@@ -116,7 +166,7 @@ Its additional compact-checkpoint change does not affect this point-scoring measThe [exact-fit measurement record](../benchmarks/results/exact-fit-reuse-20261103.json) contains all twelve final runs, source details, input hashes, and workload counts.The complete HTTP runtime uses **NumPy 2.3.5**.-The seven selected real-input tests and all 50 cache checks also passed in that runtime, with `PYTHONPATH=src` only.+For the recorded 32 MiB revision, the seven selected real-input tests and all 50 cache checks passed in that runtime, with `PYTHONPATH=src` only.Those checks cover scalar parity, prepared measurements, cache mutation, eviction, layout, and nested scope restoration.They provide a separate correctness check, without another point-timing measurement.The two NumPy environments remain separate in the recorded results.@@ -322,7 +372,7 @@ PYTHONPATH=src .venv-point/bin/python scripts/check_real_batch_cache.py \```The separate HTTP-runtime correctness check used the same commands with NumPy 2.3.5 and no additional dependency directory on `PYTHONPATH`.-It passed all seven tests and all 50 cache checks.+For the recorded 32 MiB revision, it passed all seven tests and all 50 cache checks.For the other stage comparisons, use a separate NumPy 2.3.5 environment: