ntn-constellation 0.1.0

Live TLE feeds, SGP4/SDP4 propagation, and constellation presets for the ns3-ntn-toolkit. Bridges CelesTrak/Space-Track to ns-3 SNS3 (SatelliteSGP4MobilityModel) and CesiumJS visualization.

ntn-constellation

Constellation Database, Live TLE Feeds and SGP4/SDP4 Propagation for 6G NTN Research

---

Why this module

Reproducible NTN research requires three things that, separately, are easy and, together, are surprisingly painful: fresh ephemerides (today's TLEs, not last year's), a propagator that an ns-3 simulation actually trusts (SGP4/SDP4 with frame conversions that don't drift), and export shapes that drop into both the simulator (SNS3 scenario layout) and the visualiser (CesiumJS CZML). ntn-constellation is a pure-Python, tool-side companion that produces all three in one pass — pulling from CelesTrak or Space-Track, propagating with the canonical Vallado SGP4 reference, and emitting the exact files that SatSGP4MobilityModel and the in-toolkit 3D viewer already know how to consume. It does not modify the C++ ns-3 build; it produces inputs the existing simulator already understands.

At a glance

Metric	Value
Built-in presets	Starlink (shells 1+2 + polar) · OneWeb · Kuiper · Telesat Lightspeed · Iridium NEXT
Walker generators	walker_delta · walker_star (emit valid SGP4-parseable TLEs)
Propagator backends	sgp4 (Brandon Rhodes / Vallado) + skyfield cross-check
ISL topology builders	k-NN with range cap · closed-form Walker +grid
Live feeds	CelesTrak (no credentials) · Space-Track (SPACETRACK_USER/PASS)
TLE cache	TTL-based, default 6 h, on-disk
24 h propagation, 66 sats, 1440 samples	0 NaN, 0.4 s wallclock
W1→W2 vs Skyfield (1800 s pass, STARLINK-1008)	max 23.5 µs, drift 0.006 µs/s
W1→W4 GAT next-hop accuracy (60 sats, real Walker-Star geometry)	90 %

What it does

• 3GPP-compliant ephemeris pipeline: live CelesTrak / Space-Track fetch with on-disk TTL cache, robust TLE parser with checksum-aware records.
• Six built-in named constellations and two Walker generators emitting valid SGP4-parseable TLEs (used as the input layer for every other toolkit module).
• Satellite / Constellation API over Skyfield + raw sgp4 for sub-millisecond per-tick propagation; geodetic subpoint, ECI state vector, ground-station elevation/azimuth/range.
• ISL topology generation (build_isl_topology k-nearest with range cap; grid_isl_topology_walker closed-form +grid for Walker layouts) — verified zero edge churn over 24 h on a Walker-Star shell.
• Two exporter sinks: write_sns3_scenario emits the exact positions/{tles,isls,start_date,gw_positions,ut_positions}.txt layout SatSGP4MobilityModel (SNS3) consumes, and write_czml emits sampled-position CesiumJS CZML for the in-toolkit 3D viewer.
• ntn-fetch CLI entry point for one-line scenario builds (preset or live).

Install & run

git clone https://github.com/Muhammaduazir69/ntn-constellation.git contrib/ntn-constellation
cd contrib/ntn-constellation
python3 -m venv .venv
.venv/bin/pip install -e .[test]

Live: current Starlink → SNS3 + Cesium

.venv/bin/ntn-fetch starlink --out data/starlink-now \
    --max-sats 200 --czml --czml-duration-min 120 --czml-step-sec 30 -v

Preset (no internet): Kuiper Phase-1 Walker

.venv/bin/ntn-fetch kuiper --out data/kuiper --isl-walker --czml

Programmatic:

from datetime import datetime, timedelta, timezone
from ntn_constellation import (
    CelesTrakFeed, TleCache, Constellation,
    build_isl_topology, write_sns3_scenario, write_czml,
)

feed = CelesTrakFeed(cache=TleCache("./.cache"))
tles = feed.fetch_group("oneweb")[:100]

c = Constellation.from_tles(tles)
when = datetime.now(tz=timezone.utc)

visible = c.visible_from(when, observer_lat_deg=33.6844,
                         observer_lon_deg=73.0479, min_elevation_deg=10)
isls = build_isl_topology(c, when, k_nearest=4, max_range_km=5000.0)
write_sns3_scenario(scenario_dir="data/oneweb-sample", tles=tles,
                    start_date=when, isls=isls)
write_czml(constellation=c, start=when, duration=timedelta(hours=2),
           sample_step=timedelta(seconds=30),
           out_path="data/oneweb-sample/oneweb.czml")

Verification

10 unit tests cover TLE parsing, preset generation, SGP4 propagation, ISS visibility from Islamabad, ISL topology, and SNS3 file layout. End-to-end pipeline numbers measured against an independent Skyfield reference:

Check	Result
24 h propagation, 66 sats, 1440 samples	0 NaN, 0.4 s wallclock
Orbital period (Walker-Star Starlink-shell-1)	96.00 min (TLE-line-2 nominal 95.6)
Altitude bounds across 24 h	542.9 – 554.8 km (drift end-vs-start +0.0 km)
ISL 4-NN graph across 24 hourly snapshots	132 directed edges every snapshot, every node degree 4
Live CelesTrak STARLINK-1008 vs Skyfield (600 s)	mean |err| 2.6 µs, max 5.8 µs
Extended pass (1800 s)	max |err| 23.5 µs, drift |err|/dt 0.006 µs/s
Real Walker-Star → PyG → GAT next-hop accuracy (60 sats)	90 % on real geometry

The single Walker-Star shell exhibits zero ISL edge churn over 24 h — expected analytically and confirmed by the propagator. The Skyfield-vs-SNS3 residual grows linearly at 0.006 µs/s (well under the 0.5 µs/s tolerance), so hour-long Starlink scenarios stay tightly aligned with ground-truth ephemerides.

Documentation

• INSTALL.md — full setup with the CelesTrak/Space-Track environment variables.
• Reference: B. Rhodes, sgp4 — Python implementation of SGP4 by Vallado et al., https://pypi.org/project/sgp4/
• 3GPP TR 38.821 §6.1 — Reference satellite parameters.

Cite this work

@misc{uzair2026ntnconstellation,
  author = {Uzair, Muhammad},
  title  = {ntn-constellation: Live TLE Feeds, SGP4/SDP4 Propagation and SNS3/CesiumJS Exporters for 6G NTN Research},
  year   = {2026},
  url    = {https://github.com/Muhammaduazir69/ntn-constellation}
}

Part of the ns3-ntn-toolkit

This module is part of ns3-ntn-toolkit — a pre-integrated ns-3.43 distribution for 6G NTN research:

Module	Repo
Toolkit (umbrella)	ns3-ntn-toolkit
ntn-constellation	this repo
ntn-rrc	ntn-rrc
ntn-observability	ntn-observability
ns3-ai (fork)	ns3-ai
ntn-sagin	ntn-sagin
ntn-slice	ntn-slice
ntn-v2x	ntn-v2x
flexric-bridge	flexric-bridge
ntn-sionna	ntn-sionna
ntn-digital-twin	ntn-digital-twin
ntn-cho	ntn-cho-framework
oran-ntn	oran-ntn
thz-ntn	ns3-thz-ntn

License

GPL-2.0-only — see LICENSE.

Acknowledgements

Brandon Rhodes (sgp4, Skyfield) · CelesTrak (Dr. T. S. Kelso) · Space-Track / 18th Space Defense Squadron · CesiumJS · pytroll (pyorbital) · ns-3 core team · SNS3 maintainers.