astro-tools/maneuver-detect-transformer-base

transformer-base

A transformer maneuver detector for maneuver-detect. It localises maneuvers in a satellite's mean-element TLE history; the same vis-viva / Gauss physics inversion the classical detector uses then recovers the Δv magnitude and maneuver type for each detection (the model localises, the physics inverts).

How to use

The checkpoint is fetched from this repo automatically on first use — CPU-only, cached on disk, no weights at install time:

from maneuver_detect import detect, datasets

history = datasets.tle_history(norad_id=25544, start="2024-01-01")
maneuvers = detect(history, model="transformer-base")
# DataFrame columns: epoch, confidence, type, delta_v_estimate, plus provenance

Model description

• Architecture: transformer sequence network, 9,486,337 parameters.
• Input: the frozen irregular-sampling encoding (time-encoded element deltas, no interpolation); inputs are standardised with the train-split per-class statistics frozen into this checkpoint, so inference reproduces training-time standardisation.
• Window / stride: 64 / 32.
• Default detection threshold: 0.400.
• Per-class detection thresholds: LEO 0.600, MEO 0.800, GEO 0.200, IGSO 0.100 (a class without its own gate uses the default above).
• Inference: CPU-only; the bundle ships the network weights, the normaliser, and these parameters together, so loading it never needs the training stack.

Training data

Trained on the maneuver-detect labelled dataset v0.3.0 (astro-tools/maneuver-detect), versioned in lockstep with this checkpoint. The dataset is distributed recipe-first (operator labels + a pinned reconstruction recipe + a content-hash manifest; the raw Space-Track element history is never redistributed) and partitioned by the frozen, leak-free temporal-holdout splits — novel satellites scored in novel eras.

Evaluation

Held-out test split — recall/precision at 1 false alarm(s)/satellite-year over the above-floor population (95% CI). Operating pt is the per-class confidence cut admitted within that false-alarm budget (in the detector's calibrated confidence units). Type acc is the share of above-floor true positives whose maneuver type is correct.

Class	Recall	Precision	Operating pt	Above-floor labels	Type acc
LEO	0.44	0.91	0.98	71	0.32
MEO	0.29	0.17	0.87	14	—
GEO	0.00	0.00	1.00	71	—
IGSO	0.00	0.00	0.63	3	—
HEO	—	—	—	0	—

This detector emits calibrated confidence: the raw score is mapped through a temperature (T = 1.000) fit on the val split only, so a confidence of p means about a fraction p of detections at that confidence are real. A split-conformal predictor (marginal coverage 90%) accompanies it for prediction sets. Per-orbit-class expected calibration error (ECE) of the calibrated confidence:

Class	ECE
LEO	0.512
MEO	0.673
GEO	0.274
IGSO	0.292
HEO	0.000

The per-class reliability diagrams and the calibrated per-class operating points are published in the benchmark documentation.

Best validation-split above-floor recall during training: 0.459.

The benchmark scores precision/recall at a fixed false-alarm rate per orbit class over the above-floor population, with per-class type confusion, via the deterministic scorer. Performance is sharply data-quality-stratified: well-tracked modern satellites reach literature-level recall, while noisy historical series are bounded by the TLE detectability floor.

Intended use and limitations

• Use: post-hoc detection of orbital maneuvers from public TLE history for space-situational- awareness research and as a reproducible benchmark baseline.
• Not a maneuver predictor (it detects maneuvers that already happened), not real-time, and not an orbit-determination engine.
• Detectability floor: maneuvers below the per-object TLE detectability floor are not reported; recall on noisy historical series is fundamentally limited by TLE data quality, not the model.
• MEO/GEO labels are epoch-only (no Δv), so the Δv estimate is most meaningful on the Δv-labelled LEO core.

Provenance

• Dataset version (lockstep): v0.3.0
• Parameters: 9,486,337

field	value
best_val_recall	0.4591
dataset_version	0.3.0
loss	bce
optimizer	adamw
scheduler	warmup_cosine
seed	0

License

Model weights: MIT. The dataset and authored artifacts are CC-BY-4.0; the raw Space-Track element history is never redistributed. See the repository for the full source terms, and CITATION.cff to cite.