Upload folder using huggingface_hub

README.md

@@ -0,0 +1,57 @@
+---
+datasets:
+- jgalego/orbit2vec-windows
+- juliensimon/space-track-tle-history
+- juliensimon/space-track-satcat
+- RhynoWu/starlink-maneuver-db
+library_name: pytorch
+license: mit
+model_name: orbit2vec
+pipeline_tag: feature-extraction
+tags:
+- space
+- satellites
+- tle
+- embeddings
+- contrastive-learning
+- weird2vec
+---
+
+# orbit2vec
+
+Embeddings for satellite orbit histories. Two windows of the same object, a month apart, should land close together; other objects should land apart. Part of Weird2Vec, embedding models for data nobody embeds.
+
+> [!NOTE]
+> **What is a TLE?** A two-line element set is the public record of an orbit: mean motion, eccentricity, inclination, node, perigee and drag, at one epoch. Space-Track publishes them for every tracked object, several times a day. A month of them is a trajectory, including its manoeuvres and decay.
+
+## 🚀 Usage
+
+The repo holds the script that trained the model, so one command embeds the last 32 days of a TLE file (oldest first, one object) and names the nearest catalogued objects:
+
+```
+uv run https://huggingface.co/jgalego/orbit2vec/resolve/main/orbit2vec.py embed --tle history.txt
+```
+
+It prints the nearest objects, a guess for regime, constellation or object type and owner, inclination and altitude drift, and the 256-dimensional embedding.
+
+## 🛰️ Data
+
+[jgalego/orbit2vec-windows](https://huggingface.co/datasets/jgalego/orbit2vec-windows): daily mean elements from [juliensimon/space-track-tle-history](https://huggingface.co/datasets/juliensimon/space-track-tle-history), grouped by constellation and owner with [juliensimon/space-track-satcat](https://huggingface.co/datasets/juliensimon/space-track-satcat). Repeated epochs are collapsed to the latest TLE per UTC day. Windows are 32 days long; training pairs are adjacent windows of one object, 10% of the objects are held out, and the test pair is the two windows from 2026-02-28 to 2026-05-02. Manoeuvre labels come from [RhynoWu/starlink-maneuver-db](https://huggingface.co/datasets/RhynoWu/starlink-maneuver-db) and are used for evaluation only.
+
+## 🏋️ Training
+
+Each day becomes 11 features: altitude, its change within the window, eccentricity, inclination and its change, the node and perigee angles as sine and cosine, drag and its rate. Days without a TLE are masked. A transformer encodes the window and a contrastive loss pulls two augmented views (random crop, dropped days) of adjacent windows of the same object together against the rest of the batch. Most of a batch shares one window, so satellites of the same shell compete. Small heads predict regime, constellation, owner, inclination and drift.
+
+Not trained yet.
+
+## 📊 Results
+
+Each object's later test window is matched against the earlier windows of all test test objects. *Seen* objects were in training, in other months; *unseen* objects never were. The baseline matches the mean of the standardized inputs.
+
+Not evaluated yet.
+
+## ⚠️ Limitations
+
+- Mean elements from public TLEs only; accuracy is a few km and classified objects are missing.
+- Windows are 32 days, so slow decay and long manoeuvre campaigns look like noise.
+- Manoeuvre labels cover Starlink only.