GSOC2024Channels5G

Main Page - Roadmap - Summer Projects - Project Ideas - Developer FAQ - Tools - Related Projects

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

Back to GSoC 2024 projects

Project Overview

• Project Name: 5G NR Module Benchmark and Analysis for Distinct Channel Models
• Student: Joao Albuquerque
• Mentors: Biljana Bojovic, Amir Ashtari, Gabriel Ferreira
• Google page: GSoC - Project
• Project Goals: Currently, ns-3 and the NR module provide an interface for using a channel model (3GPP). However, two other models have also been developed using the ns-3 environment: Two-ray and NYUSim. The project aims to integrate these two new models into NR module in a simplified and user-friendly manner. Furthermore, I will undertake additional tasks, such as testing the implemented code and creating an example that utilizes these implemented models.
• Repository: ns-3, NR
• About Me: I am an undergraduate student working at LASSE-UFPA, a telecommunications research laboratory, where I have been engaged in various projects using the ns-3 and nr. I have over a year and four months of experience working with ns-3 and the nr module, during which I developed applications, including a new ray-tracing module compatible with NR and the latest versions of ns-3. With this opportunity, I aim to make significant and definitive contributions to ns-3 and the NR module.

Milestones

You can track the project's plan by referring to this document: GSoC — Document Plan. The document will be constantly updated until the final submission.

Milestones for this project include updating the existing channel models in the ns-3, implementing a user-friendly interface via the nr module, and creating an example that utilizes all the added channel models within ns-3. The outline of these implementations will be separated into work packages (WPs) as follows:

WP 1 - NR interface for channel model usage (10 weeks)

• Task 1: Get familiar with BWP configuration, focusing on the channel model and how this configuration could be used from the NR helper class to initialize the BWPs. (0.5 week)
• Task 2: Get familiar with how the NYU channel model is being configured for the mmWave module in the NYU custom mmWave helper class. (0.5 week)
• Task 3: Prepare a refactoring plan for NR classes and check if the design will work for the three-channel models. (2 weeks)
• Task 4: Prepare 5G-Lena for different channel models that may not have spectrum channel matrix for su-MIMO and create a merge request to 5G-Lena. (4 weeks) [milestone 1]
• Task 5: Interface implementation for selecting the channel model via the NR helper class and creating a merge request for 5G-Lena. (3 weeks) [milestone 2]
  • Create a conditional build depending on the NYU channel model available in ns-3 and create a merge request to 5G-Lena. [milestone 3]
  • Extend NR helper to allow the configuration of 3GPP NTN channel models and create a merge request for 5G-Lena. [milestone 4]

WP 2 - Design and implement the benchmark scenario (8 weeks)

• Task 1: Identify and implement the appropriate scenario for all channel models. (1 week)
• Task 2: Prepare traces to be measured (e.g., entire simulation time, SINR, throughput, latency, etc.) and scripts for running and plotting based on the implemented example. (2 weeks)
• Task 3: Analyze, evaluate, and plot the results of the accomplished example. (3 weeks)
• Task 4: Extend the example to be used as a test and create a merge request of the implemented test to 5G-Lena; Write what was done in a blog post. [milestone 5] (2 weeks)

Weekly Report

Week 1 [May 27 - Jun 02 ]

• Finish the milestones
• Start to draft the desired implementation
• Start to study 5G-Lena and the modified MMwave helper classes

Week 2 [Jun 03 - Jun 09 ]

• Present a slide about BWP configuration and initialization [1]
• Create the first interface implementation (nr-helper)
  • Branch: scratch
• Present a slide about the mmwave-helper class (modified to support nyu); start to define a plan for the first milestone and solve some doubts [2]

Week 3 [Jun 10 - Jun 16 ]

NOTE: We are still discussing the non-su-mimo implementation. For a more detailed explanation, go to GSoC - Document Plan

• The first approach for non-su-mimo channel model implementation, back to the 2.6 version
  • Commit: Add condition to support non-SU-MIMO channel models
• The second approach for implementing the non-su-mimo channel model involves creating a spectrum channel matrix for those without it
  • Commits: Add a function to create a channel matrix if needed
• Start the interface implementation to enable the user to select distinct channel models using bandConf and initialization with nr-helper
  • Commits: First interface implementation
• Explain the NYUSIM channel model and compare it with 3GPP. Also, provide information about the interface implementation [3]
  • Many functions are used to set the TypeId (e.g., Init3GPPUma) that are all similar and could be removed. Instead, all the initialization would happen inside the main function based on the TypeIds
  • Separate the scenario from the condition when configuring the BWPs
  • Propose: Create independent enums for all channel conditions, scenarios, and channel models using enum classes.

To be done

• Check whether the channel model can be aggregated to PhasedArraySpectrumPropagationLossModel, so to obtain it with GetObject, Note: see how MobilityModel is aggregated to Node, and obtained, read in ns-3 documentation about object aggregation and usage
• Explain configuring channel, pathloss, and condition using the band ID
• Fix examples that break when trying to set parameters to AlwaysLos and Always NLos channel condition models instead of using warns
• Create initial draft MR/MRs
• Propose: Change the spectrum or the nr module if some interfaces, methods, or other things were not implemented best. Also, change or remove duplicated code and improve the design

Week 4 [Jun 17 - Jun 23 ]

• The first Draft MR related to milestone one is created, check:
  • MR(!160): Enable non-su-mimo channel models
• Update the document with a more detailed approach regarding the milestones
• Create a different way to get the type IDs in InitializeOperationBand for object factories type id configuration, using:
  • Strings: Reduce most parts of the code using the correct Type Id in string-format
    • Commits: cc-bwp-helper - Create GetTypeId functions for Condition, Channel and Scenario, nr-helper - Use band information to set the type ids
• Create a new enum for channel conditions and replace the enum for the enum class
  • Commit: Change enum for enum class
• Aggregate the matrix-based channel, in case it has one:
  •  Commit: Aggregate the matrix-based channel in the spectrum
• Assert the user's correct combination to avoid errors or wrong usage of propagation, condition, and spectrum (i.e., if the user selects NYU + V2V_Highway + LOS, we need to abort the simulation because NYU does not have V2V_Highway scenario)
  • Commit: Add abort_msg for non-supported combinations
• Explain how the band configuration in the modified InitializeOperationBand function works [4]
  • Channel condition enum should have one more value called "Buildings"
  • The mapping function should call another mapping function that maps each enum into corresponding TypeIds
  • Check how attributes of the enum type work in ns-3 and how it can be implemented in our context
  • Add the Two-ray channel model to the supported combinations

To be done

• First task: Refactor BandwidthPartInfo to allow the user to configure it with three independent strings instead of enums:
  • BandwidthPartInfo needs to be a class
  • Pass these three string arguments directly to attributes of bwp that are of enum type, so at least one conversion is done "automatically"
  • Move Buildings to the channel condition enum class
  • Add the Two-ray channel model to the supported combinations

• Second task: Translation from enum to TypeId
  • Check if the user-selected combination works (I think it is better to call it here before we make a conversion from enum to TypeIDs, but I can also do this later. I just have to ensure that the user selected a correct combination)
  • Convert from enum to TypeID using the functions I already created (instead of returning a string, return the right TypeId)
  • Improve the GetConditionTypeId() function and define it to set only the LOS, NLOS, and Buildings.

Week 5 [Jun 24 - Jun 30 ]

• Start to draft the new interface implementation [milestone 2 continuation]:
  • Make BandwidthPartInfo inherit from Object class
    • Use BandwidthPartInfo as a class and not a struct
  • Create GetTypeId() function for BandwidthPartInfo with enum attributes to get enum values using strings
  • Refactor CreateOperationBandContiguousCc to use the modified BandwidthPartInfo struct
  • Move Buildings to channel condition enum class and add 3GPP and NYU
  • Move supported combinations to BandwidthPartInfo struct and add FTR
  • Return the TypeId value instead of TypeId string format in Get{condition, channel and propagation}TypeId() function

To be done

• Implement it into the code; work branch: bwp-class-interface-imp

Week 6 [Jul 01 - Jul 07]

• Band configuration with CcBwpCreator and BandwidthPartInfo:
  • Commits:
    • Convert BandwidthPartInfo from struct to class
    • Create TypeId to BandwidthPartInfo
    • Set supported spectrum, propagation, and condition models and assert user-selected combination
    • Create Get{propagation,channel, and spectrum}TypeId functions with build conditions and lookUpTables
      • In GetChannelConditionTypeId(), the Typeid() default value returns when the channel condition is initialized directly in the propagation model. On the other hand, it returns the LOS, NLOS, or Buildings type ID.
      • In GetPropagationTypeId(), it returns the type ID based on the user-selected scenario and channel model (e.g., ThreeGpp + RMa -> ThreeGppRmaPropagationLossModel::GetTypeId())
      • In GetChannelModelTypeId(), it returns the type ID of the user-selected channel model
    • Use strings in SimpleOperationBandInfo struct and CreateCc function instead of enums
    • Create the BandwidthPartInfo with scenario, channel model, and condition to transform it from string to enum class directly

• Band initialization with nr-helper:
  • Commits:
    • Remove the lookup table to typedef functions and use the band info to set the object factories type id
    • Configure the created spectrum, propagation, and channel condition objects
    • Fix Create{ue,gnb}Phy() BandwidthPartInfo argument

• Update examples and test files to use the current approach:
  • Commits:
    • Update test files
    • Update examples

To be done

• Create a better interface in which the user can set attributes in the spectrum, channel condition, and propagation without using the band ID
• Extend the API to use different propagation and spectrum models
• Create a draft MR

Week 7 [Jul 08 - Jul 14]

• Present a slide about the possible extension of 5G-Lena to use non-fading simple pathloss models (e.g., LogDistancePropagationLossModel) [5]
  • Simulation occurs without errors, using simple pathloss models
  • Using (non-phased array) spectrum propagation loss classes (e.g., FriisSpectrumPropagationLossModel), one error related to MIMO communication appears, and we are already dealing with this in the MR(!160) - First Milestone
• Create the MR related to the second milestone:
  • (MR - !167): Refactor band configuration and initialization with a modular approach

To be done

• Extend the tests to use antennas present in ns-3 (e.g., ParabolicAntennaModel, CosineAntennaModel, etc.)
• Create an assert message to ensure the correct SISO conversion from PSD to spectrum channel matrix
• Extend the new interface implementation to fit the non-phased array spectrum and propagation loss models

Week 8 [Jul 15 - Jul 21]

• Add an assert message to ensure the correct SISO conversion from PSD to spectrum channel matrix
  • Commit: Assert single antenna port for conversion compatibility
• Present a slide about the BWP interface implementation to fit legacy antenna, spectrum, and propagation models [6]
  • Considerations:
    • The supported combinations variable is getting bigger. We may need to rethink the usage of this in this approach
    • Spectrum and propagation can't be the same (e.g., FriisSpectrum + FriisPropagation)
    • Check Tom's approach in: !MR-173

To be done

• Check Tom's MR to get insights on how we can do this
• Extend the interface to adapt manual installation of BWPs
• Start to code a draft of it

Week 9 [Jul 22 - Jul 28]

• After checking Tom's MR, present three approaches to fit into our current approach [7]:
  • First approach:
    • Maintain the current state of the code and just create a simple function to set non-phased spectrum models
  • Second approach:
    • Commit: Separate spectrum configuration from band information
    • Commit: Use a unique function to set phased and non-phased channels
  • Third approach:
    • Commit: Create a unique structure and raw function that returns a simple BWP
  • Considerations:
    • We decided to follow the second approach, which is more aligned with the original draft and the suggested improvements
• Include NYUSIM in the 5G-Lena repository (Branch)
  • A new issue #207 appeared when using the "channels/nyu" path in the 5G-lena repository
  • We decided to include NYUSIM instead of setting build conditions; see the original repository: [8]

To be done

• Create a new MR with the improvements of the second approach
• Create a new MR with the NYUSIM classes (propagation, condition, and spectrum)

Week 10 [Jul 29 - Aug 04]

• Present a slide about the current approach with everything updated [9]
• MR- !174: Refactor band configuration and initialization with a modular approach (Enhancement)
  • Examples: Fit all examples in our current approach commit: Use channel helper for spectrum channel configuration
    • [specific change] cttc-nr-3gpp-calibration-utils-v2: Manual creation of distance-based 3GPP model
  • Test: Fit all tests in our current approach commit: Use channel helper for spectrum channel configuration
  • Bug: We checked that all the BWPs share the same PhasedArraySpectrum, Propagation and Channel condition pointer. All the BWP features (e.g., frequency, scenario, etc.) override the pre-defined values

To be done

• Fix the discovered bug
  • Separate channel creation from channel configuration
  • Fix examples and tests that use more than one channel
• Extend the NR documentation (RELEASE_NOTES.md, CHANGES.md, and nr-module.rst) with our current modifications
• Create a new example that uses a non-standard propagation loss model (e.g., Friis)

Week 11 [Aug 05 - Aug 11]

• Present a slide about the MR improvements [10]
  • Use ObjectFactories for multiple SpectrumChannel creation: Update the create SpectrumChannels for ObjectFactory usage
  • Assign frequency directly in ChannelHelper class: Assign frequency directly in AssignChannelsToBands
  • Create a helper function to override the spectrum TypeId for a specific example (cttc-nr-3gpp-calibration-utils-v2): Create function to override the spectrum TypeId
  • Extend GetPropagationTypeId function to return the associated channel condition: Extend function to return the channel condition TypeId
• Fix examples and tests:
  • Examples: Update examples to use the updated channel helper API
  • Tests: Update tests to use the updated channel helper API
• Create a new example:
  • New example that illustrates how a user can configure 'legacy' propagation models (e.g., Friis) or 'standard' (e.g., 3GPP) using our current approach: cttc-nr-channels-example: Add new example

Note: I’ve updated most of the code and made several fixes. Documentation updates will be completed by week 12.

To be done

• Add different configurations for the example in examples_to_run.py - one for non-phased case and another for the phased case.
• nr-module.rst - add the description for the new helper and the example
• CHANGES.md - start a new section for the following release and add the bullet/s describing the main CHANGES due to the created MR
• RELEASE_NOTES.md - start a new one for the following release and add the bullet/s describing the main release notes related to the created MR
• Consider if non-phased could also be configured through the ChannelHelper factories
• Rename ChannelHelper into NrChannelHelper
• Change the topology to use the HexagonalHelper
• Add FlowMonitor to track the statistics - Preparation for the evaluation

Week 12 [Aug 12 - Aug 18]

• Add the newly created example variation to simulate a 'legacy' channel (Friis) in 'examples-to-run'
  • Commit: Add variation of cttc-nr-channel-example for non-phased channel usage
• Add the description for the new helper and the example in the nr-module.rst
  • Commits:
    • Extend documentation to include NrChannelHelper API
    • Extend documentation to include cttc-nr-channels-example
• Start a new section for the following release in CHANGES.md and add the bullet/s describing the main CHANGES due to the created MR
  • Commit: Update changes in the new NR-v3.4 section
• Update the RELEASE_NOTES.md and add the bullet/s describing the main release notes related to the created MR
  • Commit: Create a new section exposing the modifications and improvements made
• Rename ChannelHelper into NrChannelHelper
  • Commit: Rename ChannelHelper class into NrChannelHelper
• Change the topology to use the HexagonalHelper
  • Commit: Use HexagonalGridScenarioHelper for scenario creation
• Add FlowMonitor to track the statistics
  • Commit: Extend example to use FlowMonitor

To be done

• Define the scenario that fits all the channel models and start measurements
• Solve threads in MR !174

Week 13 [Aug 19 - Aug 25]

• Create a dataset that includes all scenarios that fit all channel models [UMi, UMa, and RMa]
  • Work branch: trace-results

• Resolve threads:
  • Fix comments and doxygen: !174 (716cc2c1), !174 (b00cdf97), and others (check the !MR - 174)
  • Fix UMi base station scenario height and add a reference: !174 (547d578a)
  • Fix the maximum delay in the CheckForLostPackets FlowMonitor function: !174 (7bc58a08)

To be done

• Continue solving threads and discussing the approach in the MR
• Start plotting the measured traces

Week 14 [Aug 26 - Sep 1]

• Present some MR improvements and results [11]
  • Start plotting the SINR 3D mesh for all channel models
  • Start plotting KPIs
  • Show achievements/improvements accomplished during the week 12-13

• Resolve threads:
  • Fix comments and doxygen:
    • nr-module: Add abbreviations and improve the text in 'Nr Channel Helper' section
    • cc-bwp-helper: Fix GetChannel doxy in BWP struct
  • Reuse the SetChannel function for BWP's spectrum channel configuration
    • cc-bwp-helper: Make spectrum channel nonpublic in the BWP struct
    • nr-channel-helper, nr-helper: Use Set/Get functions to interact with BWPs' spectrum channels

To be done

• Continue solving the threads
• Fix scenario parameters in cttc-nr-channels-example

Week 15 [Sep 2 - Sep 8]

• Show resolved threads in a presentation [12]
  • Fix scenario parameters in 'cttc-nr-channels-example'
  • Fix doxygen and documentation
  • Extend NrChannelHelper class to support Distance-based 3GPP
  • Configure distance-based 3GPP channel using standard channelHelper method

• Discussion:
  • The distance-based 3GPP channel model is the 3GPP channel model with a maximum distance attribute. It shouldn't be in the NrChannelHelper scope
  • All threads are already addressed; I can now focus on plotting the results

To be done

• Start plotting the results as discussed in WP2
• Create a Distance-based 3GPP spectrum channel model manually in cttc-nr-3gpp-calibration-utils-v2.cc

Week 16 [Sep 9 - Sep 15]

• Plot results [13]
  • Plot SINR mesh in the range of 30.5 GHz to 60.5 GHz
  • Plot ECDF of the three-channel models
  • Plot time resolution for all channel models in terms of real/user/system time
  • Plot KPIs (throughput, delay, and jitter)
• Create Distance-Based 3GPP spectrum class manually
  • Commit: cttc-nr-3gpp-calibration-utils-v2: Create DistanceBased spectrum class manually

To be done

• Double-check the created dataset and plot scripts
• Time results:
  • Add time results for 2 and 6 UEs
  • Increase the bandwidth from 5 MHz to 100 MHz

Week 17 [Sep 16 - Sep 22]

Note: Week 17 was divided into two parts:

• 17.1) We discussed the evaluated results [14]:
  • The SINR ECDF plots of 3GPP and FTR make total sense after changing the positions
  • NYUSIM remains with strange behavior
  • Discussion: HexagonalGridScenario randomly positions the UE and the gNB so that the UE is behind the gNB
    • Fix: The UE position to be in front of the gNB since we are working with only LOS
    • Fix: The bearing angle (check cttc-nr-mimo-demo)

• 17.2) We discussed the evaluated results, small issues that may happen during the test code, and NrChannelHelper API's extension to configure legacy models manually [15].

To be done

• Start the test code
• Plot time results for 3GPP without fading

Week 18 [Sep 23 - Sep 29]

• Present the updates [16]
• Develop the test code cmakelists, gsoc-channel-combinations-test: Add test to check channel creation via NrChannelHelper API

To be done

• Fix minor issues in the test code
• Rebase the MR
• Add NYUSIM files to 'utils/channels/nyu' path