Difference between revisions of "GSOC2019ThreeGPPChannel"

From Nsnam
Jump to: navigation, search
(Project Timeline)
(Deliverables)
 
(6 intermediate revisions by the same user not shown)
Line 12: Line 12:
 
* '''Code:''' [https://gitlab.com/tommasozugno/ns-3-dev/tree/three-gpp-channel GitLab repo]
 
* '''Code:''' [https://gitlab.com/tommasozugno/ns-3-dev/tree/three-gpp-channel GitLab repo]
 
* '''About Me:''' I am a first-year PhD student at the University of Padova, Italy, working under the supervision of prof. Michele Zorzi. My research focus on protocols and architectures for 5G cellular systems operating at mmWaves.
 
* '''About Me:''' I am a first-year PhD student at the University of Padova, Italy, working under the supervision of prof. Michele Zorzi. My research focus on protocols and architectures for 5G cellular systems operating at mmWaves.
 
= Deliverables =
 
== Phase 1 ==
 
* new ChannelConditionModel interface, which can be used to determine the state of the channel between two nodes [https://gitlab.com/tommasozugno/ns-3-dev/blob/three-gpp-channel/src/propagation/model/channel-condition-model.h]
 
* implementation of the channel condition models specified in 3GPP TR 38.901 [https://gitlab.com/tommasozugno/ns-3-dev/merge_requests/1]
 
* implementation of the pathloss models specified in 3GPP TR 38.901 [https://gitlab.com/tommasozugno/ns-3-dev/merge_requests/2]
 
 
== Phase 2 ==
 
* integration of the fast fading model described in 3GPP TR 38.901. The model is composed of two classes: ThreeGppChannel, which includes the procedure to generate the channel matrix, and ThreeGppSpectrumPropagationLossModel, which extends the SpectrumPropagationLossModel interface and relies on the ThreeGppChannel class to compute the received PSD [https://gitlab.com/tommasozugno/ns-3-dev/tree/new-channel]
 
  
 
= Project Timeline =
 
= Project Timeline =
Line 127: Line 118:
 
* update and refactor the tests for the channel condition models. I defined a single test case for all the 3GPP channel condition models
 
* update and refactor the tests for the channel condition models. I defined a single test case for all the 3GPP channel condition models
 
* update the documentation
 
* update the documentation
 +
 +
== Week 12 (August 12 - August 18) ==
 +
* update the example including the possibility to choose the propagation scenario and to set the update period for the channel condition and the shadowing
 +
* improve the documentation
 +
* review of the fast fading model
 +
 +
== Week 13 (August 19 - August 25) ==
 +
* refactoring of the classes modeling the antenna arrays
 +
* add documentation for the antenna models
 +
* final review of the fast fading model
 +
* move the buildings-aware channel condition model to the buildings module
 +
* submit a new MR for the fast fading model (https://gitlab.com/nsnam/ns-3-dev/merge_requests/90)
 +
* prepare the final report
 +
 +
= Final Report =
 +
 +
This project aimed at implementing the channel modeling framework described in 3GPP TR 38.901.
 +
 +
A new interface called <code>ChannelConditionModel</code> was defined to host models representing the channel condition (e.g., LOS/NLOS state, O2I propagation, etc.).
 +
The 3GPP LOS/NLOS channel condition models were implemented by extending the new interface.
 +
An additional building-aware channel condition model was implemented.
 +
The 3GPP propagation loss models were implemented by extending the interface <code>PropagationLossModel</code>.
 +
Both the  3GPP channel condition and the propagation loss models were included in the <code>propagation</code> module, while the building-aware channel condition model was included in the <code>buildings</code> module.
 +
 +
The 3GPP fast fading model was included in the spectrum module by extending the <code>SpectrumPropagationLossModel</code> interface. It consists in two classes: (i) <code>ThreeGppChannel</code>, which includes the channel matrix generation procedure (integrated starting from the channel model present in the mmwave module), and (ii) <code>ThreeGppSpectrumPropagationLossModel</code>, which extends the <code>SpectrumPropagationLossModel</code> interface and computes the power spectral density of the received signal by applying the fast fading model.
 +
For the modeling of antenna arrays, the new base class <code>AntennaArrayBasicModel</code> and an extension called <code>AntennaArrayModel</code> which were provided by CTTC, were refactored and included in the antenna module.
 +
 +
The project was divided in three phases. The work done in each phase is summarized in the following.
 +
 +
=== Phase 1 ===
 +
* design and implementation of the interface <code>ChannelConditionModel</code>
 +
* implementation of the LOS/NLOS channel condition models described in TR 38.901
 +
* implementation of a building-aware channel condition model
 +
* implementation of the pathloss models described in TR 38.901
 +
* implementation of test cases for all the new classes
 +
* documentation for all the new classes
 +
 +
=== Phase 2 ===
 +
* implementation of the fast fading model described in 3GPP TR 38.901:
 +
** definition of the class <code>ThreeGppChannel</code>
 +
** definition of the class <code>ThreeGppSpectrumPropagationLossModel</code>
 +
* testing and debugging
 +
 +
=== Phase 3 ===
 +
* implementation of a simple update procedure for the channel matrix
 +
* implementation of a simple update procedure for the long term components
 +
* implementation of test cases for <code>ThreeGppChannel</code> and <code>ThreeGppSpectrumPropagationLossModel</code>
 +
* documentation for all the new classes
 +
* implementation of a periodic update procedure for the shadowing component
 +
* implementation of a periodic update procedure for the 3GPP channel condition models
 +
 +
== Deliverables ==
 +
I created separate branches containing the work done during Phase 1, 2 and 3:
 +
* Deliverable for Phase 1: https://gitlab.com/tommasozugno/ns-3-dev/tree/gsoc-deliv-1
 +
* Deliverable for Phase 2 and 3: https://gitlab.com/tommasozugno/ns-3-dev/tree/gsoc-deliv-2
 +
 +
For each deliverable I opened a MR towards the ns-3 codebase: 
 +
* MR for Phase 1: https://gitlab.com/nsnam/ns-3-dev/merge_requests/72
 +
* MR for Phase 2 and 3: https://gitlab.com/nsnam/ns-3-dev/merge_requests/90
 +
 +
== Project repository ==
 +
The [https://gitlab.com/tommasozugno/ns-3-dev project repository] is a fork of the ns-3's primary source repository [https://gitlab.com/nsnam/ns-3-dev nsnam/ns-3-dev]. The branches <code>channel-condition-model</code>, <code>propagation-loss-models</code> and <code>new-channel</code> are feature branches containing the whole commit history. The branches <code>three-gpp-channel</code> and <code>three-gpp-channel-2</code> are the main branches used to submit the MRs towards [https://gitlab.com/nsnam/ns-3-dev nsnam/ns-3-dev]. The branches <code>gsoc-deliv-1</code> and and <code>gsoc-deliv-2</code> are permanent branches containing the work done during Phase 1, and Phase 2 and 3, respectively.
 +
 +
== Future Work ==
 +
Future extensions of this work should consider the following aspects:
 +
* add support to antenna sectors
 +
* implementation of the 3GPP O2I penetration loss model
 +
* implementation of the spatial consistency procedure
 +
* polarized antenna modeling
 +
* implementation of the oxygen absorption model
 +
* performance improvements
 +
* implementation of the channel model calibration scenarios

Latest revision as of 12:10, 17 September 2019

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 Google Summer of Code 2019.

Project Overview

  • Project Name: Integration of the 3GPP TR 38.901 channel model in the ns-3 spectrum module
  • Student: Tommaso Zugno
  • Mentor: Natale Patriciello
  • Proposal: link to the document
  • Abstract: In recent years, ns-3 has been widely used for the simulation of wireless networks, because it features several built-in and external modules implementing different wireless technologies. The overall performance of this kind of networks are strongly influenced by the characteristics of the signal propagation through the wireless link, thereby, a proper modeling of the channel behavior is of primary importance to obtain reliable results from the simulations. This project aims to tackle this issue by proposing an extension of the spectrum module to model both frequency and spatial-dependent phenomena, and to account for the directional behavior of the signal propagation. This will be achieved by implementing the modeling framework described in 3GPP TR 38.901, which includes the statistical characterization of different propagation environments, supports the modeling of multi-antenna systems, and, thanks to its modularity, can be easily extended with new environments or other additional features. Even if it has been specifically designed for the simulation of cellular networks, it supports frequency bands between 0.5 and 100 GHz, thus can be used even for other wireless technologies.
  • Code: GitLab repo
  • About Me: I am a first-year PhD student at the University of Padova, Italy, working under the supervision of prof. Michele Zorzi. My research focus on protocols and architectures for 5G cellular systems operating at mmWaves.

Project Timeline

Week 0 (Community Bonding Period)

  • discussion with my mentor about project plan, test cases, examples, model validation
  • creation of a wiki page for the project
  • project introduction in ns-developers
  • discussion with ns-developers about the extension of the "SpectrumSignalParameters" structure
  • creation of a git repository for the project

Week 1 (May 27 - June 2)

  • discussion with my mentor about the following issues:
    • how to apply the pathloss models without the knowledge of the type of the devices
    • computation of the pathloss between UE-UE and BS-BS
    • how to consider the mobility of both the devices for the computation of the Doppler frequency component and the spatial consistent procedure
  • design of the ChannelConditionModel abstract class and of the ThreeGppYYYChannelConditionModel subclasses
  • design of the ThreeGppYYYPropagationLossModel classes

Week 2 (June 3 - June 9)

  • implementation of the abstract class ChannelConditionModel, which provides the base for the implementation of specific channel condition models. The main method is GetChannelCondition (mm a, mm b), which determines the channel condition based on the tx and rx mobility models and returns it as a pointer to an object of type ChannelCondition. At this stage, the ChannelCondition class only contains information about the LOS/NLOS state of the channel, but it will be extended to include other information, e.g., whether the transmission is outdoor to indoor. The reason why we decided ChannelCondition to be a regular class (and not a struct for instance) is to be able to exploit the object aggregation system in case a derived class wants to add some additional information, without having to deal with subclassing. For instance, if we add a channel condition model which determines the condition based on the buildings deployed in the scenario, we can use the aggregation system to provide also the information about the type of the building obstructing the line of sight.
  • implementation of the subclasses ThreeGppRMaChannelConditionModel, ThreeGppUMaChannelConditionModel, ThreeGppUMiStreetCanyonChannelConditionModel, ThreeGppIndoorMixedOfficeChannelConditionModel, ThreeGppIndoorOpenOfficeChannelConditionModel, which inherits from ChannelConditionModel and statistically determines the LOS/NLOS state based on the specification in 3GPP TR 38.901.
  • addition of the subclass BuildingsChannelConditionModel, which inherits from ChannelConditionModel and determines the LOS/NLOS state based on the buildings deployed in the scenario. It has been adapted from the mmwave module.
  • design and implementation of test cases for all the new classes
    • the test cases for the ThreeGppYYYChannelConditionModel classes call the method GetChannelCondition () multiple times, estimate the LOS probability and compare it with the value computed using the baseline formula
    • the test case for the BuildingsChannelConditionModel determines the channel condition between two nodes in multiple cases: (i) there is a building in between the two nodes, (ii) no building in between, (iii) the first node is inside the building and the second is outside, (iv) the two nodes are inside the same building.
  • weekly discussion with my mentor about:
    • how to pass the information about the channel condition to the PropagationLossModel and SpectrumPropagationLoss model: we will not modify the existing APIs, the ChannelConditionModel will be used only within the propagation and spectrum implementations that wants to use it
    • where to put the ChannelConditionModel: we decided to put it the propagation module
    • how to implement the spatial consistency procedure described in TR 38.901: we decided to include procedure A, which supports mobility only at the user terminal, while the base station is considered always fixed. We will provide the possibility to enable/disable the spatial consistency procedure and to specify the channel update time through attributes.

MR for the channel condition model: https://gitlab.com/tommasozugno/ns-3-dev/merge_requests/1

Week 3 (June 10 - June 16)

  • review of the channel condition model
  • development of new classes which extends the PropagationLossModel interface and implements the pathloss models defined in 3GPP TR 38.901 (ThreeGppRmaPropagationLossModel, ThreeGppUmaPropagationLossModel, ThreeGppUmiStreeCanyonPropagationLossModel, ThreeGppIndoorOfficePropagationLossModel). The main method is DoCalcRxPower (txPow, mm a, mm b), which applies the pathloss model taking into account the LOS/NLOS channel state and then returns the received power. To retrieve the channel state, they interface with the class ChannelConditionModel through the method GetChannelCondition (mm a, mm b). Some of the models requires the knowledge of UT and BS heights, which are obtained by comparing the heights of the two nodes with the validity ranges specified by the standard, i.e., if height (a) falls inside the validity range for hUT, then hUT = height (a); else if height (a) falls inside the validity range for hBS, then hBS = height (a); and the same for node b. If hUT or hBS cannot be defined because none of the two nodes has a valid height, the default value is used.
  • discussion with my mentor about:
    • review of the channel condition model
    • how to avoid code duplication for the implementation of the pathloss models: we discussed about the possibility to define a common base class for all the ThreeGppYYYPropagationLossModel classes, since the methods DoCalcRxPower () are similar. However, this yields to multiple inheritance, which may worsen the code clarity.
    • deliverable for phase 1: it will include the new channel condition model and the 3GPP pathloss models

Week 4 (June 17 - June 23)

  • implementation of the test cases for the ThreeGppYYYPropagationLossModel classes. Each test case computes the propagation loss between two mobility models for different values of the distance and for both LOS and NLOS channel states. The resulting value is compared with the corresponding reference value obtained from the formulas specified in TR 38.901.
  • discussion with my mentor about the implementation of the propagation models

MR for the new pathloss models: https://gitlab.com/tommasozugno/ns-3-dev/merge_requests/2

Week 5 (June 24 - June 30)

  • change the pathloss models implementation following the discussion I had with my mentor. We decided to use the optional NLOS pathloss formula for the UMa and UMi scenarios. In this way we do not need to retrieve the height of the UT, which is a problem if we want to apply the models with height values different from the default ones.
  • write the doc for the new channel condition and pathloss models. I have updated the documentation of the propagation module with the description of all the new classes I have added.
  • implementation of the shadowing model. The ThreeGppYYYPropagationLossModel classes have an attribute called "ShadowingEnabled" which enables of disables the addition of the shadowing component. If the attribute is set to true, the shadowing component is computed following the procedure specified in 3GPP TR 38.901 and then added to the total loss. For the moment I have not implemented the spatial consistency procedure for the update of the shadowing component.
  • weekly discussion with my mentor about:
    • review of the pathloss models implementation
    • postpone the implementation of the O2I penetration loss model. We decided to add it at the end since it is an additional feature and to start with the development of the small scale fading model.

Week 6 (July 1 - July 7)

  • update the ThreeGppYYYPropagationLossModel classes and the related documentation following the review comments. In particular, we decided to remove the fatal error that was prompting when the distance between tx and rx is not within the validity range specified in TR 38.901, instead we print a warning message
  • open a MR to ns-3-dev containing the new channel condition and pathloss models (https://gitlab.com/nsnam/ns-3-dev/merge_requests/72)
  • start the integration of the fast fading model. I added a new class called ThreeGppSpectrumPropagationLossModel which extends the SpectrumPropagationLossModel interface. It has to generate the channel matrix, apply the small scale fading, apply the beamforming and return the PSD of the received signal following the model described in TR 38.901. For the implementation of this class I started from the MmWave3gppChannel class included in the mmwave module
  • discussion with my mentor about:
    • review of the pathloss model classes
    • structure of the ThreeGppSpectrumPropagationLossModel
    • possible usage of external libraries to speed up the channel matrix generation procedure
    • definition of a base class for antenna arrays

Week 7 (July 8 - July 14)

  • continue the integration of the fast fading model described in TR 38.901. I introduced a new class called ThreeGppChannel which includes the channel matrix generation procedure. Also, I developed the method DoCalcRxPowerSpectralDensity of the class ThreeGppSpectrumPropagationLossModel which i) makes use of an instance of ThreeGppChannel to retrieve the channel matrix, ii) applies the beamforming and iii) returns the received PSD.
  • weekly discussion with my mentor about:
    • how to update the channel matrix. We decided to update the channel matrix periodically and define the update time as attribute. Also, we decided to update the long term component (i.e., the product between the channel matrix and the beamforming vectors) only if tx and/or rx changed its beam.
    • how to define the structure used to save the channel realizations and the long term component
    • whether to apply the doppler component when the channel matrix is generated or at each call to DoCalcRxPowerSpectralDensity ()

Week 8 (July 15 - July 21)

  • continue the integration of the fast fading model described in TR 38.901, in particular:
    • development of an example which shows how to configure the channel model classes and computes the beamforming gain
    • debug and testing of the channel generation procedure
    • addition of a map to store the channel realizations in the ThreeGppChannel class

Week 9 (July 22 - July 28)

  • updated the ThreeGppSpectrumPropagationLossModel to save the long term component associated to each channel. I added a map to store the long term components. Each entry is identified by a channel ID which is computed using the Cantor function applied to the tx and rx node IDs. At each call of DoCalcRxPowerSpectralDensity (), the method looks for the long term in the map. If found, it checks whether it has to be updated (i.e., the channel matrix was updated or the beamforming vectors has changed). If not found or if it has to be updated, the method computes the long term component and stores it in the map.
  • started the implementation of the test cases for the classes ThreeGppChannel and ThreeGppSpectrumPropagationLossModel. The first test case checks:
    • if the dimensions of the channel matrix are consistent with the sizes of the antennas
    • if the expectation of the Frobenius norm of the channel matrix is equal to the product between the number of tx and rx antenna elements
    • if the channel matrix is correctly saved
  • Discussion with my mentor about:
    • review of the new classes ThreeGppChannel and ThreeGppSpectrumPropagationLossModel
    • whether to recompute the Doppler term at each transmission or at each channel update
    • comments in the MR submitted to ns-3-dev

Week 10 (July 29 - August 4)

  • add test case for the ThreeGppSpectrumPropagationLossModel class:
    • checks if the long term component for the direct and the reverse link are the same
    • checks if the long term component is updated when changing the beamforming vectors
    • checks if the long term component is updated when changing the channel matrix
  • add documentation for the classes ThreeGppChannel and ThreeGppSpectrumPropagationLossModel
  • develop an example which shows how to configure the 3GPP channel classes to compute the SNR between two nodes

Week 11 (August 5 - August 11)

  • review of the 3GPP pathloss and channel condition models (https://gitlab.com/nsnam/ns-3-dev/merge_requests/72). Some issues are still pending, if you are interested in this work please provide your feedback
  • add the possibility to update the shadowing after a certain time period. The shadowing loss is saved in the m_shadowingMap and updated after the specified time period or if the LOS/NLOS channel condition changes. The update period can be configured through the attribute "UpdatePeriod" of the class ThreeGppPropagationLossModel
  • add the possibility to update the channel condition after a certain time period. The channel condition is saved in the m_channelConditionMap and updated after the specified time period, which can be configured through the attribute "UpdatePeriod" of the class ThreeGppChannelConditionModel
  • add a new test case to check if the shadowing is correctly updated. The test checks that the shadowing loss is correctly recomputed after the specified update period and when the LOS/NLOS channel condition changes
  • update and refactor the tests for the channel condition models. I defined a single test case for all the 3GPP channel condition models
  • update the documentation

Week 12 (August 12 - August 18)

  • update the example including the possibility to choose the propagation scenario and to set the update period for the channel condition and the shadowing
  • improve the documentation
  • review of the fast fading model

Week 13 (August 19 - August 25)

  • refactoring of the classes modeling the antenna arrays
  • add documentation for the antenna models
  • final review of the fast fading model
  • move the buildings-aware channel condition model to the buildings module
  • submit a new MR for the fast fading model (https://gitlab.com/nsnam/ns-3-dev/merge_requests/90)
  • prepare the final report

Final Report

This project aimed at implementing the channel modeling framework described in 3GPP TR 38.901.

A new interface called ChannelConditionModel was defined to host models representing the channel condition (e.g., LOS/NLOS state, O2I propagation, etc.). The 3GPP LOS/NLOS channel condition models were implemented by extending the new interface. An additional building-aware channel condition model was implemented. The 3GPP propagation loss models were implemented by extending the interface PropagationLossModel. Both the 3GPP channel condition and the propagation loss models were included in the propagation module, while the building-aware channel condition model was included in the buildings module.

The 3GPP fast fading model was included in the spectrum module by extending the SpectrumPropagationLossModel interface. It consists in two classes: (i) ThreeGppChannel, which includes the channel matrix generation procedure (integrated starting from the channel model present in the mmwave module), and (ii) ThreeGppSpectrumPropagationLossModel, which extends the SpectrumPropagationLossModel interface and computes the power spectral density of the received signal by applying the fast fading model. For the modeling of antenna arrays, the new base class AntennaArrayBasicModel and an extension called AntennaArrayModel which were provided by CTTC, were refactored and included in the antenna module.

The project was divided in three phases. The work done in each phase is summarized in the following.

Phase 1

  • design and implementation of the interface ChannelConditionModel
  • implementation of the LOS/NLOS channel condition models described in TR 38.901
  • implementation of a building-aware channel condition model
  • implementation of the pathloss models described in TR 38.901
  • implementation of test cases for all the new classes
  • documentation for all the new classes

Phase 2

  • implementation of the fast fading model described in 3GPP TR 38.901:
    • definition of the class ThreeGppChannel
    • definition of the class ThreeGppSpectrumPropagationLossModel
  • testing and debugging

Phase 3

  • implementation of a simple update procedure for the channel matrix
  • implementation of a simple update procedure for the long term components
  • implementation of test cases for ThreeGppChannel and ThreeGppSpectrumPropagationLossModel
  • documentation for all the new classes
  • implementation of a periodic update procedure for the shadowing component
  • implementation of a periodic update procedure for the 3GPP channel condition models

Deliverables

I created separate branches containing the work done during Phase 1, 2 and 3:

For each deliverable I opened a MR towards the ns-3 codebase:

Project repository

The project repository is a fork of the ns-3's primary source repository nsnam/ns-3-dev. The branches channel-condition-model, propagation-loss-models and new-channel are feature branches containing the whole commit history. The branches three-gpp-channel and three-gpp-channel-2 are the main branches used to submit the MRs towards nsnam/ns-3-dev. The branches gsoc-deliv-1 and and gsoc-deliv-2 are permanent branches containing the work done during Phase 1, and Phase 2 and 3, respectively.

Future Work

Future extensions of this work should consider the following aspects:

  • add support to antenna sectors
  • implementation of the 3GPP O2I penetration loss model
  • implementation of the spatial consistency procedure
  • polarized antenna modeling
  • implementation of the oxygen absorption model
  • performance improvements
  • implementation of the channel model calibration scenarios