A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
two-ray-spectrum-propagation-loss-model.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2022 SIGNET Lab, Department of Information Engineering,
3 * University of Padova
4 *
5 * SPDX-License-Identifier: GPL-2.0-only
6 */
7
8#ifndef TWO_RAY_SPECTRUM_PROPAGATION_LOSS_H
9#define TWO_RAY_SPECTRUM_PROPAGATION_LOSS_H
10
13
14#include "ns3/channel-condition-model.h"
15
16#include <map>
17
21
22namespace ns3
23{
24
25class NetDevice;
26
27/**
28 * \ingroup spectrum
29 * \brief Two Ray Spectrum Propagation Loss Model
30 *
31 * This class implements a performance-oriented channel and beamforming models alternative to the
32 * ThreeGppSpectrumPropagationLossModel and ThreeGppChannelModel. The main method is
33 * DoCalcRxPowerSpectralDensity, which takes as input the power spectral density (PSD) of the
34 * transmitted signal, the mobility models of the transmitting node and receiving node, and returns
35 * the PSD of the received signal.
36 *
37 * The fading model is calibrated with the ThreeGppChannelModel, aiming to provide an end-to-end
38 * channel gain which matches as much as possible the TR 38.901-based channel model. Therefore, this
39 * model is to be used for large-scale simulations of MIMO wireless networks, for which the
40 * ThreeGppChannelModel would prove too computationally intensive. The target applicability of this
41 * model, in terms of frequency range, is 0.5-100 GHz.
42 *
43 * \see PhasedArrayModel
44 * \see ChannelCondition
45 */
47{
48 // Test classes needs access to CalcBeamformingGain and GetFtrFastFading
49 friend class ::FtrFadingModelAverageTest;
50 friend class ::ArrayResponseTest;
51 friend class ::OverallGainAverageTest;
52
53 public:
54 /**
55 * Struct holding the Fluctuating Two Ray fast-fading model parameters
56 */
57 struct FtrParams
58 {
59 /**
60 * Default constructor, requiring the Fluctuating Two Ray fading model parameters as
61 * arguments.
62 *
63 * \param m the m parameter of the FTR fading model, which represents the "Alpha" and "Beta"
64 * parameters of the Gamma-distributed random variable used to sample the power of the
65 * reflected components \param sigma the sigma parameter of the FTR fading model, which
66 * expresses the power of the diffuse real and imaginary components \param k the k parameter
67 * of the FTR fading model, which represents the ratio of the average power of the dominant
68 * components to the power of the remaining diffuse multipath \param delta the delta
69 * parameter of the FTR fading model, which express expressing how similar to each other are
70 * the average received powers of the specular components
71 */
72 FtrParams(double m, double sigma, double k, double delta)
73 {
74 // Make sure the parameter values belong to the proper domains
75 NS_ASSERT(delta >= 0.0 && delta <= 1.0);
76
77 m_m = m;
78 m_sigma = sigma;
79 m_k = k;
80 m_delta = delta;
81 }
82
83 /**
84 * Delete no-arguments default constructor.
85 */
86 FtrParams() = delete;
87
88 /**
89 * Parameter m for the Gamma variable. Used both as the shape and rate parameters.
90 */
91 double m_m = 0;
92
93 /**
94 * Parameter sigma. Used as the variance of the amplitudes of the normal diffuse components.
95 */
96 double m_sigma = 0;
97
98 /**
99 * Parameter K. Expresses ratio between dominant specular components and diffuse components.
100 */
101 double m_k = 0;
102
103 /**
104 * Parameter delta [0, 1]. Expresses how similar the amplitudes of the two dominant specular
105 * components are.
106 */
107 double m_delta = 0;
108 };
109
110 /**
111 * Tuple collecting vectors of carrier frequencies and FTR fading model parameters, encoded as a
112 * FtrParams struct
113 */
114 using CarrierFrequencyFtrParamsTuple = std::tuple<std::vector<double>, std::vector<FtrParams>>;
115
116 /**
117 * Nested map associating 3GPP scenario and LosCondition to the corresponding tuple of carrier
118 * frequencies and corresponding fitted FTR parameters
119 */
121 std::map<std::string,
122 std::map<ChannelCondition::LosConditionValue, CarrierFrequencyFtrParamsTuple>>;
123
124 /**
125 * Constructor
126 */
128
129 /**
130 * Destructor
131 */
133
134 void DoDispose() override;
135
136 /**
137 * Get the type ID.
138 * \return the object TypeId
139 */
140 static TypeId GetTypeId();
141
142 /**
143 * Sets the propagation scenario
144 * \param scenario the propagation scenario
145 */
146 void SetScenario(const std::string& scenario);
147
148 /**
149 * Sets the center frequency of the model
150 * \param f the center frequency in Hz
151 */
152 void SetFrequency(double f);
153
154 /**
155 * \brief Compute the received PSD.
156 *
157 * This function computes the received PSD by applying the Fluctuating Two-Ray (FTR)
158 * fast fading model and the beamforming gain.
159 * In particular, the beamforming gain is computed as the combination of the single-element
160 * and the array gains.
161 * The path loss and shadowing are to be computed separately, using the
162 * ThreeGppPropagationLossModel class.
163 *
164 * \param txPsd the PSD of the transmitted signal
165 * \param a first node mobility model
166 * \param b second node mobility model
167 * \param aPhasedArrayModel the antenna array of the first node
168 * \param bPhasedArrayModel the antenna array of the second node
169 * \return SpectrumSignalParameters including the PSD of the received signal
170 */
175 Ptr<const PhasedArrayModel> aPhasedArrayModel,
176 Ptr<const PhasedArrayModel> bPhasedArrayModel) const override;
177
178 protected:
179 int64_t DoAssignStreams(int64_t stream) override;
180
181 private:
182 /**
183 * Retrieves the LOS condition associated to the specified mobility models
184 *
185 * \param a the mobility model of the first node
186 * \param b the mobility model of the second node
187 * \return the LOS condition of the link between a and b
188 */
191
192 /**
193 * Retrieves the FTR fading model parameters related to the carrier frequency and LOS condition.
194 *
195 * The calibration has been undertaken using the 3GPP 38.901 as a reference. The latter's
196 * small-scale fading distributions depend on the scenario (UMa, UMi, RMa, InH), the LOS
197 * condition (LOS/NLOS) and the carrier frequency. Therefore, the output of the calibration is a
198 * map associating such simulation parameters to the specific FTR parameters. Specifically, such
199 * parameters represent the FTR distribution yielding channel realizations which exhibit the
200 * closest statistics to the small-scale fading obtained when using the 3GPP 38.901 model. The
201 * estimation relies on reference curves obtained by collecting multiple 38.901 channel
202 * realizations and computing the corresponding end-to-end channel gain by setting the speed of
203 * the TX and RX pair to 0, disabling the shadowing and fixing the LOS condition. In such a way,
204 * any variation of the received power around the mean is given by the small-scale fading only.
205 * Finally, the reference ECDF of the channel gains is compared to the ECDF obtained from the
206 * FTR distribution using different values of the parameters. The parameters which provide the
207 * best fit (in a goodness-of-fit sense) are kept for the specific scenario, LOS condition and
208 * carrier frequency. The goodness of the fit is measured using the well-known Anderson-Darling
209 * metric.
210 *
211 * For additional details, please refer to
212 * src/spectrum/examples/three-gpp-two-ray-channel-calibration.cc and
213 * src/spectrum/utils/two-ray-to-three-gpp-ch-calibration.py, which show how to obtain the
214 * reference curves and then estimate the FTR parameters based on the reference data,
215 * respectively.
216 *
217 * \param a first node mobility model
218 * \param b second node mobility model
219 * \return the corresponding FTR model parameters
220 */
222
223 /**
224 * Compute the stochastic power gain due to the fast fading, modeled according to the
225 * Fluctuating Two-Ray Model.
226 *
227 * Specifically, the amplitude of the random fading term is sampled as:
228 *
229 * TODO: Currently the equations are not rendered, but neither are other formulas. Fixed in the
230 * mainline, so this should also render properly after a rebase will be done
231 *
232 * \f$ V_r = \sqrt{\zeta} V_1 \exp(j \phi_1) + \sqrt{\zeta} V_2 \exp(j \phi_2) + X + jY \f$,
233 * where \f$ \zeta \f$ is a unit-mean Gamma distributed random variable of shape and rate \f$ m
234 * \f$, \f$ X \f$ and \f$ Y \f$ are zero-mean Gaussian random variables of variance \f$ \sigma^2
235 * \f$, \f$ \phi_n \f$ is a uniform random variable over \f$ \left[ 0, 2\pi \right] \f$, \f$ V_1
236 * \f$ and \f$ V_2 \f$ are the constant amplitudes of the reflected components.
237 *
238 * See J. M. Romero-Jerez, F. J. Lopez-Martinez, J. F. Paris and A. Goldsmith, "The Fluctuating
239 * Two-Ray Fading Model for mmWave Communications," 2016 IEEE Globecom Workshops (GC Wkshps) for
240 * further details on such model.
241 *
242 * \param params the FTR fading model parameters
243 * \return the stochastic power gain due to the fast fading
244 */
245 double GetFtrFastFading(const FtrParams& params) const;
246
247 /**
248 * Compute the beamforming gain by combining single-element and array gains.
249 *
250 * Computes the overall beamforming and array gain, assuming analog beamforming
251 * both at the transmitter and at the receiver and arbitrary single-element
252 * radiation patterns. The computation is performed following Rebato, Mattia, et al.
253 * "Study of realistic antenna patterns in 5G mmwave cellular scenarios.",
254 * 2018 IEEE International Conference on Communications (ICC). IEEE, 2018.
255 *
256 * Additionally, whenever the link is in NLOS a penalty factor is introduced, to take into
257 * account for the possible misalignment of the beamforming vectors due to the lack of a
258 * dominant multipath component. See Kulkarni, Mandar N., Eugene Visotsky, and Jeffrey G.
259 * Andrews. "Correction factor for analysis of MIMO wireless networks with highly directional
260 * beamforming." IEEE Wireless Communications Letters 7.5 (2018) for further details on this
261 * approach.
262 *
263 * \param a first node mobility model
264 * \param b second node mobility model
265 * \param aPhasedArrayModel the antenna array of the first node
266 * \param bPhasedArrayModel the antenna array of the second node
267 * \return the beamforming gain
268 */
271 Ptr<const PhasedArrayModel> aPhasedArrayModel,
272 Ptr<const PhasedArrayModel> bPhasedArrayModel) const;
273
274 /**
275 * Get the index of the closest carrier frequency for which the FTR estimated parameters are
276 * available.
277 *
278 * \param frequencies the vector of carrier frequencies which have been calibrated
279 * \param targetFc the carrier frequency of the current simulation
280 * \return the index of frequencies representing the argmin over frequencies of
281 * abs(frequencies[index] - targetFc)
282 */
283 std::size_t SearchClosestFc(const std::vector<double>& frequencies, double targetFc) const;
284
285 /**
286 * The operating frequency
287 */
289
290 /**
291 * Random variable used to sample the uniform distributed phases of the FTR specular components.
292 */
294
295 /**
296 * Random variable used to sample the normal distributed amplitudes of the FTR diffuse
297 * components.
298 */
300
301 /**
302 * Random variable used to sample the Nakagami distributed amplitude of the FTR specular
303 * components.
304 */
306
307 std::string m_scenario; //!< the 3GPP scenario
308
309 /**
310 * Channel condition model used to retrieve the LOS/NLOS condition of the communicating
311 * endpoints
312 */
314};
315
316} // namespace ns3
317
318#endif /* TWO_RAY_SPECTRUM_PROPAGATION_LOSS_H */
Test case for the TwoRaySpectrumPropagationLossModel class.
Test case for the TwoRaySpectrumPropagationLossModel class.
Test case for the TwoRaySpectrumPropagationLossModel class.
LosConditionValue
Possible values for Line-of-Sight condition.
spectrum-aware propagation loss model that is compatible with PhasedArrayModel type of ns-3 antenna
Smart pointer class similar to boost::intrusive_ptr.
std::map< std::string, std::map< ChannelCondition::LosConditionValue, CarrierFrequencyFtrParamsTuple > > FtrParamsLookupTable
Nested map associating 3GPP scenario and LosCondition to the corresponding tuple of carrier frequenci...
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.
ChannelCondition::LosConditionValue GetLosCondition(Ptr< const MobilityModel > a, Ptr< const MobilityModel > b) const
Retrieves the LOS condition associated to the specified mobility models.
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.
Ptr< NormalRandomVariable > m_normalRv
Random variable used to sample the normal distributed amplitudes of the FTR diffuse components.
Ptr< SpectrumSignalParameters > 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.
double GetFtrFastFading(const FtrParams &params) const
Compute the stochastic power gain due to the fast fading, modeled according to the Fluctuating Two-Ra...
std::tuple< std::vector< double >, std::vector< FtrParams > > CarrierFrequencyFtrParamsTuple
Tuple collecting vectors of carrier frequencies and FTR fading model parameters, encoded as a FtrPara...
int64_t DoAssignStreams(int64_t stream) override
Assign a fixed random variable stream number to the random variables used by this model.
Ptr< GammaRandomVariable > m_gammaRv
Random variable used to sample the Nakagami distributed amplitude of the FTR specular components.
Ptr< ChannelConditionModel > m_channelConditionModel
Channel condition model used to retrieve the LOS/NLOS condition of the communicating endpoints.
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.
void SetFrequency(double f)
Sets the center frequency of the model.
Ptr< UniformRandomVariable > m_uniformRv
Random variable used to sample the uniform distributed phases of the FTR specular components.
void SetScenario(const std::string &scenario)
Sets the propagation scenario.
a unique identifier for an interface.
Definition type-id.h:48
#define NS_ASSERT(condition)
At runtime, in debugging builds, if this condition is not true, the program prints the source file,...
Definition assert.h:55
Every class exported by the ns3 library is enclosed in the ns3 namespace.
Struct holding the Fluctuating Two Ray fast-fading model parameters.
FtrParams(double m, double sigma, double k, double delta)
Default constructor, requiring the Fluctuating Two Ray fading model parameters as arguments.
FtrParams()=delete
Delete no-arguments default constructor.