README.md

---
license: apache-2.0
base_model: Datadog/Toto-2.0-2.5B
pipeline_tag: time-series-forecasting
library_name: pytorch
tags:
- time-series
- time-series-forecasting
- foundation-model
- fine-tuned
- satellite
- orbit-prediction
- orbit-propagation
- orbital-mechanics
- TLE
- SGP4
- space-weather
- LEO
- aerospace
- toto
language:
- en
- ko
metrics:
- rmse
model-index:
- name: OrbitFM
  results:
  - task:
      type: time-series-forecasting
      name: Satellite orbit prediction (TLE element forecasting)
    dataset:
      type: tle-archive
      name: Historical TLE archive (2005-2024, LEO) + CelesTrak SW-All space weather
    metrics:
    - type: rmse
      name: Median position RMSE @ 30-day horizon (km)
      value: 140.46
    - type: rmse
      name: Mean position RMSE @ 30-day horizon (km)
      value: 798.75
---

# OrbitFM — TLE-based Satellite Orbit Forecasting Model
# OrbitFM — TLE 기반 위성 궤도 예측 모델

**OrbitFM** is a satellite orbit prediction model that forecasts future orbital elements — and, through SGP4, future satellite **positions** — directly from a satellite's historical **Two-Line Element (TLE)** time series. It is built by continued pretraining (fine-tuning) of the [Datadog/Toto-2.0-2.5B](https://huggingface.co/Datadog/Toto-2.0-2.5B) time-series foundation model on 20 years (2005–2024) of cleaned, daily-resampled TLE records for low-Earth-orbit (LEO) objects, enriched with physics-derived features and **space-weather** (solar / geomagnetic) driver channels.

**OrbitFM**은 위성의 과거 **TLE(Two-Line Element)** 시계열로부터 미래 궤도 요소를 — 그리고 SGP4를 통해 미래 위성 **위치**를 — 직접 예측하는 위성 궤도 예측 모델입니다. 시계열 파운데이션 모델 [Datadog/Toto-2.0-2.5B](https://huggingface.co/Datadog/Toto-2.0-2.5B)를, 정제 후 일 단위로 재표집한 20년치(2005–2024) 저궤도(LEO) 위성 TLE 기록에 물리 파생 피처와 **우주기상**(태양·지자기 활동) 채널을 더해 continued pretraining(fine-tuning)하여 만들었습니다.

The standard operational approach — propagating the last observed TLE forward with SGP4 ("persistence") — is very strong at short horizons but degrades quickly as atmospheric drag, solar activity, and secular element drift accumulate. OrbitFM learns these drift dynamics from data: at horizons of **7 days and beyond it roughly halves the mean position error** of the SGP4 persistence baseline, and at the 30-day horizon it reduces the **median** per-satellite position RMSE from ≈966 km to ≈140 km, beating the baseline on **81.3%** of evaluated satellites.

기존 운용 방식 — 마지막으로 관측된 TLE를 SGP4로 전파하는 "persistence" 방식 — 은 단기 예측에서는 매우 강력하지만, 대기 항력·태양 활동·궤도 요소의 장기 drift가 누적될수록 오차가 빠르게 커집니다. OrbitFM은 이러한 drift 동역학을 데이터에서 학습합니다. **7일 이상 horizon에서 SGP4 persistence baseline의 평균 위치 오차를 약 절반으로** 줄이며, 30일 horizon에서는 위성별 위치 RMSE **중앙값**을 약 966 km에서 약 140 km로 낮추고 평가 대상 위성의 **81.3%**에서 baseline보다 우수한 결과를 보였습니다.

---

## Model Details / 모델 상세

| | |
|---|---|
| **Model type** | Decoder-style multivariate time-series foundation model (Toto-2 architecture), continued-pretrained for orbital element forecasting |
| **Base model** | [Datadog/Toto-2.0-2.5B](https://huggingface.co/Datadog/Toto-2.0-2.5B) (~2.5B parameters) |
| **Task** | Multivariate time-series forecasting → satellite orbital element / position prediction |
| **Input** | Per-satellite daily-grid multivariate series, **25 channels** (6 orbital targets + 16 physics features + 3 space-weather features), default context of 8 patches × 32 days = **256 days** (evaluation uses 64-day contexts) |
| **Output** | Quantile forecasts (pinball/quantile head) of the 6 orbital target channels over the forecast horizon; median quantile used for point forecasts |
| **Position reconstruction** | Predicted element drifts are anchored at the last observed TLE, integrated into absolute elements, and converted to TEME position via **SGP4** |
| **Training data** | Public TLE archives, 2005–2024, LEO objects only (median mean motion ≥ 11.25 rev/day), outlier-cleaned; space weather from [CelesTrak SW-All.csv](https://celestrak.org/SpaceData/SW-All.csv) |
| **Languages** | Not applicable (numeric time series) |
| **License** | Apache-2.0 |
| **Developed by** | 세종대학교 인공지능 연구실 & PCN R&S 연구소 |

The model consumes a per-satellite daily-grid multivariate series of 25 channels and outputs quantile forecasts for the 6 orbital target channels; the median quantile is used as the point forecast, and positions are recovered by anchoring the predicted drifts at the last observed TLE and propagating with SGP4.

모델은 위성별 25채널 daily-grid 다변량 시계열을 입력으로 받아 6개 orbital target 채널에 대한 quantile 예측을 출력합니다. point forecast로는 중앙값 quantile을 사용하며, 예측된 drift를 마지막 관측 TLE에 anchor하여 절대 요소로 복원한 뒤 SGP4로 전파해 위치를 계산합니다.

### Why not just SGP4? / 왜 SGP4만으로는 부족한가?

Propagating the most recent TLE with SGP4 implicitly assumes the current drag state and element rates stay fixed. Over multi-day horizons, this ignores:

- **Atmospheric drag variation** driven by solar EUV flux (F10.7) and geomagnetic activity (Ap), which modulates the secular decay of mean motion — the dominant source of along-track position error;
- **Slow drift** of BSTAR and mean motion that a single TLE snapshot cannot capture;
- **Secular rates** of RAAN and argument of perigee that evolve over time.

가장 최근 TLE를 SGP4로 전파하는 방식은 현재의 drag 상태와 요소 변화율이 그대로 유지된다고 암묵적으로 가정합니다. 며칠 이상의 horizon에서는 다음 요인들이 무시됩니다.

- 태양 EUV 플럭스(F10.7)와 지자기 활동(Ap)이 유발하는 **대기 항력 변화** — mean motion의 장기 감쇠를 좌우하며 along-track 위치 오차의 지배적 원인;
- 단일 TLE 스냅숏으로는 포착할 수 없는 BSTAR와 mean motion의 **느린 drift**;
- 시간에 따라 변화하는 RAAN과 argument of perigee의 **장기 변화율**.

OrbitFM consumes the satellite's recent element history *plus* the space-weather record, and predicts how the elements will drift — exactly the information a single-TLE propagation lacks.

OrbitFM은 위성의 최근 궤도 요소 이력에 우주기상 기록을 *더하여* 입력으로 사용하고, 궤도 요소가 앞으로 어떻게 drift할지를 예측합니다 — 단일 TLE 전파 방식에 결여된 바로 그 정보입니다.

---

## Channel / Feature Design / 채널·피처 설계

The model input is a fixed 25-channel daily-grid series per satellite. Only the first 6 channels are prediction targets; the rest are **input-only context** (masked out of the loss).

모델 입력은 위성별 고정 25채널 daily-grid 시계열입니다. 처음 6개 채널만 예측 대상이며, 나머지는 loss에서 제외되는 **입력 전용(input-only) 문맥 채널**입니다.

### Predicted orbital channels (in loss, indices 0–5) / 예측 대상 orbital 채널 (loss 포함, 인덱스 0–5)

| # | Channel | Meaning (EN) | 의미 (KR) |
|---|---|---|---|
| 0 | `d_bstar_slog_per_day` | Daily drift of signed-log1p(BSTAR) — drag coefficient trend | signed log BSTAR의 일별 변화량 (drag 계수 추세) |
| 1 | `d_mean_motion_per_day` | Daily drift of mean motion — orbital decay rate | mean motion의 일별 변화량 (궤도 감쇠율) |
| 2 | `eccentricity` | Absolute eccentricity | 이심률 절대값 |
| 3 | `inclination_deg` | Absolute inclination (deg) | 궤도경사각 절대값 (deg) |
| 4 | `draan_deg_per_day` | RAAN secular rate (deg/day) | RAAN 일별 변화율 (deg/day) |
| 5 | `dargp_deg_per_day` | Argument-of-perigee secular rate (deg/day) | argument of perigee 일별 변화율 (deg/day) |

**Drift (residual) targets.** BSTAR and mean motion barely change in absolute terms over a forecast window, so predicting absolutes collapses to persistence. OrbitFM instead predicts their **per-day deltas** — zero-mean, small-magnitude drift signals — which amplifies exactly the learning signal that separates the model from persistence. Absolute anchors live in an auxiliary array and the trajectory is reconstructed as *anchor + cumulative predicted delta*.

**Drift(residual) target 설계.** BSTAR와 mean motion은 forecast window 안에서 절대값이 거의 변하지 않으므로, 절대값을 직접 예측하면 모델이 persistence에 가까운 예측으로 수렴하게 됩니다. OrbitFM은 대신 두 변수의 **일별 delta** — 평균이 0에 가깝고 크기가 작은 drift 신호 — 를 예측하여, 모델을 persistence와 구분 짓는 학습 신호를 그대로 증폭합니다. 절대값 anchor는 보조(aux) 배열에 저장되며, 궤적은 *anchor + 예측 delta의 누적합*으로 복원됩니다.

**Angles are never predicted in absolute form.** Mean anomaly, RAAN, and argument of perigee are 0–360° circular variables; predicting them directly creates 359°-vs-1° discontinuity artifacts. Mean anomaly is unwrapped into a cumulative phase using mean motion (more reliable than the TLE rev counter), and the forecast phase is re-integrated trapezoidally from the predicted mean-motion trajectory. RAAN/argp are forecast as daily rates and cumulatively summed from the anchor.

**절대 각도는 직접 예측하지 않습니다.** mean anomaly, RAAN, argument of perigee는 0–360°를 순환하는 각도형 변수이므로, 직접 예측하면 359°와 1°처럼 실제로는 가까운 값이 수치적으로 멀게 표현되는 문제가 생깁니다. mean anomaly는 mean motion을 이용해 누적 위상으로 unwrap하며(TLE의 rev counter 필드보다 신뢰도가 높음), 예측 위상은 예측된 mean motion 궤적으로부터 사다리꼴 적분으로 복원합니다. RAAN/argp는 일별 변화율로 예측한 뒤 anchor에서 누적합산합니다.

### Input-only physics features (indices 6–21) / 입력 전용 물리 파생 피처 (인덱스 6–21)

Engineered features inspired by the cm-tle-pred benchmark, computed per grid day from the elements (fully vectorized two-body Kepler solve, no per-day sgp4init):

- `sat_rx, sat_ry, sat_rz` — ECI position (km); `sat_vx, sat_vy, sat_vz` — ECI velocity (km/s)
- `semimajor_axis` (km), `period_min` (min/rev), `apoapsis_alt`, `periapsis_alt` (km)
- `ma_cos/ma_sin`, `raan_cos/raan_sin`, `argp_cos/argp_sin` — cyclical encodings of the angular elements

cm-tle-pred 벤치마크에서 착안한 엔지니어링 피처로, 각 grid day의 궤도 요소로부터 계산됩니다(완전 벡터화된 이체 Kepler 풀이 사용, 일별 sgp4init 없음).

- `sat_rx, sat_ry, sat_rz` — ECI 위치 (km); `sat_vx, sat_vy, sat_vz` — ECI 속도 (km/s)
- `semimajor_axis` 장반경 (km), `period_min` 궤도 주기 (분/rev), `apoapsis_alt` 원지점 고도, `periapsis_alt` 근지점 고도 (km)
- `ma_cos/ma_sin`, `raan_cos/raan_sin`, `argp_cos/argp_sin` — 각도형 요소의 sin/cos 순환 인코딩

### Input-only space-weather features (indices 22–24) / 입력 전용 우주기상 피처 (인덱스 22–24)

- `f107` — daily observed F10.7 cm solar radio flux (solar EUV proxy)
- `f107_81` — 81-day centered mean of F10.7
- `ap` — daily average Ap geomagnetic index

- `f107` — 일별 관측 F10.7 cm 태양 전파 플럭스 (태양 EUV 대리 지표)
- `f107_81` — F10.7의 81일 중심 이동평균
- `ap` — 일평균 Ap 지자기 지수

Source: CelesTrak `SW-All.csv` (daily since 1957; columns `F10.7_OBS`, `F10.7_OBS_CENTER81`, `AP_AVG`). These exogenous drag drivers are what allow a learned model to beat "hold the last mean motion constant" at multi-day horizons.

출처: CelesTrak `SW-All.csv` (1957년부터 일 단위; `F10.7_OBS`, `F10.7_OBS_CENTER81`, `AP_AVG` 열 사용). 이 외생적 drag 구동 변수들이 있기에 학습 기반 모델이 며칠 이상의 horizon에서 "마지막 mean motion을 그대로 유지"하는 방식을 이길 수 있습니다.

### Auxiliary anchors (not model input/output) / 보조 anchor 정보 (모델 입출력 아님)

`[mean_anomaly, RAAN, argp, mean_motion_abs, bstar_slog_abs]` per grid day — the absolute reference values used to anchor/reconstruct forecasts and to compute truth.

grid day별 `[mean_anomaly, RAAN, argp, mean_motion_abs, bstar_slog_abs]` — 예측 복원의 anchor 및 ground truth 계산에 사용되는 절대 기준값입니다.

---

## Data & Preprocessing Pipeline / 데이터·전처리 파이프라인

Raw TLE archives are noisy; the cleaning pipeline was one of the largest accuracy levers.

원본 TLE archive에는 노이즈가 많으며, 정제 파이프라인은 가장 큰 정확도 향상 요인 중 하나였습니다.

1. **Group & sort** — parse raw TLE text files, group records by NORAD ID, sort by epoch, drop duplicate/near-duplicate epochs.
2. **Physical-integrity filter** — drop records with impossible elements: eccentricity ∉ [0, 1), inclination ∉ (0°, 180°), mean motion ∉ (0.1, 20) rev/day.
3. **Early-record drop** — discard the first 5 TLEs of each object (pre-stabilization, least reliable).
4. **LEO filter** — keep objects with median mean motion ≥ 11.25 rev/day.
5. **Robust outlier removal** — per satellite, flag any record deviating from the time-linear interpolation of its neighbors by more than **6 MAD** robust scales, on each smoothly-evolving quantity (mean motion, inclination, eccentricity, log-BSTAR, cumulative mean-anomaly phase, unwrapped RAAN/argp); union of flags removed, up to 2 passes. This is a cheap, dependency-free equivalent of the DBSCAN-on-differences cleaning that the cm-tle-pred benchmark reports as its single biggest accuracy gain.
6. **Daily-grid resampling** — TLE epochs are irregular, so each element series is linearly interpolated onto a 1-day grid; grid days farther than 2 days from any real TLE are masked out of loss and evaluation.
7. **Angle handling** — mean anomaly → cumulative phase via mean motion; RAAN/argp unwrapped; all angles additionally exposed as sin/cos input features.
8. **Feature assembly** — 6 orbital + 16 physics + 3 solar channels + 5 auxiliary anchors, cached as a compressed `.npz` per configuration.
---
1. **정렬 및 그룹화** — 원본 TLE 텍스트 파일을 파싱해 NORAD ID 기준으로 그룹화하고, epoch 기준으로 정렬한 뒤 동일·근접 epoch의 중복 record를 제거합니다.
2. **물리적 무결성 필터** — 물리적으로 불가능한 요소를 가진 record 제거: eccentricity ∉ [0, 1), inclination ∉ (0°, 180°), mean motion ∉ (0.1, 20) rev/day.
3. **초기 record 제거** — 각 물체의 첫 5개 TLE 폐기 (궤도 안정화 이전으로 신뢰도가 가장 낮음).
4. **LEO 필터** — mean motion 중앙값 ≥ 11.25 rev/day인 물체만 유지.
5. **Robust outlier 제거** — 위성별로, 부드럽게 변화해야 하는 각 물리량(mean motion, inclination, eccentricity, log-BSTAR, mean anomaly 누적 위상, unwrap된 RAAN/argp)에 대해 양쪽 이웃 record의 시간 선형 보간값에서 **6 MAD** robust scale 이상 벗어나는 record를 flag하고, flag의 합집합을 최대 2회 반복 제거합니다. 이는 cm-tle-pred 벤치마크가 단일 최대 정확도 향상 요인으로 보고한 DBSCAN 기반 정제의 저비용·무의존성 등가 기법입니다.
6. **Daily-grid 재표집** — TLE epoch 간격은 불규칙하므로 각 요소 시계열을 1일 간격 grid로 선형 보간하고, 실제 TLE에서 2일 이상 떨어진 grid day는 mask 처리하여 loss와 평가에서 제외합니다.
7. **각도 처리** — mean anomaly는 mean motion 기반 누적 위상으로 변환; RAAN/argp는 unwrap; 모든 각도는 추가로 sin/cos 입력 피처로도 제공됩니다.
8. **피처 조립** — orbital 6 + 물리 16 + 우주기상 3 채널 + 보조 anchor 5개를 구성별 압축 `.npz` 캐시로 저장합니다.

Satellites with fewer than 64 observed grid days are excluded at cache-build time.

관측된 grid day가 64일 미만인 위성은 캐시 생성 단계에서 제외됩니다.

---

## Training / 학습

Fine-tuning (continued pretraining) from Toto-2.0-2.5B pretrained weights, with the next-patch **quantile (pinball) loss in Toto's asinh-scaled space** applied **only to the 6 orbital channels** — physics and solar channels are context the model reads but is never asked to forecast.

Toto-2.0-2.5B 사전학습 가중치로부터 fine-tuning(continued pretraining)하였으며, **Toto의 asinh 스케일 공간에서의 next-patch quantile(pinball) loss**를 **6개 orbital 채널에만** 적용했습니다. 물리 피처와 우주기상 채널은 모델이 읽기만 하고 예측하도록 요구되지 않는 문맥 정보입니다.

| Hyperparameter | Value |
|---|---|
| Base checkpoint | `Datadog/Toto-2.0-2.5B` (pretrained init) |
| Objective | Next-patch quantile pinball loss (asinh-scaled), orbital channels only |
| Drift-channel loss weight | **×4.0** on `d_bstar_slog_per_day` and `d_mean_motion_per_day` |
| Optimizer | AdamW (β₁ = 0.9, β₂ = 0.95, weight decay 0) |
| Learning rate | 4e-5, linear warmup 1,000 steps, cosine decay to lr/10 |
| Max steps | 10,000 |
| Batch size | 16 |
| Context window | 8 patches × patch_size 32 = 256 days (stride 4 patches) |
| Precision | bf16 autocast (CUDA) |
| Gradient clipping | 1.0 |
| Validation | Every 2,000 steps; best-validation and final checkpoints saved |
| Seed | 42 |

The two drift channels (`d_bstar_slog_per_day`, `d_mean_motion_per_day`) receive a ×4.0 loss weight: SGP4 along-track position error is governed by mean motion and drag, so upweighting them aligns the training objective with position accuracy.

두 drift 채널(`d_bstar_slog_per_day`, `d_mean_motion_per_day`)에는 4배의 loss 가중치를 부여했습니다. SGP4의 along-track 위치 오차는 mean motion과 drag가 좌우하므로, 이 가중치는 학습 목적 함수를 위치 정확도와 정렬시킵니다.

### Data split (forecast-honest time split) / 데이터 분할 (미래 누출 없는 시간 기준 분할)

The default split is **by time**, so evaluation is a true forecasting test with no future leakage:

- **Train**: windows ending before 2022-01-01
- **Validation**: windows ending in [2022-01-01, 2023-01-01)
- **Test**: windows ending on/after 2023-01-01

기본 분할은 **시간 기준**이므로, 평가는 미래 정보 누출이 없는 실제 예측 시험이 됩니다.

- **Train**: 2022-01-01 이전에 끝나는 window
- **Validation**: [2022-01-01, 2023-01-01) 구간에 끝나는 window
- **Test**: 2023-01-01 이후에 끝나는 window

A cm-tle-pred-style **satellite-level 70/15/15 split** (deterministic by NORAD-ID hash; every record of a satellite in one split) is also supported via `--split-mode satellite`.

cm-tle-pred 방식의 **위성 단위 70/15/15 분할**(NORAD ID 해시 기반 결정적 분할; 한 위성의 모든 record가 같은 split에 속함)도 `--split-mode satellite` 옵션으로 지원됩니다.

---

## Evaluation / 평가

**Protocol.** Per-satellite evaluation on the **time-split test set** (windows ending 2023+): at each anchor the model receives 64 days of true context (solar channels fed as true context), then forecasts the next horizon. Up to 50 anchors per satellite, up to 1,500 satellites. For horizons ≤ patch size a single forward pass is used (no autoregressive feedback of predicted solar values).

**평가 방식.** **시간 기준 test set**(2023년 이후에 끝나는 window)에 대한 위성별(per-satellite) 평가입니다. 각 anchor 시점에서 모델은 64일의 실제 context(solar 채널은 실제 값)를 입력받아 이후 horizon을 예측합니다. 위성당 최대 50개 anchor, 최대 1,500개 위성을 평가했습니다. horizon이 patch size 이하인 경우 단일 forward pass를 사용하므로 예측된 solar 값의 자기회귀적 피드백이 없습니다.

**Baseline.** SGP4 persistence — propagate the last observed TLE unchanged to the target time (the standard operational method).

**Baseline.** SGP4 persistence — 마지막 관측 TLE를 그대로 목표 시점까지 전파하는 방식(표준 운용 방법)입니다.

**Metrics.**
1. **Element RMSE** — mean motion, inclination, eccentricity as absolute error; mean anomaly / RAAN / argp as circular error.
2. **Position RMSE (km)** — predicted elements → SGP4 → TEME position at t₀+Δ, Euclidean distance to the truth-TLE-derived position. In the reported `sgp4` reconstruction mode, the model's forecast drives SGP4 through an interval-averaged predicted mean motion (BSTAR zeroed to avoid double-counting drag), so the phase stays analytic but at the model's predicted decay rate.

**평가 지표.**
1. **궤도 요소 RMSE** — mean motion, inclination, eccentricity는 절대 오차, mean anomaly / RAAN / argp는 circular error로 계산합니다.
2. **위치 RMSE (km)** — 예측 요소 → SGP4 → t₀+Δ 시점의 TEME 위치를 계산하고, ground truth TLE 기반 위치와의 유클리드 거리를 측정합니다. 보고된 `sgp4` 복원 모드에서는 모델 예측이 구간 평균 mean motion으로 SGP4를 구동하며(drag 이중 반영을 막기 위해 BSTAR는 0으로 설정), 위상 계산은 해석적(SGP4)으로 유지하되 모델이 예측한 감쇠율을 따릅니다.

### Position RMSE vs. SGP4 persistence baseline / 위치 RMSE — SGP4 persistence baseline 대비 (test split, 최대 1,500개 위성)

| Horizon | Model mean RMSE (km) | Baseline mean RMSE (km) | Mean improvement / 평균 개선율 | Model median RMSE (km) | Baseline median RMSE (km) | Model wins / 모델 우세 위성 비율 |
|---|---|---|---|---|---|---|
| 1 d | 6.10 | 6.01 | −1.4% | 3.76 | 2.86 | 55.6% |
| 3 d | 16.73 | 24.89 | **+32.8%** | 9.69 | 11.75 | 55.5% |
| 7 d | 56.55 | 110.50 | **+48.8%** | 22.70 | 49.05 | 74.0% |
| 14 d | 199.97 | 399.04 | **+49.9%** | 50.54 | 192.29 | 82.9% |
| 30 d | 798.75 | 1589.82 | **+49.8%** | 140.46 | 966.21 | **81.3%** |

At 1 day the persistence baseline is already near-optimal — the last TLE is still fresh — and the model is on par. From 3 days onward the learned drift model pulls ahead, and from 7 days onward it cuts mean position error roughly in half. The median-error gap is even larger (30 d: 140 km vs. 966 km), showing the improvement holds for the *typical* satellite rather than being driven by a few outliers.

1일 horizon에서는 마지막 TLE의 정보가 아직 유효해 persistence baseline이 이미 거의 최적이며, 모델은 그와 대등한 수준입니다. 3일부터 학습된 drift 모델이 앞서기 시작하고, 7일 이상에서는 평균 위치 오차를 약 절반으로 줄입니다. 중앙값 기준 격차는 더 큽니다(30일: 140 km vs 966 km). 이는 개선이 일부 특이 위성에 의한 것이 아니라 *일반적인* 위성 다수에서 안정적으로 나타남을 보여줍니다.

### Per-element median RMSE @ 30-day horizon / 궤도 요소별 30일 중앙값 RMSE

| Element | Model | Baseline | Note (EN) | 해석 (KR) |
|---|---|---|---|---|
| Mean motion | 0.000154 rev/day | 0.000178 rev/day | Model learns part of the decay drift | 모델이 mean motion drift를 일부 학습 |
| Mean anomaly | 47.03° | 77.33° | Long-horizon phase advantage | 장기 phase 예측에서 모델 우세 |
| Inclination | 0.00185° | 0.00227° | Small but consistent gain | 작은 차이지만 모델이 개선 |
| Eccentricity | 5.48e-5 | 7.84e-5 | Gain at long horizon | 장기 horizon에서 모델이 개선 |
| RAAN | 0.00560° | 63.11° | Rate forecasting vs. no-rate baseline — largest gap | RAAN 변화율 예측 효과가 매우 큼 |
| Argument of perigee | 10.60° | 42.04° | Rate forecasting improves over baseline | 각도 변화율 예측으로 baseline 대비 개선 |

The RAAN / argp gains are structural: the persistence baseline holds these angles' rates at zero, while OrbitFM forecasts the daily rates and integrates them. The mean-anomaly gain reflects the mean-motion drift being modeled — the driver of long-horizon phase (along-track) error.

RAAN / argp의 개선은 구조적입니다. persistence baseline은 이 각도들의 변화율을 0으로 고정하는 반면, OrbitFM은 일별 변화율을 예측해 적분하기 때문입니다. mean anomaly의 개선은 mean motion drift가 모델링된 결과로, 이는 장기 phase(along-track) 오차의 핵심 원인입니다.

---

## How to Use / 사용 방법

The repository provides the fine-tuned checkpoint (`ckpt/toto_v2_Toto-2.0-2.5B-001.pt`, ~9.8 GB) and the training / evaluation pipeline (`train/train.py`, `eval/eval.py`, `utils/`). The model is a Toto-2 checkpoint; loading follows the Toto-2 API with the fine-tuned state dict.

이 저장소는 fine-tuning된 체크포인트(`ckpt/toto_v2_Toto-2.0-2.5B-001.pt`, 약 9.8 GB)와 학습/평가 파이프라인(`train/train.py`, `eval/eval.py`, `utils/`)을 제공합니다. 모델은 Toto-2 체크포인트이며, Toto-2 API로 로드한 뒤 fine-tuning된 state dict를 적용합니다.

```python
import torch
from toto2 import Toto2Model  # Toto-2 modeling code

# 1. Load the fine-tuned checkpoint on top of the base architecture
#    베이스 아키텍처 위에 fine-tuning된 체크포인트를 로드
model = Toto2Model.from_pretrained("Datadog/Toto-2.0-2.5B")
ckpt = torch.load("ckpt/toto_v2_Toto-2.0-2.5B-001.pt", map_location="cuda")
model.load_state_dict(ckpt["model"])
model = model.to("cuda").eval()

# 2. Build the 25-channel daily-grid context for one satellite
#    위성 1기의 25채널 daily-grid context 구성
#    (see utils/tle_dataset.py: build_daily_series / TLEDatasetV2)
#    target:      (B, 25, T) float — 6 orbital + 16 physics + 3 solar channels
#    target_mask: (B, 25, T) bool  — orbital channels use the coverage mask
batch = {
    "target": context.to("cuda"),
    "target_mask": mask.to("cuda"),
    "series_ids": torch.zeros(context.shape[0], 25, dtype=torch.long, device="cuda"),
}

# 3. Forecast 30 days of element drift (quantile output; take the median knot)
#    30일치 요소 drift 예측 (quantile 출력에서 중앙값 사용)
q = model.forecast(batch, horizon=30, decode_block_size=None, has_missing_values=True)
median_idx = model.output_head.knots.index(0.5)
pred = q[median_idx].float().cpu().numpy()  # (B, 25, 30) — use channels 0..5

# 4. Reconstruct absolute elements from the last observed TLE anchor,
#    then propagate to a position with SGP4 (see eval/eval.py)
#    마지막 관측 TLE anchor에서 절대 요소를 복원한 뒤 SGP4로 위치 전파
from tle_dataset import reconstruct_track
track = reconstruct_track(anchor_aux, pred[0, :6].T)  # per-day absolute elements
```

End-to-end reproduction (cache build → train → eval) is scripted in `main.sh`:

전체 재현 과정(캐시 생성 → 학습 → 평가)은 `main.sh`에 스크립트로 정리되어 있습니다.

```bash
# build the 2005-2024 daily-grid cache (downloads SW-All.csv if missing)
# 2005-2024 daily-grid 캐시 생성 (SW-All.csv가 없으면 자동 다운로드)
python utils/tle_dataset.py --start-year 2005 --end-year 2024 \
  --sw-csv data/SW-All.csv --cache-dir ./cache --window-patches 3 --min-grid-points 64

# fine-tune Toto-2.0-2.5B / Toto-2.0-2.5B fine-tuning
python train/train.py --cache-file $CACHE --model Datadog/Toto-2.0-2.5B \
  --window-patches 8 --batch-size 16 --lr 4e-5 --max-steps 10000 --warmup 1000 \
  --drift-loss-weight 4.0 --split-mode time \
  --train-until 2022-01-01 --valid-until 2023-01-01

# evaluate on the test split (SGP4 reconstruction) / test split 평가 (SGP4 복원)
python eval/eval.py --cache-file $CACHE --ckpt ./ckpt/toto_v2_Toto-2.0-2.5B-001.pt \
  --model Datadog/Toto-2.0-2.5B --split test --split-mode time --recon sgp4 \
  --context-days 64 --horizon-days 30 --horizons 1 3 7 14 30 \
  --per-sat-samples 50 --max-eval-sats 1500
```

**Dependencies:** PyTorch, numpy, pandas, sgp4, huggingface_hub, tqdm, plus the Toto-2 modeling code.

**의존성:** PyTorch, numpy, pandas, sgp4, huggingface_hub, tqdm, 그리고 Toto-2 모델링 코드.

---

## Intended Use / 사용 목적

- **Intended:** research on data-driven orbit prediction; medium-horizon (3–30 day) LEO orbit forecasting studies; conjunction-screening research; TLE data-quality and space-weather-coupling analysis; baseline for satellite time-series foundation-model research.
- **Out of scope / not intended:** operational collision avoidance or safety-of-flight decisions without independent validation; high-precision ephemeris generation (this is a TLE/SGP4-fidelity model, not a numerical-propagation replacement); non-LEO regimes (MEO/GEO/HEO were filtered out of training); maneuvering-satellite prediction (maneuvers are not modeled).

- **권장 용도:** 데이터 기반 궤도 예측 연구; 중기(3–30일) LEO 궤도 예측 연구; conjunction screening 연구; TLE 데이터 품질 및 우주기상 연동 분석; 위성 시계열 파운데이션 모델 연구의 baseline.
- **비권장 / 범위 외:** 독립 검증 없는 실운용 충돌 회피·비행 안전 의사결정; 고정밀 궤도력(ephemeris) 생성(본 모델은 TLE/SGP4 정확도 수준의 모델이며 수치 전파의 대체재가 아님); 비-LEO 궤도(MEO/GEO/HEO는 학습에서 제외됨); 기동(maneuver) 위성 예측(기동은 모델링되지 않음).

## Limitations / 한계

1. **Short horizons (~1 day):** the SGP4 persistence baseline is already near-optimal; the model provides no meaningful advantage there.
2. **Per-satellite variance:** on a minority of satellites the model is worse than the baseline — difficulty varies with orbit regime, TLE quality, drag variability, and maneuver activity.
3. **No feature ablation yet:** the reported numbers are for the full model (physics + space-weather features together); the independent contribution of each feature group has not been isolated.
4. **True future space weather is unknown at inference time.** Evaluation feeds observed (true) solar context; operational use would require forecast space-weather inputs (or a variant trained without solar channels), which may reduce accuracy.
5. **Maneuvers and anomalies** are not modeled; station-keeping or deorbit burns will break the drift assumptions.
6. **Truth is TLE-derived:** both training targets and evaluation truth inherit TLE/SGP4 accuracy limits (TLEs themselves carry km-level errors).

1. **초단기 horizon (~1일):** SGP4 persistence baseline이 이미 거의 최적이므로 모델의 이점이 제한적입니다.
2. **위성별 편차:** 일부 위성에서는 모델이 baseline보다 성능이 낮습니다 — 궤도 특성, TLE 품질, drag 변동성, 기동 여부에 따라 예측 난이도가 크게 달라집니다.
3. **피처 ablation 미수행:** 보고된 수치는 물리 피처와 우주기상 피처를 모두 사용한 최종 모델 기준이며, 각 피처군의 독립적 기여도는 아직 분리 검증되지 않았습니다.
4. **추론 시점에 미래 우주기상 값은 알 수 없습니다.** 평가에서는 관측된(실제) solar context를 입력했으나, 실운용에서는 우주기상 예보값(또는 solar 채널 없이 학습한 변형 모델)이 필요하며 이 경우 정확도가 낮아질 수 있습니다.
5. **기동과 이상 이벤트**는 모델링되지 않습니다. station-keeping이나 deorbit burn은 drift 가정을 깨뜨립니다.
6. **Ground truth가 TLE 기반입니다.** 학습 target과 평가 truth 모두 TLE/SGP4의 정확도 한계(TLE 자체가 km 수준 오차 보유)를 물려받습니다.

## Ethical & Safety Considerations / 윤리·안전 고려사항

TLE data is publicly distributed (e.g., CelesTrak / Space-Track) and this model adds no sensing capability beyond it. Nevertheless, orbit predictions should not be used as the sole basis for conjunction-assessment or safety-critical decisions; operational users must validate against authoritative special-perturbation ephemerides.

TLE 데이터는 공개적으로 배포되며(CelesTrak / Space-Track 등), 본 모델은 그 이상의 관측 능력을 추가하지 않습니다. 다만 궤도 예측을 conjunction 평가나 안전 관련 의사결정의 단독 근거로 사용해서는 안 되며, 실운용 사용자는 공인된 special-perturbation 궤도력과의 교차 검증을 수행해야 합니다.

---

## Citation / 인용

```bibtex
@misc{orbitfm2026,
  title  = {OrbitFM: TLE-based Satellite Orbit Forecasting by Continued Pretraining of a Time-Series Foundation Model},
  author = {{세종대학교 인공지능 연구실 & PCN R\&S}},
  year   = {2026},
  note   = {Fine-tuned from Datadog Toto-2.0-2.5B on 2005--2024 LEO TLE archives with space-weather channels}
}
```

**Base model:** please also cite [Datadog Toto-2](https://huggingface.co/Datadog/Toto-2.0-2.5B).

**베이스 모델:** [Datadog Toto-2](https://huggingface.co/Datadog/Toto-2.0-2.5B)도 함께 인용해 주세요.

**Acknowledgements:** space-weather data from [CelesTrak](https://celestrak.org/SpaceData/); data-cleaning and feature-engineering design informed by the cm-tle-pred benchmark analysis; TLE parsing/propagation via the [sgp4](https://pypi.org/project/sgp4/) Python package.

**감사의 글:** 우주기상 데이터는 [CelesTrak](https://celestrak.org/SpaceData/)에서 제공받았으며, 데이터 정제 및 피처 엔지니어링 설계는 cm-tle-pred 벤치마크 분석을 참고했습니다. TLE 파싱/전파에는 [sgp4](https://pypi.org/project/sgp4/) Python 패키지를 사용했습니다.