--- license: apache-2.0 tags: - trajectory-prediction - aviation - adsb - time-series - llm-reprogramming - gpt2 - air-traffic-management - spatiotemporal datasets: - petchthwr/ATFMTraj pipeline_tag: time-series-forecasting --- # LLM4AirTrack: LLM-Driven Multi-Feature Fusion for Aircraft Trajectory Prediction ## Overview **LLM4AirTrack** adapts the [LLM4STP](https://github.com/Joker-hang/LLM4STP) (Large Language Model for Ship Trajectory Prediction) framework from maritime AIS to aviation ADS-B domain. The core insight is that pre-trained LLMs encode powerful sequential pattern recognition that transfers to spatiotemporal trajectory data through lightweight reprogramming — without full fine-tuning. The framework uses a **frozen GPT-2 backbone** with trainable adapter modules (~2.4% of total parameters) to predict future aircraft positions and classify flight routes/procedures. ## Architecture ``` ┌─────────────────────────────────────────────────────────────────┐ │ LLM4AirTrack Framework │ │ │ │ ADS-B Features (9-dim: xyz + direction + polar) │ │ │ │ │ ▼ │ │ ┌──────────────────┐ │ │ │ RevIN Normalizer │ Instance normalization per feature │ │ └──────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────┐ │ │ │ Patch Tokenizer │ Overlapping temporal patches (8×9=72) │ │ └──────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────┐ ┌─────────────────────┐ │ │ │ Patch Embedder │ │ Text Prototype Bank │ │ │ │ (72 → 768) │ │ (256 learned protos) │ │ │ └──────────────────┘ └─────────────────────┘ │ │ │ │ │ │ ▼ ▼ │ │ ┌──────────────────────────────────────┐ │ │ │ Cross-Attention Reprogrammer │ │ │ │ Q=patches, K=V=prototypes (8-head) │ │ │ │ Maps trajectory → LLM text space │ │ │ └──────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────┐ │ │ │ Prompt-as-Prefix │ Aviation context prompt prepended │ │ └──────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────┐ │ │ │ Frozen GPT-2 │ 124M params frozen, language knowledge │ │ └──────────────────┘ │ │ │ │ │ ├──────────────────┐ │ │ ▼ ▼ │ │ ┌──────────┐ ┌──────────────────┐ │ │ │ Traj Head│ │ Classification │ │ │ │ (xyz) │ │ Head (route/rwy) │ │ │ └──────────┘ └──────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Key Components 1. **9-Dimensional Kinematic Features** (from [ATSCC](https://arxiv.org/abs/2407.20028)): - Position: (x, y, z) in East-North-Up coordinates - Directional unit vectors: (ux, uy, uz) — velocity direction - Polar components: (r, sin θ, cos θ) — angular position 2. **Patch Tokenization**: Overlapping temporal windows (patch_len=8, stride=4) → 14 patches from 60-step context 3. **Cross-Attention Reprogramming** (from [Time-LLM](https://arxiv.org/abs/2310.01728)): 256 learned text prototypes serve as a "translation dictionary" between trajectory and language domains 4. **Frozen GPT-2 Backbone**: 124M frozen parameters preserve pre-trained language understanding while keeping training efficient 5. **Dual Output Heads**: - **Trajectory Prediction**: Future (x, y, z) positions via Smooth L1 loss - **Route Classification**: STAR/IAF/Runway procedure via Cross-Entropy loss ### Parameter Efficiency | Component | Parameters | Trainable | |-----------|-----------|-----------| | GPT-2 Backbone | 124,439,808 | 0 (frozen) | | Patch Embedder | 57,600 | 57,600 | | Cross-Attention Reprogrammer | 2,560,512 | 2,560,512 | | Trajectory Head | 329,946 | 329,946 | | Classification Head | 150,543 | 150,543 | | **Total** | **127,543,059** | **3,103,251 (2.43%)** | ## Training ### Dataset - **Source**: [ATFMTraj](https://huggingface.co/datasets/petchthwr/ATFMTraj) — RKSIa (Incheon International Airport arrivals) - **Origin**: OpenSky ADS-B recordings, 2018-2023 - **Preprocessing**: Raw lat/lon/alt → ENU coordinates → normalized to [-1,1] by r_max=120km - **Trajectories**: 8,091 training + 8,092 test (16,183 total flights) - **Windows**: 282,191 training + 20,000 evaluation sliding windows - **Context**: 60 timesteps (1-second intervals = 1 minute of flight) - **Prediction**: 30 timesteps ahead (30 seconds) - **Classes**: 39 route labels (STAR × IAF × Runway combinations) ### Hyperparameters | Parameter | Value | |-----------|-------| | LLM Backbone | `openai-community/gpt2` (768 hidden, 12 layers) | | Optimizer | AdamW (β₁=0.9, β₂=0.999) | | Learning Rate | 5×10⁻⁴ with cosine annealing warm restarts | | Weight Decay | 1×10⁻⁵ | | Batch Size | 128 | | Epochs | 5 | | Gradient Clipping | max_norm=1.0 | | Multi-task Weight | λ_traj=1.0, λ_cls=0.1 | | Loss (trajectory) | Smooth L1 (Huber) | | Loss (classification) | Cross-Entropy | | Hardware | NVIDIA T4 (16GB VRAM, used ~1.4GB) | ## Results | Epoch | Train Loss | ADE | FDE | Route Accuracy | |-------|-----------|-----|-----|----------------| | 1 | 0.2335 | 0.01500 | 0.02047 | 34.7% | | 2 | 0.2110 | 0.01200 | 0.01635 | 36.1% | | **3** | **0.2033** | **0.01026** | **0.01426** | **36.3%** | | 4 | 0.2037 | 0.01345 | 0.01858 | 34.9% | | 5 | 0.2003 | 0.01518 | 0.02043 | 36.5% | **Best model (epoch 3)**: - **ADE: 0.01026** (normalized ENU scale; with r_max=120km → ~1.23km average displacement) - **FDE: 0.01426** (~1.71km final displacement error at 30s horizon) - **Route Classification: 36.3%** accuracy over 39 classes (14× above random baseline of 2.6%) - **RMSE**: x=0.00957, y=0.00942, z=0.00072 (altitude prediction is very accurate) ## Usage ### Quick Inference ```python import torch import json from huggingface_hub import hf_hub_download # Download model files config_path = hf_hub_download("Jdice27/LLM4AirTrack", "config.json") weights_path = hf_hub_download("Jdice27/LLM4AirTrack", "adapter_weights.pt") # You can use the self-contained train_full.py or the modular llm4airtrack package from llm4airtrack.model import LLM4AirTrack with open(config_path) as f: cfg = json.load(f) model = LLM4AirTrack( llm_name=cfg["llm_name"], context_len=cfg["context_len"], pred_len=cfg["pred_len"], n_classes=cfg["n_classes"], n_prototypes=cfg["n_prototypes"], patch_len=cfg["patch_len"], patch_stride=cfg["patch_stride"], ) state = torch.load(weights_path, map_location="cpu") model.load_state_dict(state, strict=False) model.eval() # Input: 60 timesteps × 9 kinematic features # Features: [x, y, z, ux, uy, uz, r, sin_θ, cos_θ] in ENU coordinates context = torch.randn(1, 60, 9) # Replace with real data outputs = model(context, task="both") future_xyz = outputs["pred_trajectory"] # (1, 30, 3) — future ENU positions route_probs = outputs["pred_class"].softmax(-1) # (1, 39) — route probabilities ``` ### Data Pipeline ```python from llm4airtrack.data import download_atfm_dataset, load_atfm_raw, compute_kinematic_features # Download and load ATFMTraj download_atfm_dataset("RKSIa", cache_dir="./data") data, labels = load_atfm_raw("RKSIa", "TEST", "./data") # Get kinematic features for a single trajectory traj = data[0] # (T_max, 3) ENU coordinates valid = ~np.isnan(traj[:, 0]) features = compute_kinematic_features(traj[valid]) # (T, 9) ``` ## Downstream Tasks The model produces rich trajectory representations suitable for: | Task | How to Use | |------|-----------| | **Track Activity Classification** | Use `pred_class` output — identifies STAR/IAF/runway procedure | | **Trajectory Prediction** | Use `pred_trajectory` — 30-second position forecast | | **Anomaly Detection** | Compare `pred_trajectory` vs actual — large deviations flag anomalies | | **Conflict Detection** | Run on multiple aircraft, check predicted trajectory intersections | | **ETA Prediction** | Extract LLM hidden states as features for regression head | | **Transfer to New Airports** | Fine-tune adapter weights on new airport data (ESSA, LSZH included in ATFMTraj) | ## Design Decisions & Adaptation from Maritime (LLM4STP) to Aviation (ADS-B) | Aspect | LLM4STP (Maritime AIS) | LLM4AirTrack (Aviation ADS-B) | |--------|----------------------|-------------------------------| | Dimensionality | 2D (lat, lon) | **3D (lat, lon, altitude → ENU xyz)** | | Features | SOG, COG, ROT | Ground speed → directional vectors; vertical rate → uz | | Update Rate | ~10s intervals | **1s intervals** (higher resolution) | | Route Structure | Free navigation | **Defined STARs/SIDs** (structured procedures) | | Context | Port/strait proximity | Airport/procedure context (encoded in prompt) | | Phase Segmentation | Anchoring/transiting | Climb/cruise/descent/approach | | Classification | Vessel type | **Route procedure (39 STAR×IAF×RWY classes)** | | Spatial Encoding | Lat/lon directly | **ENU Cartesian + polar components** | ## References ### Foundational Work - **LLM4STP**: [GitHub](https://github.com/Joker-hang/LLM4STP) — Original maritime trajectory prediction framework - **Time-LLM**: [arXiv 2310.01728](https://arxiv.org/abs/2310.01728) — LLM reprogramming for time series (ICLR 2024) ### Aviation Domain - **ATSCC**: [arXiv 2407.20028](https://arxiv.org/abs/2407.20028) — Self-supervised trajectory representation, 9-dim feature engineering - **LLM4Delay**: [arXiv 2510.23636](https://arxiv.org/abs/2510.23636) — Cross-modality LLM for aviation delay prediction - **ATFMTraj**: [HuggingFace Dataset](https://huggingface.co/datasets/petchthwr/ATFMTraj) — Aircraft trajectory classification data ### Related Approaches - **Flight2Vec**: [arXiv 2412.16581](https://arxiv.org/abs/2412.16581) — Behavior-adaptive patching for flight trajectories - **H3+CLM**: [arXiv 2405.09596](https://arxiv.org/abs/2405.09596) — Spatial tokenization for trajectory prediction - **SKETCH**: [arXiv 2601.18537](https://arxiv.org/abs/2601.18537) — Semantic key-point conditioning ## Citation ```bibtex @misc{llm4airtrack2026, title={LLM4AirTrack: LLM-Driven Multi-Feature Fusion for Aircraft Trajectory Prediction}, author={Jdice27}, year={2026}, url={https://huggingface.co/Jdice27/LLM4AirTrack}, note={Adapted from LLM4STP for aviation ADS-B domain} } ```