GSoC 2022 on "A simplified channel and beamforming model for ns-3"

This is the MR which refers to the work which I carried out in the context of my GSoC project "A simplified channel and beamforming model for ns-3".

Simplified channel model

The model aims to provide a performance-oriented alternative to the 3GPP TR 38.901 framework which is currently implemented in the mainline ns-3. The overall design follows the general approach of [1], with aim of providing the means for computing a 3GPP TR 38.901-like end-to-end channel gain by combining:

• the path loss and shadowing terms provided by the ThreeGppPropagationLossModel class;
• the array and beamforming gain, computed as outlined in [2] using the novel TwoRaySpectrumPropagationLossModel class. This term supports the presence of multiple antenna elements both at the transmitter and at the receiver and arbitrary antenna radiation patterns. Whenever the link is in NLOS, a penalty factor is introduced, to account for beam misalignment due to the lack of a dominant multipath component [4]; and
• a fast fading term, sampled using the Fluctuating Two Ray (FTR) model distribution [3]. The latter is a fading model which is more general than typical ones, and which has been shown to provide a better fit to fading phenomena at mmWaves. The model parameters are automatically picked once the simulation scenario is set, using a lookup table which associates the simulation parameters (such as carrier frequency and LOS condition) to the FTR parameters providing the best fit to the corresponding TR 38.901 channel statistics. As a consequence, this channel model can be used for all the frequencies which are supported by the 38.901 model, i.e., 0.5-100 GHz. The calibration has been done by first obtaining the statistics of the channel gain due to the small-scale fading in the 3GPP model, using an ad hoc simulation script (src/spectrum/examples/three-gpp-two-ray-channel-calibration.cc). Then, this information has been used as a reference to estimate the FTR parameters yielding the closest (in a goodness-of-fit sense) fading realizations, using a custom Python script ( src/spectrum/utils/two-ray-to-three-gpp-ch-calibration.py) which is also provided.

The class has been thoroughly documented and an ad-hoc test (two-ray-splm-test-suite) has been implemented, to check the correctness of the related computations. In particular, the test checks the consistency of the FTR empirical mean with the expected value, and compares the overall array gain at boresight with the theoretical value, using different array configurations.

Furthermore, the array radiation pattern versus the relative azimuth of transmitter and receiver has been plotted (see below) and visually compared to that presented in [5], matching the expected behavior.

UPA with 3GPP 38.901 antenna elements:

UPA with isotropic antenna elements:

[1] Michele Polese and Michele Zorzi. “Impact of channel models on the end-to-end performance of mmwave cellular networks”. In: 2018 IEEE 19th International Workshop on Signal Processing Advances in Wireless Communications (SPAWC). IEEE. 2018, pp. 1–5

[2] Mattia Rebato et al. “Study of realistic antenna patterns in 5G mmWave cellular scenarios”. In: 2018 IEEE International Conference on Communications (ICC). IEEE. 2018, pp. 1–6.

[3] Juan M Romero-Jerez et al. “The fluctuating two-ray fading model: Statistical characterization and performance analysis”. In: IEEE Transactions on Wireless Communications 16.7 (2017), pp. 4420–4432.

[4] Kulkarni, Mandar N., Eugene Visotsky, and Jeffrey G. Andrews, "Correction factor for analysis of MIMO wireless networks with highly directional beamforming.", IEEE Wireless Communications Letters, 2018

[5] Asplund, Henrik, et al. Advanced Antenna Systems for 5G Network Deployments: Bridging the Gap Between Theory and Practice. Academic Press, 2020.

Original MR, reviewed by the project mentors: pagmatt/ns-3-dev!2 (merged)

Eigen optimizations

For the second part of my project, I introduced support for the open-source linear algebra Eigen, with the goal of bringing performance improvements to the 3GPP TR 38.901 framework which is currently available in the ns-3 mainline. Moreover, the installation of Eigen is set as optional, and the code runs as usual whenever the library is not installed in the system.

The library has been integrated in ns-3 by mimicking the support for other third-party libraries such as SQLite. In particular, the Eigen library is set as an optional dependency in the build-support/macros-and-definitions.cmake file and its presence in the system is shown to the user by exposing whether it has been found or not int the build-support/custom-modules/ns3-configtable.cmake file (see image below). The linking of the Eigen's sources with the ns3 source files is taken care of using the FindEigen3.cmake file provided by the library itself, as suggested in the related ns-3 guide.

The main design goal has been minimizing the portion of the code which varies based on Eigen’s availability in the system (dictated by the value of the CMake-defined HAVE_EIGEN3 flag). Since most of the needed operators can not be overloaded for STL C++ vectors (for instance, ()), a uniform interface for both Eigen and STL’s based vectors and matrices has been implemented by defining ad-hoc structs with custom operators. In particular, this interface has been implemented for the PhasedArrayModel::ComplexVector and the MatrixBasedChannelModel::Complex2DVector data structures, since they are involved in computationally intensive linear algebra operations.

The interface has been designed with Eigen's API in mind, striving to provide the same API also for STL C++ data-structures, whenever Eigen's is not installed in the system. Specifically, yhe main differences are:

• size () does not exist for Eigen’s matrices. Instead, the methods rows () and cols () are to be used to get the respective sizes of a matrix. On the other hand, Eigen’s vectors provide the size () method, thus they are aligned with STL’s vectors in this regard.
• resize () takes as inputs both the numbers of rows and columns in the case of Eigen’s matrices. On the other hand, Eigen’s vectors provide a single-argument resize () method, thus they are aligned with STL’s vectors in this regard.
• the elements of Eigen’s matrices are to be accessed using the () operator, taking as input the row and column indexes of the specific element to be accessed. This is in contrast to the [] operator provided by STL vectors. On the other hand, Eigen’s vectors provide a single-argument [] operator, thus they are aligned with STL’s vectors in this regard.

Moreover, this MR includes also the optimizations to the channel matrix generation procedure for the three-gpp-channel-model originally presented in MR !897.

To measure the improvements brought by these changes, I setup a benchmark script which is based on cttc-nr-demo and varied the main simulation parameters which have an impact on the simulation runtime, i.e., the update period of the 3GPP channel (how often new channels and related long terms are generated), the number of antenna elements at the gNB and the number of gNBs and UEs in the simulation. The figures below depict the results which I obtained:

Channel update period (pre-GSoC on the left):

Number of radiating elements (pre-GSoC on the left):

Number of gNBs, with a fixed number of UEs per gNB (pre-GSoC on the left):

Even though these results are good, I would still like to aim for further improvements after the completion of the project. Towards such end, I will continue working on speeding up the calls to the trigonometric function in . The latest WIP work in this regard can be found here.

Original MR, reviewed by the project mentors: pagmatt/ns-3-dev!3 (merged)