From Nsnam
Jump to: navigation, search

Main Page - Current Development - Developer FAQ - Tools - Related Projects - Project Ideas - Summer Projects

Installation - Troubleshooting - User FAQ - HOWTOs - Samples - Models - Education - Contributed Code - Papers

Back to GSoC 2022 projects

Project Overview

  • Project Name: A simplified channel and beamforming model for ns-3
  • Student: Matteo Pagin
  • Mentors: Sandra Lagen, Biljana Bojovic, Michele Polese
  • Google page: [1]
  • Project Goals: Currently, ns-3 provides the TR 38.901 channel model as the default option for sampling MIMO wireless channels which take into account the presence of (possibly directional) multiple antenna elements at both transmitter and receiver. However, this model represents a major performance bottleneck for most end-to-end simulations, especially whenever they involve upwards of hundreds of nodes. Accordingly, the goal of my proposal is twofold:
    • to provide ns-3 with a simplified statistical channel model, to be used for analyses which are focused on the upper layers of the protocol stack only, and
    • to improve the performance of the TR 38.901-based framework which is currently available in ns-3, for the remainder of the use cases.
  • Repository: GitLab
  • About Me: I am a first year PhD student at the University of Padova, working with the SIGNET group under the supervision of professor Michele Zorzi. Previously, I have been a research engineer in the same group, and I have obtained both my master and bachelor degree from the University of Padova, in Information Engineering and ICT for Internet and Multimedia, respectively. During these first years of my research career I have been working quite extensively with ns-3, primarily by working on the mmwave module for simulating 5G cellular networks. However, with this project I aim to contribute in a more direct manner to the ns-3 project! I spend most of my free time having "aperitivo"s with friends, training at the gym, hiking and learning to play the guitar.
  • Project proposal: GDrive link
  • Final MR: pagmatt/ns-3-dev:gsoc-2022
  • Final project report: 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. A final report on my overall experience can be found here.

Milestones and Deliverables

Project plan, which will be periodically updated during the whole GSoC: GDoc.

The project objectives will be achieved through three incremental updates of the spectrum and antenna modules, representing the project deliverables and each providing additional features with respect to the previous one. Specifically, the following deliverables are planned:

  • D1, which will comprise the addition of the simplified channel and beamforming models and which will be completed by the end of Week 5.
  • D2, which will include the port of the spectrum and antenna modules to the Eigen linear algebra library and the aforementioned optimizations. It will be completed by the end of Week 9.
  • D3, which will comprise the validation campaign for the 3GPP model and the calibration of the simplified model, based on the former. This deliverable will be completed by the end of Week 12.

Weekly Progress Reports

  • Week 1
    • Discussion with the mentors and the ns-3 maintainers regarding the level of integration of Eigen in ns-3. Optional, external installation is the chosen approach.
    • Study of the FTR fading model, draft implementation in MATLAB and consistency checks among such implementation and the related paper.
    • Further definition of the calibration steps. Identification of the 3GPP calibration campaigns which can be used to such end. Since most of the latter make use of older versions of the 38.901 SCM (v14.0.0), only selected scenarios will be calibrated, i.e., the ones which are consistent among the v.14.0.0 and the one currently implemented in ns-3. The full SCM will be calibrated first, using the 3GPP campaigns as a reference. Then, the simplified channel model will be calibrated using the latter.
  • Week 2
    • Definition of the APIs of the new SpectrumPropagationLossModel, i.e., MimoSpectrumPropagationLossModel, which extends the PhasedArraySpectrumPropagationLossModel class and implements the performance-oriented channel model.
    • Implementation of the GetFtrFastFading function, which samples the squared norm of a fading sample distributed as per the Two-Ray Fluctuating (FTR) Model fast-fading model.
    • Implementation of the first test, i.e., MimoFtrAverageTest, which compares the empirical mean obtained using the GetFtrFastFading function with the expected theoretical one. The test is repeated for different combinations of the FTR model input parameters.
    • First study on how to extend the above test by checking also the Emprirical CDF. The open issue is that while other statistical tests can rely on the GNU Scientific Library to compute the CDF of the distribution and then compare it with the ECDF, the FTR model is not implemented in the GSL. Therefore, the most promising approach at the moment is to generate a set of ECDFs in MATLAB, export them and then compare them to the ECDF computed in ns-3.
  • Week 3
    • Further study of ECDF test for the FTR fading model. Consistency checks with the original paper led to finding typos in the closed form CDF and PDF equations. Currently exchanging mails with the authors to fix them and have a correct reference.
    • Definition and implementation of the computation of the combined array and beamforming gains in the MimoSpectrumPropagationLossModel class, by defining the CalcBeamformingGain.
  • Week from 4th to the 10th of July
    • No major work on the project due to participation at the "Lipari School on Advanced Networking Systems"
  • Week 4
    • Setup of a SEM script for the benchmarking of the code, in order to compare the progressive updates which will be introduced with this project. The script makes use of the NR module, using as a baseline the simulation script "cttc-nr-demo". In order to do this, experimental support for CMake versions of ns-3 (3.36+) has been added to SEM. Initial benchmark of the baseline ns-3 versus relevant parameters, i.e., number of antenna elements at the nodes, number of simulation nodes (gNBs and UEs), update period of the channel matrices and system bandwidth.
    • Testing and bugfixing of the computation of the combined array and beamforming gains in the MimoSpectrumPropagationLossModel. Defined the test ArrayResponseTest, which checks the gain along a given direction for different configurations of antenna arrays and related antenna elements.
  • Week 5
    • Further testing and bugfixing of the computation of the combined array and beamforming gains in the MimoSpectrumPropagationLossModel. Fixed an error in the computation of the relative angle between transmitter and receiver.
    • Polishing of the MimoSplmTestSuite and MimoSpectrumPropagationLossModel classes by correcting typos, using more descriptive variable names and improving the documentation.
    • Initial work on the Eigen port of the ThreeGppChannelModel and PhasedArrayModel classes. Implementation of the Eigen support in the CMake build system as an optional external library. The possible presence of Eigen is then exposed to the source files by conditionally declaring the preprocessor definition "HAVE_EIGEN3".
    • Import (i.e., using git cherry-pick) of the channel matrix generation optimizations proposed in MR #897 in the Eigen branch of the GSoC.
  • Week 6
    • Implementation of a uniform interface for both Eigen and STL’s based vectors and matrices. Its aim is to minimize 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). In particular, this interface has been implemented for the PhasedArrayModel::ComplexVector and the MatrixBasedChannelModel::Complex2DVector data structures.
    • Update of the ThreeGppChannelModel, ThreeGppPropagationLossModel and ThreeGppChannelTestSuite to reflect the above interface implemented for the PhasedArrayModel::ComplexVector and the MatrixBasedChannelModel::Complex2DVector data structures.
    • Creation of a fork of the NR module which introduces the changes needed for supporting Eigen. This is a necessary step for carrying out the benchmarking of the proposed changes, as the simulation script chosen for such purposes requires the NR module.
  • Week 7
    • Benchmarking of the performance improvements brought by all the work up to Week 6.
    • Profiling of the Eigen and performance-related changes, in order to identify possible remaining performance bottlenecks. Thanks to the above changes, the function CalcBeamformingGain now represents the main performance bottleneck.
    • Experimenting possible solutions for speeding up the CalcBeamformingGain function.
    • Setting up the draft MRs concerning the work up to Week 7. In particular, two MRs towards the main development branch gsoc-2022 have been opened. They are related to the simplified channel model ( and the Eigen optimizations (, respectively. Then, another MR from my development branch gsoc-2022 towards ns-3 mainline, referencing the above MRs, has been opened.
  • Week 8 and first half of Week 9
    • Since the function CalcBeamformingGain now represents the main performance bottleneck, further tests have been carried to identify the hotspots within this function. It has been found the the most computationally intensive operations are the computation of the sine and cosine terms for the Doppler.
    • As a consequence (despite not being originally part of the project plan), a significant portion of time has been dedicated to speeding up the trigonometric sine and cosine functions. In particular, the following approaches have been implemented, tested and compared:
      • The FastTrigo library, available here [2]. This library uses AVX instructions to compute multiple values of the sine and cosine functions at the same time, leveraging the SIMD (Single Instruction Multiple Data) paradigm. Moreover, the trigonometric functions are also approximated, to further speedup the computation.
      • A lookup table. The table has been implemented by first wrapping the argument to [0, 2*PI]. Then, the wrapped angle is multiplied by 100 and casted to int, in such a way to map the [0, 2*PI] interval to [0, (int) 2*PI*100] and use the mapped value as the index of a (int) 2*PI*100-dimensional array containing the lookup values.
      • A custom approximation based on Chebyshev polynomials [3]. These polynomials are one of the best option for efficient approximation of arbitrary functions, with an error which is non-diverging from a single point (as is the case for Taylor's expansion)
    • From preliminary results, the tested options rank as follows: the FastTrigo library is the slowest (the compiler seems to vectorize the calls to the standard library already!), the lookup table is the second fastest option and finally a degree-4 Chebyshev approximation yields the fastest results.
  • Second half of Week 9 and Week 10
    • Discussion with the project mentors regarding the possible approaches for the calibration of the Fluctuating Two Ray fading model of the simplified channel model, using the full 3GPP TR 38.901 model as the reference. The chosen methodology is the following:
      • First, reference curves are to obtained using the 3GPP channel model. Specifically, these curves will depict the Empirical Cumulative Distribution Function (ECDF) of the channel gains obtained using the reference implementation. With the goal of isolating the effect of the small-scale fading only, these terms will be obtained by computing the channel gain at the receiver by using a 1x1 antenna array, disabling shadowing and considering the DoCalcRxPowerSpectralDensity gain only, thus neglecting beamforming gain and large-scale fading phenomena. Indeed, the latter terms are to be modeled by the other components of the model.
      • Then, these reference curves are to be used to find the FTR fading model parameters which yield the closest representation, in a statistical sense. In particular, these parameters will be found by defining a grid of possible parameters, and then finding the combination yielding the best Anderson-Darling goodness-of-fit measure.
    • Generation of the 3GPP reference curves for the different 3GPP scenarios (UMa, UMi, RMa, InH), LoS conditions (LoS/NLoS) and and various carrier frequencies.
  • Week 11
    • Python implementation of a script which parses the 3GPP reference curves and estimates the FTR fading model parameters which best match them. The criteria for choosing such parameters within a predefined search grid is the Anderson-Darling goodness-of-fit measure. Then the script outputs the fit results into the appropriate C++ code for defining the corresponding lookup table.
  • Week 12
    • Description of the novel fading model in the spectrum.rst documentation file.
    • General polishing of the codebase.
    • Renaming of MimoSpectrumPropagationLossModel into TwoRaySpectrumPropagationLossModel and MimoSplmTestSuite into TwoRaySplmTestSuite.
    • Addition of the OverallGainAverageTest in the test suite TwoRaySplmTestSuite. This test checks that the average overall channel gain obtained using the TwoRaySpectrumPropagationLossModel class is close (it is, after all, a simplified and performance-oriented model) to the one obtained using the ThreeGppSpectrumPropagationLossModel. Fixed a bug in the calibration script, which caused the fit results to be exported as a C++ data structure incorrectly, thanks to such test.
    • Rebase of the GSoC branch on top of master. Changes to the spectrum module which have occurred during the project duration have been reflected on the development branch.