← Go back to home

5G-LENA

ns-3 module to simulate 5G NR networks
4.83/5 (874 reviews)
0 downloads
Categories: LTE, Wireless, 5G

The ns-3 NR module (aka 5G-LENA) is a pluggable module for ns-3 that can be used to simulate 5G New Radio (NR) cellular networks. The simulator is the natural evolution of LENA, the LTE/EPC Network Simulator, but its development started from the mmWave module because it was more advanced in terms of beamforming, TDD, 3GPP channel model, and operation at FR2. It incorporates fundamental PHY-MAC NR features aligned with 3GPP NR Release-15 and later.

It is a module that can be plugged in ns-3-dev and supports the following features:

  • NSA (Non-Standalone Architecture): 5G RAN and 4G EPC
  • Compatible with ns-3 3GPP 38.901 spatial channel and antenna array models able to simulate 0.5-100 GHz frequency ranges

  • PHY:

    • 3GPP antenna arrays with multiple-ports and dual-polarized antennas
    • 3GPP MIMO supporting currently up to two streams through either multiple antenna ports or dual-polarized antennas
    • 3GPP-compliant PMI (precoding matrix indicator) and RI (rank indicator), assuming MMSE-IRC (interference rejection combining) receiver for inter-stream interference suppression
    • CQI/PMI/RI feedback, PM search, and rank adaptation for MIMO
    • NR PHY layer abstraction, considering LDPC codes, MCS Tables 1 and 2 (up to 256-QAM), LDPC base graph selection and NR block segmentation
    • Chase Combining and Incremental Redundancy HARQ
    • Uplink power control
    • SRS(Sounding reference signals ) modeling
    • Realistic beamforming based on SRS-based channel estimates
    • NR-compliant processing delays and control timings (N0, N1, N2; K0, K1, K2)
    • Multiple BWPs and component carriers support
    • TDD (Time Division Duplexing) and FDD(Frequency Division Duplexing) modes
    • Configurable TDD patterns
    • ICIC (Inter-Cell Interference Coordination) through notching
    • Flexible and automatic configuration of the NR frame structure through multiple numerologies
    • TDMA (Time-Division Multiple Access)
    • OFDMA (Orthogonal Frequency-Division Multiple Access) with variable transmission time intervals and single beam capability

  • MAC:

    • Flexible MAC schedulers that simultaneously consider time- and frequency-domain resources both for TDMA and OFDMA-based access schemes
    • QoS schedulers
    • QoS LC assignment
    • UL grant-based access scheme with scheduling request
    • 3GPP-compliant UL buffer status reporting
  • Utilities:
    • NGMN traffic models: video streaming, voice over IP (VoIP), uplink/downlink gaming, FTP
    • 3GPP XR traffic models: XR (AR, VR and CG) and 3GPP FTP Model 1
  • Helpers:
    • REM (Radio Environment Map) visualization helpers
    • Topologies helpers, e.g., hexagonal topology helper and grid topology helper
    • Spectrum configuration helpers
    • Multi-Cell and multi-BWP configurations helpers support allowing multiple cells with different configurations
    • RAN protocol stack trace helpers

We additionally offer two extensions: NR-U and NR V2X extensions. NR-U is distributed as a separate module, while NR V2X is distributed as a branch of the NR module.

  • NR-U extension aims to operate in unlicensed spectrum, through multiple channel access managers, including duty-cycling as well as Listen-Before-Talk (LBT)-based procedures.
  • NR V2X extension is intended for vehicular communications, including support of NR frame structure, PSCCH and PSSCH multiplexing, resource allocation for NR V2X using mode 2 (autonomous resource selection), SCI (Sidelink Control Information) update, compliance with scenarios and channel models based on TR 38.885. Our initial focus is on: frequency range 1 with numerologies 0, 1, and 2, TDD system, out-of-coverage scenarios, mode 2 resource allocation, broadcast communications, omnidirectional transmissions/receptions for sidelink, sensing-based semi-persistent scheduling (for basic service messages), slot-based scheduling, PSCCH/PSSCH time multiplexing, and blind retransmissions.

Publications

For further information about the capabilities, implementation model and validation details of the 5G-LENA Simulator, please refer to the full list of publications.

If you use the NR module in your research, please consider citing some of the:

  • N. Patriciello, S. Lagen, B. Bojovic, L. Giupponi, An E2E Simulator for 5G NR Networks, Elsevier Simulation Modelling Practice and Theory (SIMPAT), vol. 96, 101933, Nov. 2019. Available here.
  • K. Koutlia, B. Bojovic, Z. Ali, S. Lagen, Calibration of the 5G-LENA System Level Simulator in 3GPP reference scenarios, Elsevier Simulation Modelling Practice and Theory (SIMPAT), vol. 119, 102580, Sept. 2022. Available here.

If your work is based on the NR-U extension, please cite:

  • N. Patriciello, S. Lagen, B. Bojovic, L. Giupponi, NR-U and IEEE 802.11 Technologies Coexistence in Unlicensed mmWave Spectrum: Models and Evaluation, in IEEE Access, vol. 8, pp. 71254-71271, 2020. Available here.

If your work is based on the NR V2X extension, please cite:

  • Z. Ali, S. Lagen, L. Giupponi, R. Rouil, 3GPP NR V2X Mode 2: Overview, Models and System-level Evaluation, IEEE Access, vol. 9, pp. 89554-89579, June 2021. Available here.

Future work

The following features are intended to be added to the project in the future:

  • NR RRC improvements (RACH, handover, etc.)
  • NR RLC improvements
  • NR-U improvements
  • NR-V2X improvements
  • UL configured grant
  • Real modeling of control channels (PDCCH, PUCCH)
  • Xn interface

About 5G-LENA

The (5G-LENA)[https://5g-lena.cttc.es/] module is being developed and maintained by the CTTC OpenSim Research Unit. Its initial development was funded by InterDigital, and subsequent support has been provided by the Lawrence Livermore National Lab (LLNL), a grant from the National Institute of Standards and Technologies (NIST), and Meta (earlier Facebook). It continues to evolve through successful collaborations with industrial partners.

Documentation

The documentation for NR is available in the docs/manual of https://5g-lena.cttc.es

The documentation for NR V2X is available here in Section 2.16.

v3.1

Works with ns-3.42

Latest Build :

Build History : 5G-LENA v3.1

Release Notes

<ul> <li>This release comes with a completely new PMI Type-I Single Panel codebook for MIMO.</li> <li>Performance optimizations were included for faster simulations.</li> <li>The code base is updated for C++ conformance and aligned with ns-3.42.</li> <li>Many bugs were fixed. One of them is significant, however it is limited to NR-U users.</li> <li>We introduced two new CI jobs. The first to improve uniformization of commit messages. The second catches memory related bugs, allowing for us or contributors to fix them before finding them on the wild, crashing simulations or generating bogus results.</li> </ul> <p>Remember to follow the instructions from the README.md file, i.e., to checkout the correct release branch of both ns-3 and the NR module. The information about compatibility with the corresponding ns-3 release branch is stated in the README.md file.</p>

NR-v3.0

Works with ns-3.41

Build History : 5G-LENA NR-v3.0

Release Notes

<h2>Release NR-v3.0</h2> <h2>Availability</h2> <p>Available since February 16, 2024</p> <h2>Cite this version</h2> <p>DOI: 10.5281/zenodo.10670856</p> <h2>Supported platforms</h2> <p>This release has been tested on the following platforms: - Arch Linux with g++-13 and clang-16. - Ubuntu 20.04 with g++-9 and 10, and clang-10. - Ubuntu 22.04 with g++11 and 12 and clang-11 and 14. - Ubuntu 23.04 with g++13. - Ubuntu 23.10 (Mantic Minotaur) with clang-16.</p> <p>This release is compatible with ns-3.41.</p> <h2>Important news</h2> <ul> <li> <p>This release comes with a completely new MIMO model implementation. Comparing to the previous dual-polarized implementation, this new model offers a much more general approach and can be easily extended to support different types of MIMO, which was not the case with the previous implementation which was limited to a particular case of MIMO, i.e., DualPolarized-MIMO (DP-MIMO), supporting only 2 streams with no possibility for extension. Old DP-MIMO implementation used some assumptions related to the mapping of the streams to ports that were limiting its application, i.e., each stream was mapped to the antenna elements with a specific polarization. This means that there was a hard limitation on the assignment of streams to a specific port and to the specific antenna elements of one polarization. Also, it used a not realistic inter-stream interference rejection model. Instead, the new MIMO implementation will support general MIMO, through the inclusion of 3GPP-compliant PMI (precoding matrix indicator) and RI (rank indicator), assuming MMSE-IRC (interference rejection combining) receiver for inter-stream interference suppression, as adopted in 3GPP. Such general MIMO includes as particular case the old DP-MIMO, but with a more generic and realistic model for DP-MIMO in which the streams/port/antennas mapping is not predefined but defined through digital precoding and in which a more accurate model for the inter-stream interference calculation is considered. The new MIMO is flexible and can be easily extended for more streams/ranks/ports.</p> </li> <li> <p>The current MIMO implementation requires Eigen3 library (https://eigen.tuxfamily.org/).</p> </li> <li> <p>When creating an MR, 5G-LENA users will be able to use CI/CD minutes belonging to the NR module project.</p> </li> <li> <p>The code base is updated and a bit modernized, e.g. to use standard integer types, simpler bool checks, spelling errors are fixed, automatic clang-tidy fixes are applied, for loops are modernized, python formatter settings were added, etc.</p> </li> <li> <p>Remember to follow the instructions from the README.md file, i.e., to checkout the correct release branch of both ns-3 and the NR module. The information about compatibility with the corresponding ns-3 release branch is stated in the <code>README.md</code> file.</p> </li> </ul> <h2>New user-visible features</h2> <ul> <li> <p>A new MIMO model is available in the NR module. The <code>cttc-nr-mimo-demo</code> example shows how to use and configure the new MIMO model. See the NR manual and Doxygen for the full description of the new MIMO model and APIs. The new APIs are also listed CHANGES.md.</p> </li> <li> <p>The NR module pipelines have been improved in multiple aspects:</p> </li> <li>GCC 13 CI jobs are added.</li> <li>Ubuntu rolling CI jobs are added to weekly tests.</li> <li>Cmake format CI job is added.</li> <li>Black and isort formatter settings for python were added and applied.</li> <li>Added python format CI job.</li> <li>Added spell-checking CI job.</li> <li>Clang-tidy CI job is added.</li> <li>The documentation build and deployment are split now, and the deployment is limited to master.</li> <li>Merge request pipelines are enabled.</li> </ul>

NR-U-v0.2

Works with ns-3.34

Build History : 5G-LENA NR-U-v0.2

Release Notes

<p>In this release, nr-u module is upgraded to be compatible with the latest official ns-3-dev and nr modules.</p> <p>The upgrade, completed by [Rediet] (https://gitlab.com/rediet), contains:</p> <ul> <li> <p>Standard renaming for class/file/variable names (MmWave -&gt; Nr, Enb -&gt; Gnb)</p> </li> <li> <p>Deprecated NR classes MmWavePhyMacCommon, BandwidthPartRepresentation replaced with CcBwpCreator, OperationBandInfo, IdealBeamformingHelper</p> </li> <li> <p>wscript: added libraries for classes now part of the ns-3 core instead of NR.</p> </li> </ul> <p>The release is compatible with nr module release 5g-lena-v1.1.y and later, and ns-3.34 and later.</p>

NR-v1.2

Works with ns-3.33

Build History : 5G-LENA NR-v1.2

Release Notes

<p>This release includes File Transfer Protocol (FTP) model 1 traffic model, new helpers, new APIs and various fixes.</p>

NR-v1.1

Works with ns-3.32

Build History : 5G-LENA NR-v1.1

Release Notes

<ul> <li>The scheduler can selectively leave particular RBG empty. This feature is called notching, and is used when multiple gNBs are collaborating to avoid interferences over a spectrum part.</li> <li>Added SRS allocation,transmission, and reception. Added an SRS message that takes 4 symbols (in the default configuration) within some periodicity (default at 80 slots). SRS are dynamically scheduled by the gNB (with an interface and an example specialized scheduler for it, NrMacSchedulerSrsDefault), and its allocation is signaled to the UE through a DCI. This is used by the UE to transmit SRS.</li> <li>RealisticBeamformingAlgorithm class is added. It implements a beamforming algorithm that determines the beamforming vectors of the transmitter and the receiver based on the SINR SRS. Uplink power control functionality implemented through the NrUePowerControl class, supporting UL power control for PUSCH, PUCCH, and SRS.</li> <li>IPV6 is now supported. That is, the end-to-end connections between the UEs and the remote hosts can be IPv4 or IPv6.</li> </ul>

NR-v1.0

Works with ns-3.31

Build History : 5G-LENA NR-v1.0

Release Notes

<p>This release adds new features, including FDD, channel model aligned with ns-3-dev, control timings and processing delays, realistic MAC headers, various trace sources, renamed traces/classes/examples/helpers.</p>

NR-v0.4

Works with ns-3.31

Build History : 5G-LENA NR-v0.4

Release Notes

<p>This release includes the complete PHY abstraction for NR error modelling.</p>

NR-v0.2

Works with ns-3.29

Build History : 5G-LENA NR-v0.2

Release Notes

<p>This release adds new features, including NR frame structure, support of numerologies, flexible TTI, mini-slots, mixed UL-DL slot formats, OFDMA- and TDMA-based access, a selection of schedulers, NR timings, FDM of numerologies, and UL standard-compliant scheme with SR/UL-grant/BSR.</p>

NR-v0.3

Works with ns-3.30

Build History : 5G-LENA NR-v0.3

Release Notes

<p>This release adds new features, including a new MAC/PHY state machine to control channel access, an updated channel model, with a separate procedure for beamforming and the possibility to compute UE/UE and gNB/gNB interferences, and the interface for the new NR L2SM.</p>
Note that we have three ns-3 extensions, and the installation steps for each are different: 1. NR module, which is released as a standalone 'nr' module compatible with mainline ns-3 2. NR V2X extension, which is released as a branch of 'nr' with a patched ns-3 3. NR-U extension, for which both the 'nr' and 'nr-u' modules are needed, and which is compatible with mainline ns-3 To get the NR module, please follow the instructions here: [https://5g-lena.cttc.es/download/](https://5g-lena.cttc.es/download/). The instructions to download the NR module are available here: [https://cttc-lena.gitlab.io/nr/getting-started.html](https://cttc-lena.gitlab.io/nr/getting-started.html) The implementation of NR V2X is divided between a customized ns-3 LTE (RLC and above) and 5G-LENA NR (MAC and PHY) modules. Therefore, it is very important to follow the instruction under “Building NR V2X code” section in the README.md to download and configure the code. The NR-U implementation is included in a separate repository. The public git repository for nr-u is here: [https://gitlab.com/cttc-lena/nr-u](https://gitlab.com/cttc-lena/nr-u). Please follow the instruction on the README.md to download and configure the code.
To report bugs, please open an issue in the module GitLab repository.
Contributions to the module are welcome. To do so, please make a pull request against the master branch on the GitLab repository.

This ns-3 extension is one or more contributed modules.

Version v3.1

Released July 26, 2024

Works with ns-3.42