Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)
Python acoustic-geolocationads-baircraft-trackingairplaneaudio-forensicsdoppler-effectdoppler-shiftgeolocationosintsignal-processing
"""Compare complete point scoring on recorded ridges and historical trajectories.
The archived research candidate supplies workload coordinates and a clock, not
independent truth. Each source runs in a separate interpreter with bounded work
and identical observed inputs. This script generates no audio or trajectories.
"""
from __future__ import annotations
import argparse
from collections import Counter
from dataclasses import asdict
import json
import math
import os
from pathlib import Path
import statistics
import subprocess
import sys
import time
try:
import resource
except ImportError: # Windows does not provide the Unix resource module.
resource = None
ROOT = Path(__file__).resolve().parents[1]
def json_scalar(value):
if hasattr(value, "tolist"):
return value.tolist()
raise TypeError(f"Cannot serialize {type(value).__name__}")
def write_new(path, value):
path = Path(path)
path.parent.mkdir(parents=True, exist_ok=True)
with path.open("x") as output:
json.dump(value, output, indent=2, allow_nan=True, default=json_scalar)
output.write("\n")
def canonical(value):
return json.dumps(value, sort_keys=True, separators=(",", ":"),
allow_nan=True, default=json_scalar)
def timing_instrumentation_active():
"""Observe profiling/debugging without installing or changing any hooks."""
if sys.getprofile() is not None or sys.gettrace() is not None:
return True
monitoring = getattr(sys, "monitoring", None)
if monitoring is None:
return False
# Python 3.12 cProfile uses monitoring, leaving getprofile() unset. Count
# all reserved monitoring slots, including coverage/custom tools, even when
# events are temporarily paused or enabled only for individual code objects.
return any(monitoring.get_tool(tool_id) is not None for tool_id in range(6))
def query_tracks(index, points, events, budget, scoring, bounds, time_range, *,
anchor_window=None, clock_partition_query=False):
"""Count actual index traversal while exercising the production overload path."""
from dopplergeist import tiled_search
requested_time_range = list(time_range)
narrow_query = getattr(tiled_search, "_partition_query_time_range", None)
if clock_partition_query and callable(narrow_query):
time_range = narrow_query(time_range, events, scoring, {}, anchor_window)
if "elev_m" not in points:
raise ValueError("The recorded receiver hypothesis must include its elevation")
operations = {"query_calls": 0, "decoded_track_yields": 0, "decoded_sample_yields": 0}
inventory = {}
class CountedIndex:
def query(self, query_bounds, query_time):
operations["query_calls"] += 1
for track in index.query(query_bounds, query_time):
operations["decoded_track_yields"] += 1
operations["decoded_sample_yields"] += len(track.time)
inventory[track.id] = len(track.time)
yield track
radius = max(event["slant_range_m"][1] for event in events)
tracks, points = tiled_search._tracks_for_points(
[CountedIndex()], bounds, time_range, budget, points, None, radius,
scoring.get("c", 343.0))
accounting = {
"requested_time_range_s": requested_time_range,
"effective_time_range_s": list(time_range),
"clock_partition_time_narrowed": list(time_range) != requested_time_range,
"queried_track_ids": sorted(inventory),
"queried_trajectory_samples": sum(inventory.values()),
"selected_track_ids": [track.id for track in tracks],
"selected_trajectory_samples": sum(len(track.time) for track in tracks),
}
return tracks, points, operations, accounting
_PARTITION_WORK_COUNTS = {"cpa_rows", "per_event_survivors", "work_units", "unsupported_cpa_tracks"}
def partition_outcomes(payload):
"""Project only the explicitly allowed early-work diagnostics out of parity.
Scored candidate payloads, rankings, trial evidence, support during scoring,
retention records/bounds/stages, and all other counts remain exact checks.
The removed fields receive separate monotonicity and time-exclusion checks.
"""
return {key: ({name: value for name, value in item.items()
if name not in _PARTITION_WORK_COUNTS} if key == "counts" else item)
for key, item in payload.items() if key != "track_query_accounting"}
def verify_partition_work(baseline, current):
"""Explain every permitted diagnostic change; reject unexplained omissions."""
before, after = (payload["track_query_accounting"] for payload in (baseline, current))
if before["requested_time_range_s"] != after["requested_time_range_s"]:
raise AssertionError("Partition comparison changed the requested source interval")
lower, upper = after["effective_time_range_s"]
broad_lower, broad_upper = before["effective_time_range_s"]
if not broad_lower <= lower <= upper <= broad_upper:
raise AssertionError("Partition query did not conservatively narrow the original query")
if not set(after["queried_track_ids"]) <= set(before["queried_track_ids"]):
raise AssertionError("Partition query introduced unobserved source tracks")
if after["queried_trajectory_samples"] > before["queried_trajectory_samples"]:
raise AssertionError("Partition query increased source sample traversal")
old_counts, new_counts = baseline["counts"], current["counts"]
for field in ("cpa_rows", "work_units"):
if new_counts.get(field, 0) > old_counts.get(field, 0):
raise AssertionError(f"Partition unexpectedly increased {field}")
old_survivors = old_counts.get("per_event_survivors", [])
new_survivors = new_counts.get("per_event_survivors", [])
if len(old_survivors) != len(new_survivors) or any(
new > old for old, new in zip(old_survivors, new_survivors)):
raise AssertionError("Partition unexpectedly changed event filtering")
old_support = {canonical(item): item for item in old_counts.get("unsupported_cpa_tracks", [])}
old_multiplicity = Counter(canonical(item) for item in old_counts.get("unsupported_cpa_tracks", []))
new_multiplicity = Counter(canonical(item) for item in new_counts.get("unsupported_cpa_tracks", []))
if not new_multiplicity <= old_multiplicity:
raise AssertionError("Partition introduced or changed an unsupported-track report")
removed = old_multiplicity - new_multiplicity
for identity in removed:
lo, hi = old_support[identity]["emission_time_range_s"]
if lo <= upper and hi >= lower:
raise AssertionError("Partition dropped an unsupported track touching the feasible emission interval")
return {
"requested_time_range_s": before["requested_time_range_s"],
"effective_time_range_s": after["effective_time_range_s"],
"excluded_unsupported_tracks_proved_outside_time_range": removed.total(),
"baseline": {"queried_tracks": len(before["queried_track_ids"]),
"queried_samples": before["queried_trajectory_samples"],
"selected_tracks": len(before["selected_track_ids"]),
"cpa_rows": old_counts["cpa_rows"],
"unsupported_cpa_tracks": old_multiplicity.total(),
"association_work_units": old_counts.get("work_units")},
"current": {"queried_tracks": len(after["queried_track_ids"]),
"queried_samples": after["queried_trajectory_samples"],
"selected_tracks": len(after["selected_track_ids"]),
"cpa_rows": new_counts["cpa_rows"],
"unsupported_cpa_tracks": new_multiplicity.total(),
"association_work_units": new_counts.get("work_units")},
}
def prepare(args):
import pandas as pd
from dopplergeist.data_access import FlightIndex
from dopplergeist.geometry import AcousticSupportError, ecef
from dopplergeist.matching import prepare_events
from dopplergeist.search import cpa_table
from dopplergeist.tiled_search import SearchBudget, _support_error
if args.output.exists():
raise FileExistsError(f"Choose a new fixture path: {args.output}")
discovery = json.loads(args.discovery.read_text())
report = json.loads(args.reference_report.read_text())
seed = report[0] if isinstance(report, list) else report["best"]
point = {key: seed[key] for key in ("point_id", "lat", "lon", "elev_m", "x", "y")}
clock = float(seed["recording_start_time_s"])
events, measurements = prepare_events(discovery["events"])
index = FlightIndex(args.index)
window = [clock - args.clock_half_width_s, clock + args.clock_half_width_s]
query_time = [window[0] - 120.0, window[1] + max(e["end_s"] for e in events) + 120.0]
if args.full_day:
query_time = list(index.report["coverage"]["time_range_s"])
query_bounds = list(index.report["coverage"]["bounds"])
budget = SearchBudget(max_tracks_per_tile=args.max_tracks,
max_track_samples_per_tile=args.max_samples,
max_candidates_per_tile=args.max_candidates, top_k=args.top_k)
points = pd.DataFrame([point])
query_preparation = None
if args.include_track_query:
tracks, points, query_operations, query_accounting = query_tracks(
index, points, events, budget, {"mode": "robust_ridge"}, query_bounds, query_time)
samples = query_accounting["selected_trajectory_samples"]
query_preparation = {
"queried_trajectories": len(query_accounting["queried_track_ids"]),
"queried_trajectory_samples": query_accounting["queried_trajectory_samples"],
"operations": query_operations,
}
else:
tracks, samples = [], 0
for track in index.query(query_bounds, query_time):
tracks.append(track)
samples += len(track.time)
if len(tracks) > args.max_tracks or samples > args.max_samples:
raise ValueError("Declared trajectory budget exceeded; no input was silently truncated")
if not tracks:
raise ValueError("The declared real-data query returned no trajectories")
observers = ecef(points.lat.to_numpy(), points.lon.to_numpy(), points.elev_m.to_numpy())
radius = max(e["slant_range_m"][1] for e in events)
tables, unsupported, row_count = [], [], 0
for track in tracks:
try:
if track.outside_observer_radius(observers, radius):
continue
table = cpa_table([track], points, radius, step_s=budget.cpa_step_s)
except AcousticSupportError as error:
unsupported.append(_support_error(error))
continue
row_count += len(table)
if row_count > budget.max_cpa_rows:
raise ValueError("Declared CPA budget exceeded; no rows were silently truncated")
if len(table):
tables.append(table)
if not tables:
raise ValueError("The real-data point has no supported CPA rows")
fixture = {
"scope": ("Recorded-input computation comparison; source-informed receiver, no recording-clock prior or accuracy claim"
if args.full_day else
"Recorded-input computation comparison; source-informed receiver/clock, no accuracy claim"),
"discovery_source": str(args.discovery.resolve()),
"reference_report": str(args.reference_report.resolve()),
"real_index": str(args.index.resolve()), "index_input_hash": index.report["input_hash"],
"events": discovery["events"], "point": point,
"query_bounds": query_bounds, "query_time_s": query_time,
"track_ids": [track.id for track in tracks],
"cpa_rows": pd.concat(tables, ignore_index=True).to_dict(orient="records"),
"unsupported_cpa_tracks": unsupported,
"budget": asdict(budget), "scoring": {"mode": "robust_ridge"},
"recording_start_window_s": None if args.full_day else window,
"counts": {"trajectories": len(tracks), "trajectory_samples": samples,
"ridge_records": len(discovery["events"]), "independent_groups": len(events),
"ridge_samples": sum(len(measurement[1]) for measurement in measurements),
"cpa_rows": row_count, "unsupported_cpa_tracks": len(unsupported)},
}
if args.anchor_window_s is not None:
fixture["anchor_window_s"] = args.anchor_window_s
fixture["scope"] += ". One association-anchor partition. Physical fit intervals remain unchanged."
if query_preparation is not None:
fixture["track_query_preparation"] = query_preparation
write_new(args.output, fixture)
print(json.dumps({"fixture": str(args.output), **fixture["counts"],
"scope": fixture["scope"],
**({"track_query_preparation": query_preparation}
if query_preparation is not None else {})}), flush=True)
def worker(args):
source = args.source.resolve()
sys.path.insert(0, str(source))
import dopplergeist
import pandas as pd
from dopplergeist import geometry, matching, tiled_search
from dopplergeist.data_access import FlightIndex
from dopplergeist.finite_search import RetentionLedger
from dopplergeist.geometry import AcousticSupportError, Track
if Path(dopplergeist.__file__).resolve().parent != source / "dopplergeist":
raise RuntimeError("Comparison imported a different source tree")
native_fit = getattr(matching, "_native_fit_irls", None)
native_module = getattr(matching, "_native_ridge_module", None)
native_statistics = getattr(native_module, "fit_statistics", None)
ridge_backend = getattr(matching, "RIDGE_FIT_BACKEND", "python-irls-v1")
acoustic_backend = getattr(geometry, "ACOUSTIC_BACKEND", "python-acoustic-v1")
try:
from dopplergeist.native_acoustic import _native as native_acoustic
except ImportError:
native_acoustic = None
try:
from dopplergeist.native_cpa import _native as native_cpa
except ImportError:
native_cpa = None
if args.require_native and not callable(native_fit):
raise RuntimeError("The selected source's native ridge fitter is unavailable")
if args.require_native_acoustic and native_acoustic is None:
raise RuntimeError("The selected source's native acoustic solver is unavailable")
if args.require_native_cpa and native_cpa is None:
raise RuntimeError("The selected source's native CPA reducer is unavailable")
fixture = json.loads(args.fixture.read_text())
index = FlightIndex(args.index or fixture["real_index"])
if index.report["input_hash"] != fixture["index_input_hash"]:
raise ValueError("The real trajectory index no longer matches the fixture")
budget = tiled_search.SearchBudget(**fixture["budget"])
loaded_at = time.perf_counter()
tracks = None
if not args.include_track_query:
tracks = list(index.lookup(fixture["track_ids"], max_tracks=budget.max_tracks_per_tile,
max_samples=budget.max_track_samples_per_tile))
if sorted(track.id for track in tracks) != sorted(fixture["track_ids"]):
raise ValueError("The index is missing a recorded trajectory")
events, measurements = matching.prepare_events(fixture["events"])
points = pd.DataFrame([fixture["point"]])
load_seconds = time.perf_counter() - loaded_at
args.output.mkdir(parents=True, exist_ok=False)
ledger = RetentionLedger(args.output / "retention.sqlite", "recorded-point-benchmark",
"matched_group_support_minus_normalized_residual")
stage = "coarse:recorded-point"
operations = {"scalar_fit_calls": 0, "acoustic_calls": 0, "scored_candidates": 0,
"native_fit_calls": 0, "native_fit_successes": 0,
"native_acoustic_successes": 0}
all_rows = []
original_fit, original_acoustic = matching._fit_ridge_uncached, Track.acoustic
original_score = tiled_search.score_candidate
phase_seconds, phase_patches = {}, []
def timed_phase(name, function):
def run(*values, **options):
began, cpu = time.perf_counter(), time.process_time()
try:
return function(*values, **options)
finally:
phase = phase_seconds.setdefault(name, {"wall_seconds": 0.0, "cpu_seconds": 0.0, "calls": 0})
phase["wall_seconds"] += time.perf_counter() - began
phase["cpu_seconds"] += time.process_time() - cpu
phase["calls"] += 1
return run
if args.stage_timing:
phase_targets = [
(Track, "outside_observer_radius", "distance_sieve"),
(matching, "association_candidates", "association_enumeration"),
(tiled_search, "merge_candidates", "retention"),
]
if callable(getattr(tiled_search, "cpa_table", None)):
phase_targets.append((tiled_search, "cpa_table", "closest_approach"))
else:
prepared_cpa = getattr(tiled_search, "_PreparedCPATrack", None)
if prepared_cpa is not None:
phase_targets.extend([
(prepared_cpa, "__init__", "closest_approach_preparation"),
(prepared_cpa, "raw_rows", "closest_approach"),
])
for owner, attribute, name in phase_targets:
function = getattr(owner, attribute, None)
if function is not None:
phase_patches.append((owner, attribute, function))
setattr(owner, attribute, timed_phase(name, function))
score_function = timed_phase("candidate_scoring", original_score) if args.stage_timing else original_score
def counted_fit(*values, **options):
operations["scalar_fit_calls"] += 1
return original_fit(*values, **options)
def counted_acoustic(*values, **options):
operations["acoustic_calls"] += 1
return original_acoustic(*values, **options)
def counted_native(*values, **options):
operations["native_fit_calls"] += 1
result = native_fit(*values, **options)
if result is not None and all(math.isfinite(value) for value in result):
operations["native_fit_successes"] += 1
return result
def captured_score(*values, **options):
operations["scored_candidates"] += 1
try:
result = score_function(*values, **options)
except AcousticSupportError as error:
all_rows.append({"support_failure": tiled_search._support_error(error)})
raise
all_rows.append(result)
return result
if args.instrument_numerics:
matching._fit_ridge_uncached, Track.acoustic = counted_fit, counted_acoustic
else:
for name in ("scalar_fit_calls", "acoustic_calls", "native_fit_calls", "native_fit_successes"):
operations[name] = None
tiled_search.score_candidate = captured_score
native_before = native_statistics() if callable(native_statistics) else None
if args.instrument_numerics and callable(native_fit) and native_before is None:
matching._native_fit_irls = counted_native
native_acoustic_before = native_acoustic.successful_calls() if native_acoustic is not None else 0
native_cpa_before = native_cpa.successful_calls() if native_cpa is not None else 0
query_accounting, query_operations, execution_stages = None, None, {}
diagnostic = args.instrument_numerics or args.stage_timing or timing_instrumentation_active()
began, cpu = time.perf_counter(), time.process_time()
try:
if args.include_track_query:
query_began, query_cpu = time.perf_counter(), time.process_time()
tracks, points, query_operations, query_accounting = query_tracks(
index, points, events, budget, fixture["scoring"],
fixture["query_bounds"], fixture["query_time_s"],
anchor_window=fixture.get("anchor_window_s"),
clock_partition_query=args.clock_partition_query)
execution_stages["track_query_and_distance_sieve"] = {
"wall_seconds": time.perf_counter() - query_began,
"cpu_seconds": time.process_time() - query_cpu,
}
if not query_accounting["clock_partition_time_narrowed"]:
if query_accounting["selected_track_ids"] != fixture["track_ids"]:
raise AssertionError("The real query changed the ordered selected-track inventory")
if query_accounting["selected_trajectory_samples"] != fixture["counts"]["trajectory_samples"]:
raise AssertionError("The real query changed the selected trajectory sample count")
prepared_query = fixture.get("track_query_preparation")
if prepared_query is not None:
if (len(query_accounting["queried_track_ids"]) != prepared_query["queried_trajectories"]
or query_accounting["queried_trajectory_samples"] != prepared_query["queried_trajectory_samples"]):
raise AssertionError("The real query changed the complete observed-track inventory")
scoring_began, scoring_cpu = time.perf_counter(), time.process_time()
partition = ({"anchor_window": fixture["anchor_window_s"]}
if "anchor_window_s" in fixture else {})
ranked, counts = tiled_search._score(
points, tracks, events, measurements, budget, fixture["scoring"], {},
start_window=fixture["recording_start_window_s"], ledger=ledger, stage=stage, **partition)
if args.include_track_query:
execution_stages["cpa_association_scoring_and_retention"] = {
"wall_seconds": time.perf_counter() - scoring_began,
"cpu_seconds": time.process_time() - scoring_cpu,
}
finally:
elapsed, cpu_seconds = time.perf_counter() - began, time.process_time() - cpu
diagnostic = diagnostic or timing_instrumentation_active()
matching._fit_ridge_uncached, Track.acoustic = original_fit, original_acoustic
tiled_search.score_candidate = original_score
if callable(native_fit):
matching._native_fit_irls = native_fit
if native_before is not None:
native_after = native_statistics()
delta = {key: native_after[key] - native_before[key] for key in native_before}
operations["native_fit_calls"] = delta["scalar_calls"] + delta["batch_rows"]
operations["native_fit_successes"] = delta["scalar_successes"] + delta["batch_successful_rows"]
operations["native_batch_calls"] = delta["batch_calls"]
operations["native_batch_rows"] = delta["batch_rows"]
if native_acoustic is not None:
operations["native_acoustic_successes"] = native_acoustic.successful_calls() - native_acoustic_before
if native_cpa is not None:
operations["native_cpa_successes"] = native_cpa.successful_calls() - native_cpa_before
for owner, attribute, function in reversed(phase_patches):
setattr(owner, attribute, function)
expected_counts = fixture.get("expected_counts")
if expected_counts is not None:
actual_counts = {"cpa_rows": counts["cpa_rows"],
"associations": counts["candidates"], "retained": len(ranked)}
changed_work_only = (args.clock_partition_query
and actual_counts["cpa_rows"] <= expected_counts["cpa_rows"]
and all(actual_counts[key] == expected_counts[key] for key in ("associations", "retained")))
if actual_counts != expected_counts and not changed_work_only:
raise AssertionError(f"Recorded workload counts changed: {actual_counts}")
# Linux ru_maxrss can include the comparison parent's high-water mark
# inherited across fork/exec. VmHWM belongs to this worker's address space.
# Keep unknown platforms usable without guessing a memory unit or scope.
peak_rss_mib = None
peak_rss_method = "Unavailable on this platform"
if sys.platform.startswith("linux"):
try:
for line in Path("/proc/self/status").read_text().splitlines():
if line.startswith("VmHWM:"):
fields = line.split()
if len(fields) == 3 and fields[2] == "kB":
peak_rss_mib = int(fields[1]) / 1024
peak_rss_method = "/proc/self/status VmHWM after exec"
break
except (OSError, ValueError):
pass
elif resource is not None and sys.platform == "darwin":
peak_rss_mib = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss / (1024 * 1024)
peak_rss_method = "resource.getrusage(RUSAGE_SELF).ru_maxrss"
checksum = ledger.checksum(stage)
if not ledger.stage_valid(stage, checksum):
raise AssertionError("The scoring pass produced an invalid retention ledger")
if not operations["scored_candidates"]:
raise AssertionError("The benchmark did not score any real associations")
if (args.require_native and (args.instrument_numerics or native_before is not None)
and not operations["native_fit_successes"]):
raise AssertionError("No successful native ridge fit occurred inside the timed scoring call")
if args.require_native_acoustic and not operations["native_acoustic_successes"]:
raise AssertionError("No successful native acoustic solve occurred inside the timed scoring call")
if args.require_native_cpa and not operations.get("native_cpa_successes"):
raise AssertionError("No successful native CPA reduction occurred inside the timed scoring call")
with ledger.connect() as database:
retention = {name: database.execute(f"SELECT * FROM {name} ORDER BY 1,2").fetchall()
for name in ("records", "bounds", "stages")}
results = {"ranked": ranked, "counts": counts,
"all_scored_candidates": all_rows, "retention": retention}
if query_accounting is not None:
results["track_query_accounting"] = query_accounting
write_new(args.output / "results.json", results)
summary = {"wall_seconds": elapsed, "cpu_seconds": cpu_seconds,
"load_seconds_excluded": load_seconds, "operations": operations,
"numerical_functions_canonical": not (args.instrument_numerics or args.stage_timing),
"performance_timing_eligible": not diagnostic,
"ridge_execution_check": ("In-module successful-call counters" if native_before is not None else
"Wrapped successful-call counters" if args.instrument_numerics else
"Backend availability; successful-call count unmeasured"),
"ridge_fit_backend": ridge_backend, "acoustic_backend": acoustic_backend,
"native_extension_available": callable(native_fit),
"peak_rss_mib": peak_rss_mib,
"peak_rss_measurement": peak_rss_method,
"peak_rss_scope": ("Worker lifetime through scoring, including imports and input loading"
if peak_rss_mib is not None else "Unavailable on this platform"),
"retained": len(ranked), "independent_groups": len(events), "scope": fixture["scope"]}
if "anchor_window_s" in fixture:
summary["anchor_window_s"] = fixture["anchor_window_s"]
if args.include_track_query:
summary["track_query_operations"] = query_operations
summary["clock_partition_time_narrowed"] = query_accounting["clock_partition_time_narrowed"]
summary["execution_stage_seconds"] = execution_stages
summary["timing_scope"] = (
"Initial local index traversal and conservative distance sieve, followed by complete "
"CPA/association scoring and retention. Excludes imports, index metadata, event "
"preparation, downloads, terrain sampling, audio discovery, and refinement.")
if args.stage_timing:
summary["phase_seconds"] = phase_seconds
summary["phase_timing_scope"] = "Inclusive instrumented call times; overlapping phases must not be summed."
write_new(args.output / "summary.json", summary)
print(json.dumps(summary), flush=True)
def compare(args):
args.output.mkdir(parents=True, exist_ok=False)
sources = {"baseline": args.baseline_source.resolve(), "current": args.current_source.resolve()}
environment = dict(os.environ)
for variable in ("OPENBLAS_NUM_THREADS", "OMP_NUM_THREADS", "MKL_NUM_THREADS"):
environment[variable] = "1"
runs, expected, source_payloads, source_canonical = [], None, {}, {}
for repetition in range(args.repeats):
order = ("baseline", "current") if repetition % 2 == 0 else ("current", "baseline")
for name in order:
output = args.output / f"{repetition + 1}-{name}"
command = [sys.executable, str(Path(__file__).resolve()), "_worker", "--source", str(sources[name]),
"--fixture", str(args.fixture.resolve()), "--output", str(output.resolve())]
if args.index:
command.extend(["--index", str(args.index.resolve())])
if args.stage_timing:
command.append("--stage-timing")
if args.include_track_query:
command.append("--include-track-query")
if args.clock_partition_query:
command.append("--clock-partition-query")
if args.instrument_numerics:
command.append("--instrument-numerics")
if name == "current" and args.require_current_native:
command.append("--require-native")
if name == "current" and args.require_current_native_acoustic:
command.append("--require-native-acoustic")
if name == "current" and args.require_current_native_cpa:
command.append("--require-native-cpa")
subprocess.run(command, check=True, env=environment, timeout=args.timeout_s)
result = json.loads((output / "results.json").read_text())
complete = canonical(result)
if name in source_canonical and source_canonical[name] != complete:
raise AssertionError(f"Repeated source output was not deterministic: {output}")
source_canonical[name] = complete
source_payloads[name] = result
payload = canonical(partition_outcomes(result) if args.clock_partition_query else result)
if expected is None:
expected = payload
elif payload != expected:
raise AssertionError(f"Exact candidate, diagnostic, support, or retention mismatch: {output}")
summary = json.loads((output / "summary.json").read_text())
runs.append({"source": name, "repetition": repetition + 1, **summary})
medians = {}
for name in sources:
medians[name] = {}
for metric in ("wall_seconds", "cpu_seconds", "peak_rss_mib"):
values = [row[metric] for row in runs if row["source"] == name and row[metric] is not None]
medians[name][metric] = statistics.median(values) if values else None
report = {"identical_results": source_canonical["baseline"] == source_canonical["current"],
"identical_scored_candidates_rankings_and_retention": True, "repeats": args.repeats,
"fixture": str(args.fixture.resolve()),
"sources": {name: str(path) for name, path in sources.items()}, "medians": medians,
"speedup": {metric: medians["baseline"][metric] / medians["current"][metric]
for metric in ("wall_seconds", "cpu_seconds")},
"scope": runs[0]["scope"], "runs": runs}
if args.clock_partition_query:
report["clock_partition_query_verification"] = verify_partition_work(
source_payloads["baseline"], source_payloads["current"])
report["equality_scope"] = (
"Exact scored candidate payloads, rankings, trial/support evidence and retention records. "
"Early query/CPA/event/work counts may decrease; every removed unsupported track's "
"complete emission interval must miss the proved partition interval.")
report["performance_timing_eligible"] = all(row["performance_timing_eligible"] for row in runs)
if not report["performance_timing_eligible"]:
report["diagnostic_ratio"] = report["speedup"]
report["speedup"] = None
if args.include_track_query:
report["timing_scope"] = runs[0]["timing_scope"]
report["track_query_included"] = True
report["execution_stage_medians"] = {
name: {stage: {metric: statistics.median(
row["execution_stage_seconds"][stage][metric]
for row in runs if row["source"] == name)
for metric in ("wall_seconds", "cpu_seconds")}
for stage in runs[0]["execution_stage_seconds"]}
for name in sources}
write_new(args.output / "comparison.json", report)
print(json.dumps({key: report[key] for key in ("identical_results", "medians", "speedup", "scope")}), flush=True)
def main():
parser = argparse.ArgumentParser(description=__doc__)
commands = parser.add_subparsers(dest="command", required=True)
preparation = commands.add_parser("prepare", help="Freeze a real observed-data scoring workload")
preparation.add_argument("--discovery", required=True, type=Path)
preparation.add_argument("--index", required=True, type=Path)
preparation.add_argument("--reference-report", type=Path,
default=ROOT / "evidence/results/reference-local/report.json")
preparation.add_argument("--clock-half-width-s", type=float, default=120.0)
preparation.add_argument("--full-day", action="store_true", help="Use all indexed times with an unknown clock")
preparation.add_argument("--anchor-window-s", nargs=2, type=float, metavar=("LOW", "HIGH"),
help="Optional half-open association ownership partition; physical fit windows remain unchanged")
preparation.add_argument("--include-track-query", action="store_true",
help="Prepare the production query/sieve workload; budgets bound retained tracks, including overloaded queries")
preparation.add_argument("--max-tracks", type=int, default=5000)
preparation.add_argument("--max-samples", type=int, default=1000000)
preparation.add_argument("--max-candidates", type=int, default=20000)
preparation.add_argument("--top-k", type=int, default=100)
preparation.add_argument("--output", required=True, type=Path)
comparison = commands.add_parser("compare", help="Require exact output parity before reporting speedup")
comparison.add_argument("--fixture", required=True, type=Path)
comparison.add_argument("--index", type=Path)
comparison.add_argument("--baseline-source", required=True, type=Path, help="Baseline src/ directory")
comparison.add_argument("--current-source", type=Path, default=ROOT / "src")
comparison.add_argument("--repeats", type=int, default=3)
comparison.add_argument("--timeout-s", type=float, default=600.0)
comparison.add_argument("--output", required=True, type=Path)
comparison.add_argument("--stage-timing", action="store_true",
help="Collect inclusive phase times in a separate diagnostic run")
comparison.add_argument("--include-track-query", action="store_true",
help="Include initial index traversal and the production overload sieve in each timed worker")
comparison.add_argument("--clock-partition-query", action="store_true",
help="Exercise the production clock-partition query bound where available; verify exact outcomes and explain reduced work")
comparison.add_argument("--instrument-numerics", action="store_true",
help="Diagnostic only: wrap numerical calls for counters; changes execution overhead")
comparison.add_argument("--require-current-native", action="store_true",
help="Require successful native ridge fits inside each current scoring run")
comparison.add_argument("--require-current-native-acoustic", action="store_true",
help="Require successful native acoustic solves inside each current scoring run")
comparison.add_argument("--require-current-native-cpa", action="store_true",
help="Require successful native CPA reductions inside each current scoring run")
internal = commands.add_parser("_worker", help=argparse.SUPPRESS)
internal.add_argument("--source", required=True, type=Path)
internal.add_argument("--fixture", required=True, type=Path)
internal.add_argument("--index", type=Path)
internal.add_argument("--output", required=True, type=Path)
internal.add_argument("--stage-timing", action="store_true", help=argparse.SUPPRESS)
internal.add_argument("--instrument-numerics", action="store_true", help=argparse.SUPPRESS)
internal.add_argument("--include-track-query", action="store_true", help=argparse.SUPPRESS)
internal.add_argument("--clock-partition-query", action="store_true", help=argparse.SUPPRESS)
internal.add_argument("--require-native", action="store_true", help=argparse.SUPPRESS)
internal.add_argument("--require-native-acoustic", action="store_true", help=argparse.SUPPRESS)
internal.add_argument("--require-native-cpa", action="store_true", help=argparse.SUPPRESS)
args = parser.parse_args()
if args.command == "prepare":
if args.clock_half_width_s < 0:
parser.error("--clock-half-width-s must be nonnegative")
if (args.anchor_window_s is not None
and (not all(math.isfinite(value) for value in args.anchor_window_s)
or args.anchor_window_s[0] >= args.anchor_window_s[1])):
parser.error("--anchor-window-s requires finite increasing endpoints")
sys.path.insert(0, str(ROOT / "src"))
prepare(args)
elif args.command == "compare":
if args.repeats < 1 or args.timeout_s <= 0:
parser.error("--repeats and --timeout-s must be positive")
if args.clock_partition_query:
fixture = json.loads(args.fixture.read_text())
if not args.include_track_query or "anchor_window_s" not in fixture:
parser.error("--clock-partition-query requires --include-track-query and a recorded anchor partition")
compare(args)
else:
worker(args)
if __name__ == "__main__":
main()