openntn 2.0.0a3

3GPP TR 38.811 non-terrestrial network channel models for Sionna

Overview

OpenNTN is an open-source extension of Sionna that implements the non-terrestrial network (NTN) channel models of 3GPP TR 38.811 for satellite links. Its channel models follow the interface of Sionna's TR 38.901 models, so they can be used in Sionna's link-level and system-level simulations. OpenNTN 2 is built on Sionna 2, which uses PyTorch.

Key features

• Scenarios: dense urban (DenseUrban), urban (Urban) and suburban (SubUrban), with the parameter tables of TR 38.811 clause 6.7.2 and the fast-fading process of TR 38.901 clause 7.5.
• Bands and links: S band (1.9 GHz to 4 GHz) and Ka band (19 GHz to 40 GHz), uplink and downlink, elevation angles from 10 to 90 degrees.
• Propagation (TR 38.811 clause 6.6): line-of-sight probability, free-space path loss, shadow fading, clutter loss, atmospheric gas absorption, ionospheric scintillation in the S band and tropospheric scintillation in the Ka band. The shadow fading is the large scale parameter SF of TR 38.901 clause 7.5, step 4, applied once in step 12: TR 38.811 eq. (6.6-4) writes it into the basic path loss, and its Tables 6.7.2-1a to 6.7.2-8b give its cross-correlations and correlation distance, so the basic path loss of the models is the free-space path loss plus the clutter loss.
• Satellite Doppler: the Doppler shift of the satellite's orbital motion, in addition to the motion of the user terminals; it can be switched off.
• Antennas: Sionna-style antenna elements, panels and arrays with the TR 38.901 element pattern, an omnidirectional pattern, a circular-aperture pattern and the co-phased dual-linear-polarization pattern of 3GPP R1-1802551.
• Topology: a generator for one satellite and the user terminals of a single sector at a given elevation angle and satellite height.
• Sionna integration: the models are Sionna channel models. They return path coefficients and delays in Sionna's format and work with Sionna's channel functions and blocks, such as cir_to_ofdm_channel and OFDMChannel.

Installation and requirements

OpenNTN 2 requires Python 3.11 or later and Sionna 2.0.1 or later within 2.x (sionna>=2.0.1,<3.0). Further dependencies (PyTorch, NumPy, matplotlib) are installed with it.

1. Install PyTorch for your platform, CPU or CUDA, as described at https://pytorch.org/get-started/locally/.

2. Install OpenNTN:

   python -m pip install openntn
   

OpenNTN 2 is a pre-release until 2.0.0, and its interfaces can still change. pip installs a pre-release only if no final release of openntn is available; otherwise --pre is needed (python -m pip install --pre openntn). The changes of this version are listed in the changelog.

Note: openntn 2.x requires Sionna 2.x. Installing it into an environment with Sionna 1.x upgrades Sionna to 2.x. For Sionna 1.x and Sionna 0.19, use the corresponding versions of OpenNTN from the repository at https://github.com/ant-uni-bremen/OpenNTN.

Quickstart

from sionna.phy.channel import cir_to_ofdm_channel, subcarrier_frequencies

from openntn import Antenna, AntennaArray, Urban
from openntn.utils import gen_single_sector_topology

carrier_frequency = 2.2e9   # S band downlink
elevation_angle = 50.0      # degrees

# User terminal: one antenna; satellite: 4 x 4 dual-polarized array
ut_array = Antenna(polarization="single", polarization_type="V",
                   antenna_pattern="omni", carrier_frequency=carrier_frequency)
bs_array = AntennaArray(num_rows=4, num_cols=4, polarization="dual",
                        polarization_type="cross", antenna_pattern="38.901",
                        carrier_frequency=carrier_frequency)

channel_model = Urban(carrier_frequency=carrier_frequency, ut_array=ut_array,
                      bs_array=bs_array, direction="downlink",
                      elevation_angle=elevation_angle)

# 16 examples of a single sector: one satellite at 600 km, 4 user terminals
topology = gen_single_sector_topology(batch_size=16, num_ut=4, scenario="urb",
                                      elevation_angle=elevation_angle, bs_height=600e3)
channel_model.set_topology(*topology)

# One channel realization: path coefficients a and path delays tau
a, tau = channel_model(num_time_samples=1, sampling_frequency=15e3)

# Frequency response on 72 subcarriers with Sionna's channel functions
frequencies = subcarrier_frequencies(num_subcarriers=72, subcarrier_spacing=30e3)
h_freq = cir_to_ofdm_channel(frequencies, a, tau, normalize=True)
print(h_freq.shape)  # [batch, rx, rx antennas, tx, tx antennas, time steps, subcarriers]

A channel model runs on the device given by its argument device, for example device="cuda:0", which defaults to sionna.phy.config.device at the construction of the model; create the antennas on the same device, with their argument device, which has the same default. A model stays on its device and in its precision: build it with the device and precision it is to use instead of moving it with .to() or casting it. Moved or cast after the last set_topology, its call raises ValueError; a move or cast at another point fails with an error from PyTorch.

Citation

If you use OpenNTN in your research, please cite:

T. Düe, M. Vakilifard, C. Bockelmann, D. Wübben and A. Dekorsy, "OpenNTN: An Open-Source Framework for Non-Terrestrial Network Channel Simulations," 2025 28th International Workshop on Smart Antennas (WSA), Erlangen, Germany, 2025, https://doi.org/10.1109/WSA65299.2025.11202820

@inproceedings{OpenNTNPaper,
  author = {T. D\"{u}e and M. Vakilifard and C. Bockelmann and D. W\"{u}bben and A. Dekorsy},
  title = {OpenNTN: An Open-Source Framework for Non-Terrestrial Network Channel Simulations},
  booktitle = {2025 28th International Workshop on Smart Antennas (WSA)},
  address = {Erlangen, Germany},
  year = {2025},
  month = {Sep},
  pages = {1--7},
  doi = {10.1109/WSA65299.2025.11202820}
}

Licence

OpenNTN is distributed under the licence expression MIT AND Apache-2.0:

• Files derived from NVIDIA Sionna are licensed under the Apache License 2.0 (LICENSE-APACHE). Their headers keep NVIDIA's copyright notice and, for modified files, state that they were modified at the University of Bremen.
• All other files are licensed under the MIT License (LICENSE).

Data files cannot carry a header. TDL-A30.json, TDL-B100.json and TDL-C300.json in openntn/models are unchanged copies of Sionna's files and therefore under Apache-2.0; the other TDL and CDL files hold the NTN-TDL and NTN-CDL parameters of TR 38.811 (Tables 6.9.1-1 to 6.9.1-4 and 6.9.2-1 to 6.9.2-4) and are under MIT like all other files.

The OpenNTN logo is not covered by these licences.

Maintainer and contact

Louis Lagona lagona@ant.uni-bremen.de

Bug reports and questions: https://github.com/ant-uni-bremen/OpenNTN/issues

Acknowledgements

OpenNTN was originally written by Tim Düe at the Department of Communications Engineering (Arbeitsbereich Nachrichtentechnik) of the University of Bremen, https://www.ant.uni-bremen.de/. It builds on NVIDIA Sionna.