[Release] ns-3-NTN: a full-stack 5G NR non-terrestrial network simulation on ns-3.45 + 5G-LENA

[Jesse Chiu]

Hello all,

We are releasing ns-3-NTN v1.0.0, an open-source full-stack system-level simulator for 5G NR Non-Terrestrial Networks. It couples LEO orbital dynamics and the 3GPP NTN channel models to the complete 5G NR PHY/MAC and higher-layer stack, so the whole chain runs end to end:
orbit geometry → slant range and elevation → channel and propagation delay → PHY SINR/BLER → link adaptation, HARQ, scheduling → RLC/PDCP and application performance.


WHAT IS IN IT

• 3GPP-aligned satellite architectures: regenerative payload (gNB on board, single hop) and transparent bent-pipe variants with a gateway-to-satellite feeder link, an optional
•  inter-satellite link, and a satellite-to-UE service link.
• Dynamic, elevation-dependent, per-UE NTN control-loop RTT applied to scheduling requests, CQI reports and DL HARQ feedback, so scheduling, link adaptation and HARQ observe the delay produced by the current satellite geometry rather than a constant.
• Link adaptation for NTN: downlink OLLA on top of the existing ILLA/CQI path, and
•  limited-soft-buffer rate matching in the EESM error model, so incremental redundancy is modelled against a finite buffer rather than an infinite one.
• Rel-17 HARQ: up to 32 processes, N1/N2 timing extended to 100 slots, and feedback-disabled operation.
• RLC: retransmission re-segmentation in AM, plus reassembly and buffer-reporting fixes.
• Traces: satellite trajectory, per-RB SINR, MCS, HARQ, TBLER, throughput and latency, all time-resolved.
• LEO orbit mobility ported from ns-3-leo, with geocentric ECEF positioning.

WORKED EXAMPLES

The NTN teaching and example guide provides seven worked examples, each isolating one mechanism:
https://gitlab.com/jessest94106/ns-3-dev-NTN/-/blob/v1.0.1/ntn/README.md

1. Pre-simulation link check: close the link budget and check slant range, SNR, Shannon throughput ceiling, RTT and HARQ-pipeline depth before starting a long simulation.
2. Full regenerative LEO pass: 5° → 90° → 5°, coupling live geometry to channel quality,
3. MCS, HARQ and delivered throughput.
4. ILLA versus OLLA: show how the outer loop moves the CQI-selected MCS toward a target first-transmission BLER at fixed elevations.
5. Transparent bent-pipe pass: separate feeder, optional ISL and service-link geometry, cascaded SNR and the resulting HARQ loop RTT.
6. RLC ARQ: compare UM and AM when RLC must recover the blocks left corrupt after all HARQ attempts, including the resulting loss-versus-delay tradeoff.
7. Beam edge: compare centre, 30 km and 50 km UEs under a time-varying Airy spot-beam pattern.
8. Scheduling under CSI aging: compare RR, PF and MR for ten UEs with fresh versus stale channel-state information.

*Examples 1, 2, 4 and 6 include exact commands and reproduce as written. Examples 3 and 5 publish their full configurations and use the included parameter-file harnesses. Every tracked figure has a generating command and source description in the figure-provenance guide:
https://gitlab.com/jessest94106/ns-3-dev-NTN/-/blob/v1.0.1/ntn/figures/README.md

TOOLS AND EXPERIMENT HARNESSES

The release includes the supporting workflow needed to configure, run, analyse and reproduce the examples:

• - ntn_precheck.py: an arithmetic pre-check with regenerative and bent-pipe presets. It reports slant range, FSPL, SNR, a first-order throughput ceiling, RTT and HARQ-loop time, and warns when the link falls below MCS 0 or the loop exceeds the configured HARQ pipeline. https://gitlab.com/jessest94106/ns-3-dev-NTN/-/blob/v1.0.1/ntn/tools/ntn_precheck.py
• Simulation harnesses: regenerative full-pass sweeps, one- and two-satellite bent-pipe comparisons, and parameter-file runners for both payload architectures.
• Analysis and plotting: scripts for summary tables, elevation-binned statistics, HARQ and RLC analysis, per-UE beam-footprint statistics, scheduler plots and full-pass figures.

The complete released script inventory and direct-use examples are in the tools and harness guide:
https://gitlab.com/jessest94106/ns-3-dev-NTN/-/blob/v1.0.1/ntn/scripts/README.md

GETTING IT

    git clone --branch v1.0.1 --recurse-submodules \
      https://gitlab.com/jessest94106/ns-3-dev-NTN.git
    cd ns-3-dev-NTN
    ./ns3 configure --enable-examples -d optimized
    ./ns3 build leo-link-bent-pipe-1hop
    ./ns3 run "leo-link-bent-pipe-1hop"

contrib/nr is a submodule pinned to an exact commit of:
https://gitlab.com/jessest94106/nr-ntn-dev
The pin matters: the examples will not build against stock 5G-LENA v4.1.

Components:

• ns-3: 3.45
• 5G-LENA (contrib/nr): v4.1 fork
• License: GPL-2.0-only

Toolchain and known environment issues:
https://gitlab.com/jessest94106/ns-3-dev-NTN/-/blob/v1.0.1/COMPATIBILITY.md



WHAT IT DOES NOT DO YET
TN–NTN integration, handover and DVB-S2 are planned, not implemented. Anything not listed in the NTN example guide should be treated as unverified. The current timing model uses an ideal timing-advance abstraction: the PHY remains slot-synchronous while geometry-derived RTT is applied when the gNB processes scheduling requests, CQI reports and HARQ feedback. The configuration is parameterised from published Starlink radio and orbital parameters.

UPSTREAMING
New features land in ns-3-NTN first. Where they are general rather than NTN-specific — the RLC AM re-segmentation work, the HARQ timing range and downlink OLLA — we intend to propose them to 5G-LENA and to mainline ns-3. ns-3-NTN will continue as the development platform for NTN-specific harnesses, tools and experimental features.

------------
We welcome feedback, questions, issue reports, feature requests and contributions, and we are happy to discuss roadmap priorities and upstreaming paths that best serve the ns-3 and 5G-LENA user communities.

Jesse Chiu (Kuan-Po) 

FUNLab, ECE, University of Washington, Seattle