Skip to content

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

Integrate current association traversal and document measured scoring gains

Cinna Davisd6a0c860bd5a
diff --cc .github/workflows/real-performance.yml
index f7863d7,0000000..2794633
mode 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: 3
diff --cc README.md
index 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 inventory
DOPPLERGEIST 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.json
index 0000000,0000000..ccc0c6a
new 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.json
index 0000000,0000000..a8bc7aa
new 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.md
index 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 sha
tighten that ceiling or establish a residual rejection before the remaining
groups are fitted. Comparisons are strict, so ties remain eligible. Acoustic
batches 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 to
reach 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 event
matching/scoring modules with the current fitter and requires identical shared
geometry. Timing includes scoring with a bounded fit cache. Scaling experiments
and location-accuracy evidence must be labelled separately.
++
diff --cc docs/PERFORMANCE.md
index 0000000,0000000..8402bd9
new 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.