My GSoC 2022 experience

Final thoughts on my participation to the 2022 edition of the Google Summer of Code for the ns-3 organization

During the summer of 2022 I have been participating in the Google Summer of Code initiative, aiming to contribute to the ns-3 organization with a project titled “A simplified channel and beamforming model for ns-3”. In this blog post I am sharing a final report on the project and my overall experience.

Goals

The overall objective of my proposal was twofold:

To provide ns-3 with a simplified statistical channel model; and
to improve the performance of the TR 38.901-based framework which is available in ns-3.

My project plan proposed to meet such objectives by performing the following tasks:

The design of the simplified channel and beamforming models. This task aims at providing ns-3 with a simplified channel model for the end-to-end performance evaluation of MIMO wireless networks. The approach which I propose is to compute the end-to-end channel gain as the sum of several losses and gains terms which account for the large-scale phenomena such as free-space path loss and shadowing, the small-scale fading (based on the Fluctuating Two Ray (FTR) model ) and the antenna and beamforming gains.
The implementation of the matrix-based channel model optimizations. This part of the project consists in porting the TR 38.901-based channel and beamforming models to the open-source linear algebra library Eigen, on top of completing the optimizations proposed in MR 897, which proposes the caching of the cluster-only dependent trigonometric terms to speedup the generation of new channel matrices.
The calibration of the simplified channel model. This final task aims at calibrating the FTR model with respect to the pre-existing 3GPP TR 38.901 framework of .. Additionally, the goal is to first calibrate the latter as well, since it has been previously skipped due to missing functionality.

For additional details, please refer to the complete project proposal.

Results, Two-Ray fading model

The model aims to provide a performance-oriented alternative to the 3GPP TR 38.901 framework which is implemented in the ThreeGppSpectrumPropagationLossModel and ThreeGppChannelModel classes and whose implementation is described in . The overall design follows the general approach of , with aim of providing the means for computing a 3GPP TR 38.901-like end-to-end channel gain by combining several statistical terms. The frequency range of applicability is the same as that of , i.e., 0.5 - 100 GHz.

TwoRaySpectrumPropagationLossModel implementation

The computation of the channel gain is taken care of by the TwoRaySpectrumPropagationLossModel class. In particular, the latter samples a statistical term which combines:

The array and beamforming gain, computed as outlined in using the CalcBeamformingGain function. This term supports the presence of multiple antenna elements both at the transmitter and at the receiver and arbitrary antenna radiation patterns. Specifically, the array gain is compute as:
\[G_{\mathrm{AA}}(\theta, \varphi)=\left|\boldsymbol{a}^{\mathrm{T}}(\theta, \varphi) \boldsymbol{w}\left(\theta_0, \varphi_0\right)\right|^2=\left|\mathrm{AF}_{\mathrm{v}}(\theta, \varphi)\right|^2\left|\mathrm{AF}_{\mathrm{h}}(\theta, \varphi)\right|^2 G(\theta, \varphi),\]
where:
\[\operatorname{AF}_{\mathrm{v}}(\theta, \varphi)=\frac{1}{\sqrt{N_{\mathrm{v}}}} \sum_{m=0}^{N_{\mathrm{v}}-1} e^{j k d_{\mathrm{v}} m\left(\cos \theta-\cos \theta_0\right)} \\\]
and
\[\operatorname{AF}_{\mathrm{h}}(\theta, \varphi)=\frac{1}{\sqrt{N_{\mathrm{h}}}} \sum_{n=0}^{N_{\mathrm{h}}-1} e^{j k d_{\mathrm{h}} n\left(\sin \theta \sin \varphi-\sin \theta_0 \sin \varphi_0\right)},\]
In turn, \(N_h, N_v\) are the number of horizontal and vertical antenna elements, respectively and \(d_h, d_v\) are the element spacing in the horizontal and vertical direction, respectively.

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 ;
A fast fading term, sampled using the Fluctuating Two Ray (FTR) model distribution . The latter is a fading model which is more general than typical ones, taking into account two dominant specular components and a mixture of scattered paths. As, a consequence it has been shown to provide a better fit to fading phenomena at mmWaves.

Calibration

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).

Note:

To then obtain a full channel model characterization, the model is intended to be used in conjunction of the path loss and shadowing capability provided by the ThreeGppPropagationLossModel class. Indeed, the goal of this model is to provide channel realizations which are as close as possible to ones of , but at a fraction of the complexity. Since the path loss and shadowing terms are not computationally demanding anyway, the ones of
have been kept;
Currently, the value of NLOS beamforming factor penalty factor is taken from the preliminary work of and it is scenario-independent; As future work, the possibility of using scenario-dependent penalty factors will be investigated.

Testing

The test suite TwoRaySplmTestSuite includes three test cases:

FtrFadingModelAverageTest, which checks that the average of the Fluctuating Two Ray (FTR) fading model realizations is consistent with the theoretical value provided in .
ArrayResponseTest, which checks that the overall array response at boresight computed by the ù CalcBeamformingGain function coincides with the expected theoretical values.
OverallGainAverageTest, which checks that the average overall channel gain obtained using the DoCalcRxPowerSpectralDensity method of the TwoRaySpectrumPropagationLossModel class is close (it is, after all, a simplified and performance-oriented model) to the one obtained using the ThreeGppSpectrumPropagationLossModel and ThreeGppChannelModel classes.

Results, 38.901 framework 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. 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 ThreeGppChannelModel originally presented in MR !897.

Results, TLDR

All the main objectives of the project i.e., the speed-up of the channel matrix generation procedure in the ThreeGppChannelModel class, the optional support for the Eigen linear algebra library and its use for the spectrum model matrix/vector operations and the design, and the implementation and calibration of the simplified 3GPP 39.901-based channel model have been met. Due to time constraints, the 3GPP TR 38.901 calibration was left as future work.