Skip to content

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

fix(#7): cap recursive tile evaluations per run

Cinna Davis890c82dcd389
diff --git a/docs/PRODUCT.md b/docs/PRODUCT.md
index 7bd8d72..7700a36 100644
--- a/docs/PRODUCT.md
+++ b/docs/PRODUCT.md
@@ -294,12 +294,18 @@ does not establish real terrain or altitude-datum accuracy. Its result retains
that limitation for real recordings.
Local overrides require prebuilt indexes and retain their actual coverage.
-`search_budget.max_tiles` bounds tile work. Reaching a tile, memory, data or wall
-time limit leaves incomplete coverage and cannot produce a supported national
-location. Full search completion does not prove the archive captured every real
-aircraft. Grid finalists undergo jointly constrained position/clock refinement;
-`refine_finalists` (default 5) limits physical sensitivity refinement. Unassessed
-retained approaches prevent an affirmative confidence decision.
+`search_budget.max_tiles` limits the initial root-tile prefix. Recursive
+subdivision can create more work than that root limit, so use
+`search_budget.max_tile_evaluations` to cap newly scored coarse tiles in one
+search invocation. Verified tile checkpoints do not consume that per-invocation
+allowance, allowing a later resume to continue with the same configuration.
+Exhausting the work cap leaves the result partial. Reaching a tile, memory, data
+or wall-time limit leaves incomplete coverage and cannot produce a supported
+national location. Full search completion does not prove the archive captured
+every real aircraft. Grid finalists undergo jointly constrained position/clock
+refinement; `refine_finalists` (default 5) limits physical sensitivity
+refinement. Unassessed retained approaches prevent an affirmative confidence
+decision.
For chunk-boundary checks on real recordings, an operator can set
`"discovery": {"chunk_s": 120.0, "overlap_s": 60.0}` in this private configuration.
diff --git a/src/dopplergeist/tiled_search.py b/src/dopplergeist/tiled_search.py
index c7230eb..06a1014 100644
--- a/src/dopplergeist/tiled_search.py
+++ b/src/dopplergeist/tiled_search.py
@@ -75,10 +75,12 @@ class SearchBudget:
refine_finalists: int = 10
cpa_step_s: float = 2.0
max_tiles: int | None = None
+ max_tile_evaluations: int | None = None
def __post_init__(self):
integer_fields = ("tile_cells", "max_tracks_per_tile", "max_track_samples_per_tile", "max_cpa_rows",
- "max_candidates_per_tile", "top_k", "refine_finalists", "max_tiles")
+ "max_candidates_per_tile", "top_k", "refine_finalists", "max_tiles",
+ "max_tile_evaluations")
for name, value in asdict(self).items():
if value is not None and (not np.isfinite(value) or value <= 0):
raise ValueError(f"{name} must be positive and finite")
@@ -915,7 +917,7 @@ def search_national(indexes, terrain, events, measurements, *, time_range_s, out
workers = max(1, available - 1)
if type(workers) is not int or workers < 1:
raise ValueError("workers must be a positive integer")
- workers = min(workers, total, budget.max_tiles or total)
+ workers = min(workers, total, budget.max_tiles or total, budget.max_tile_evaluations or total)
# GDAL virtual/in-memory datasets can be valid in the parent but cannot
# necessarily be reopened in a spawned process. Preserve the serial path
# for those inputs instead of turning a working search into a failed one.
@@ -996,6 +998,7 @@ def search_national(indexes, terrain, events, measurements, *, time_range_s, out
elif has_fine_checkpoints:
raise DataUnavailable("Fine-stage checkpoint configuration is missing")
began, ranked, failures, done, processed_cells, resumed, points_searched = time.monotonic(), [], [], 0, 0, 0, 0
+ tile_evaluations_started, tile_budget_exhausted = 0, False
counted_clock_cells = set()
support = dict(unsupported_cpa_track_evaluations=0, unclassified_score_candidates=0,
bounded_score_candidates=0, unbounded_score_candidates=0,
@@ -1061,11 +1064,18 @@ def search_national(indexes, terrain, events, measurements, *, time_range_s, out
return stage, cells, cached, None
def requests_for_wave(wave, next_wave):
- nonlocal total
+ nonlocal total, tile_evaluations_started, tile_budget_exhausted
for tile_id, cells in wave:
marker = output / f"split-{tile_id}.json"
if not marker.exists():
- yield tile_request(tile_id, cells)
+ request = tile_request(tile_id, cells)
+ if request[2] is None:
+ if (budget.max_tile_evaluations is not None
+ and tile_evaluations_started >= budget.max_tile_evaluations):
+ tile_budget_exhausted = True
+ continue
+ tile_evaluations_started += 1
+ yield request
continue
try:
record = json.loads(marker.read_text())
@@ -1406,7 +1416,8 @@ def search_national(indexes, terrain, events, measurements, *, time_range_s, out
model_assessed = not (support["unsupported_cpa_track_evaluations"] or support["unbounded_score_candidates"]
or support["unreported_trial_envelopes"])
model_assessed &= support["bounded_score_candidates"] == support["unclassified_score_candidates"]
- complete = done == total and not failures and not refinement_failure and data_complete and not event_limit_applied and model_assessed
+ complete = (done == total and not failures and not refinement_failure and data_complete
+ and not event_limit_applied and model_assessed and not tile_budget_exhausted)
finite = ledger.evidence(ranked, complete=complete, spacing_m=budget.spacing_m,
refine_spacing_m=min(budget.spacing_m, budget.refine_spacing_m), max_event_groups=len(events),
expected_stages={"coarse": done, "global": done, "fine": fine_stages, "fine-global": fine_stages})
@@ -1439,6 +1450,9 @@ def search_national(indexes, terrain, events, measurements, *, time_range_s, out
"model_assessment_complete": model_assessed,
"refinement_points_searched": refinement_points_searched, "refinement_points_skipped": refinement_points_skipped,
"refinement_stages_resumed": fine_resumed,
+ "tile_work_budget": {"max_new_tile_evaluations_per_invocation": budget.max_tile_evaluations,
+ "new_tile_evaluations_started": tile_evaluations_started,
+ "exhausted": tile_budget_exhausted},
"required_flight_bounds": flight_bounds,
"candidate_retention_limit": budget.top_k, "alternative_modes_exhaustively_assessed": False,
"finite_search_evidence": finite,