Upload 14 files

README.md

@@ -1,3 +1,400 @@
 ---
 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 패키지를 사용했습니다.

ckpt/toto_v2_Toto-2.0-2.5B-001.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:760b4af9910af0f1e03a6e165aa43d0ae6b15c8dfd3aa656a14c5145d03d7728
+size 9817331385

eval/eval.py

@@ -0,0 +1,373 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Per-satellite evaluation for the v2 (cleaned + solar) Toto TLE forecaster.
+
+Same two metric families as v1, reported PER SATELLITE:
+  (1) element RMSE (mean_motion, inclination, eccentricity; mean anomaly / RAAN /
+      argp as circular error) vs truth and vs a persistence baseline;
+  (2) SGP4 position error (km): predicted elements -> SGP4 -> TEME @ t0+Δ, vs
+      truth; baseline = propagate the last observed TLE.
+
+Framing: given n=context-days, forecast m=horizon-days. Solar channels are fed
+as true context. For horizons <= patch_size we use a single forward pass
+(decode_block_size=None), so no autoregressive feedback of predicted solar.
+
+Run:
+  python v2/eval/eval.py --ckpt v2/ckpt/toto_v2_Toto-2.0-4m.pt \
+    --model Datadog/Toto-2.0-4m --years 2020 --split all \
+    --sw-csv v2/data/SW-All.csv --context-days 64 --horizon-days 30 \
+    --horizons 1 3 7 14 30 --max-samples 4000 --out-csv v2/eval_out/per_sat.csv
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import math
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+import numpy as np
+import torch
+from tqdm import tqdm
+
+UTILS = Path(__file__).resolve().parent.parent / "utils"
+sys.path.insert(0, str(UTILS))
+
+from tle_dataset import (  # noqa: E402
+    build_daily_series, elements_from_feat_aux, reconstruct_track, sat_split_of,
+    N_CHANNELS, N_ORBITAL,
+)
+from tle_future_dataset import parse_date_to_unix  # noqa: E402
+from toto2 import Toto2Model  # noqa: E402
+from sgp4.api import Satrec, WGS72  # noqa: E402
+
+_JD_UNIX_EPOCH = 2440587.5
+_JD_SGP4_EPOCH = 2433281.5
+
+
+def unix_to_jd(u):
+    return u / 86400.0 + _JD_UNIX_EPOCH
+
+
+def build_satrec(elem, epoch_unix, satnum=99999):
+    sat = Satrec()
+    sat.sgp4init(
+        WGS72, "i", satnum, unix_to_jd(epoch_unix) - _JD_SGP4_EPOCH,
+        float(elem["bstar"]), 0.0, 0.0, float(elem["eccentricity"]),
+        math.radians(elem["argp_deg"]), math.radians(elem["inclination_deg"]),
+        math.radians(elem["mean_anomaly_deg"]),
+        elem["mean_motion_rev_per_day"] * 2.0 * math.pi / 1440.0,
+        math.radians(elem["raan_deg"]),
+    )
+    return sat
+
+
+def propagate(sat, target_unix):
+    jd = unix_to_jd(target_unix)
+    jd_i = math.floor(jd - 0.5) + 0.5
+    e, r, v = sat.sgp4(jd_i, jd - jd_i)
+    return None if e != 0 else np.asarray(r, dtype=np.float64)
+
+
+ELEMS = ["mean_motion_rev_per_day", "inclination_deg", "eccentricity",
+         "mean_anomaly_deg", "raan_deg", "argp_deg"]
+CIRC = {"mean_anomaly_deg", "raan_deg", "argp_deg"}
+SHORT = {"mean_motion_rev_per_day": "mm", "inclination_deg": "inc", "eccentricity": "ecc",
+         "mean_anomaly_deg": "ma", "raan_deg": "raan", "argp_deg": "argp"}
+
+
+def elem_err(pred, true, key):
+    d = pred[key] - true[key]
+    if key in CIRC:
+        d = ((d + 180.0) % 360.0) - 180.0
+    return abs(d)
+
+
+def split_of(epoch, tu, vu):
+    return "train" if epoch < tu else ("valid" if epoch < vu else "test")
+
+
+def rmse(xs):
+    return float(np.sqrt(np.mean(np.square(xs)))) if len(xs) else math.nan
+
+
+@torch.no_grad()
+def evaluate(model, series, device, patch_size, n_days, horizons, split, tu, vu,
+             stride_days, per_sat_samples, max_eval_sats, batch_sats, recon="integrate",
+             dump_k=0, split_mode="time"):
+    model.eval()
+    m_days = max(horizons)
+    L = math.ceil(n_days / patch_size) * patch_size
+    median_idx = model.output_head.knots.index(0.5)
+    block = None if m_days <= patch_size else patch_size  # single forward for short horizons
+
+    def empty():
+        return {"pos_m": [], "pos_b": [], "e_m": defaultdict(list), "e_b": defaultdict(list)}
+    per_sat = defaultdict(lambda: {h: empty() for h in horizons})
+
+    # Group anchors PER satellite so each satellite gets several samples (real
+    # per-satellite RMSE), instead of ~1 anchor each after a global subsample.
+    by_sat = {}
+    for norad, s in series.items():
+        T = s.feats.shape[0]
+        # satellite-level split: whole satellite belongs to one split (cm-tle-pred)
+        if split != "all" and split_mode == "satellite" and sat_split_of(norad) != split:
+            continue
+        anchors = []
+        for a in range(n_days - 1, T - m_days, stride_days):
+            if not s.mask[a - n_days + 1: a + 1].all():
+                continue
+            if not s.mask[a + 1: a + m_days + 1].all():
+                continue
+            if split != "all" and split_mode == "time" \
+                    and split_of(float(s.grid_epochs[a]), tu, vu) != split:
+                continue
+            anchors.append(a)
+        if not anchors:
+            continue
+        if per_sat_samples and len(anchors) > per_sat_samples:
+            pick = np.linspace(0, len(anchors) - 1, per_sat_samples).astype(int)
+            anchors = [anchors[i] for i in sorted(set(pick))]
+        by_sat[norad] = anchors
+
+    sats = list(by_sat)
+    if max_eval_sats and len(sats) > max_eval_sats:
+        pick = np.linspace(0, len(sats) - 1, max_eval_sats).astype(int)
+        sats = [sats[i] for i in sorted(set(pick))]
+    jobs = [(n, a) for n in sats for a in by_sat[n]]
+    print(f"[eval] {len(sats)} satellites x up to {per_sat_samples} samples = {len(jobs)} windows")
+
+    n_fail = 0
+    dumps = []   # concrete (truth | model | base) values for sanity-checking magnitudes
+    for bstart in tqdm(range(0, len(jobs), batch_sats), desc="eval", unit="batch"):
+        batch = jobs[bstart: bstart + batch_sats]
+        tgt = torch.zeros(len(batch), N_CHANNELS, L, dtype=torch.float32)
+        msk = torch.zeros(len(batch), N_CHANNELS, L, dtype=torch.bool)
+        for bi, (norad, a) in enumerate(batch):
+            ctx = series[norad].feats[a - n_days + 1: a + 1]
+            tgt[bi, :, L - n_days:] = torch.from_numpy(ctx.T.copy())
+            msk[bi, :, L - n_days:] = True
+        sids = torch.zeros(len(batch), N_CHANNELS, dtype=torch.long)
+        q = model.forecast({"target": tgt.to(device), "target_mask": msk.to(device),
+                            "series_ids": sids.to(device)},
+                           horizon=m_days, decode_block_size=block, has_missing_values=True)
+        pred = q[median_idx].float().cpu().numpy()       # (B,C,m_days)
+
+        for bi, (norad, a) in enumerate(batch):
+            s = series[norad]
+            anchor_aux, anchor_feat = s.aux[a], s.feats[a]
+            t_a = float(s.grid_epochs[a])
+            anchor_full = elements_from_feat_aux(anchor_feat, anchor_aux)
+            track_m = reconstruct_track(anchor_aux, pred[bi].T[:m_days])
+            # persistence baseline: zero drift, ecc/inc held at anchor, no angle drift
+            base_orbital = np.array([0.0, 0.0, float(anchor_feat[2]), float(anchor_feat[3]), 0.0, 0.0])
+            track_b = reconstruct_track(anchor_aux, np.tile(base_orbital, (m_days, 1)))
+            base_sat = build_satrec(anchor_full, t_a)
+            for h in horizons:
+                j = a + h
+                t_j = float(s.grid_epochs[j])
+                true_el = elements_from_feat_aux(s.feats[j], s.aux[j])
+                pred_el, base_el = track_m[h - 1], track_b[h - 1]
+                rec = per_sat[norad][h]
+                for k in ELEMS:
+                    rec["e_m"][k].append(elem_err(pred_el, true_el, k))
+                    rec["e_b"][k].append(elem_err(base_el, true_el, k))
+                r_true = propagate(build_satrec(true_el, t_j), t_j)
+                if recon == "sgp4":
+                    # Drive SGP4 with the model's FORECAST, not just bstar: along-track
+                    # comes from the model's predicted mean motion, interval-averaged over
+                    # [t_a, t_j] so it already embodies the drag-driven decay. bstar is set
+                    # to 0 so SGP4 does not re-apply that decay (double count). Phase stays
+                    # analytic (SGP4), but now at the model's predicted rate.
+                    mm_eff = float(np.mean([track_m[k]["mean_motion_rev_per_day"]
+                                            for k in range(h)]))
+                    model_sat = build_satrec(
+                        {**anchor_full, "mean_motion_rev_per_day": mm_eff, "bstar": 0.0}, t_a)
+                    r_model = propagate(model_sat, t_j)
+                else:  # "integrate": daily trapezoidal phase reconstruction
+                    r_model = propagate(build_satrec(pred_el, t_j), t_j)
+                r_base = propagate(base_sat, t_j)
+                if r_true is None or r_model is None or r_base is None:
+                    n_fail += 1
+                    continue
+                pos_m = float(np.linalg.norm(r_model - r_true))
+                pos_b = float(np.linalg.norm(r_base - r_true))
+                rec["pos_m"].append(pos_m)
+                rec["pos_b"].append(pos_b)
+                if len(dumps) < dump_k:
+                    bstar_model = float(pred_el["bstar"])   # model's forecast bstar
+                    dumps.append({
+                        "norad": norad, "h": h, "recon": recon,
+                        "true": {k: float(true_el[k]) for k in ELEMS},
+                        "model": {k: float(pred_el[k]) for k in ELEMS},
+                        "base": {k: float(base_el[k]) for k in ELEMS},
+                        "bstar_true": float(true_el["bstar"]),
+                        "bstar_model": float(bstar_model),
+                        "bstar_base": float(base_el["bstar"]),
+                        "r_true": r_true.tolist(), "r_model": r_model.tolist(),
+                        "r_base": r_base.tolist(), "pos_m": pos_m, "pos_b": pos_b,
+                    })
+    model.train()
+    return per_sat, len(jobs), n_fail, dumps
+
+
+def summarize(per_sat, horizons):
+    rows = []
+    for norad, hd in per_sat.items():
+        row = {"norad": norad, "n": 0}
+        for h in horizons:
+            rec = hd[h]
+            row["n"] = max(row["n"], len(rec["pos_m"]))
+            row[f"posR_m_{h}"] = rmse(rec["pos_m"]); row[f"posR_b_{h}"] = rmse(rec["pos_b"])
+            for k in ELEMS:
+                row[f"{SHORT[k]}R_m_{h}"] = rmse(rec["e_m"][k])
+                row[f"{SHORT[k]}R_b_{h}"] = rmse(rec["e_b"][k])
+        rows.append(row)
+    return rows
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--ckpt", default=None)
+    ap.add_argument("--model", default="Datadog/Toto-2.0-4m")
+    ap.add_argument("--input-dir", default="/home/irteam/data-vol1/models/OrbitGPT/data/TLEs")
+    ap.add_argument("--cache-dir", default="/home/irteam/data-vol1/models/OrbitGPT/v2/cache")
+    ap.add_argument("--cache-file", default=None,
+                    help="explicit prebuilt cache npz (e.g. the full 2005-2024 superset); "
+                         "filters by --split")
+    ap.add_argument("--sw-csv", default="/home/irteam/data-vol1/models/OrbitGPT/v2/data/SW-All.csv")
+    ap.add_argument("--years", type=int, nargs="+", default=[2020])
+    ap.add_argument("--split", default="all")
+    ap.add_argument("--split-mode", default="time", choices=["time", "satellite"],
+                    help="time = epoch cutoffs; satellite = cm-tle-pred 70/15/15 by NORAD")
+    ap.add_argument("--no-clean", action="store_true")
+    ap.add_argument("--no-leo", action="store_true", help="disable LEO-only filter")
+    ap.add_argument("--train-until", default="2022-01-01")
+    ap.add_argument("--valid-until", default="2023-01-01")
+    ap.add_argument("--context-days", type=int, default=64)
+    ap.add_argument("--horizon-days", type=int, default=30)
+    ap.add_argument("--horizons", type=int, nargs="+", default=[1, 3, 7, 14, 30])
+    ap.add_argument("--stride-days", type=int, default=15)
+    ap.add_argument("--per-sat-samples", type=int, default=8,
+                    help="max evaluation anchors per satellite (gives n>1 per-sat RMSE)")
+    ap.add_argument("--max-eval-sats", type=int, default=1500,
+                    help="max number of satellites to evaluate")
+    ap.add_argument("--max-satellites", type=int, default=None)
+    ap.add_argument("--batch-sats", type=int, default=64)
+    ap.add_argument("--recon", default="sgp4", choices=["integrate", "sgp4"],
+                    help="model position reconstruction: 'integrate' (daily trapezoidal "
+                         "phase) or 'sgp4' (SGP4 analytic phase + model bstar drag correction)")
+    ap.add_argument("--dump-samples", type=int, default=8,
+                    help="print this many concrete (truth|model|base) rows for sanity-checking")
+    ap.add_argument("--device", default="cuda:0")
+    ap.add_argument("--out-csv", default="/home/irteam/data-vol1/models/OrbitGPT/v2/eval_out/per_sat.csv")
+    ap.add_argument("--show", type=int, default=12)
+    args = ap.parse_args()
+
+    horizons = [h for h in args.horizons if h <= args.horizon_days]
+    device = torch.device(args.device if torch.cuda.is_available() else "cpu")
+    model = Toto2Model.from_pretrained(args.model).to(device)
+    patch_size = model.config.patch_size
+    if args.ckpt:
+        sd = torch.load(args.ckpt, map_location=device)
+        model.load_state_dict(sd["model"] if "model" in sd else sd)
+        print(f"[eval] loaded checkpoint {args.ckpt}")
+    else:
+        print("[eval] zero-shot pretrained weights")
+
+    series = build_daily_series(
+        args.input_dir, years=args.years, cache_dir=args.cache_dir, cache_file=args.cache_file,
+        sw_csv=args.sw_csv, clean=not args.no_clean, leo_only=not args.no_leo,
+        min_grid_points=args.context_days + args.horizon_days, verbose=True,
+    )
+    if args.max_satellites is not None:
+        keep = sorted(series.keys())[: args.max_satellites]
+        series = {k: series[k] for k in keep}
+
+    per_sat, n_jobs, n_fail, dumps = evaluate(
+        model, series, device, patch_size, args.context_days, horizons, args.split,
+        parse_date_to_unix(args.train_until), parse_date_to_unix(args.valid_until),
+        args.stride_days, args.per_sat_samples, args.max_eval_sats, args.batch_sats,
+        recon=args.recon, dump_k=args.dump_samples, split_mode=args.split_mode,
+    )
+    print(f"[eval] reconstruction mode: {args.recon}")
+    rows = summarize(per_sat, horizons)
+    rows.sort(key=lambda r: r["norad"])
+    print(f"\n[eval] n={args.context_days}d ctx -> m={args.horizon_days}d | "
+          f"samples={n_jobs} satellites={len(rows)} sgp4_fail={n_fail}")
+
+    hdr = ["norad", "n"]
+    for h in horizons:
+        hdr += [f"posR_m_{h}", f"posR_b_{h}"]
+        for k in ELEMS:
+            hdr += [f"{SHORT[k]}R_m_{h}", f"{SHORT[k]}R_b_{h}"]
+    Path(args.out_csv).parent.mkdir(parents=True, exist_ok=True)
+    with open(args.out_csv, "w", newline="") as f:
+        w = csv.DictWriter(f, fieldnames=hdr); w.writeheader()
+        for r in rows:
+            w.writerow({k: r.get(k, "") for k in hdr})
+    print(f"[eval] per-satellite CSV ({len(hdr)} cols) -> {args.out_csv}")
+
+    print("\nper-satellite position RMSE model/base (km):")
+    print(f"{'norad':>7} {'n':>4}  " + "  ".join(f"{f'{h}d':>15}" for h in horizons))
+    for r in rows[: args.show]:
+        print(f"{r['norad']:>7} {r['n']:>4}  " +
+              "  ".join(f"{r[f'posR_m_{h}']:>6.0f}/{r[f'posR_b_{h}']:<8.1f}" for h in horizons))
+
+    hmax = max(horizons)
+    print(f"\nper-satellite element RMSE @ {hmax}d  (model | baseline):")
+    print(f"{'norad':>7} {'n':>4}  {'mm(rev/d)':>20}  {'ma(deg)':>16}  {'inc(deg)':>16}  {'ecc':>20}")
+    for r in rows[: args.show]:
+        print(f"{r['norad']:>7} {r['n']:>4}  "
+              f"{r[f'mmR_m_{hmax}']:>9.6f}|{r[f'mmR_b_{hmax}']:<10.6f}  "
+              f"{r[f'maR_m_{hmax}']:>7.2f}|{r[f'maR_b_{hmax}']:<8.2f}  "
+              f"{r[f'incR_m_{hmax}']:>7.4f}|{r[f'incR_b_{hmax}']:<8.4f}  "
+              f"{r[f'eccR_m_{hmax}']:>9.6f}|{r[f'eccR_b_{hmax}']:<10.6f}")
+
+    if dumps:
+        print("\nground-truth check — actual values (true | model | base):")
+        print("  [recon=sgp4 → position uses ONLY bstar; printed mm/ma/inc/ecc are the "
+              "model's element forecast, NOT what drives r_model]")
+        for d in dumps:
+            t, m, b = d["true"], d["model"], d["base"]
+            rt, rm, rb = d["r_true"], d["r_model"], d["r_base"]
+            print(f"  norad {d['norad']} @{d['h']}d  [recon={d['recon']}]")
+            print(f"    mm(rev/d) true={t['mean_motion_rev_per_day']:.7f}  "
+                  f"model={m['mean_motion_rev_per_day']:.7f}  base={b['mean_motion_rev_per_day']:.7f}")
+            print(f"    ma(deg)   true={t['mean_anomaly_deg']:8.3f}  "
+                  f"model={m['mean_anomaly_deg']:8.3f}  base={b['mean_anomaly_deg']:8.3f}")
+            print(f"    inc(deg)  true={t['inclination_deg']:8.4f}  "
+                  f"model={m['inclination_deg']:8.4f}  base={b['inclination_deg']:8.4f}")
+            print(f"    ecc       true={t['eccentricity']:.7f}  "
+                  f"model={m['eccentricity']:.7f}  base={b['eccentricity']:.7f}")
+            print(f"    bstar     true={d['bstar_true']:.6e}  "
+                  f"model={d['bstar_model']:.6e}  base={d['bstar_base']:.6e}")
+            print(f"    |r_true|={math.sqrt(sum(x*x for x in rt)):.1f}km   "
+                  f"pos_err: model={d['pos_m']:.1f}km  base={d['pos_b']:.1f}km")
+            print(f"      r_true =[{rt[0]:9.1f},{rt[1]:9.1f},{rt[2]:9.1f}]")
+            print(f"      r_model=[{rm[0]:9.1f},{rm[1]:9.1f},{rm[2]:9.1f}]")
+            print(f"      r_base =[{rb[0]:9.1f},{rb[1]:9.1f},{rb[2]:9.1f}]")
+
+    def med(key):
+        v = np.array([r[key] for r in rows if not math.isnan(r.get(key, math.nan))])
+        return np.median(v) if len(v) else math.nan
+    def sat_win(mk, bk):
+        m = np.array([r[mk] for r in rows]); b = np.array([r[bk] for r in rows])
+        ok = ~(np.isnan(m) | np.isnan(b))
+        return float(np.mean(m[ok] < b[ok]) * 100.0) if ok.any() else math.nan
+
+    print("\naggregate over satellites (median per-sat RMSE) | model vs baseline:")
+    print(f"{'horizon':>8} {'posKm_m':>9} {'posKm_b':>9} {'satwin%':>7} | "
+          f"{'mm_m':>8} {'mm_b':>8} {'ma_m':>8} {'ma_b':>8}")
+    for h in horizons:
+        print(f"{h:>6}d {med(f'posR_m_{h}'):>9.1f} {med(f'posR_b_{h}'):>9.1f} "
+              f"{sat_win(f'posR_m_{h}', f'posR_b_{h}'):>7.1f} | "
+              f"{med(f'mmR_m_{h}'):>8.5f} {med(f'mmR_b_{h}'):>8.5f} "
+              f"{med(f'maR_m_{h}'):>8.2f} {med(f'maR_b_{h}'):>8.2f}")
+
+
+if __name__ == "__main__":
+    main()

main.sh

@@ -0,0 +1,49 @@
+set -euo pipefail
+cd /home/irteam/data-vol1/models/OrbitFM
+
+PY=/home/irteam/.conda/envs/orbit/bin/python
+ROOT=/home/irteam/data-vol1/models/OrbitFM
+SW=$ROOT./data/SW-All.csv 
+# CACHE=$ROOT./cache/tle_v4_TLEs_5acc79_2005-2024_20_g1_v5cmtle_feats_c1s1m64L1.npz
+
+SPLIT_MODE=time
+
+mkdir -p ./cache ./ckpt ./eval_out
+
+if [ ! -s "$SW" ]; then
+  echo "[0] downloading space weather -> $SW"
+  curl -L -o "$SW" https://celestrak.org/SpaceData/SW-All.csv
+fi
+
+if [ ! -f "$CACHE" ]; then
+  echo "[1] building v4 cache -> $CACHE"
+  $PY ./utils/tle_dataset.py \
+    --start-year 2005 --end-year 2024 \
+    --sw-csv "$SW" --cache-dir ./cache \
+    --window-patches 3 --min-grid-points 64
+else
+  echo "[1] cache present: $CACHE"
+fi
+
+
+$PY ./train/train.py --cache-file "$CACHE" --out ./ckpt \
+  --model Datadog/Toto-2.0-2.5B --window-patches 8 --batch-size 16 \
+  --lr 4e-5 --max-steps 10000 --warmup 1000 --val-every 2000 \
+  --drift-loss-weight 4.0 --split-mode "$SPLIT_MODE" \
+  --train-until 2022-01-01 --valid-until 2023-01-01
+
+$PY ./eval/eval.py --cache-file "$CACHE" \
+  --ckpt ./ckpt/toto_v2_Toto-2.0-2.5B.pt --model Datadog/Toto-2.0-2.5B \
+  --split test --split-mode "$SPLIT_MODE" --recon sgp4 \
+  --context-days 64 --horizon-days 30 --horizons 1 3 7 14 30 60 90 120 \
+  --per-sat-samples 50 --max-eval-sats 1500 \
+  --out-csv ./eval_out/per_sat_2.5b_test.csv
+
+$PY ./eval/eval.py --cache-file "$CACHE" \
+  --ckpt ./ckpt/toto_v2_Toto-2.0-2.5B.pt --model Datadog/Toto-2.0-2.5B \
+  --split test --split-mode "$SPLIT_MODE" --recon integrate \
+  --context-days 64 --horizon-days 30 --horizons 1 3 7 14 30 60 90 120 \
+  --per-sat-samples 50 --max-eval-sats 1500 \
+  --out-csv ./eval_out/per_sat_2.5b_test_integrate.csv
+
+echo "[done] per-satellite CSVs in ./eval_out/"

train/train.py

@@ -0,0 +1,257 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Fine-tune Toto-2 on cleaned TLE daily series with space-weather channels (v2).
+
+Objective: next-patch quantile (pinball) loss in Toto's asinh-scaled space, the
+same as v1, but the loss is applied ONLY to the orbital channels -- the solar
+channels (F10.7, Ap) are input-only context (LOSS_CHANNEL_MASK), so the model
+uses them to inform drag but is not asked to forecast them.
+
+Run (smoke, 4m, one year):
+  python v2/train/train.py \
+    --years 2020 --model Datadog/Toto-2.0-4m \
+    --sw-csv v2/data/SW-All.csv --window-patches 3 \
+    --batch-size 64 --max-steps 800
+
+Then full all-years:
+  python v2/train/train.py --years 2005 ... 2024 --model Datadog/Toto-2.0-2.5B ...
+"""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import json
+import math
+import sys
+import time
+from pathlib import Path
+
+import torch
+from torch.utils.data import DataLoader
+from tqdm import tqdm
+
+UTILS = Path(__file__).resolve().parent.parent / "utils"
+sys.path.insert(0, str(UTILS))
+
+from tle_dataset import (  # noqa: E402
+    TLEDatasetV2, series_collate_fn, N_CHANNELS, LOSS_CHANNEL_MASK, DRIFT_CHANNELS,
+)
+from toto2 import Toto2Model, Toto2ModelConfig  # noqa: E402
+
+
+def build_model(model_id: str, init: str) -> Toto2Model:
+    """Load Toto-2 for (A) continued pretraining from Toto weights, or
+    (B) from-scratch pretraining (same architecture, random init)."""
+    if init == "pretrained":
+        return Toto2Model.from_pretrained(model_id)
+    # scratch: fetch only the architecture config, randomly initialize weights
+    from huggingface_hub import hf_hub_download
+    raw = json.loads(Path(hf_hub_download(model_id, "config.json")).read_text())
+    known = {f.name for f in dataclasses.fields(Toto2ModelConfig)}
+    cfg = Toto2ModelConfig(**{k: v for k, v in raw.items() if k in known})
+    return Toto2Model(cfg)
+
+
+def quantile_pinball_loss(quantiles, target_scaled, valid, knots):
+    pred = quantiles[..., :-1, :]          # (Q,B,C,S-1,P) position i predicts i+1
+    tgt = target_scaled[..., 1:, :].unsqueeze(0)
+    m = valid[..., 1:, :].unsqueeze(0)
+    err = tgt - pred
+    k = knots.view(-1, 1, 1, 1, 1)
+    pin = torch.maximum(k * err, (k - 1.0) * err)
+    m = m.expand_as(pin)
+    return (pin * m).sum() / m.sum().clamp_min(1.0)
+
+
+def compute_loss(model, batch, device, patch_size, chan_weight):
+    target = batch["target"].to(device)            # (B,C,T)
+    mask = batch["target_mask"].to(device)         # (B,C,T)
+    series_ids = batch["series_ids"].to(device)
+    cpm_mask = torch.ones_like(mask)
+    B, C, T = target.shape
+    S = T // patch_size
+
+    with torch.no_grad():
+        scaled, _, _ = model.scaler(target, mask & cpm_mask)
+        target_scaled = scaled.asinh().view(B, C, S, patch_size)
+    # per-channel loss WEIGHT (float): solar=0, orbital=1, drift channels upweighted.
+    # Weighted pinball = sum(w*pin)/sum(w), so the denominator stays a proper mean.
+    valid = (mask.float() * chan_weight.to(device).view(1, C, 1)).view(B, C, S, patch_size)
+
+    out = model.forward(target, mask, cpm_mask, series_ids, num_return_steps=None)
+    knots = torch.tensor(model.output_head.knots, device=device, dtype=torch.float32)
+    return quantile_pinball_loss(out.quantiles.float(), target_scaled.float(), valid, knots)
+
+
+def build_loader(args, split, shuffle, verbose):
+    ds = TLEDatasetV2(
+        input_dir=args.input_dir, cache_dir=args.cache_dir, cache_file=args.cache_file,
+        sw_csv=args.sw_csv, years=args.years, patch_size=args.patch_size,
+        window_patches=args.window_patches, stride_patches=args.stride_patches,
+        split=split, clean=not args.no_clean, leo_only=not args.no_leo,
+        split_mode=args.split_mode,
+        train_until=args.train_until, valid_until=args.valid_until,
+        max_satellites=args.max_satellites, verbose=verbose,
+    )
+    if len(ds) == 0:
+        return None
+    return DataLoader(ds, batch_size=args.batch_size, shuffle=shuffle,
+                      num_workers=args.num_workers, collate_fn=series_collate_fn,
+                      drop_last=shuffle)
+
+
+def lr_at(step, base_lr, warmup, max_steps, min_lr, schedule):
+    """Linear warmup, then constant or cosine decay to min_lr."""
+    if warmup > 0 and step < warmup:
+        return base_lr * (step + 1) / warmup
+    if schedule == "cosine":
+        prog = min(1.0, (step - warmup) / max(1, max_steps - warmup))
+        return min_lr + 0.5 * (base_lr - min_lr) * (1.0 + math.cos(math.pi * prog))
+    return base_lr
+
+
+@torch.no_grad()
+def validate(model, loader, device, patch_size, chan_weight, max_batches):
+    model.eval()
+    tot, n = 0.0, 0
+    for i, b in enumerate(loader):
+        if i >= max_batches:
+            break
+        tot += float(compute_loss(model, b, device, patch_size, chan_weight)); n += 1
+    model.train()
+    return tot / max(1, n)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--input-dir", default="/home/irteam/data-vol1/models/OrbitGPT/data/TLEs")
+    ap.add_argument("--cache-dir", default="/home/irteam/data-vol1/models/OrbitGPT/v2/cache")
+    ap.add_argument("--cache-file", default=None,
+                    help="explicit prebuilt cache npz (e.g. the full 2005-2024 superset); "
+                         "skips parsing, ignores --years/--no-clean/--sw-csv, filters by --split")
+    ap.add_argument("--sw-csv", default="/home/irteam/data-vol1/models/OrbitGPT/v2/data/SW-All.csv")
+    ap.add_argument("--years", type=int, nargs="+", default=[2020])
+    ap.add_argument("--model", default="Datadog/Toto-2.0-4m")
+    ap.add_argument("--init", default="pretrained", choices=["pretrained", "scratch"],
+                    help="pretrained = continue-pretrain from Toto weights (recommended); "
+                         "scratch = same architecture, random init")
+    ap.add_argument("--no-clean", action="store_true")
+    ap.add_argument("--no-leo", action="store_true",
+                    help="disable cm-tle-pred LEO-only filter (affects cache key)")
+    ap.add_argument("--split-mode", default="time", choices=["time", "satellite"],
+                    help="time = epoch cutoffs (forecast-honest); satellite = cm-tle-pred 70/15/15")
+    # default context = 8 patches (256 days) for pretraining; pass smaller for quick smokes
+    ap.add_argument("--window-patches", type=int, default=8)
+    ap.add_argument("--stride-patches", type=int, default=4)
+    ap.add_argument("--train-until", default="2022-01-01")
+    ap.add_argument("--valid-until", default="2023-01-01")
+    ap.add_argument("--max-satellites", type=int, default=None)
+    ap.add_argument("--batch-size", type=int, default=64)
+    ap.add_argument("--num-workers", type=int, default=4)
+    ap.add_argument("--lr", type=float, default=2e-4)
+    ap.add_argument("--min-lr", type=float, default=None, help="cosine floor (default lr/10)")
+    ap.add_argument("--schedule", default="cosine", choices=["cosine", "constant"])
+    ap.add_argument("--weight-decay", type=float, default=0.0)
+    ap.add_argument("--drift-loss-weight", type=float, default=4.0,
+                    help="loss weight multiplier for the position-critical drift channels "
+                         "(d_bstar, d_mean_motion); 1.0 = uniform (old behavior)")
+    ap.add_argument("--warmup", type=int, default=40)
+    ap.add_argument("--max-steps", type=int, default=800)
+    ap.add_argument("--grad-clip", type=float, default=1.0)
+    ap.add_argument("--val-every", type=int, default=250,
+                    help="run validation every N steps (0 = off). Needs a non-empty "
+                         "valid split (train_until <= epoch < valid_until).")
+    ap.add_argument("--val-batches", type=int, default=20)
+    ap.add_argument("--amp", default="bf16", choices=["bf16", "fp32"])
+    ap.add_argument("--device", default="cuda:0")
+    ap.add_argument("--out", default="/home/irteam/data-vol1/models/OrbitGPT/v2/ckpt")
+    args = ap.parse_args()
+
+    device = torch.device(args.device if torch.cuda.is_available() else "cpu")
+    torch.manual_seed(42)
+    if args.min_lr is None:
+        args.min_lr = args.lr / 10.0
+    print(f"[model] {args.init} init of {args.model}")
+    model = build_model(args.model, args.init).to(device)
+    patch_size = model.config.patch_size
+    args.patch_size = patch_size
+    model.train()
+    print(f"[model] patch_size={patch_size} params={sum(p.numel() for p in model.parameters())/1e6:.1f}M "
+          f"| schedule={args.schedule} lr={args.lr}->{args.min_lr} window={args.window_patches}patch")
+
+    # per-channel loss weights: orbital=1, solar=0, position-critical drift channels
+    # (d_bstar, d_mean_motion) upweighted so the objective tracks SGP4 along-track/drag.
+    chan_weight = torch.from_numpy(LOSS_CHANNEL_MASK.astype("float32")).clone()
+    for c in DRIFT_CHANNELS:
+        chan_weight[c] = chan_weight[c] * args.drift_loss_weight
+    print(f"[loss] channel weights = {chan_weight.tolist()} (drift x{args.drift_loss_weight})")
+    train_loader = build_loader(args, "train", True, True)
+    if train_loader is None:
+        print("[data] train split empty -> split=all")
+        ds = TLEDatasetV2(input_dir=args.input_dir, cache_dir=args.cache_dir, cache_file=args.cache_file,
+                          sw_csv=args.sw_csv, years=args.years, patch_size=patch_size,
+                          window_patches=args.window_patches, stride_patches=args.stride_patches,
+                          split="all", clean=not args.no_clean, leo_only=not args.no_leo,
+                          split_mode=args.split_mode,
+                          max_satellites=args.max_satellites, verbose=True)
+        train_loader = DataLoader(ds, batch_size=args.batch_size, shuffle=True,
+                                  num_workers=args.num_workers, collate_fn=series_collate_fn, drop_last=True)
+    val_loader = build_loader(args, "valid", False, False) if args.val_every else None
+    if args.val_every and val_loader is None:
+        print("[valid] no valid-split windows (e.g. single-year smoke) -> validation disabled")
+
+    opt = torch.optim.AdamW(model.parameters(), lr=args.lr, weight_decay=args.weight_decay, betas=(0.9, 0.95))
+    use_amp = args.amp == "bf16" and device.type == "cuda"
+
+    Path(args.out).mkdir(parents=True, exist_ok=True)
+    ckpt = Path(args.out) / f"toto_v2_{Path(args.model).name}.pt"
+    best_ckpt = Path(args.out) / f"toto_v2_{Path(args.model).name}_best.pt"
+    step, t0 = 0, time.time()
+    best_val, last_val = float("inf"), None
+    pbar = tqdm(total=args.max_steps, desc="train", unit="step")
+    while step < args.max_steps:
+        for batch in train_loader:
+            if step >= args.max_steps:
+                break
+            for g in opt.param_groups:
+                g["lr"] = lr_at(step, args.lr, args.warmup, args.max_steps, args.min_lr, args.schedule)
+            opt.zero_grad(set_to_none=True)
+            if use_amp:
+                with torch.autocast("cuda", dtype=torch.bfloat16):
+                    loss = compute_loss(model, batch, device, patch_size, chan_weight)
+            else:
+                loss = compute_loss(model, batch, device, patch_size, chan_weight)
+            loss.backward()
+            gn = torch.nn.utils.clip_grad_norm_(model.parameters(), args.grad_clip)
+            opt.step()
+            pbar.update(1)
+            post = {"loss": f"{float(loss):.4f}", "gnorm": f"{float(gn):.2f}",
+                    "lr": f"{opt.param_groups[0]['lr']:.1e}"}
+            if last_val is not None:
+                post["val"] = f"{last_val:.4f}"
+            pbar.set_postfix(**post)
+
+            if val_loader is not None and step > 0 and step % args.val_every == 0:
+                last_val = validate(model, val_loader, device, patch_size, chan_weight, args.val_batches)
+                improved = last_val < best_val
+                if improved:
+                    best_val = last_val
+                    torch.save({"model": model.state_dict(), "config": vars(args),
+                                "step": step, "val_loss": last_val}, best_ckpt)
+                pbar.write(f"[valid] step {step:6d}  val_loss {last_val:.5f}  "
+                           f"train_loss {float(loss):.5f}{'  (best, saved)' if improved else ''}")
+            step += 1
+    pbar.close()
+
+    if val_loader is not None:
+        last_val = validate(model, val_loader, device, patch_size, chan_weight, args.val_batches)
+        print(f"[valid] final val_loss {last_val:.5f} (best {best_val:.5f} -> {best_ckpt.name})")
+
+    torch.save({"model": model.state_dict(), "config": vars(args)}, ckpt)
+    print(f"[done] {step} steps in {time.time()-t0:.1f}s -> {ckpt}")
+
+
+if __name__ == "__main__":
+    main()

utils/space_weather.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Space-weather (solar / geomagnetic activity) features for TLE drag modelling.
+
+Atmospheric density -- and therefore drag and the secular decay of mean motion
+-- is driven mostly by solar EUV (tracked by the F10.7 cm radio flux) and
+geomagnetic activity (Ap index). Feeding these as extra input channels gives the
+model the exogenous information it needs to predict how an orbit decays, which is
+exactly where a learned model can beat "hold the last mean motion constant" SGP4
+propagation at multi-day horizons.
+
+Data source (download once, no auth):
+    https://celestrak.org/SpaceData/SW-All.csv
+Save it to v2/data/SW-All.csv (or pass --sw-csv). The CSV is daily from 1957.
+
+Columns used: DATE, F10.7_OBS, F10.7_OBS_CENTER81, AP_AVG.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+
+SOLAR_FEATURES = ["f107", "f107_81", "ap"]
+N_SOLAR = len(SOLAR_FEATURES)
+SW_URL = "https://celestrak.org/SpaceData/SW-All.csv"
+
+
+class SpaceWeather:
+    """Daily F10.7 / Ap lookup, aligned to arbitrary unix epochs."""
+
+    def __init__(self, day_unix: np.ndarray, table: np.ndarray):
+        self.day_unix = day_unix      # (D,) sorted unix seconds at 00:00 UTC
+        self.table = table            # (D, N_SOLAR) float32
+
+    @classmethod
+    def from_csv(cls, csv_path: str | Path) -> "SpaceWeather":
+        df = pd.read_csv(csv_path)
+        cols = {c.upper(): c for c in df.columns}
+
+        def col(*names):
+            for nm in names:
+                if nm in cols:
+                    return df[cols[nm]]
+            raise KeyError(f"none of {names} in SW csv columns {list(df.columns)}")
+
+        dates = pd.to_datetime(col("DATE"))
+        f107 = pd.to_numeric(col("F10.7_OBS", "F10.7_ADJ"), errors="coerce")
+        f107_81 = pd.to_numeric(col("F10.7_OBS_CENTER81", "F10.7_ADJ_CENTER81",
+                                    "F10.7_OBS_LAST81"), errors="coerce")
+        ap = pd.to_numeric(col("AP_AVG"), errors="coerce")
+
+        tab = pd.DataFrame({"f107": f107, "f107_81": f107_81, "ap": ap})
+        tab = tab.ffill().bfill()  # fill predicted/missing tail+head
+        day_unix = np.array(
+            [d.replace(tzinfo=timezone.utc).timestamp() for d in dates.dt.to_pydatetime()],
+            dtype=np.float64,
+        )
+        order = np.argsort(day_unix)
+        return cls(day_unix[order], tab.to_numpy(dtype=np.float32)[order])
+
+    def for_epochs(self, epochs_unix: np.ndarray) -> np.ndarray:
+        """Return (len(epochs), N_SOLAR) by nearest-preceding-day lookup."""
+        idx = np.searchsorted(self.day_unix, epochs_unix, side="right") - 1
+        idx = np.clip(idx, 0, len(self.day_unix) - 1)
+        return self.table[idx]
+
+
+def load_space_weather(csv_path: Optional[str | Path]) -> Optional[SpaceWeather]:
+    if csv_path is None:
+        return None
+    p = Path(csv_path)
+    if not p.exists():
+        print(f"[space_weather] WARNING: {p} not found -> solar channels will be ZERO.\n"
+              f"               download once: {SW_URL}")
+        return None
+    sw = SpaceWeather.from_csv(p)
+    print(f"[space_weather] loaded {len(sw.day_unix)} daily records from {p}")
+    return sw

utils/tle_clean.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Robust outlier removal for per-satellite TLE record sequences.
+
+Why: raw TLE archives contain corrupted records (bad element fields, wrong
+epochs, mis-decoded mean anomaly / rev counter). These single-point outliers
+poison linear interpolation onto the daily grid and the angle unwrapping. The
+cm-tle-pred benchmark reports that outlier removal (DBSCAN on 1st/2nd-order
+differences of the elements) gave their single biggest accuracy gain (~2 orders
+of magnitude). We use a cheaper, dependency-free equivalent: flag any record
+whose element deviates from a time-linear interpolation of its neighbors by more
+than ``k_mad`` robust (MAD) scales, on the elements that should evolve smoothly.
+
+Cleaning runs on the raw record list BEFORE daily resampling / unwrapping.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import List, Tuple
+
+import numpy as np
+
+# reuse the parser's record type + helpers from the original code/utils
+_CODE_UTILS = Path(__file__).resolve().parents[2] / "code" / "utils"
+if str(_CODE_UTILS) not in sys.path:
+    sys.path.insert(0, str(_CODE_UTILS))
+from tle_future_dataset import TLERecord, signed_log1p  # noqa: E402
+
+SECONDS_PER_DAY = 86400.0
+
+
+def cumulative_mean_anomaly(recs: List[TLERecord]) -> np.ndarray:
+    """Unwrap mean anomaly into a monotone cumulative phase (deg).
+
+    Revolution count between epochs is disambiguated with the mean motion
+    (rev/day), which is far more reliable than the TLE rev-counter field.
+    """
+    n = len(recs)
+    phi = np.empty(n, dtype=np.float64)
+    phi[0] = recs[0].mean_anomaly_deg
+    for i in range(1, n):
+        dt_days = (recs[i].epoch_unix - recs[i - 1].epoch_unix) / SECONDS_PER_DAY
+        n_avg = 0.5 * (recs[i].mean_motion_rev_per_day + recs[i - 1].mean_motion_rev_per_day)
+        predicted = phi[i - 1] + n_avg * dt_days * 360.0
+        m_i = recs[i].mean_anomaly_deg
+        k = round((predicted - m_i) / 360.0)
+        phi[i] = 360.0 * k + m_i
+    return phi
+
+
+def _neighbor_interp_resid(t: np.ndarray, x: np.ndarray) -> np.ndarray:
+    """Residual of each interior point vs a time-linear interp of its neighbors."""
+    resid = np.zeros_like(x, dtype=np.float64)
+    if len(x) < 3:
+        return resid
+    t0, t1, t2 = t[:-2], t[1:-1], t[2:]
+    denom = np.where((t2 - t0) == 0, 1.0, (t2 - t0))
+    w = (t1 - t0) / denom
+    x_hat = x[:-2] + (x[2:] - x[:-2]) * w
+    resid[1:-1] = x[1:-1] - x_hat
+    return resid
+
+
+def _mad(v: np.ndarray) -> float:
+    v = v[np.isfinite(v)]
+    if v.size == 0:
+        return 0.0
+    med = np.median(v)
+    return float(1.4826 * np.median(np.abs(v - med)))
+
+
+def clean_records(
+    recs: List[TLERecord], k_mad: float = 6.0, max_passes: int = 2,
+) -> Tuple[List[TLERecord], int]:
+    """Remove single-point outlier records. Returns (cleaned, n_removed).
+
+    Flags the union of outliers across the smoothly-evolving quantities:
+    mean motion, inclination, eccentricity, bstar(log), and the cumulative /
+    unwrapped angles (mean anomaly phase, RAAN, argp).
+    """
+    recs = sorted(recs, key=lambda r: r.epoch_unix)
+    removed = 0
+    for _ in range(max_passes):
+        n = len(recs)
+        if n < 5:
+            break
+        t = np.array([r.epoch_unix for r in recs], dtype=np.float64)
+        series = {
+            "mm": np.array([r.mean_motion_rev_per_day for r in recs]),
+            "inc": np.array([r.inclination_deg for r in recs]),
+            "ecc": np.array([r.eccentricity for r in recs]),
+            "bstar": np.array([signed_log1p(r.bstar) for r in recs]),
+            "phiM": cumulative_mean_anomaly(recs),
+            "raan": np.degrees(np.unwrap(np.radians([r.raan_deg for r in recs]))),
+            "argp": np.degrees(np.unwrap(np.radians([r.argp_deg for r in recs]))),
+        }
+        flag = np.zeros(n, dtype=bool)
+        for s in series.values():
+            resid = _neighbor_interp_resid(t, s)
+            scale = _mad(resid[1:-1])
+            if scale > 0:
+                flag |= np.abs(resid) > (k_mad * scale)
+        flag[0] = flag[-1] = False  # keep endpoints (no two-sided neighbors)
+        if not flag.any():
+            break
+        recs = [r for r, bad in zip(recs, flag) if not bad]
+        removed += int(flag.sum())
+    return recs, removed

utils/tle_dataset.py

@@ -0,0 +1,612 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+TLE daily-grid dataset v2: outlier-cleaned + space-weather channels.
+
+Builds on the v1 daily-grid cumulative-phase formulation and adds the two
+data-quality / physics levers from the cm-tle-pred benchmark analysis:
+
+  (1) Robust outlier removal per satellite (tle_clean.clean_records) before
+      resampling -- their single biggest accuracy lever.
+  (2) Space-weather input channels (F10.7, F10.7-81d, Ap) -- exogenous drivers
+      of atmospheric drag, i.e. the secular decay of mean motion.
+
+Channels (CHANNEL_NAMES):
+  orbital, PREDICTED + in loss (indices 0..5):
+    bstar_slog, mean_motion, eccentricity, inclination_deg,
+    draan_deg_per_day, dargp_deg_per_day
+  solar, INPUT-ONLY context, excluded from loss (indices 6..8):
+    f107, f107_81, ap
+Absolute angles [MA, RAAN, argp] are kept as aux (anchor/truth), never predicted.
+
+Angles are reconstructed by anchoring at the last observed TLE and integrating
+the predicted rates (reconstruct_track) -- absolute phase is never predicted.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional
+
+import numpy as np
+import torch
+from torch.utils.data import Dataset
+from tqdm import tqdm
+
+_HERE = Path(__file__).resolve().parent
+_CODE_UTILS = _HERE.parents[1] / "code" / "utils"
+for p in (str(_HERE), str(_CODE_UTILS)):
+    if p not in sys.path:
+        sys.path.insert(0, p)
+
+from tle_future_dataset import (  # noqa: E402
+    collect_txt_files, iter_tle_pairs_from_txt, parse_tle_pair,
+    parse_date_to_unix, signed_log1p, extract_year_from_filename,
+)
+from tle_clean import clean_records, cumulative_mean_anomaly  # noqa: E402
+from space_weather import SpaceWeather, load_space_weather, SOLAR_FEATURES, N_SOLAR  # noqa: E402
+
+# v3: persistence-RESIDUAL (drift) targets.
+#
+# v2 predicted absolute mean_motion / bstar. Because these barely change over the
+# forecast window, the loss-optimal prediction was ≈persistence and the model
+# could not beat SGP4 propagation at short/mid horizons. v3 makes the slowly
+# DRIFTING magnitudes into per-day DELTA channels, so the training target IS the
+# drift (zero-mean, small) — the learning signal we care about is amplified.
+# Absolute mean_motion / bstar at the anchor live in aux, and the trajectory is
+# reconstructed by anchor + cumulative predicted delta (like the angle rates).
+#
+# Eccentricity / inclination drift even less and are well predicted as absolutes,
+# so they stay absolute. RAAN/argp remain secular rate channels (as in v2).
+ORBITAL_NAMES = [
+    "d_bstar_slog_per_day",   # 0  daily drift of signed_log1p(bstar)
+    "d_mean_motion_per_day",  # 1  daily drift of mean motion (orbital decay rate)
+    "eccentricity",           # 2  absolute
+    "inclination_deg",        # 3  absolute
+    "draan_deg_per_day",      # 4  RAAN secular rate
+    "dargp_deg_per_day",      # 5  argp secular rate
+]
+N_ORBITAL = len(ORBITAL_NAMES)
+
+# v4 = cm-tle-pred-style processing. The cm-tle-pred benchmark feeds, on top of the
+# raw elements, a set of engineered physical features. We add the reproducible ones
+# as INPUT-ONLY channels (excluded from the loss), mirroring their feature names:
+#   - SAT_RX..VZ      : Cartesian ECI state from the day's elements (two-body
+#                       osculating r,v -- same role as their SGP4 SAT_R*/V*)
+#   - SEMIMAJOR_AXIS / PERIOD / APOAPSIS / PERIAPSIS : derived orbit geometry
+#   - *_COS / *_SIN   : cyclical encodings of the angular elements (MA/RAAN/argp)
+# What is PREDICTED is unchanged (the 6 orbital drift/rate channels) -- this only
+# enriches Toto's context, exactly like the solar channels do.
+PHYS_NAMES = [
+    "sat_rx", "sat_ry", "sat_rz",      # 6..8   ECI position (km)
+    "sat_vx", "sat_vy", "sat_vz",      # 9..11  ECI velocity (km/s)
+    "semimajor_axis", "period_min",    # 12..13 (km), (minutes/rev)
+    "apoapsis_alt", "periapsis_alt",   # 14..15 altitude (km)
+    "ma_cos", "ma_sin",                # 16..17 mean anomaly cyclical
+    "raan_cos", "raan_sin",            # 18..19 RAAN cyclical
+    "argp_cos", "argp_sin",            # 20..21 argp cyclical
+]
+N_PHYS = len(PHYS_NAMES)
+
+CHANNEL_NAMES = ORBITAL_NAMES + PHYS_NAMES + SOLAR_FEATURES   # 6 + 16 + 3 = 25
+N_CHANNELS = len(CHANNEL_NAMES)
+# aux carries the absolute anchors/truth NOT directly predicted:
+# [mean_anomaly, RAAN, argp, mean_motion, bstar_slog]
+N_AUX = 5
+AUX_MA, AUX_RAAN, AUX_ARGP, AUX_MM, AUX_BSTAR = 0, 1, 2, 3, 4
+# orbital channels are prediction targets; PHYS + solar are input-only context.
+LOSS_CHANNEL_MASK = np.array([1] * N_ORBITAL + [0] * (N_PHYS + N_SOLAR), dtype=bool)
+# Position-critical drift channels: d_bstar_slog (0) and d_mean_motion (1). SGP4
+# along-track error is governed by mean motion and drag, so these are upweighted in
+# the training loss (--drift-loss-weight) to align the objective with position.
+DRIFT_CHANNELS = (0, 1)
+SECONDS_PER_DAY = 86400.0
+MU_EARTH = 398600.4418      # km^3/s^2  (WGS-72 gravitational parameter)
+R_EARTH = 6378.137          # km        (equatorial radius, for apo/peri altitude)
+LEO_MIN_MEAN_MOTION = 11.25  # rev/day; cm-tle-pred LEO cutoff
+CHANNEL_VERSION = "v5cmtle_feats"
+
+
+def signed_expm1(x: float) -> float:
+    return math.copysign(math.expm1(abs(x)), x)
+
+
+def _clip_ecc(x):
+    return float(min(max(x, 0.0), 0.9999999))
+
+
+def _clip_inc(x):
+    return float(min(max(x, 0.0), 180.0))
+
+
+def elements_from_feat_aux(feat_row, aux_row) -> Dict[str, float]:
+    """Full physical elements for an OBSERVED grid row (truth/anchor).
+
+    ecc/inc come from the absolute channels; bstar/mean_motion/angles from aux.
+    """
+    f = np.asarray(feat_row, dtype=np.float64)
+    a = np.asarray(aux_row, dtype=np.float64)
+    return {
+        "bstar": signed_expm1(float(a[AUX_BSTAR])),
+        "mean_motion_rev_per_day": float(max(a[AUX_MM], 1e-6)),
+        "eccentricity": _clip_ecc(f[2]),
+        "inclination_deg": _clip_inc(f[3]),
+        "mean_anomaly_deg": float(a[AUX_MA] % 360.0),
+        "raan_deg": float(a[AUX_RAAN] % 360.0),
+        "argp_deg": float(a[AUX_ARGP] % 360.0),
+    }
+
+
+def reconstruct_track(anchor_aux, pred_seq, grid_step_days=1.0):
+    """Absolute elements per forecast day, anchored at the last observed TLE.
+
+    bstar(log) and mean_motion are integrated from their anchor (aux) by summing
+    the predicted per-day DELTAS; mean-anomaly phase is integrated trapezoidally
+    from the (reconstructed) mean motion; RAAN/argp from predicted daily rates;
+    ecc/inc are read from the absolute channels. Nothing absolute-phase is predicted.
+    """
+    a = np.asarray(anchor_aux, dtype=np.float64)
+    pred = np.asarray(pred_seq, dtype=np.float64)
+    ma, raan, argp = a[AUX_MA], a[AUX_RAAN], a[AUX_ARGP]
+    mm = float(a[AUX_MM]); bstar_slog = float(a[AUX_BSTAR])
+    prev_mm = mm
+    out = []
+    for h in range(pred.shape[0]):
+        bstar_slog += float(pred[h, 0]) * grid_step_days   # cumulative d_bstar
+        mm += float(pred[h, 1]) * grid_step_days           # cumulative d_mean_motion
+        mm_h = max(mm, 1e-6)
+        ma += 360.0 * 0.5 * (prev_mm + mm_h) * grid_step_days
+        prev_mm = mm_h
+        raan += float(pred[h, 4]) * grid_step_days
+        argp += float(pred[h, 5]) * grid_step_days
+        out.append({
+            "bstar": signed_expm1(bstar_slog),
+            "mean_motion_rev_per_day": mm_h,
+            "eccentricity": _clip_ecc(pred[h, 2]),
+            "inclination_deg": _clip_inc(pred[h, 3]),
+            "mean_anomaly_deg": ma % 360.0,
+            "raan_deg": raan % 360.0,
+            "argp_deg": argp % 360.0,
+        })
+    return out
+
+
+# -----------------------------
+# cm-tle-pred physical features (input-only channels)
+# -----------------------------
+
+def _kepler_rv(a, e, inc_r, raan_r, argp_r, M_r):
+    """Vectorized two-body osculating ECI state from classical elements.
+
+    Inputs are numpy arrays (one element per grid day); returns rx,ry,rz (km) and
+    vx,vy,vz (km/s). This plays the same role as cm-tle-pred's SGP4 SAT_R*/V*
+    Cartesian features but is fully vectorized over the daily grid (no per-day
+    sgp4init), which matters for the all-years (~23 GB) build.
+    """
+    E = np.array(M_r, dtype=np.float64, copy=True)
+    for _ in range(12):                      # Newton on Kepler's equation
+        E = E - (E - e * np.sin(E) - M_r) / np.maximum(1.0 - e * np.cos(E), 1e-9)
+    cosE, sinE = np.cos(E), np.sin(E)
+    r = a * (1.0 - e * cosE)
+    nu = np.arctan2(np.sqrt(np.maximum(1.0 - e * e, 0.0)) * sinE, cosE - e)
+    cosnu, sinnu = np.cos(nu), np.sin(nu)
+    p = np.maximum(a * (1.0 - e * e), 1e-6)
+    rp_x, rp_y = r * cosnu, r * sinnu
+    vfac = np.sqrt(MU_EARTH / p)
+    vp_x, vp_y = -vfac * sinnu, vfac * (e + cosnu)
+    co, so = np.cos(raan_r), np.sin(raan_r)
+    ci, si = np.cos(inc_r), np.sin(inc_r)
+    cw, sw = np.cos(argp_r), np.sin(argp_r)
+    # perifocal -> ECI rotation R3(-raan) R1(-inc) R3(-argp)
+    R11 = co * cw - so * sw * ci
+    R12 = -co * sw - so * cw * ci
+    R21 = so * cw + co * sw * ci
+    R22 = -so * sw + co * cw * ci
+    R31, R32 = sw * si, cw * si
+    rx = R11 * rp_x + R12 * rp_y
+    ry = R21 * rp_x + R22 * rp_y
+    rz = R31 * rp_x + R32 * rp_y
+    vx = R11 * vp_x + R12 * vp_y
+    vy = R21 * vp_x + R22 * vp_y
+    vz = R31 * vp_x + R32 * vp_y
+    return rx, ry, rz, vx, vy, vz
+
+
+def physics_features(g_mm, g_ecc, g_inc_deg, g_raan_deg, g_argp_deg, g_ma_deg):
+    """(T, N_PHYS) cm-tle-pred input features from the daily-grid elements."""
+    mm = np.maximum(np.asarray(g_mm, dtype=np.float64), 1e-6)
+    n_rad_s = mm * 2.0 * math.pi / SECONDS_PER_DAY
+    a = (MU_EARTH / (n_rad_s ** 2)) ** (1.0 / 3.0)             # semimajor axis (km)
+    e = np.clip(np.asarray(g_ecc, dtype=np.float64), 0.0, 0.999999)
+    inc_r = np.radians(g_inc_deg)
+    raan_r = np.radians(np.asarray(g_raan_deg) % 360.0)
+    argp_r = np.radians(np.asarray(g_argp_deg) % 360.0)
+    ma_r = np.radians(np.asarray(g_ma_deg) % 360.0)
+    rx, ry, rz, vx, vy, vz = _kepler_rv(a, e, inc_r, raan_r, argp_r, ma_r)
+    period_min = 1440.0 / mm
+    apo = a * (1.0 + e) - R_EARTH                              # apoapsis altitude (km)
+    peri = a * (1.0 - e) - R_EARTH                            # periapsis altitude (km)
+    return np.stack([
+        rx, ry, rz, vx, vy, vz,
+        a, period_min, apo, peri,
+        np.cos(ma_r), np.sin(ma_r),
+        np.cos(raan_r), np.sin(raan_r),
+        np.cos(argp_r), np.sin(argp_r),
+    ], axis=1)
+
+
+def sat_split_of(norad_id, train_frac=0.70, valid_frac=0.15):
+    """cm-tle-pred-style SATELLITE-level split (70/15/15): every record of a given
+    satellite lands in the same split, deterministically by NORAD id."""
+    h = int(hashlib.md5(str(int(norad_id)).encode()).hexdigest(), 16) % 1000
+    if h < int(train_frac * 1000):
+        return "train"
+    if h < int((train_frac + valid_frac) * 1000):
+        return "valid"
+    return "test"
+
+
+# -----------------------------
+# Parse + clean (with progress)
+# -----------------------------
+
+def _is_physically_possible(r) -> bool:
+    """cm-tle-pred 'data integrity' check: drop physically impossible records."""
+    return (0.0 <= r.eccentricity < 1.0
+            and 0.0 < r.inclination_deg < 180.0
+            and 0.1 < r.mean_motion_rev_per_day < 20.0)
+
+
+def load_and_clean(
+    input_dir, years: Optional[Iterable[int]] = None, clean: bool = True,
+    min_records_per_object: int = 2, drop_first_n: int = 5, leo_only: bool = True,
+) -> Dict[int, List]:
+    """Parse raw TLE txt (tqdm over files), group by NORAD, dedup, outlier-clean.
+
+    v4 adds the cm-tle-pred 'data integrity' steps:
+      - drop physically impossible records (impossible ecc/inc/mean_motion),
+      - discard the first ``drop_first_n`` TLEs per satellite (least reliable),
+      - keep only LEO objects (median mean_motion >= LEO_MIN_MEAN_MOTION) when
+        ``leo_only`` is set.
+    """
+    files = collect_txt_files(input_dir, years=years)
+    by_norad: Dict[int, List] = {}
+    for path in tqdm(files, desc="parse files", unit="file"):
+        year = extract_year_from_filename(path)
+        ridx = 0
+        for obj, l1, l2, ln in iter_tle_pairs_from_txt(path):
+            ridx += 1
+            rec = parse_tle_pair(l1, l2, source_file=str(path), source_year=year,
+                                 source_line_number=ln, object_name_raw=obj, record_index=ridx)
+            if rec is not None and _is_physically_possible(rec):
+                by_norad.setdefault(rec.norad_id, []).append(rec)
+
+    out: Dict[int, List] = {}
+    removed_total = 0
+    n_nonleo = 0
+    for norad, recs in tqdm(by_norad.items(), desc="dedup+clean", unit="sat"):
+        recs = sorted(recs, key=lambda r: r.epoch_unix)
+        deduped, seen = [], set()
+        for r in recs:
+            key = round(r.epoch_unix, 3)
+            if key in seen:
+                continue
+            seen.add(key)
+            deduped.append(r)
+        if drop_first_n > 0 and len(deduped) > drop_first_n:   # least-reliable early TLEs
+            deduped = deduped[drop_first_n:]
+        if leo_only:
+            med_mm = float(np.median([r.mean_motion_rev_per_day for r in deduped])) if deduped else 0.0
+            if med_mm < LEO_MIN_MEAN_MOTION:
+                n_nonleo += 1
+                continue
+        if clean and len(deduped) >= 5:
+            deduped, nrem = clean_records(deduped)
+            removed_total += nrem
+        if len(deduped) >= min_records_per_object:
+            out[norad] = deduped
+    print(f"[load] {len(out)} satellites, removed {removed_total} outlier records, "
+          f"dropped {n_nonleo} non-LEO objects (leo_only={leo_only})")
+    return out
+
+
+# -----------------------------
+# Daily-grid series + solar
+# -----------------------------
+
+@dataclass
+class DailySeries:
+    norad_id: int
+    grid_epochs: np.ndarray   # (T,)
+    feats: np.ndarray         # (T, N_CHANNELS)
+    mask: np.ndarray          # (T,) orbital coverage
+    aux: np.ndarray           # (T, N_AUX) absolute angles
+
+
+def _build_one(recs, sw: Optional[SpaceWeather], grid_step_days=1.0) -> Optional[DailySeries]:
+    if len(recs) < 2:
+        return None
+    recs = sorted(recs, key=lambda r: r.epoch_unix)
+    ep = np.array([r.epoch_unix for r in recs], dtype=np.float64)
+    bstar_log = np.array([signed_log1p(r.bstar) for r in recs])
+    mm = np.array([r.mean_motion_rev_per_day for r in recs])
+    ecc = np.array([r.eccentricity for r in recs])
+    inc = np.array([r.inclination_deg for r in recs])
+    raan_uw = np.degrees(np.unwrap(np.radians([r.raan_deg for r in recs])))
+    argp_uw = np.degrees(np.unwrap(np.radians([r.argp_deg for r in recs])))
+    phiM = cumulative_mean_anomaly(recs)
+
+    step = grid_step_days * SECONDS_PER_DAY
+    t0 = math.floor(ep[0] / step) * step
+    t1 = math.ceil(ep[-1] / step) * step
+    grid = np.arange(t0, t1 + 0.5 * step, step, dtype=np.float64)
+    if grid.size < 2:
+        return None
+
+    def itp(y):
+        return np.interp(grid, ep, y)
+
+    g_raan, g_argp = itp(raan_uw), itp(argp_uw)
+    g_mm, g_bstar = itp(mm), itp(bstar_log)
+    g_ecc, g_inc, g_ma = itp(ecc), itp(inc), itp(phiM)   # g_ma = cumulative MA (deg)
+    draan = np.gradient(g_raan) / grid_step_days
+    dargp = np.gradient(g_argp) / grid_step_days
+    d_bstar = np.gradient(g_bstar) / grid_step_days      # daily drift (persistence residual)
+    d_mm = np.gradient(g_mm) / grid_step_days
+
+    orbital = np.stack([d_bstar, d_mm, g_ecc, g_inc, draan, dargp], axis=1)
+    # cm-tle-pred input-only physical features (Cartesian r/v, SMA/period/apo/peri,
+    # cyclical angle encodings) derived from the day's elements
+    phys = physics_features(g_mm, g_ecc, g_inc, g_raan, g_argp, g_ma)
+    if sw is not None:
+        solar = sw.for_epochs(grid)                      # (T, N_SOLAR)
+    else:
+        solar = np.zeros((grid.size, N_SOLAR), dtype=np.float32)
+    feats = np.concatenate([orbital, phys, solar], axis=1).astype(np.float32)
+
+    # aux = [MA, RAAN, argp, mean_motion_abs, bstar_slog_abs]
+    aux = np.stack(
+        [g_ma % 360.0, g_raan % 360.0, g_argp % 360.0, g_mm, g_bstar], axis=1
+    ).astype(np.float32)
+
+    idx = np.clip(np.searchsorted(ep, grid), 1, len(ep) - 1)
+    gap = np.minimum(np.abs(grid - ep[idx]), np.abs(grid - ep[idx - 1]))
+    mask = gap <= (2.0 * step)
+    return DailySeries(recs[0].norad_id, grid, feats, mask, aux)
+
+
+def _cache_key(input_dir, years, grid_step_days, clean, with_solar, min_grid_points, leo_only) -> str:
+    h = hashlib.md5(str(Path(input_dir).resolve()).encode()).hexdigest()[:6]
+    tag = Path(input_dir).resolve().name
+    ys = "all" if years is None else f"{min(years)}-{max(years)}_{len(list(years))}"
+    flags = f"c{int(clean)}s{int(with_solar)}m{int(min_grid_points)}L{int(leo_only)}"
+    return f"{tag}_{h}_{ys}_g{grid_step_days:g}_{CHANNEL_VERSION}_{flags}"
+
+
+def _load_cache_npz(cache_path, verbose) -> Dict[int, DailySeries]:
+    d = np.load(cache_path, allow_pickle=True)
+    out = {int(n): DailySeries(int(n), d[f"e_{int(n)}"], d[f"f_{int(n)}"],
+                               d[f"m_{int(n)}"], d[f"a_{int(n)}"]) for n in d["norads"]}
+    if verbose:
+        print(f"[cache] {len(out)} satellites loaded from {cache_path}")
+    return out
+
+
+def build_daily_series(
+    input_dir, years=None, grid_step_days=1.0, min_grid_points=64,
+    clean=True, sw_csv=None, cache_dir=None, cache_file=None, rebuild=False,
+    leo_only=True, verbose=True,
+) -> Dict[int, DailySeries]:
+    # Explicit prebuilt cache (e.g. the full 2005-2024 superset): load it directly
+    # and let the dataset/eval filter by window + time-split. Skips parsing & solar.
+    if cache_file is not None:
+        cp = Path(cache_file)
+        if not cp.exists():
+            raise FileNotFoundError(f"--cache-file not found: {cp}")
+        if verbose:
+            print(f"[cache] using explicit cache {cp}")
+        return _load_cache_npz(cp, verbose)
+
+    sw = load_space_weather(sw_csv)
+    with_solar = sw is not None
+    cache_path = None
+    if cache_dir is not None:
+        cache_dir = Path(cache_dir); cache_dir.mkdir(parents=True, exist_ok=True)
+        cache_path = cache_dir / f"tle_v4_{_cache_key(input_dir, years, grid_step_days, clean, with_solar, min_grid_points, leo_only)}.npz"
+        if cache_path.exists() and not rebuild:
+            if verbose:
+                print(f"[cache] loading {cache_path}")
+            d = np.load(cache_path, allow_pickle=True)
+            out = {int(n): DailySeries(int(n), d[f"e_{int(n)}"], d[f"f_{int(n)}"],
+                                       d[f"m_{int(n)}"], d[f"a_{int(n)}"]) for n in d["norads"]}
+            if verbose:
+                print(f"[cache] {len(out)} satellites loaded")
+            return out
+
+    by_norad = load_and_clean(input_dir, years=years, clean=clean, leo_only=leo_only)
+    out: Dict[int, DailySeries] = {}
+    for norad, recs in tqdm(by_norad.items(), desc="daily grid+solar", unit="sat"):
+        ser = _build_one(recs, sw, grid_step_days)
+        if ser is None or int(ser.mask.sum()) < min_grid_points:
+            continue
+        out[norad] = ser
+
+    if cache_path is not None:
+        kw: Dict[str, Any] = {"norads": np.asarray(sorted(out.keys()))}
+        for n, s in out.items():
+            kw[f"e_{n}"] = s.grid_epochs; kw[f"f_{n}"] = s.feats
+            kw[f"m_{n}"] = s.mask; kw[f"a_{n}"] = s.aux
+        np.savez(cache_path, **kw)
+        if verbose:
+            print(f"[cache] saved {len(out)} satellites -> {cache_path}")
+    return out
+
+
+# -----------------------------
+# Windowed dataset
+# -----------------------------
+
+@dataclass
+class DayWindow:
+    norad_id: int
+    start: int
+    end_epoch: float
+
+
+class TLEDatasetV2(Dataset):
+    def __init__(
+        self, input_dir, patch_size, years=None, window_patches=4, stride_patches=2,
+        min_valid_steps=None, min_grid_points=None, split="train", train_until="2022-01-01",
+        valid_until="2023-01-01", clean=True, sw_csv=None, cache_dir=None,
+        cache_file=None, rebuild_cache=False, max_satellites=None,
+        grid_step_days=1.0, leo_only=True, split_mode="time", verbose=True,
+    ):
+        if split not in {"train", "valid", "test", "all"}:
+            raise ValueError("split must be train|valid|test|all")
+        if split_mode not in {"time", "satellite"}:
+            raise ValueError("split_mode must be time|satellite")
+        self.patch_size = int(patch_size)
+        self.window_length = int(window_patches) * self.patch_size
+        self.stride = max(1, int(stride_patches) * self.patch_size)
+        self.min_obs = int(min_valid_steps or self.window_length)
+        self.split = split
+        self.split_mode = split_mode    # 'time' (epoch cutoffs) or 'satellite' (cm-tle-pred 70/15/15)
+        self.train_until_unix = parse_date_to_unix(train_until)
+        self.valid_until_unix = parse_date_to_unix(valid_until)
+
+        # cache-build satellite filter: keep a satellite if it has at least this many
+        # observed grid days. Decoupled from window length so the cache can hold the
+        # full population (per-window length is enforced later in _build_index).
+        cache_min = int(min_grid_points) if min_grid_points is not None else self.window_length
+        self.series = build_daily_series(
+            input_dir, years=years, grid_step_days=grid_step_days,
+            min_grid_points=cache_min, clean=clean, sw_csv=sw_csv,
+            cache_dir=cache_dir, cache_file=cache_file, rebuild=rebuild_cache,
+            leo_only=leo_only, verbose=verbose,
+        )
+        if max_satellites is not None:
+            keep = sorted(self.series.keys())[:max_satellites]
+            self.series = {k: self.series[k] for k in keep}
+        self.index: List[DayWindow] = self._build_index()
+        if verbose:
+            print(json.dumps({
+                "dataset": "TLEDatasetV2", "split": split, "split_mode": split_mode,
+                "num_satellites": len(self.series), "num_windows": len(self.index),
+                "window_days": self.window_length, "patch_size": self.patch_size,
+                "n_channels": N_CHANNELS, "orbital": N_ORBITAL,
+                "phys": N_PHYS, "solar": N_SOLAR,
+            }, indent=2))
+
+    def _split_of(self, epoch):
+        if self.train_until_unix is None or self.valid_until_unix is None:
+            return "all"
+        if epoch < self.train_until_unix:
+            return "train"
+        if epoch < self.valid_until_unix:
+            return "valid"
+        return "test"
+
+    def _build_index(self):
+        out, W = [], self.window_length
+        for norad, s in self.series.items():
+            T = s.feats.shape[0]
+            if T < W:
+                continue
+            # satellite-level split: the whole satellite belongs to one split
+            if self.split != "all" and self.split_mode == "satellite" \
+                    and sat_split_of(norad) != self.split:
+                continue
+            for st in range(0, T - W + 1, self.stride):
+                if int(s.mask[st:st + W].sum()) < self.min_obs:
+                    continue
+                end_epoch = float(s.grid_epochs[st + W - 1])
+                if self.split != "all" and self.split_mode == "time" \
+                        and self._split_of(end_epoch) != self.split:
+                    continue
+                out.append(DayWindow(norad, st, end_epoch))
+        return out
+
+    def __len__(self):
+        return len(self.index)
+
+    def __getitem__(self, i):
+        w = self.index[i]
+        s = self.series[w.norad_id]
+        W = self.window_length
+        feats = s.feats[w.start:w.start + W]
+        mask = s.mask[w.start:w.start + W]
+        epochs = s.grid_epochs[w.start:w.start + W]
+        aux = s.aux[w.start:w.start + W]
+
+        # orbital channels use coverage mask; solar channels are always observed
+        chan_mask = np.zeros((N_CHANNELS, W), dtype=bool)
+        chan_mask[:N_ORBITAL] = mask[None, :]
+        chan_mask[N_ORBITAL:] = True
+
+        return {
+            "target": torch.from_numpy(feats.T.copy()),          # (C, W)
+            "target_mask": torch.from_numpy(chan_mask),           # (C, W)
+            "series_ids": torch.zeros(N_CHANNELS, dtype=torch.long),
+            "meta": {"norad_id": w.norad_id, "length": int(mask.sum()),
+                     "epochs": epochs.copy(), "feats": feats.copy(), "aux": aux.copy()},
+        }
+
+
+def series_collate_fn(batch):
+    return {
+        "target": torch.stack([b["target"] for b in batch], 0),
+        "target_mask": torch.stack([b["target_mask"] for b in batch], 0),
+        "series_ids": torch.stack([b["series_ids"] for b in batch], 0),
+        "meta": [b["meta"] for b in batch],
+    }
+
+
+def main():
+    import argparse
+    from torch.utils.data import DataLoader
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--input-dir", default="/home/irteam/data-vol1/models/OrbitGPT/data/TLEs")
+    ap.add_argument("--cache-dir", default="/home/irteam/data-vol1/models/OrbitGPT/v2/cache")
+    ap.add_argument("--sw-csv", default="/home/irteam/data-vol1/models/OrbitGPT/v2/data/SW-All.csv")
+    ap.add_argument("--start-year", type=int, default=2020)
+    ap.add_argument("--end-year", type=int, default=2020)
+    ap.add_argument("--patch-size", type=int, default=32)
+    ap.add_argument("--window-patches", type=int, default=3)
+    ap.add_argument("--stride-patches", type=int, default=1)
+    ap.add_argument("--min-grid-points", type=int, default=64,
+                    help="cache-build filter: keep satellites with >= this many observed "
+                         "grid days. Low value (e.g. 64) keeps the full population.")
+    ap.add_argument("--no-clean", action="store_true")
+    ap.add_argument("--no-leo", action="store_true", help="disable LEO-only filter")
+    ap.add_argument("--split", default="all")
+    ap.add_argument("--split-mode", default="time", choices=["time", "satellite"])
+    args = ap.parse_args()
+
+    ds = TLEDatasetV2(
+        input_dir=args.input_dir, cache_dir=args.cache_dir, sw_csv=args.sw_csv,
+        years=range(args.start_year, args.end_year + 1), patch_size=args.patch_size,
+        window_patches=args.window_patches, stride_patches=args.stride_patches,
+        min_grid_points=args.min_grid_points, clean=not args.no_clean,
+        leo_only=not args.no_leo, split=args.split, split_mode=args.split_mode,
+    )
+    if len(ds) == 0:
+        print("No windows."); return
+    b = next(iter(DataLoader(ds, batch_size=4, shuffle=True, collate_fn=series_collate_fn)))
+    print("target", tuple(b["target"].shape), "obs frac", round(float(b["target_mask"].float().mean()), 3))
+    print("channels:", N_CHANNELS, "= orbital", N_ORBITAL, "+ phys", N_PHYS, "+ solar", N_SOLAR)
+    m0 = b["meta"][0]
+    print("phys[t0] (rx,ry,rz,vx,vy,vz,...):",
+          [round(float(x), 3) for x in m0["feats"][0][N_ORBITAL:N_ORBITAL + N_PHYS]])
+    print("solar[t0] (f107,f107_81,ap):", m0["feats"][0][N_ORBITAL + N_PHYS:].tolist())
+    track = reconstruct_track(m0["aux"][0], m0["feats"][1:6])
+    print("reconstructed[+5d]:", json.dumps(track[-1], indent=2))
+    print("true[+5d]:", json.dumps(elements_from_feat_aux(m0["feats"][5], m0["aux"][5]), indent=2))
+
+
+if __name__ == "__main__":
+    main()