Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)
Python acoustic-geolocationads-baircraft-trackingairplaneaudio-forensicsdoppler-effectdoppler-shiftgeolocationosintsignal-processing
Integrate current association traversal and document measured scoring gains
Cinna Davisd6a0c860bd5a
diff --cc .github/workflows/real-performance.ymlindex f7863d7,0000000..2794633mode 100644,000000..100644--- a/.github/workflows/real-performance.yml+++ b/.github/workflows/real-performance.yml@@@ -1,71 -1,0 +1,78 @@@+name: Real performance comparison+on:+ workflow_dispatch:+ inputs:+ baseline:+ description: Scalar-consistent baseline commit+ default: d7cc1dd2e8089768253492b3269dfae97b3ad1a4+ required: true+ push:+ branches: [perf/measured-hotpath-20261103]- paths: [.github/workflows/real-performance.yml]++ paths:++ - .github/workflows/real-performance.yml++ - src/dopplergeist/geometry.py++ - src/dopplergeist/matching.py++ - src/dopplergeist/batch_ridge.py++ - src/dopplergeist/search.py++ - scripts/benchmark_prepared_measurements.py++ - tests/test_real_*.py+permissions:+ contents: read+jobs:+ compare:+ runs-on: ubuntu-latest+ timeout-minutes: 20+ env:+ OPENBLAS_NUM_THREADS: '1'+ OMP_NUM_THREADS: '1'+ MKL_NUM_THREADS: '1'+ PYTHONPATH: src+ BASELINE_REF: ${{ inputs.baseline || 'd7cc1dd2e8089768253492b3269dfae97b3ad1a4' }}+ steps:+ - uses: actions/checkout@v4+ with:+ fetch-depth: 0+ - uses: actions/setup-python@v5+ with:+ python-version: '3.12'+ - name: Install runtime+ run: python -m pip install '.[test]'+ - name: Restore public recorded observations+ env:+ GH_TOKEN: ${{ github.token }}+ run: python scripts/restore_artifacts.py --bundle data-adsb-derived --bundle data-terrain+ - name: Prepare index and baseline+ run: |+ python scripts/prepare_reference_upload.py --data-root data --output benchmark-inputs+ baseline_commit=$(git rev-parse --verify --end-of-options "${BASELINE_REF}^{commit}")+ git worktree add --detach "$RUNNER_TEMP/baseline" "$baseline_commit"+ - name: Freeze real workloads+ run: |+ for width in 120 10; do+ python scripts/benchmark_prepared_measurements.py prepare --discovery evidence/audio/w1-sensitivity-20261102/reference/discovery.json --index benchmark-inputs/reference-region.sqlite --clock-half-width-s "$width" --output "benchmark-inputs/point-$width.json"+ done+ - name: Real-input regression tests+ env:+ DOPPLERGEIST_REAL_CPA_FIXTURE: benchmark-inputs/point-120.json+ run: python -m pytest -q tests/test_real_prepared_measurements.py tests/test_real_geometry_kinematics.py tests/test_real_batch_scalar_parity.py+ - name: Compare complete payloads and timings+ run: |+ for width in 10 120; do+ python scripts/benchmark_prepared_measurements.py compare --fixture "benchmark-inputs/point-$width.json" --baseline-source "$RUNNER_TEMP/baseline/src" --current-source src --repeats 2 --timeout-s 600 --output "results/performance-$width"+ done+ - uses: actions/upload-artifact@v4+ if: always()+ with:+ name: real-performance-summary+ path: |+ results/performance-*/comparison.json+ results/performance-*/*/summary.json+ if-no-files-found: ignore+ retention-days: 14+ - uses: actions/upload-artifact@v4+ if: failure()+ with:+ name: real-performance-failure-diagnostics+ path: results/performance-*+ if-no-files-found: ignore+ retention-days: 3diff --cc README.mdindex 9b0e42f,9b0e42f..382b473--- a/README.md+++ b/README.md@@@ -88,6 -88,6 +88,8 @@@ Recording-time evidence matters: audio-The 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.++At one source-informed receiver point, median scoring time fell from **68.92 to 25.59 CPU seconds**, a **2.69×** speedup. All 3,905 associations across 16 event groups matched the scalar-corrected baseline in three alternating pairs. The [performance report](docs/PERFORMANCE.md) describes this bounded test, which does not establish nationwide runtime or independent location accuracy.++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).Missing events, incomplete flight coverage, competing locations or inadequate sensitivity evidence can require an **inconclusive** outcome. See [Decision rules](docs/CONFIDENCE.md).@@@ -182,3 -182,3 +184,4 @@@ Fully vibecoded if it wasn't obvious. U- [Implementation handoff](docs/HANDOFF.md), [acceptance issue](https://github.com/1337isnot1337/DOPPLERGEIST/issues/13) and [development discussion](https://github.com/1337isnot1337/DOPPLERGEIST/discussions/39) — ongoing work; the handoff includes historical context and is not a current feature inventoryDOPPLERGEIST is an **independent reconstruction** of the approach described in [colsto's video](https://www.youtube.com/watch?v=UytYrhYLOKI), with independently written code. It is not a release by or affiliation with the video's author. External recordings, ADS-B and terrain assets retain their own rights and attribution requirements; see [data provenance](docs/DATA_SOURCES.md). The banner's outlined typography and illustrative model are documented in [asset notes](assets/README.md).++diff --cc benchmarks/results/performance-20261103.jsonindex 0000000,0000000..ccc0c6anew file mode 100644--- /dev/null+++ b/benchmarks/results/performance-20261103.json@@@ -1,0 -1,0 +1,329 @@@++{++ "schema_version": 1,++ "date": "2026-11-03",++ "scope": "Recorded-input point scoring. Source-informed receiver and clock; no independent accuracy or complete-pipeline speed claim.",++ "original_main_commit": "7a8dd27979bd9a984c8675c38a00dfbf98a5b01e",++ "scalar_consistent_baseline_commit": "d7cc1dd2e8089768253492b3269dfae97b3ad1a4",++ "optimized_source_commit": "3725e9d2027d979e579ba9c347fb688ebf0895c3",++ "method": {++ "repeats_per_source": 3,++ "order": [++ "baseline",++ "current",++ "current",++ "baseline",++ "baseline",++ "current"++ ],++ "blas_threads": 1,++ "comparison": "Exact complete JSON equality for every scored candidate, diagnostics, counts, ranked rows, and retention records/bounds/stages.",++ "timing_scope": "Scoring only, excluding imports, input loading, fixture preparation, acquisition, and discovery.",++ "memory_scope": "Worker lifetime through scoring, including imports and input loading."++ },++ "environment": {++ "os": "Linux-6.18.57-x86_64-with-glibc2.39",++ "processor": "AMD EPYC 9V74",++ "python": "3.12.14",++ "numpy": "2.3.5",++ "scipy": "1.17.0",++ "pandas": "2.2.3"++ },++ "workloads": {++ "clock_plus_minus_120_seconds": {++ "clock_half_width_seconds": 120,++ "fixture_counts": {++ "trajectories": 452,++ "trajectory_samples": 91889,++ "ridge_records": 16,++ "independent_groups": 16,++ "ridge_samples": 724,++ "cpa_rows": 100,++ "unsupported_cpa_tracks": 4++ },++ "index_input_hash": "ed0ab12af801d1451edea17f1212740758569338dd601f9eb4a82c763b291955",++ "query_bounds": [++ -74.299988,++ 40.100005,++ -72.700011,++ 41.599964++ ],++ "query_time_s": [++ 1788898409.6620934,++ 1788902359.1620934++ ],++ "recording_start_window_s": [++ 1788898529.6620934,++ 1788898769.6620934++ ],++ "identical_results": true,++ "medians": {++ "baseline": {++ "wall_seconds": 69.0859555940001,++ "cpu_seconds": 68.924716452,++ "peak_rss_mib": 264.76171875++ },++ "current": {++ "wall_seconds": 25.598263117999977,++ "cpu_seconds": 25.589540803,++ "peak_rss_mib": 263.953125++ }++ },++ "speedup": {++ "wall_seconds": 2.698853249360532,++ "cpu_seconds": 2.6934721878213455++ },++ "runs": [++ {++ "source": "baseline",++ "repetition": 1,++ "wall_seconds": 69.10836225899993,++ "cpu_seconds": 69.072218921,++ "load_seconds_excluded": 1.3023584929999288,++ "operations": {++ "scalar_fit_calls": 65207,++ "acoustic_calls": 850,++ "scored_candidates": 3905++ },++ "peak_rss_mib": 264.24609375,++ "peak_rss_scope": "Worker lifetime through scoring, including imports and input loading",++ "retained": 100,++ "independent_groups": 16,++ "scope": "Recorded-input computation comparison; source-informed receiver/clock, no accuracy claim"++ },++ {++ "source": "current",++ "repetition": 1,++ "wall_seconds": 26.04211123999994,++ "cpu_seconds": 26.019312861,++ "load_seconds_excluded": 1.3072379929999443,++ "operations": {++ "scalar_fit_calls": 72,++ "acoustic_calls": 850,++ "scored_candidates": 3905++ },++ "peak_rss_mib": 264.36328125,++ "peak_rss_scope": "Worker lifetime through scoring, including imports and input loading",++ "retained": 100,++ "independent_groups": 16,++ "scope": "Recorded-input computation comparison; source-informed receiver/clock, no accuracy claim"++ },++ {++ "source": "current",++ "repetition": 2,++ "wall_seconds": 25.598263117999977,++ "cpu_seconds": 25.589540803,++ "load_seconds_excluded": 1.157314174000021,++ "operations": {++ "scalar_fit_calls": 72,++ "acoustic_calls": 850,++ "scored_candidates": 3905++ },++ "peak_rss_mib": 263.953125,++ "peak_rss_scope": "Worker lifetime through scoring, including imports and input loading",++ "retained": 100,++ "independent_groups": 16,++ "scope": "Recorded-input computation comparison; source-informed receiver/clock, no accuracy claim"++ },++ {++ "source": "baseline",++ "repetition": 2,++ "wall_seconds": 69.0859555940001,++ "cpu_seconds": 68.924716452,++ "load_seconds_excluded": 1.1775878469998133,++ "operations": {++ "scalar_fit_calls": 65207,++ "acoustic_calls": 850,++ "scored_candidates": 3905++ },++ "peak_rss_mib": 274.72265625,++ "peak_rss_scope": "Worker lifetime through scoring, including imports and input loading",++ "retained": 100,++ "independent_groups": 16,++ "scope": "Recorded-input computation comparison; source-informed receiver/clock, no accuracy claim"++ },++ {++ "source": "baseline",++ "repetition": 3,++ "wall_seconds": 66.31141195999999,++ "cpu_seconds": 66.27671456,++ "load_seconds_excluded": 1.201154365000093,++ "operations": {++ "scalar_fit_calls": 65207,++ "acoustic_calls": 850,++ "scored_candidates": 3905++ },++ "peak_rss_mib": 264.76171875,++ "peak_rss_scope": "Worker lifetime through scoring, including imports and input loading",++ "retained": 100,++ "independent_groups": 16,++ "scope": "Recorded-input computation comparison; source-informed receiver/clock, no accuracy claim"++ },++ {++ "source": "current",++ "repetition": 3,++ "wall_seconds": 25.13654742300014,++ "cpu_seconds": 25.128385459,++ "load_seconds_excluded": 1.1243659609999668,++ "operations": {++ "scalar_fit_calls": 72,++ "acoustic_calls": 850,++ "scored_candidates": 3905++ },++ "peak_rss_mib": 263.9375,++ "peak_rss_scope": "Worker lifetime through scoring, including imports and input loading",++ "retained": 100,++ "independent_groups": 16,++ "scope": "Recorded-input computation comparison; source-informed receiver/clock, no accuracy claim"++ }++ ]++ },++ "clock_plus_minus_10_seconds": {++ "clock_half_width_seconds": 10,++ "fixture_counts": {++ "trajectories": 426,++ "trajectory_samples": 87206,++ "ridge_records": 16,++ "independent_groups": 16,++ "ridge_samples": 724,++ "cpa_rows": 97,++ "unsupported_cpa_tracks": 4++ },++ "index_input_hash": "ed0ab12af801d1451edea17f1212740758569338dd601f9eb4a82c763b291955",++ "query_bounds": [++ -74.299988,++ 40.100005,++ -72.700011,++ 41.599964++ ],++ "query_time_s": [++ 1788898519.6620934,++ 1788902249.1620934++ ],++ "recording_start_window_s": [++ 1788898639.6620934,++ 1788898659.6620934++ ],++ "identical_results": true,++ "medians": {++ "baseline": {++ "wall_seconds": 4.6818429729999025,++ "cpu_seconds": 4.678170888,++ "peak_rss_mib": 207.25390625++ },++ "current": {++ "wall_seconds": 4.012459500999967,++ "cpu_seconds": 4.009227627,++ "peak_rss_mib": 205.05078125++ }++ },++ "speedup": {++ "wall_seconds": 1.1668262251203072,++ "cpu_seconds": 1.1668509057692376++ },++ "runs": [++ {++ "source": "baseline",++ "repetition": 1,++ "wall_seconds": 4.5884519399999135,++ "cpu_seconds": 4.585285469,++ "load_seconds_excluded": 1.1915359130000525,++ "operations": {++ "scalar_fit_calls": 2456,++ "acoustic_calls": 53,++ "scored_candidates": 1055++ },++ "peak_rss_mib": 207.32421875,++ "peak_rss_scope": "Worker lifetime through scoring, including imports and input loading",++ "retained": 100,++ "independent_groups": 16,++ "scope": "Recorded-input computation comparison; source-informed receiver/clock, no accuracy claim"++ },++ {++ "source": "current",++ "repetition": 1,++ "wall_seconds": 4.012459500999967,++ "cpu_seconds": 4.009227627,++ "load_seconds_excluded": 1.1970985870000277,++ "operations": {++ "scalar_fit_calls": 31,++ "acoustic_calls": 53,++ "scored_candidates": 1055++ },++ "peak_rss_mib": 203.1796875,++ "peak_rss_scope": "Worker lifetime through scoring, including imports and input loading",++ "retained": 100,++ "independent_groups": 16,++ "scope": "Recorded-input computation comparison; source-informed receiver/clock, no accuracy claim"++ },++ {++ "source": "current",++ "repetition": 2,++ "wall_seconds": 3.2934764280000763,++ "cpu_seconds": 3.285141417,++ "load_seconds_excluded": 0.9147789820001435,++ "operations": {++ "scalar_fit_calls": 31,++ "acoustic_calls": 53,++ "scored_candidates": 1055++ },++ "peak_rss_mib": 205.05078125,++ "peak_rss_scope": "Worker lifetime through scoring, including imports and input loading",++ "retained": 100,++ "independent_groups": 16,++ "scope": "Recorded-input computation comparison; source-informed receiver/clock, no accuracy claim"++ },++ {++ "source": "baseline",++ "repetition": 2,++ "wall_seconds": 4.6818429729999025,++ "cpu_seconds": 4.678170888,++ "load_seconds_excluded": 0.8518669599998248,++ "operations": {++ "scalar_fit_calls": 2456,++ "acoustic_calls": 53,++ "scored_candidates": 1055++ },++ "peak_rss_mib": 205.07421875,++ "peak_rss_scope": "Worker lifetime through scoring, including imports and input loading",++ "retained": 100,++ "independent_groups": 16,++ "scope": "Recorded-input computation comparison; source-informed receiver/clock, no accuracy claim"++ },++ {++ "source": "baseline",++ "repetition": 3,++ "wall_seconds": 6.029455899000141,++ "cpu_seconds": 6.025133543000001,++ "load_seconds_excluded": 1.157568615999935,++ "operations": {++ "scalar_fit_calls": 2456,++ "acoustic_calls": 53,++ "scored_candidates": 1055++ },++ "peak_rss_mib": 207.25390625,++ "peak_rss_scope": "Worker lifetime through scoring, including imports and input loading",++ "retained": 100,++ "independent_groups": 16,++ "scope": "Recorded-input computation comparison; source-informed receiver/clock, no accuracy claim"++ },++ {++ "source": "current",++ "repetition": 3,++ "wall_seconds": 4.336940211999945,++ "cpu_seconds": 4.329032449,++ "load_seconds_excluded": 1.1144543640000393,++ "operations": {++ "scalar_fit_calls": 31,++ "acoustic_calls": 53,++ "scored_candidates": 1055++ },++ "peak_rss_mib": 213.59765625,++ "peak_rss_scope": "Worker lifetime through scoring, including imports and input loading",++ "retained": 100,++ "independent_groups": 16,++ "scope": "Recorded-input computation comparison; source-informed receiver/clock, no accuracy claim"++ }++ ]++ }++ }++}diff --cc benchmarks/results/performance-ci-20261103.jsonindex 0000000,0000000..a8bc7aanew file mode 100644--- /dev/null+++ b/benchmarks/results/performance-ci-20261103.json@@@ -1,0 -1,0 +1,216 @@@++{++ "schema_version": 1,++ "date": "2026-11-03",++ "workflow_url": "https://github.com/1337isnot1337/DOPPLERGEIST/actions/runs/41656583534",++ "job_id": 125988403104,++ "source_commit": "3725e9d2027d979e579ba9c347fb688ebf0895c3",++ "baseline_commit": "d7cc1dd2e8089768253492b3269dfae97b3ad1a4",++ "environment": {++ "runner": "ubuntu-latest",++ "os": "Ubuntu 26.04.1",++ "python": "3.12",++ "numpy": "2.5.4",++ "scipy": "1.18.1",++ "pandas": "3.1.0"++ },++ "tests": {++ "passed": 8,++ "seconds": 16.51,++ "files": [++ "tests/test_real_prepared_measurements.py",++ "tests/test_real_geometry_kinematics.py",++ "tests/test_real_batch_scalar_parity.py"++ ]++ },++ "repeats_per_source": 2,++ "order": [++ "baseline",++ "current",++ "current",++ "baseline"++ ],++ "workloads": {++ "clock_plus_minus_10_seconds": {++ "clock_half_width_seconds": 10,++ "identical_results": true,++ "medians": {++ "baseline": {++ "wall_seconds": 3.7185562825000034,++ "cpu_seconds": 3.7121624735,++ "peak_rss_mib": 307.5390625++ },++ "current": {++ "wall_seconds": 2.780230859999989,++ "cpu_seconds": 2.7627671865,++ "peak_rss_mib": 305.58984375++ }++ },++ "speedup": {++ "wall_seconds": 1.337499103401801,++ "cpu_seconds": 1.3436392656026646++ },++ "scope": "Recorded-input computation comparison; source-informed receiver/clock, no accuracy claim",++ "runs": [++ {++ "source": "baseline",++ "repetition": 1,++ "wall_seconds": 3.716933076999993,++ "cpu_seconds": 3.71052622,++ "load_seconds_excluded": 0.9306310000000053,++ "operations": {++ "scalar_fit_calls": 2456,++ "acoustic_calls": 53,++ "scored_candidates": 1055++ },++ "peak_rss_mib": 307.296875,++ "peak_rss_scope": "Worker lifetime through scoring, including imports and input loading",++ "retained": 100,++ "independent_groups": 16,++ "scope": "Recorded-input computation comparison; source-informed receiver/clock, no accuracy claim"++ },++ {++ "source": "current",++ "repetition": 1,++ "wall_seconds": 2.8197890319999885,++ "cpu_seconds": 2.7922890469999997,++ "load_seconds_excluded": 0.9174293930000204,++ "operations": {++ "scalar_fit_calls": 31,++ "acoustic_calls": 53,++ "scored_candidates": 1055++ },++ "peak_rss_mib": 305.2109375,++ "peak_rss_scope": "Worker lifetime through scoring, including imports and input loading",++ "retained": 100,++ "independent_groups": 16,++ "scope": "Recorded-input computation comparison; source-informed receiver/clock, no accuracy claim"++ },++ {++ "source": "current",++ "repetition": 2,++ "wall_seconds": 2.7406726879999894,++ "cpu_seconds": 2.7332453260000005,++ "load_seconds_excluded": 0.9199184869999897,++ "operations": {++ "scalar_fit_calls": 31,++ "acoustic_calls": 53,++ "scored_candidates": 1055++ },++ "peak_rss_mib": 305.96875,++ "peak_rss_scope": "Worker lifetime through scoring, including imports and input loading",++ "retained": 100,++ "independent_groups": 16,++ "scope": "Recorded-input computation comparison; source-informed receiver/clock, no accuracy claim"++ },++ {++ "source": "baseline",++ "repetition": 2,++ "wall_seconds": 3.7201794880000136,++ "cpu_seconds": 3.7137987269999995,++ "load_seconds_excluded": 0.9181344309999986,++ "operations": {++ "scalar_fit_calls": 2456,++ "acoustic_calls": 53,++ "scored_candidates": 1055++ },++ "peak_rss_mib": 307.78125,++ "peak_rss_scope": "Worker lifetime through scoring, including imports and input loading",++ "retained": 100,++ "independent_groups": 16,++ "scope": "Recorded-input computation comparison; source-informed receiver/clock, no accuracy claim"++ }++ ]++ },++ "clock_plus_minus_120_seconds": {++ "clock_half_width_seconds": 120,++ "identical_results": true,++ "medians": {++ "baseline": {++ "wall_seconds": 45.1779612145,++ "cpu_seconds": 45.1466901755,++ "peak_rss_mib": 366.904296875++ },++ "current": {++ "wall_seconds": 17.331677818499998,++ "cpu_seconds": 17.302663175,++ "peak_rss_mib": 355.53515625++ }++ },++ "speedup": {++ "wall_seconds": 2.606669803559158,++ "cpu_seconds": 2.6092336028785925++ },++ "scope": "Recorded-input computation comparison; source-informed receiver/clock, no accuracy claim",++ "runs": [++ {++ "source": "baseline",++ "repetition": 1,++ "wall_seconds": 45.202507631,++ "cpu_seconds": 45.172905578,++ "load_seconds_excluded": 0.9542231679999986,++ "operations": {++ "scalar_fit_calls": 65207,++ "acoustic_calls": 850,++ "scored_candidates": 3905++ },++ "peak_rss_mib": 366.84765625,++ "peak_rss_scope": "Worker lifetime through scoring, including imports and input loading",++ "retained": 100,++ "independent_groups": 16,++ "scope": "Recorded-input computation comparison; source-informed receiver/clock, no accuracy claim"++ },++ {++ "source": "current",++ "repetition": 1,++ "wall_seconds": 17.328689800999996,++ "cpu_seconds": 17.300306945,++ "load_seconds_excluded": 0.9637239040000054,++ "operations": {++ "scalar_fit_calls": 72,++ "acoustic_calls": 850,++ "scored_candidates": 3905++ },++ "peak_rss_mib": 355.10546875,++ "peak_rss_scope": "Worker lifetime through scoring, including imports and input loading",++ "retained": 100,++ "independent_groups": 16,++ "scope": "Recorded-input computation comparison; source-informed receiver/clock, no accuracy claim"++ },++ {++ "source": "current",++ "repetition": 2,++ "wall_seconds": 17.334665836,++ "cpu_seconds": 17.305019405,++ "load_seconds_excluded": 0.9546623070000066,++ "operations": {++ "scalar_fit_calls": 72,++ "acoustic_calls": 850,++ "scored_candidates": 3905++ },++ "peak_rss_mib": 355.96484375,++ "peak_rss_scope": "Worker lifetime through scoring, including imports and input loading",++ "retained": 100,++ "independent_groups": 16,++ "scope": "Recorded-input computation comparison; source-informed receiver/clock, no accuracy claim"++ },++ {++ "source": "baseline",++ "repetition": 2,++ "wall_seconds": 45.153414798,++ "cpu_seconds": 45.120474773,++ "load_seconds_excluded": 0.9614073959999985,++ "operations": {++ "scalar_fit_calls": 65207,++ "acoustic_calls": 850,++ "scored_candidates": 3905++ },++ "peak_rss_mib": 366.9609375,++ "peak_rss_scope": "Worker lifetime through scoring, including imports and input loading",++ "retained": 100,++ "independent_groups": 16,++ "scope": "Recorded-input computation comparison; source-informed receiver/clock, no accuracy claim"++ }++ ]++ }++ }++}diff --cc docs/DATA_AND_SCALE.mdindex 67851cd,67851cd..ee94caa--- a/docs/DATA_AND_SCALE.md+++ b/docs/DATA_AND_SCALE.md@@@ -148,10 -148,10 +148,26 @@@ cannot enter Top-K. While fitting a shatighten that ceiling or establish a residual rejection before the remaininggroups are fitted. Comparisons are strict, so ties remain eligible. Acousticbatches for later groups are deferred until a surviving trial needs them.--For the first event, a measured-ridge loss bound can screen individual clocks;--the remaining supported clocks are fitted together. Representative batched--fits are checked against the scalar fitter, with fallback for mismatches or--unsupported and numerically degenerate batches.++++At each event group, the scorer fits only the shared-clock trials that survive++earlier groups and the acoustic bound. It reuses validated group contributions++and preserves the order and upward rounding of the conservative score ceiling.++If the product of clock trials and event groups exceeds 4,096, the scorer keeps++the scalar traversal.++++Batch arithmetic matches the scalar model and uses Python `float` powers.++Regression tests compare every fitted clock in the recorded-data test batches++with the scalar fitter. Unsupported, nonfinite or degenerate batches use scalar++fitting. The same fallback handles overflowing powers, zero drift bounds and++noncanonical numeric parameters.++++A replay at one source-informed receiver point used 16 event groups and 3,905++associations. Across three alternating pairs, median CPU time fell from 68.9247++to 25.5895 seconds, a 2.6935× speedup. All candidate results, diagnostics, support++records and retention data matched the baseline with the separate correction to++scalar rounding. A narrower clock window had a smaller change: 4.6782 to 4.0092 CPU++seconds. The [performance report](PERFORMANCE.md) gives the inputs, procedure and++limits.When an event's conservative loss bound alone makes the association unable toreach the current Top-K floor, the scorer may also skip that clock and retain a@@@ -265,3 -265,3 +281,4 @@@ The diagnostic contains measured eventmatching/scoring modules with the current fitter and requires identical sharedgeometry. Timing includes scoring with a bounded fit cache. Scaling experimentsand location-accuracy evidence must be labelled separately.++diff --cc docs/PERFORMANCE.mdindex 0000000,0000000..8402bd9new file mode 100644--- /dev/null+++ b/docs/PERFORMANCE.md@@@ -1,0 -1,0 +1,215 @@@++# Measured scoring performance++++The 2026-11-03 implementation reduces median CPU time by **62.87%** on the broad-clock workload described here.++The same workload takes **68.92 → 25.59 CPU seconds**, a **2.69× speedup**.++Every scored candidate, diagnostic, support count, and retention record matches the scalar-consistent baseline exactly.++++These measurements cover complete scoring at one receiver point, using recorded audio ridges and historical flight trajectories.++They exclude discovery, downloads, input loading, nationwide search, and refinement.++The receiver point and recording clock come from a historical fit.++This experiment does not establish independent location accuracy or a nationwide completion time.++++## Measurements++++Each result is the median of three runs per source in separate Python processes.++The harness alternates baseline/current, current/baseline, then baseline/current.++OpenBLAS, OpenMP, and MKL each use one thread.++++| Recording-start window | Baseline CPU | Optimized CPU | CPU speedup | Baseline wall time | Optimized wall time | Median peak RSS, baseline → optimized |++| --- | ---: | ---: | ---: | ---: | ---: | ---: |++| ±120 seconds | 68.9247 s | 25.5895 s | **2.6935×** | 69.0860 s | 25.5983 s | 264.76 → 263.95 MiB |++| ±10 seconds | 4.6782 s | 4.0092 s | **1.1669×** | 4.6818 s | 4.0125 s | 207.25 → 205.05 MiB |++++Broad-window CPU ranges were 66.2767–69.0722 seconds for the baseline and 25.1284–26.0193 seconds for the optimized source.++Narrow-window CPU ranges were 4.5853–6.0251 seconds and 3.2851–4.3290 seconds, respectively.++The narrow workload has more timing variation and a smaller benefit.++Peak RSS includes imports, input loading, and diagnostic capture through the end of scoring.++++The machine used an AMD EPYC 9V74 processor, Linux 6.18.57, and Python 3.12.14.++Package versions were NumPy 2.3.5, SciPy 1.17.0, and pandas 2.2.3.++[The measurement record](../benchmarks/results/performance-20261103.json) contains every run, the input hash, source commits, and workload counts.++++### Fixed workloads++++Both workloads use all 16 recorded ridge records, 16 independent groups, and 724 ridge samples from the archived discovery result.++The trajectory query retains complete recorded tracks within the declared query.++The preparation command stops on a budget excess instead of truncating the inputs.++++| Quantity | ±120 seconds | ±10 seconds |++| --- | ---: | ---: |++| Recorded trajectories | 452 | 426 |++| Trajectory samples | 91,889 | 87,206 |++| CPA rows | 100 | 97 |++| Unsupported CPA tracks | 4 | 4 |++| Scored associations | 3,905 | 1,055 |++| Retained associations | 100 | 100 |++| Scalar fit calls, baseline → optimized | 65,207 → 72 | 2,456 → 31 |++| Acoustic calls, both versions | 850 | 53 |++++Batch fits replace most scalar calls while preserving all required fits and all six IRLS iterations.++The two clock windows define different workloads.++The difference between those workloads is not a code speedup.++A narrower clock window requires independent recording-time evidence.++++## Changes that reduce work++++**Batch surviving clocks after each group.**++The scorer preserves the event order within each clock trial.++After the existing conservative screen, it fits surviving clocks together for the next group.++Later groups still wait until a surviving clock requires them.++The scorer consumes completed trials in the original clock order, preserving tie behavior.++++**Reuse validated score contributions.**++The scorer validates each completed group once and retains its conservative prefix bound.++It preserves the original arithmetic order and rounds each positive accumulation upward.++Unknown groups retain their full possible contribution.++Strict comparisons preserve tied candidates and the original retention evidence.++++**Prepare measurements once per scoped cache.**++Repeated fits reuse selected samples, normalized weights, and the independent-sample count.++Content-sensitive keys detect changed measurements.++The prepared-measurement cache has a 4 MiB limit.++Cached diagnostic dictionaries contain scalar values and use separate shallow copies.++++**Reuse trajectory calculations.**++A packed polynomial evaluates position and velocity with one interval lookup.++Its arithmetic matches the original separate evaluations.++The cache retains at most eight small spline pairs and adds at most 6 MiB of coefficients.++Large splines use the original path.++The acoustic solver reuses its final position and velocity only after the unchanged-time condition succeeds.++++**Remove repeated scalar reference fits.**++The old batch fitter repeated up to three scalar fits for every batch.++The regression suite compares every eligible fitted clock against the scalar model on the recorded workload.++The batch fitter keeps scalar fallback for unsupported, nonfinite, degenerate, overflowing, or noncanonical numeric inputs.++++The staged table has a limit of 4,096 event-clock slots.++Larger products use the existing scalar traversal.++This limit changes the execution path without reducing the search domain.++++## Numerical baseline++++The untouched starting revision is `7a8dd27979bd9a984c8675c38a00dfbf98a5b01e`.++Its batch fitter uses NumPy array squaring where the scalar fitter uses Python scalar powers.++One recorded fit exposed a one-ULP rounding difference in the prior.++Later IRLS iterations propagated this difference.++The original first/middle/last checks did not detect every affected clock.++++Commit `d7cc1dd2e8089768253492b3269dfae97b3ad1a4` corrects those powers and preserves the original repeated reference checks.++It also preserves the original geometry, measurement preparation, and search traversal.++This numerical correction is separate from the speed changes.++The performance comparison uses this scalar-consistent commit as its baseline.++++Commit `3725e9d2027d979e579ba9c347fb688ebf0895c3` contains the optimized source used for these measurements.++All six outputs match exactly within each workload.++The comparison includes every scored association, all diagnostics, support counts, ranked rows, and persisted retention records, bounds, stages, and checksums.++The harness uses no numerical tolerance.++++Against untouched main, the broad workload retains the same top 100 candidates and support counts.++One discarded candidate retains the legacy rounding difference in its old diagnostic values.++Exact equality with untouched main is therefore not the correctness claim.++An earlier single observation took 77.43 CPU seconds on untouched main, but the table uses the repeated scalar-consistent baseline.++++## Reproduce the comparison++++Use Python 3.11 or later, Git, and the GitHub CLI `gh` configured for release downloads.++Run these POSIX-shell commands from the repository root.++For the published source comparison, use optimized commit `3725e9d2027d979e579ba9c347fb688ebf0895c3` as the current checkout.++Use a fresh output directory for each experiment.++The commands require access to the public checkpoint assets and sufficient disk space for the restored flight and terrain data.++++Install the runtime and restore the recorded inputs:++++```bash++python -m venv .venv++.venv/bin/python -m pip install '.[test]'++.venv/bin/python scripts/restore_artifacts.py \++ --bundle data-adsb-derived --bundle data-terrain++PYTHONPATH=src .venv/bin/python scripts/prepare_reference_upload.py \++ --data-root data --output results/performance-inputs++```++++Create the baseline worktree:++++```bash++git worktree add --detach ../dopplergeist-scalar-baseline \++ d7cc1dd2e8089768253492b3269dfae97b3ad1a4++```++++Freeze each workload and compare both sources:++++```bash++for width in 120 10; do++ PYTHONPATH=src .venv/bin/python scripts/benchmark_prepared_measurements.py prepare \++ --discovery evidence/audio/w1-sensitivity-20261102/reference/discovery.json \++ --index results/performance-inputs/reference-region.sqlite \++ --clock-half-width-s "$width" \++ --output "results/performance-inputs/point-$width.json"++++ PYTHONPATH=src .venv/bin/python scripts/benchmark_prepared_measurements.py compare \++ --fixture "results/performance-inputs/point-$width.json" \++ --baseline-source ../dopplergeist-scalar-baseline/src \++ --current-source src --repeats 3 --timeout-s 600 \++ --output "results/performance-$width"++done++```++++Run the focused regression suite with the recorded broad-window fixture:++++```bash++DOPPLERGEIST_REAL_CPA_FIXTURE=results/performance-inputs/point-120.json \++PYTHONPATH=src .venv/bin/python -m pytest -q \++ tests/test_real_prepared_measurements.py \++ tests/test_real_geometry_kinematics.py \++ tests/test_real_batch_scalar_parity.py++```++++The comparison command fixes numerical library thread counts for its worker processes.++It stops on any candidate, diagnostic, support, or retention mismatch.++It also rejects a changed index hash, missing trajectory, empty workload, or invalid retention ledger.++The focused tests skip without an explicitly supplied real fixture.++++The [Real performance comparison workflow](../.github/workflows/real-performance.yml) repeats this procedure on a separate GitHub runner.++It uses two pairs per workload and saves the raw timing summaries.++The workflow also runs the focused real-input tests.++It does not run the historical synthetic suite.++++## Method for further optimization++++1. Freeze the source, recording, trajectory index, clock window, and search budgets.++2. Profile a complete bounded workload with all independent groups.++3. Identify repeated work through call counts and cumulative CPU time.++4. Preserve the physical model, conservative bounds, support failures, and candidate accounting.++5. Compare complete outputs before accepting a timing result.++6. Alternate separate-process runs and report their medians and ranges.++7. Measure discovery, acquisition, search, and refinement separately before predicting total runtime.++++Existing data indexes and terrain caches avoid repeated acquisition costs.++The recording clock controls the number of plausible flight associations.++Clock evidence can reduce work, but an unsupported clock restriction changes the scientific question.++++Worker count also affects throughput and memory use.++Excess workers can increase memory pressure and compete for the same CPU resources.++The measurements here establish single-worker scoring gains without assuming linear parallel scaling.++++An existing process continues to use its loaded source.++New measurements require a new run with the new source identity.++Checkpoint reuse must pass the existing source and input identity rules.++++## Independent runner and integration validation++++The [independent CI run](https://github.com/1337isnot1337/DOPPLERGEIST/actions/runs/41656583534) passed all eight focused real-input tests.++Both complete-output comparisons also passed, with two alternating pairs per workload.++The PR installation/static checks pass for the measured source.++++| Window | Baseline median CPU | Optimized median CPU | Speedup |++| --- | ---: | ---: | ---: |++| ±120 seconds | 45.1467 s | 17.3027 s | 2.6092× |++| ±10 seconds | 3.7122 s | 2.7628 s | 1.3436× |++++The GitHub runner used Python 3.12, NumPy 2.5.4, SciPy 1.18.1, and pandas 3.1.0 on Ubuntu 26.04.1.++[The CI measurement record](../benchmarks/results/performance-ci-20261103.json) preserves all eight runs and their source revisions.++These ratios support the local result on a second environment without pooling timings from different machines.++++The complete HTTP replay uses the entire 3,600.1845-second reference recording and an explicit source-informed clock.++Its regional flight coverage cannot establish an accepted independent location.