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

Public Member Functions
	TwoRaySpectrumPropagationLossModel ()
	Constructor.

	~TwoRaySpectrumPropagationLossModel () override
	Destructor.

int64_t	AssignStreams (int64_t stream)
	Assign a fixed random variable stream number to the random variables used by this model.

Ptr< SpectrumValue >	DoCalcRxPowerSpectralDensity (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

Ptr< SpectrumValue >	CalcRxPowerSpectralDensity (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.

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< Object >	GetObject () 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< Object >	GetObject (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.

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.

SimpleRefCount &	operator= (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) 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.

virtual TypeId	GetInstanceTypeId () const =0
	Get the most derived TypeId for this Object.

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.

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< ChannelConditionModel >	m_channelConditionModel
	Channel condition model used to retrieve the LOS/NLOS condition of the communicating endpoints.

double	m_frequency
	The operating frequency.

Ptr< GammaRandomVariable >	m_gammaRv
	Random variable used to sample the Nakagami distributed amplitude of the FTR specular components.

Ptr< NormalRandomVariable >	m_normalRv
	Random variable used to sample the normal distributed amplitudes of the FTR diffuse components.

std::string	m_scenario
	the 3GPP scenario

Ptr< UniformRandomVariable >	m_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
void	DoDispose () override
	Destructor implementation.

Protected Member Functions inherited from ns3::Object
	Object (const Object &o)
	Copy an Object.

virtual void	DoDispose ()
	Destructor implementation.

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.

Related Functions inherited from ns3::ObjectBase
static TypeId	GetObjectIid ()
	Ensure the TypeId for ObjectBase gets fully configured to anchor the inheritance tree properly.

Detailed Description

Two Ray Spectrum Propagation Loss Model.

Introspection did not find any typical Config paths.

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

Attributes

ChannelConditionModel: Pointer to the channel condition model.
- Set with class: ns3::PointerValue
- Underlying type: ns3::Ptr< ns3::ChannelConditionModel>
- Initial value: 0
- Flags: constructwriteread
Frequency: The operating Frequency in Hz
- Set with class: ns3::DoubleValue
- Underlying type: double -1.79769e+308:1.79769e+308
- Initial value: 5e+08
- Flags: constructwrite
Scenario: The 3GPP scenario (RMa, UMa, UMi-StreetCanyon, InH-OfficeOpen, InH-OfficeMixed).
- Set with class: ns3::StringValue
- Underlying type: std::string
- Initial value: RMa
- Flags: constructwrite

No TraceSources are defined for this type.
Size of this type is 88 bytes (on a 64-bit architecture).

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

Member Typedef Documentation

◆ CarrierFrequencyFtrParamsTuple

using ns3::TwoRaySpectrumPropagationLossModel::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.

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

◆ FtrParamsLookupTable

using ns3::TwoRaySpectrumPropagationLossModel::FtrParamsLookupTable = 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 130 of file two-ray-spectrum-propagation-loss-model.h.

Constructor & Destructor Documentation

◆ TwoRaySpectrumPropagationLossModel()

ns3::TwoRaySpectrumPropagationLossModel::TwoRaySpectrumPropagationLossModel ( )

Constructor.

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

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

Here is the call graph for this function:

◆ ~TwoRaySpectrumPropagationLossModel()

ns3::TwoRaySpectrumPropagationLossModel::~TwoRaySpectrumPropagationLossModel ( )

override

Destructor.

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

References m_gammaRv, m_normalRv, m_uniformRv, and NS_LOG_FUNCTION.

Member Function Documentation

◆ AssignStreams()

int64_t ns3::TwoRaySpectrumPropagationLossModel::AssignStreams ( int64_t stream )

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

Parameters

stream first stream index to use

Returns: the number of stream indices assigned by this model

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

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

Here is the call graph for this function:

◆ 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

a	first node mobility model
b	second node mobility model
aPhasedArrayModel	the antenna array of the first node
bPhasedArrayModel	the antenna array of the second node

Returns: the beamforming gain

Definition at line 1031 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:

◆ DoCalcRxPowerSpectralDensity()

Ptr< SpectrumValue > 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

txPsd	the PSD of the transmitted signal
a	first node mobility model
b	second node mobility model
aPhasedArrayModel	the antenna array of the first node
bPhasedArrayModel	the antenna array of the second node

Returns: the PSD of the received signal

Implements ns3::PhasedArraySpectrumPropagationLossModel.

Definition at line 1116 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 927 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

params the FTR fading model parameters

Returns: the stochastic power gain due to the fast fading

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

References ns3::UniformRandomVariable::GetValue(), ns3::TwoRaySpectrumPropagationLossModel::FtrParams::m_delta, m_gammaRv, ns3::TwoRaySpectrumPropagationLossModel::FtrParams::m_k, ns3::TwoRaySpectrumPropagationLossModel::FtrParams::m_m, m_normalRv, ns3::TwoRaySpectrumPropagationLossModel::FtrParams::m_sigma, m_uniformRv, 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:

◆ 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

a	first node mobility model
b	second node mobility model

Returns: the corresponding FTR model parameters

Definition at line 1002 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