[jsteinberg34]

Why

track_to_box_windows padded every box window with post_pad_minutes=13 and bounded it with corridor_km=100. Both were unexplained constants. The post-pad is 82.8% of every byte the pipeline downloads (a typical box window is 120 s pre-pad + ~42 s of actual transit + 780 s post-pad), so the dominant cost term in the whole pipeline had no stated basis, and neither did the corridor that determines how many stations get queried.

Neidhart et al. (2021), PASA 38, e016 supplies both, from a survey of 1,410 fireballs against the Australian National Seismograph Network.

What changes

The post-pad is now derived:

post_pad = min(sqrt(corridor_km² + 100²), 215) / celerity_km_s + margin_seconds

All three constants are cited:

• 215 km — "Beyond 215 km we do not detect any unambiguous seismic signals [...] It is therefore reasonable to place a threshold at 215 km as an approximate limit for the seismic detection of fireballs." (Section 4). Stated as a "direct air distance", so a true slant range, which means no height correction is needed.
• 0.30 km/s — their reported celerity (300 ± 60 m/s), used in the paper to convert direct distances into airwave arrival times, exactly the operation performed here.
• 100 km — the continuum-flow limit above which the mean free path is too large for a shock to form at all. Corroborated by the paper's observed mean bright-flight start height of 86 ± 25 km.

Resulting window by corridor width:

corridor_km	post-pad
50 km	7.21 min
100 km	8.86 min
150 km	11.02 min
200 km (new default)	12.94 min

Above ~190 km the envelope binds and the pad stops growing, since no signal has ever been observed from farther away.

Changed default behaviour

corridor_km defaults to 200 km, up from 100. Roughly twice the stations queried per box, so expect download volume to roughly double. This is deliberate: it buys coverage to the edge of the published detectability envelope. corridor_km=100, post_pad_minutes=13 restores the previous behaviour exactly.

No API is broken by this: no signature is incompatible, no call site needs editing, and nothing raises. Existing code runs unchanged and produces valid output, it just downloads more of it.

The derived pad at the new default is 12.94 min against the previous fixed 13, so the window length itself barely moves. What changes is that it now responds to corridor_km, which it previously did not.

Also

• Added celerity_km_s (0.30) and margin_seconds (60) to track_to_box_windows and run_pipeline. Celerity is the largest lever here: the paper's ±60 m/s spans 10.95 to 15.93 minutes of pad at the default corridor.
• Two silent-failure modes now warn: a post_pad_minutes shorter than the corridor requires, and a corridor_km above 210 km (the widest ground offset consistent with a 215 km slant envelope, since the object is always at altitude).
• derive_post_pad_minutes and max_corridor_km are exported so a caller can check what window a configuration implies before running.
• The three acoustic constants are deliberately not parameters. They are published survey results, not preferences, and the only motive to lower them is downloading less data. A signature-inspection test enforces this.
• derive_post_pad_minutes raises ValueError on non-positive celerity. It previously returned a negative pad, which would place t_download_end before t_exit — an inverted window indistinguishable from a short download.

Verification

All eight onsets reported in two independent papers (Eickhoff et al. 2026 for Starlink-2382, Hupe et al. 2026 for the Falcon 9 R/B) still fall inside the download window under the new defaults, at both 100 km and 200 km corridors. The largest pad any of them needed was 2.27 minutes.

222 tests pass. Each of the five commits is green independently. tests/test_regression_shenzhou15.py is untouched — it pins every parameter explicitly, so its passing is the check that the override path still works.

Caveats worth knowing

• Neidhart is a fireball survey, not a spacecraft one. Its 215 km is the extreme tail of a 1.8% detection rate (25 detections from 1,410 events). Measured against three real re-entries, the largest requirement was 5.2 minutes and no confirmed detection appeared beyond 76 km cross-track, roughly 2.5x inside the envelope. The envelope is being adopted as a conservative cited default, with that gap reported as margin rather than treated as agreement.
• The paper used a slower celerity for its own search window. Their 28-minute window for stations within 400 km implies ~0.238 km/s, the −1σ end of their own figure. Using 0.30 is a deliberate departure, supported by an independent fit to CLARITY-1 data that disfavours the slow end (RMSE 31.0 s at 0.24 versus 22.3 s at 0.30).
• margin_seconds = 60 is smaller than the 100-200 s of measured SGP4 along-track error. It works because the acoustic term carries ~400 s of unused headroom at a 200 km corridor. That slack shrinks as the corridor narrows and should be revisited if narrow corridors become routine.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!