Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,93 @@
+---
+license: apache-2.0
+tags:
+- trajectory-prediction
+- aviation
+- adsb
+- time-series
+- llm-reprogramming
+- gpt2
+datasets:
+- petchthwr/ATFMTraj
+pipeline_tag: time-series-forecasting
+---
+
+# LLM4AirTrack: LLM-Driven Aircraft Trajectory Prediction
+
+Adapts the [LLM4STP](https://github.com/Joker-hang/LLM4STP) framework from maritime AIS to aviation ADS-B.
+Uses a **frozen GPT-2 backbone** with lightweight trainable adapters (~2.4% of params).
+
+## Architecture
+
+```
+ADS-B Features (9-dim) → RevIN → Patch Tokenizer → Patch Embedder
+    → Cross-Attention Reprogrammer (learned text prototypes)
+    → Prompt-as-Prefix → Frozen GPT-2 Backbone
+    → Trajectory Head (future xyz) + Classification Head (STAR/runway)
+```
+
+### Key Components
+1. **9-dim Kinematic Features**: Position (x,y,z ENU) + Direction (ux,uy,uz) + Polar (r, sinθ, cosθ)
+2. **Patch Tokenization**: Overlapping temporal patches (len=8, stride=4)
+3. **Cross-Attention Reprogramming**: 256 learned text prototypes, 8-head attention
+4. **Frozen GPT-2**: 124M params frozen, only ~3.1M trainable
+5. **Dual Heads**: Trajectory prediction (Smooth L1) + Route classification (CE)
+
+## Training
+
+- **Dataset**: [ATFMTraj](https://huggingface.co/datasets/petchthwr/ATFMTraj) - RKSIa
+- **Source**: OpenSky ADS-B, Incheon International Airport arrivals (2018-2023)
+- **Context**: 60 timesteps (1s intervals)
+- **Prediction**: 30 timesteps ahead
+- **Optimizer**: AdamW, lr=0.0005, cosine annealing
+- **Epochs**: 5
+
+## Results
+
+| Metric | Value |
+|--------|-------|
+| ADE (normalized) | 0.010258 |
+| Best Epoch | 3 |
+| Route Classification Acc | 0.3649 |
+
+## Usage
+
+```python
+import torch, json
+from train_full import LLM4AirTrack
+
+# Load
+with open("config.json") 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"],
+)
+state = torch.load("adapter_weights.pt", map_location="cpu")
+model.load_state_dict(state, strict=False)
+model.eval()
+
+# Predict (input: 60 timesteps of 9-dim kinematic features)
+context = torch.randn(1, 60, 9)
+out = model(context)
+future_xyz = out["pred_trajectory"]  # (1, 30, 3)
+route_class = out["pred_class"].argmax(-1)  # (1,)
+```
+
+## Downstream Tasks
+
+- **Track Activity Classification**: Route/procedure identification from trajectory embeddings
+- **Anomaly Detection**: Flag deviations from predicted trajectory
+- **Conflict Detection**: Multi-aircraft trajectory forecasting
+- **ETA Prediction**: Time-to-threshold from trajectory state
+
+## References
+
+- [LLM4STP](https://github.com/Joker-hang/LLM4STP) - Original maritime framework
+- [Time-LLM](https://arxiv.org/abs/2310.01728) - Foundational reprogramming approach
+- [ATFMTraj](https://huggingface.co/datasets/petchthwr/ATFMTraj) - Aviation trajectory dataset
+- [ATSCC](https://arxiv.org/abs/2407.20028) - Self-supervised trajectory representation
+- [LLM4Delay](https://arxiv.org/abs/2510.23636) - Cross-modality LLM adaptation for aviation