A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
ns3::TwoRaySpectrumPropagationLossModel Class Reference

Two Ray Spectrum Propagation Loss Model. More...

#include "two-ray-spectrum-propagation-loss-model.h"

+ Inheritance diagram for ns3::TwoRaySpectrumPropagationLossModel:
+ Collaboration diagram for ns3::TwoRaySpectrumPropagationLossModel:

Classes

struct  FtrParams
 Struct holding the Fluctuating Two Ray fast-fading model parameters. More...
 

Public Types

using CarrierFrequencyFtrParamsTuple = std::tuple<std::vector<double>, std::vector<FtrParams>>
 Tuple collecting vectors of carrier frequencies and FTR fading model parameters, encoded as a FtrParams struct.
 
using FtrParamsLookupTable
 Nested map associating 3GPP scenario and LosCondition to the corresponding tuple of carrier frequencies and corresponding fitted FTR parameters.
 

Public Member Functions

 TwoRaySpectrumPropagationLossModel ()
 Constructor.
 
 ~TwoRaySpectrumPropagationLossModel () override
 Destructor.
 
Ptr< SpectrumSignalParametersDoCalcRxPowerSpectralDensity (Ptr< const SpectrumSignalParameters > txPsd, Ptr< const MobilityModel > a, Ptr< const MobilityModel > b, Ptr< const PhasedArrayModel > aPhasedArrayModel, Ptr< const PhasedArrayModel > bPhasedArrayModel) const override
 Compute the received PSD.
 
void DoDispose () override
 Destructor implementation.
 
void SetFrequency (double f)
 Sets the center frequency of the model.
 
void SetScenario (const std::string &scenario)
 Sets the propagation scenario.
 
- Public Member Functions inherited from ns3::PhasedArraySpectrumPropagationLossModel
 PhasedArraySpectrumPropagationLossModel ()
 
 ~PhasedArraySpectrumPropagationLossModel () override
 
int64_t AssignStreams (int64_t stream)
 If this loss model uses objects of type RandomVariableStream, set the stream numbers to the integers starting with the offset 'stream'.
 
Ptr< SpectrumSignalParametersCalcRxPowerSpectralDensity (Ptr< const SpectrumSignalParameters > txPsd, Ptr< const MobilityModel > a, Ptr< const MobilityModel > b, Ptr< const PhasedArrayModel > aPhasedArrayModel, Ptr< const PhasedArrayModel > bPhasedArrayModel) const
 This method is to be called to calculate.
 
Ptr< PhasedArraySpectrumPropagationLossModelGetNext () const
 Return the pointer to the next PhasedArraySpectrumPropagationLossModel, if any.
 
void SetNext (Ptr< PhasedArraySpectrumPropagationLossModel > next)
 Used to chain various instances of PhasedArraySpectrumPropagationLossModel.
 
- Public Member Functions inherited from ns3::Object
 Object ()
 Constructor.
 
 ~Object () override
 Destructor.
 
void AggregateObject (Ptr< Object > other)
 Aggregate two Objects together.
 
void Dispose ()
 Dispose of this Object.
 
AggregateIterator GetAggregateIterator () const
 Get an iterator to the Objects aggregated to this one.
 
TypeId GetInstanceTypeId () const override
 Get the most derived TypeId for this Object.
 
template<typename T >
Ptr< T > GetObject () const
 Get a pointer to the requested aggregated Object.
 
template<>
Ptr< ObjectGetObject () const
 Specialization of () for objects of type ns3::Object.
 
template<typename T >
Ptr< T > GetObject (TypeId tid) const
 Get a pointer to the requested aggregated Object by TypeId.
 
template<>
Ptr< ObjectGetObject (TypeId tid) const
 Specialization of (TypeId tid) for objects of type ns3::Object.
 
void Initialize ()
 Invoke DoInitialize on all Objects aggregated to this one.
 
bool IsInitialized () const
 Check if the object has been initialized.
 
void UnidirectionalAggregateObject (Ptr< Object > other)
 Aggregate an Object to another Object.
 
- Public Member Functions inherited from ns3::SimpleRefCount< Object, ObjectBase, ObjectDeleter >
 SimpleRefCount ()
 Default constructor.
 
 SimpleRefCount (const SimpleRefCount &o)
 Copy constructor.
 
uint32_t GetReferenceCount () const
 Get the reference count of the object.
 
SimpleRefCountoperator= (const SimpleRefCount &o)
 Assignment operator.
 
void Ref () const
 Increment the reference count.
 
void Unref () const
 Decrement the reference count.
 
- Public Member Functions inherited from ns3::ObjectBase
virtual ~ObjectBase ()
 Virtual destructor.
 
void GetAttribute (std::string name, AttributeValue &value, bool permissive=false) const
 Get the value of an attribute, raising fatal errors if unsuccessful.
 
bool GetAttributeFailSafe (std::string name, AttributeValue &value) const
 Get the value of an attribute without raising errors.
 
void SetAttribute (std::string name, const AttributeValue &value)
 Set a single attribute, raising fatal errors if unsuccessful.
 
bool SetAttributeFailSafe (std::string name, const AttributeValue &value)
 Set a single attribute without raising errors.
 
bool TraceConnect (std::string name, std::string context, const CallbackBase &cb)
 Connect a TraceSource to a Callback with a context.
 
bool TraceConnectWithoutContext (std::string name, const CallbackBase &cb)
 Connect a TraceSource to a Callback without a context.
 
bool TraceDisconnect (std::string name, std::string context, const CallbackBase &cb)
 Disconnect from a TraceSource a Callback previously connected with a context.
 
bool TraceDisconnectWithoutContext (std::string name, const CallbackBase &cb)
 Disconnect from a TraceSource a Callback previously connected without a context.
 

Static Public Member Functions

static TypeId GetTypeId ()
 Get the type ID.
 
- Static Public Member Functions inherited from ns3::PhasedArraySpectrumPropagationLossModel
static TypeId GetTypeId ()
 Get the type ID.
 
- Static Public Member Functions inherited from ns3::Object
static TypeId GetTypeId ()
 Register this type.
 
- Static Public Member Functions inherited from ns3::ObjectBase
static TypeId GetTypeId ()
 Get the type ID.
 

Protected Member Functions

int64_t DoAssignStreams (int64_t stream) override
 Assign a fixed random variable stream number to the random variables used by this model.
 
- Protected Member Functions inherited from ns3::Object
 Object (const Object &o)
 Copy an Object.
 
virtual void DoInitialize ()
 Initialize() implementation.
 
virtual void NotifyNewAggregate ()
 Notify all Objects aggregated to this one of a new Object being aggregated.
 
- Protected Member Functions inherited from ns3::ObjectBase
void ConstructSelf (const AttributeConstructionList &attributes)
 Complete construction of ObjectBase; invoked by derived classes.
 
virtual void NotifyConstructionCompleted ()
 Notifier called once the ObjectBase is fully constructed.
 

Private Member Functions

double CalcBeamformingGain (Ptr< const MobilityModel > a, Ptr< const MobilityModel > b, Ptr< const PhasedArrayModel > aPhasedArrayModel, Ptr< const PhasedArrayModel > bPhasedArrayModel) const
 Compute the beamforming gain by combining single-element and array gains.
 
double GetFtrFastFading (const FtrParams &params) const
 Compute the stochastic power gain due to the fast fading, modeled according to the Fluctuating Two-Ray Model.
 
FtrParams GetFtrParameters (Ptr< const MobilityModel > a, Ptr< const MobilityModel > b) const
 Retrieves the FTR fading model parameters related to the carrier frequency and LOS condition.
 
ChannelCondition::LosConditionValue GetLosCondition (Ptr< const MobilityModel > a, Ptr< const MobilityModel > b) const
 Retrieves the LOS condition associated to the specified mobility models.
 
std::size_t SearchClosestFc (const std::vector< double > &frequencies, double targetFc) const
 Get the index of the closest carrier frequency for which the FTR estimated parameters are available.
 

Private Attributes

Ptr< ChannelConditionModelm_channelConditionModel
 Channel condition model used to retrieve the LOS/NLOS condition of the communicating endpoints.
 
double m_frequency
 The operating frequency.
 
Ptr< GammaRandomVariablem_gammaRv
 Random variable used to sample the Nakagami distributed amplitude of the FTR specular components.
 
Ptr< NormalRandomVariablem_normalRv
 Random variable used to sample the normal distributed amplitudes of the FTR diffuse components.
 
std::string m_scenario
 the 3GPP scenario
 
Ptr< UniformRandomVariablem_uniformRv
 Random variable used to sample the uniform distributed phases of the FTR specular components.
 

Friends

class ::ArrayResponseTest
 
class ::FtrFadingModelAverageTest
 
class ::OverallGainAverageTest
 

Additional Inherited Members

Detailed Description

Two Ray Spectrum Propagation Loss Model.

This class implements a performance-oriented channel and beamforming models alternative to the ThreeGppSpectrumPropagationLossModel and ThreeGppChannelModel. The main method is DoCalcRxPowerSpectralDensity, which takes as input the power spectral density (PSD) of the transmitted signal, the mobility models of the transmitting node and receiving node, and returns the PSD of the received signal.

The fading model is calibrated with the ThreeGppChannelModel, aiming to provide an end-to-end channel gain which matches as much as possible the TR 38.901-based channel model. Therefore, this model is to be used for large-scale simulations of MIMO wireless networks, for which the ThreeGppChannelModel would prove too computationally intensive. The target applicability of this model, in terms of frequency range, is 0.5-100 GHz.

See also
PhasedArrayModel
ChannelCondition

Definition at line 46 of file two-ray-spectrum-propagation-loss-model.h.

Member Typedef Documentation

◆ CarrierFrequencyFtrParamsTuple

Tuple collecting vectors of carrier frequencies and FTR fading model parameters, encoded as a FtrParams struct.

Definition at line 114 of file two-ray-spectrum-propagation-loss-model.h.

◆ FtrParamsLookupTable

Initial value:
std::map<std::string,
std::map<ChannelCondition::LosConditionValue, CarrierFrequencyFtrParamsTuple>>

Nested map associating 3GPP scenario and LosCondition to the corresponding tuple of carrier frequencies and corresponding fitted FTR parameters.

Definition at line 120 of file two-ray-spectrum-propagation-loss-model.h.

Constructor & Destructor Documentation

◆ TwoRaySpectrumPropagationLossModel()

ns3::TwoRaySpectrumPropagationLossModel::TwoRaySpectrumPropagationLossModel ( )

Constructor.

Definition at line 891 of file two-ray-spectrum-propagation-loss-model.cc.

References ns3::CreateObject(), m_gammaRv, m_normalRv, m_uniformRv, and NS_LOG_FUNCTION.

+ Here is the call graph for this function:

◆ ~TwoRaySpectrumPropagationLossModel()

ns3::TwoRaySpectrumPropagationLossModel::~TwoRaySpectrumPropagationLossModel ( )
override

Destructor.

Definition at line 906 of file two-ray-spectrum-propagation-loss-model.cc.

References m_gammaRv, m_normalRv, m_uniformRv, and NS_LOG_FUNCTION.

Member Function Documentation

◆ CalcBeamformingGain()

double ns3::TwoRaySpectrumPropagationLossModel::CalcBeamformingGain ( Ptr< const MobilityModel > a,
Ptr< const MobilityModel > b,
Ptr< const PhasedArrayModel > aPhasedArrayModel,
Ptr< const PhasedArrayModel > bPhasedArrayModel ) const
private

Compute the beamforming gain by combining single-element and array gains.

Computes the overall beamforming and array gain, assuming analog beamforming both at the transmitter and at the receiver and arbitrary single-element radiation patterns. The computation is performed following Rebato, Mattia, et al. "Study of realistic antenna patterns in 5G mmwave cellular scenarios.", 2018 IEEE International Conference on Communications (ICC). IEEE, 2018.

Additionally, whenever the link is in NLOS a penalty factor is introduced, to take into account for the possible misalignment of the beamforming vectors due to the lack of a dominant multipath component. See 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 7.5 (2018) for further details on this approach.

Parameters
afirst node mobility model
bsecond node mobility model
aPhasedArrayModelthe antenna array of the first node
bPhasedArrayModelthe antenna array of the second node
Returns
the beamforming gain

Definition at line 1020 of file two-ray-spectrum-propagation-loss-model.cc.

References GetLosCondition(), ns3::ChannelCondition::NLOS, MRG32k3a::norm, and NS_LOG_FUNCTION.

Referenced by DoCalcRxPowerSpectralDensity().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ DoAssignStreams()

int64_t ns3::TwoRaySpectrumPropagationLossModel::DoAssignStreams ( int64_t stream)
overrideprotectedvirtual

Assign a fixed random variable stream number to the random variables used by this model.

Subclasses must implement this; those not using random variables can return zero.

Parameters
streamfirst stream index to use
Returns
the number of stream indices assigned by this model

Implements ns3::PhasedArraySpectrumPropagationLossModel.

Definition at line 1157 of file two-ray-spectrum-propagation-loss-model.cc.

References m_gammaRv, m_normalRv, m_uniformRv, and NS_LOG_FUNCTION.

◆ DoCalcRxPowerSpectralDensity()

Ptr< SpectrumSignalParameters > ns3::TwoRaySpectrumPropagationLossModel::DoCalcRxPowerSpectralDensity ( Ptr< const SpectrumSignalParameters > txPsd,
Ptr< const MobilityModel > a,
Ptr< const MobilityModel > b,
Ptr< const PhasedArrayModel > aPhasedArrayModel,
Ptr< const PhasedArrayModel > bPhasedArrayModel ) const
overridevirtual

Compute the received PSD.

This function computes the received PSD by applying the Fluctuating Two-Ray (FTR) fast fading model and the beamforming gain. In particular, the beamforming gain is computed as the combination of the single-element and the array gains. The path loss and shadowing are to be computed separately, using the ThreeGppPropagationLossModel class.

Parameters
txPsdthe PSD of the transmitted signal
afirst node mobility model
bsecond node mobility model
aPhasedArrayModelthe antenna array of the first node
bPhasedArrayModelthe antenna array of the second node
Returns
SpectrumSignalParameters including the PSD of the received signal

Implements ns3::PhasedArraySpectrumPropagationLossModel.

Definition at line 1105 of file two-ray-spectrum-propagation-loss-model.cc.

References CalcBeamformingGain(), GetFtrFastFading(), GetFtrParameters(), NS_ASSERT_MSG, NS_LOG_DEBUG, and NS_LOG_FUNCTION.

+ Here is the call graph for this function:

◆ DoDispose()

void ns3::TwoRaySpectrumPropagationLossModel::DoDispose ( )
overridevirtual

Destructor implementation.

This method is called by Dispose() or by the Object's destructor, whichever comes first.

Subclasses are expected to implement their real destruction code in an overridden version of this method and chain up to their parent's implementation once they are done. i.e, for simplicity, the destructor of every subclass should be empty and its content should be moved to the associated DoDispose() method.

It is safe to call GetObject() from within this method.

Reimplemented from ns3::PhasedArraySpectrumPropagationLossModel.

Definition at line 916 of file two-ray-spectrum-propagation-loss-model.cc.

◆ GetFtrFastFading()

double ns3::TwoRaySpectrumPropagationLossModel::GetFtrFastFading ( const FtrParams & params) const
private

Compute the stochastic power gain due to the fast fading, modeled according to the Fluctuating Two-Ray Model.

Specifically, the amplitude of the random fading term is sampled as:

TODO: Currently the equations are not rendered, but neither are other formulas. Fixed in the mainline, so this should also render properly after a rebase will be done

$ V_r = \sqrt{\zeta} V_1 \exp(j \phi_1) + \sqrt{\zeta} V_2 \exp(j \phi_2) + X + jY $, where $ \zeta $ is a unit-mean Gamma distributed random variable of shape and rate $ m
$, $ X $ and $ Y $ are zero-mean Gaussian random variables of variance $ \sigma^2
$, $ \phi_n $ is a uniform random variable over $ \left[ 0, 2\pi \right] $, $ V_1
$ and $ V_2 $ are the constant amplitudes of the reflected components.

See J. M. Romero-Jerez, F. J. Lopez-Martinez, J. F. Paris and A. Goldsmith, "The Fluctuating Two-Ray Fading Model for mmWave Communications," 2016 IEEE Globecom Workshops (GC Wkshps) for further details on such model.

Parameters
paramsthe FTR fading model parameters
Returns
the stochastic power gain due to the fast fading

Definition at line 1072 of file two-ray-spectrum-propagation-loss-model.cc.

References m_gammaRv, m_normalRv, m_uniformRv, MRG32k3a::norm, and NS_LOG_FUNCTION.

Referenced by DoCalcRxPowerSpectralDensity().

+ Here is the caller graph for this function:

◆ GetFtrParameters()

TwoRaySpectrumPropagationLossModel::FtrParams ns3::TwoRaySpectrumPropagationLossModel::GetFtrParameters ( Ptr< const MobilityModel > a,
Ptr< const MobilityModel > b ) const
private

Retrieves the FTR fading model parameters related to the carrier frequency and LOS condition.

The calibration has been undertaken using the 3GPP 38.901 as a reference. The latter's small-scale fading distributions depend on the scenario (UMa, UMi, RMa, InH), the LOS condition (LOS/NLOS) and the carrier frequency. Therefore, the output of the calibration is a map associating such simulation parameters to the specific FTR parameters. Specifically, such parameters represent the FTR distribution yielding channel realizations which exhibit the closest statistics to the small-scale fading obtained when using the 3GPP 38.901 model. The estimation relies on reference curves obtained by collecting multiple 38.901 channel realizations and computing the corresponding end-to-end channel gain by setting the speed of the TX and RX pair to 0, disabling the shadowing and fixing the LOS condition. In such a way, any variation of the received power around the mean is given by the small-scale fading only. Finally, the reference ECDF of the channel gains is compared to the ECDF obtained from the FTR distribution using different values of the parameters. The parameters which provide the best fit (in a goodness-of-fit sense) are kept for the specific scenario, LOS condition and carrier frequency. The goodness of the fit is measured using the well-known Anderson-Darling metric.

For additional details, please refer to src/spectrum/examples/three-gpp-two-ray-channel-calibration.cc and src/spectrum/utils/two-ray-to-three-gpp-ch-calibration.py, which show how to obtain the reference curves and then estimate the FTR parameters based on the reference data, respectively.

Parameters
afirst node mobility model
bsecond node mobility model
Returns
the corresponding FTR model parameters

Definition at line 991 of file two-ray-spectrum-propagation-loss-model.cc.

References GetLosCondition(), m_frequency, m_scenario, NS_ASSERT, NS_ASSERT_MSG, NS_LOG_FUNCTION, SearchClosestFc(), and ns3::SIM_PARAMS_TO_FTR_PARAMS_TABLE.

Referenced by DoCalcRxPowerSpectralDensity().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ GetLosCondition()

ChannelCondition::LosConditionValue ns3::TwoRaySpectrumPropagationLossModel::GetLosCondition ( Ptr< const MobilityModel > a,
Ptr< const MobilityModel > b ) const
private

Retrieves the LOS condition associated to the specified mobility models.

Parameters
athe mobility model of the first node
bthe mobility model of the second node
Returns
the LOS condition of the link between a and b

Definition at line 979 of file two-ray-spectrum-propagation-loss-model.cc.

References m_channelConditionModel, NS_ASSERT, and NS_LOG_FUNCTION.

Referenced by CalcBeamformingGain(), and GetFtrParameters().

+ Here is the caller graph for this function:

◆ GetTypeId()

TypeId ns3::TwoRaySpectrumPropagationLossModel::GetTypeId ( )
static

Get the type ID.

Returns
the object TypeId

Definition at line 921 of file two-ray-spectrum-propagation-loss-model.cc.

References m_channelConditionModel, ns3::MakeDoubleAccessor(), ns3::MakeDoubleChecker(), ns3::MakePointerAccessor(), ns3::MakePointerChecker(), ns3::MakeStringAccessor(), ns3::MakeStringChecker(), SetFrequency(), ns3::TypeId::SetParent(), and SetScenario().

+ Here is the call graph for this function:

◆ SearchClosestFc()

std::size_t ns3::TwoRaySpectrumPropagationLossModel::SearchClosestFc ( const std::vector< double > & frequencies,
double targetFc ) const
private

Get the index of the closest carrier frequency for which the FTR estimated parameters are available.

Parameters
frequenciesthe vector of carrier frequencies which have been calibrated
targetFcthe carrier frequency of the current simulation
Returns
the index of frequencies representing the argmin over frequencies of abs(frequencies[index] - targetFc)

Definition at line 1145 of file two-ray-spectrum-propagation-loss-model.cc.

Referenced by GetFtrParameters().

+ Here is the caller graph for this function:

◆ SetFrequency()

void ns3::TwoRaySpectrumPropagationLossModel::SetFrequency ( double f)

Sets the center frequency of the model.

Parameters
fthe center frequency in Hz

Definition at line 970 of file two-ray-spectrum-propagation-loss-model.cc.

References m_frequency, NS_ASSERT_MSG, and NS_LOG_FUNCTION.

Referenced by GetTypeId().

+ Here is the caller graph for this function:

◆ SetScenario()

void ns3::TwoRaySpectrumPropagationLossModel::SetScenario ( const std::string & scenario)

Sets the propagation scenario.

Parameters
scenariothe propagation scenario

Definition at line 949 of file two-ray-spectrum-propagation-loss-model.cc.

References m_scenario, NS_ABORT_MSG, NS_LOG_FUNCTION, and ns3::SIM_PARAMS_TO_FTR_PARAMS_TABLE.

Referenced by GetTypeId().

+ Here is the caller graph for this function:

Friends And Related Symbol Documentation

◆ ::ArrayResponseTest

friend class ::ArrayResponseTest
friend

Definition at line 50 of file two-ray-spectrum-propagation-loss-model.h.

◆ ::FtrFadingModelAverageTest

friend class ::FtrFadingModelAverageTest
friend

Definition at line 49 of file two-ray-spectrum-propagation-loss-model.h.

◆ ::OverallGainAverageTest

friend class ::OverallGainAverageTest
friend

Definition at line 51 of file two-ray-spectrum-propagation-loss-model.h.

Member Data Documentation

◆ m_channelConditionModel

Ptr<ChannelConditionModel> ns3::TwoRaySpectrumPropagationLossModel::m_channelConditionModel
private

Channel condition model used to retrieve the LOS/NLOS condition of the communicating endpoints.

Definition at line 313 of file two-ray-spectrum-propagation-loss-model.h.

Referenced by GetLosCondition(), and GetTypeId().

◆ m_frequency

double ns3::TwoRaySpectrumPropagationLossModel::m_frequency
private

The operating frequency.

Definition at line 288 of file two-ray-spectrum-propagation-loss-model.h.

Referenced by GetFtrParameters(), and SetFrequency().

◆ m_gammaRv

Ptr<GammaRandomVariable> ns3::TwoRaySpectrumPropagationLossModel::m_gammaRv
private

Random variable used to sample the Nakagami distributed amplitude of the FTR specular components.

Definition at line 305 of file two-ray-spectrum-propagation-loss-model.h.

Referenced by TwoRaySpectrumPropagationLossModel(), ~TwoRaySpectrumPropagationLossModel(), DoAssignStreams(), and GetFtrFastFading().

◆ m_normalRv

Ptr<NormalRandomVariable> ns3::TwoRaySpectrumPropagationLossModel::m_normalRv
private

Random variable used to sample the normal distributed amplitudes of the FTR diffuse components.

Definition at line 299 of file two-ray-spectrum-propagation-loss-model.h.

Referenced by TwoRaySpectrumPropagationLossModel(), ~TwoRaySpectrumPropagationLossModel(), DoAssignStreams(), and GetFtrFastFading().

◆ m_scenario

std::string ns3::TwoRaySpectrumPropagationLossModel::m_scenario
private

the 3GPP scenario

Definition at line 307 of file two-ray-spectrum-propagation-loss-model.h.

Referenced by GetFtrParameters(), and SetScenario().

◆ m_uniformRv

Ptr<UniformRandomVariable> ns3::TwoRaySpectrumPropagationLossModel::m_uniformRv
private

Random variable used to sample the uniform distributed phases of the FTR specular components.

Definition at line 293 of file two-ray-spectrum-propagation-loss-model.h.

Referenced by TwoRaySpectrumPropagationLossModel(), ~TwoRaySpectrumPropagationLossModel(), DoAssignStreams(), and GetFtrFastFading().


The documentation for this class was generated from the following files: