ns-3-NTN (source code) is an open-source simulation framework for studying 5G non-terrestrial networks. Built on ns-3 and 5G-LENA, ns-3-NTN is a full-stack simulation framework that integrates SGP4-based orbital and constellation dynamics with a detailed 5G NR protocol stack. It enables joint study of time-varying satellite geometry, radio propagation, PHY/MAC procedures, and higher-layer protocols within a single system-level environment. The framework supports regenerative and transparent payload architectures and is designed to study cross-layer NTN behavior, including link adaptation, scheduling, HARQ, RLC/PDCP interactions, throughput, latency, and other geometry-dependent network effects.
Contributors: Jesse Chiu, Sumit Roy
Research area: Simulation-based Analysis of Airborne Networks
Framework Architecture
Figure 1. Connecting satellite dynamics, radio propagation, and NR protocol behavior.
The framework integrates SGP4-based satellite and constellation dynamics with ns-3 and 5G-LENA to provide a full-stack NTN simulation environment. SGP4 continuously updates satellite position and velocity, from which the simulator derives time-varying link geometry, including slant range, elevation angle, propagation delay, and antenna pointing. These geometric states drive either statistical NTN channel models or Sionna RT-based site-specific channels, enabling both standardized system studies and digital-twin investigations tied to a particular propagation environment.
The resulting channel state is coupled directly into the 5G NR stack, so orbital motion and scene geometry propagate through instantaneous channel response and delay, SINR and block-error probability, PHY procedures, MAC scheduling and HARQ, and higher-layer RLC/PDCP behavior. This enables cross-layer studies of how realistic satellite motion, constellation topology, and propagation dynamics ultimately affect packet delivery, throughput, latency, and protocol performance.
Why ns-3-NTN?
The following summarizes additions in ns-3-NTN compared to stock ns-3.48 and 5G-LENA v5.1. The upstream projects provide LEO mobility, statistical NTN channel models, and the NR protocol stack; ns-3-NTN extends their integration for satellite-network experiments.
| Capability | Stock ns-3.48 + 5G-LENA v5.1 | ns-3-NTN v1.1 (Built on top of ns-3.48 + 5G-LENA v5.1) |
|---|---|---|
| Propagation delay | The LEO example uses zero propagation delay; no channel delay model is configured. | Computes propagation delay from the instant satellite-to-terminal distance. Transparent payloads also include feeder-link and relay delay. |
| Satellite payload architectures | Regenerative payloads only, with the base station (gNB) on the satellite. | Supports both regenerative and transparent bent-pipe payloads. The transparent model includes the gateway-to-satellite-to-UE path and noise accumulation through the amplify-and-forward relay. |
| Multiple UEs per satellite | Supports multiple UEs without propagation delay. | Supports per-UE propagation delay and timing advance, with examples covering up to 10 UEs. |
| NTN scheduling and access timing (TS 38.213) | No NTN K_offset or geometry-based timing advance. | Applies cell-specific K_offset to K1, K2, and Msg3 timing. Updates geometry-based timing advance every slot, models random access with propagation delay, and adjusts RRC timers for the satellite round-trip time. |
| Link-budget configurations | Provides example-specific parameter presets. | Provides TR 38.821 study cases 6, 9, 14, and 15 through --ntnPreset. The simulated SINR is validated with TR 38.821 validation numbers. |
| Link adaptation | Inner-loop link adaptation only. | Adds downlink outer-loop link adaptation (OLLA) to account for outdated channel-state information (CSI). |
| HARQ timing and soft-buffer limits | The timeout, in slots, equals the number of HARQ processes. Soft-buffer capacity is unlimited. | Provides a separate HARQ timeout, finite soft-buffer capacity following TS 38.212 limited-buffer rate matching, and Release 17 HARQ feedback-disabled operation. |
| RLC retransmissions with smaller grants | A retransmission that exceeds the available grant is not re-segmented. | Re-segments RLC acknowledged-mode (AM) retransmissions to fit smaller grants, including when the modulation and coding scheme (MCS) decreases. |
| Sionna RT satellite channels | Includes a Sionna RT channel, but multi-element array handling requires corrections. | Supports LEO passes over Sionna RT scenes, including the UW campus example. Corrects channel coefficients, Doppler, and array orientation, and provides a tool to build scenes from OpenStreetMap data. |
| Experiment and analysis tools | No corresponding NTN tool suite is listed in the baseline comparison. | Provides experiment and analysis scripts, link-budget pre-checks, satellite-pass targeting for a chosen location, animations, and a patch kit with tests on a fresh upstream checkout. |
See the repository comparison table for the detailed baseline comparison. Capabilities and upstream support may change in later releases.
Supported Capabilities
Satellite Architectures and Mobility
Regenerative payloads place the gNB on the satellite and model the satellite-to-terminal service link. Transparent bent-pipe payloads relay the ground-based gNB’s signal through a satellite, accounting for feeder and service links, relay gain, and forwarded noise. Configurable orbits and terminal positions support full-pass studies, while fixed-geometry scenarios help isolate the effects of elevation, channel conditions, and protocol settings.
Propagation and Antennas
Statistical 3GPP NTN channels provide reference propagation scenarios, while Sionna RT represents a specific local environment. Researchers can configure carrier frequency, bandwidth, channel-update interval, antenna gain, array geometry, polarization, and beamwidth. These controls support studies of how satellite motion, propagation loss, Doppler, antenna pointing, and multipath affect link quality.
Link-to-System and Full-Stack PHY/MAC Coupling
To capture how realistic NTN channel dynamics affect PHY and protocol behavior, the framework uses link-to-system mapping to translate the instantaneous, geometry-dependent channel state into SINR, block-error probability, and transport-block outcomes. This preserves the impact of time-varying propagation on the NR stack, rather than representing the satellite link only through fixed capacity, connectivity, or independently generated error models as network simulators usually do.
These PHY outcomes directly drive modulation and coding, outer-loop link adaptation, MAC scheduling, HARQ retransmissions, and higher-layer behavior. NTN-specific extensions further incorporate delayed feedback, scheduling offsets, geometry-derived timing advance, and RTT-dependent protocol timers. Configurable HARQ process counts, finite soft-buffer constraints, HARQ-feedback disabling, and RLC AM/UM operation enable cross-layer studies of how satellite-channel dynamics propagate from PHY reliability to throughput, latency, and end-to-end protocol performance.
Figure 2. Simulation architecture and the interaction between mobility, channel models, and NR processing. Parameter values in the schematic illustrate a particular configuration.
Performance Evaluation
TCP and UDP traffic models, configurable offered loads, and packet sizes support application-level experiments. Time-resolved traces connect satellite trajectory and signal-to-interference-plus-noise ratio (SINR) with modulation and coding scheme (MCS), block errors, HARQ activity, throughput, and packet delay. Experiment scripts support parameter sweeps, repeated runs, and analysis of link adaptation and retransmission behavior.
ns-3-NTN Digital twin: Ray Tracing with Sionna RT
ns-3-NTN now supports Sionna RT to enable digital-twin NTN studies. Building on our Sionna NTN RT framework, a site-specific three-dimensional scene captures local buildings, terrain and ground surfaces, radio materials, and terminal locations. Ray tracing resolves the direct and multipath propagation components, allowing blockage, reflection, and diffraction with different materials to modify the instantaneous NR channel. As the satellite moves, these site-specific channel changes propagate through link adaptation, HARQ, scheduling, and packet delivery, directly connecting the local physical environment to network-level performance.
Sionna RT is invoked through an embedded Python interface within ns-3. The satellite direction, velocity, and antenna orientation are transformed into the scene’s local coordinate system. The resulting path coefficients, excess delays, Doppler shifts, and antenna responses are then used to construct the time-varying channel consumed by 5G-LENA.
This integration provides a reproducible path from a site-specific digital representation of the environment to full-stack NTN performance, enabling digital-twin studies that cannot be captured by purely statistical channel models.
Ray-traced LEO pass over UW Red Square, showing changing propagation geometry, channel quality, MCS, and throughput. The example uses a 500 km orbit, a 12 GHz carrier, and 10 MHz bandwidth. Building data © OpenStreetMap contributors, ODbL.
Software and Publications
The repository provides source code, installation instructions, simulation examples, and tools for reproducing the documented experiments.
K.-P. Chiu and S. Roy, “5G NR NTN Link-to-System Simulation in ns-3-NTN,” 4th Workshop on LEO Networking and Communication (LEO-NET ’26), Denver, CO, USA, August 2026, ACM. Read the paper.
