A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
uniform-planar-array.cc
Go to the documentation of this file.
1/*
2 * Copyright (c) 2020 University of Padova, Dep. of Information Engineering, SIGNET lab.
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 */
6
8
9#include <ns3/boolean.h>
10#include <ns3/double.h>
11#include <ns3/log.h>
12#include <ns3/uinteger.h>
13
14namespace ns3
15{
16
17NS_LOG_COMPONENT_DEFINE("UniformPlanarArray");
18
19NS_OBJECT_ENSURE_REGISTERED(UniformPlanarArray);
20
25
29
32{
33 static TypeId tid =
34 TypeId("ns3::UniformPlanarArray")
36 .AddConstructor<UniformPlanarArray>()
37 .SetGroupName("Antenna")
38 .AddAttribute(
39 "AntennaHorizontalSpacing",
40 "Horizontal spacing between antenna elements, in multiples of wave length",
41 DoubleValue(0.5),
45 .AddAttribute("AntennaVerticalSpacing",
46 "Vertical spacing between antenna elements, in multiples of wave length",
47 DoubleValue(0.5),
51 .AddAttribute("NumColumns",
52 "Horizontal size of the array",
57 .AddAttribute("NumRows",
58 "Vertical size of the array",
63 .AddAttribute("BearingAngle",
64 "The bearing angle in radians",
65 DoubleValue(0.0),
67 MakeDoubleChecker<double>(-M_PI, M_PI))
68 .AddAttribute("DowntiltAngle",
69 "The downtilt angle in radians",
70 DoubleValue(0.0),
72 MakeDoubleChecker<double>(-M_PI, M_PI))
73 .AddAttribute("PolSlantAngle",
74 "The polarization slant angle in radians",
75 DoubleValue(0.0),
78 MakeDoubleChecker<double>(-M_PI, M_PI))
79 .AddAttribute("NumVerticalPorts",
80 "Vertical number of ports",
85 .AddAttribute("NumHorizontalPorts",
86 "Horizontal number of ports",
91 .AddAttribute("IsDualPolarized",
92 "If true, dual polarized antenna",
93 BooleanValue(false),
97 return tid;
98}
99
100void
102{
103 NS_LOG_FUNCTION(this << n);
104 if (n != m_numColumns)
105 {
106 m_isBfVectorValid = false;
107 }
108 m_numColumns = n;
109}
110
116
117void
119{
120 NS_LOG_FUNCTION(this << n);
121 if (n != m_numRows)
122 {
123 m_isBfVectorValid = false;
124 }
125 m_numRows = n;
126}
127
130{
131 return m_numRows;
132}
133
134void
136{
137 m_alpha = alpha;
138 m_cosAlpha = cos(m_alpha);
139 m_sinAlpha = sin(m_alpha);
140}
141
142void
144{
145 m_beta = beta;
146 m_cosBeta = cos(m_beta);
147 m_sinBeta = sin(m_beta);
148}
149
150void
152{
153 m_polSlant = polSlant;
154 m_cosPolSlant[0] = cos(m_polSlant);
155 m_sinPolSlant[0] = sin(m_polSlant);
156}
157
158void
160{
161 NS_LOG_FUNCTION(this << s);
162 NS_ABORT_MSG_IF(s <= 0, "Trying to set an invalid spacing: " << s);
163
164 if (s != m_disH)
165 {
166 m_isBfVectorValid = false;
167 }
168 m_disH = s;
169}
170
171double
176
177void
179{
180 NS_LOG_FUNCTION(this << s);
181 NS_ABORT_MSG_IF(s <= 0, "Trying to set an invalid spacing: " << s);
182
183 if (s != m_disV)
184 {
185 m_isBfVectorValid = false;
186 }
187 m_disV = s;
188}
189
190double
195
196std::pair<double, double>
198{
199 NS_LOG_FUNCTION(this << a);
200 NS_ASSERT_MSG(polIndex < GetNumPols(), "Polarization index can be 0 or 1.");
201
202 // convert the theta and phi angles from GCS to LCS using eq. 7.1-7 and 7.1-8 in 3GPP TR 38.901
203 // NOTE we assume a fixed slant angle of 0 degrees
204 double inclination = a.GetInclination();
205 double azimuth = a.GetAzimuth();
206 double cosIncl = cos(inclination);
207 double sinIncl = sin(inclination);
208 double cosAzim = cos(azimuth - m_alpha);
209 double sinAzim = sin(azimuth - m_alpha);
210 double thetaPrime = std::acos(m_cosBeta * cosIncl + m_sinBeta * cosAzim * sinIncl);
211 double phiPrime =
212 std::arg(std::complex<double>(m_cosBeta * sinIncl * cosAzim - m_sinBeta * cosIncl,
213 sinAzim * sinIncl));
214 Angles aPrime(phiPrime, thetaPrime);
215 NS_LOG_DEBUG(a << " -> " << aPrime);
216
217 // compute the antenna element field patterns using eq. 7.3-4 and 7.3-5 in 3GPP TR 38.901,
218 // using the configured polarization slant angle (m_polSlant)
219 // NOTE: the slant angle (assumed to be 0) differs from the polarization slant angle
220 // (m_polSlant, given by the attribute), in 3GPP TR 38.901
221 double aPrimeDb = m_antennaElement->GetGainDb(aPrime);
222 double fieldThetaPrime =
223 pow(10, aPrimeDb / 20) * m_cosPolSlant[polIndex]; // convert to linear magnitude
224 double fieldPhiPrime =
225 pow(10, aPrimeDb / 20) * m_sinPolSlant[polIndex]; // convert to linear magnitude
226
227 // compute psi using eq. 7.1-15 in 3GPP TR 38.901, assuming that the slant
228 // angle (gamma) is 0
229 double psi = std::arg(std::complex<double>(m_cosBeta * sinIncl - m_sinBeta * cosIncl * cosAzim,
230 m_sinBeta * sinAzim));
231 NS_LOG_DEBUG("psi " << psi);
232
233 // convert the antenna element field pattern to GCS using eq. 7.1-11
234 // in 3GPP TR 38.901
235 double fieldTheta = cos(psi) * fieldThetaPrime - sin(psi) * fieldPhiPrime;
236 double fieldPhi = sin(psi) * fieldThetaPrime + cos(psi) * fieldPhiPrime;
238 << " " << RadiansToDegrees(a.GetInclination()) << " "
239 << fieldTheta * fieldTheta + fieldPhi * fieldPhi);
240
241 return std::make_pair(fieldPhi, fieldTheta);
242}
243
244Vector
246{
247 NS_LOG_FUNCTION(this << index);
248 uint64_t tmpIndex = index;
249 // for dual polarization, the top half corresponds to one polarization and
250 // lower half corresponds to the other polarization
251 if (m_isDualPolarized && tmpIndex >= m_numRows * m_numColumns)
252 {
253 tmpIndex -= m_numRows * m_numColumns;
254 }
255 // compute the element coordinates in the LCS
256 // assume the left bottom corner is (0,0,0), and the rectangular antenna array is on the y-z
257 // plane.
258 double xPrime = 0;
259 double yPrime = m_disH * (tmpIndex % m_numColumns);
260 double zPrime = m_disV * floor(tmpIndex / m_numColumns);
261
262 // convert the coordinates to the GCS using the rotation matrix 7.1-4 in 3GPP
263 // TR 38.901
264 Vector loc;
265 loc.x = m_cosAlpha * m_cosBeta * xPrime - m_sinAlpha * yPrime + m_cosAlpha * m_sinBeta * zPrime;
266 loc.y = m_sinAlpha * m_cosBeta * xPrime + m_cosAlpha * yPrime + m_sinAlpha * m_sinBeta * zPrime;
267 loc.z = -m_sinBeta * xPrime + m_cosBeta * zPrime;
268 return loc;
269}
270
271uint8_t
273{
274 return m_isDualPolarized ? 2 : 1;
275}
276
277size_t
279{
280 // From 38.901 [M, N, P, Mg, Ng] = [m_numRows, m_numColumns, 2, 1, 1]
281 return GetNumPols() * m_numRows * m_numColumns;
282 // with dual polarization, the number of antenna elements double up
283}
284
285void
287{
288 NS_LOG_FUNCTION(this);
289 NS_ASSERT_MSG(nPorts > 0, "Ports should be greater than 0");
290 NS_ASSERT_MSG(((m_numRows % nPorts) == 0),
291 "The number of vertical ports must divide number of rows");
292 m_numVPorts = nPorts;
293}
294
295void
297{
298 NS_ASSERT_MSG(nPorts > 0, "Ports should be greater than 0");
299 NS_ASSERT_MSG(((m_numColumns % nPorts) == 0),
300 "The number of horizontal ports must divide number of columns");
301 m_numHPorts = nPorts;
302}
303
304uint16_t
309
310uint16_t
315
316uint16_t
321
322size_t
327
328size_t
333
334size_t
336{
337 // Multiply the number of rows and number of columns belonging to one antenna port.
338 // This also holds for dual polarization, where each polarization belongs to a separate port.
340}
341
342uint16_t
343UniformPlanarArray::ArrayIndexFromPortIndex(uint16_t portIndex, uint16_t subElementIndex) const
344{
345 NS_ASSERT_MSG(portIndex < GetNumPorts(), "Port should be less than total Ports");
346 NS_ASSERT(subElementIndex < (GetHElemsPerPort() * GetVElemsPerPort()));
347
348 // In case the array is dual-polarized, change to the index that belongs to the first
349 // polarization
350 auto firstPolPortIdx = portIndex;
351 auto polarizationOffset = 0;
352 auto arraySize = GetNumHorizontalPorts() * GetNumVerticalPorts();
353 if (firstPolPortIdx >= arraySize)
354 {
355 firstPolPortIdx = portIndex - arraySize;
356 polarizationOffset = GetNumColumns() * GetNumRows();
357 }
358 // column-major indexing
359 auto hPortIdx = firstPolPortIdx / GetNumVerticalPorts();
360 auto vPortIdx = firstPolPortIdx % GetNumVerticalPorts();
361 auto hElemIdx = (hPortIdx * GetHElemsPerPort()) + (subElementIndex % GetHElemsPerPort());
362 auto vElemIdx = (vPortIdx * GetVElemsPerPort()) + (subElementIndex / GetHElemsPerPort());
363 return (vElemIdx * GetNumColumns() + hElemIdx + polarizationOffset);
364}
365
366bool
371
372void
374{
375 m_isDualPolarized = isDualPol;
376 if (isDualPol)
377 {
378 m_cosPolSlant[1] = cos(m_polSlant - M_PI / 2);
379 m_sinPolSlant[1] = sin(m_polSlant - M_PI / 2);
380 }
381}
382
383double
385{
386 return m_polSlant;
387}
388
389uint8_t
390UniformPlanarArray::GetElemPol(size_t elemIndex) const
391{
392 NS_ASSERT(elemIndex < GetNumElems());
393 return (elemIndex < GetNumRows() * GetNumColumns()) ? 0 : 1;
394}
395
396} /* namespace ns3 */
Class holding the azimuth and inclination angles of spherical coordinates.
Definition angles.h:107
double GetInclination() const
Getter for inclination angle.
Definition angles.cc:236
double GetAzimuth() const
Getter for azimuth angle.
Definition angles.cc:230
This class can be used to hold variables of floating point type such as 'double' or 'float'.
Definition double.h:31
Class implementing the phased array model virtual base class.
Ptr< AntennaModel > m_antennaElement
the model of the antenna element in use
bool m_isBfVectorValid
ensures the validity of the beamforming vector
a unique identifier for an interface.
Definition type-id.h:48
TypeId SetParent(TypeId tid)
Set the parent TypeId.
Definition type-id.cc:1001
Hold an unsigned integer type.
Definition uinteger.h:34
double m_disV
antenna spacing in the vertical direction in multiples of wave length
double m_sinAlpha
the sine of alpha
void SetPolSlant(double polSlant)
Set the polarization slant angle This method sets the polarization slant angle and computes its cosin...
uint16_t GetNumPorts() const override
Get the total number of antenna ports.
double m_disH
antenna spacing in the horizontal direction in multiples of wave length
void SetBeta(double beta)
Set the downtilt angle This method sets the downtilt angle and computes its cosine and sine.
bool m_isDualPolarized
if true antenna elements are dual-polarized
uint16_t ArrayIndexFromPortIndex(uint16_t portIndex, uint16_t subElementIndex) const override
Maps element within a port to an index of element within the antenna array.
void SetNumRows(uint32_t n) override
Set the number of rows of the phased array This method resets the stored beamforming vector to a Comp...
bool IsDualPol() const override
Check if an antenna array contains dual-polarized elements.
static TypeId GetTypeId()
Get the type ID.
void SetAlpha(double alpha)
Set the bearing angle This method sets the bearing angle and computes its cosine and sine.
void SetNumColumns(uint32_t n) override
Set the number of columns of the phased array This method resets the stored beamforming vector to a C...
double GetAntennaVerticalSpacing() const
Get the vertical spacing for the antenna elements of the phased array.
uint16_t GetNumVerticalPorts() const override
Get the number of vertical antenna ports.
uint16_t m_numVPorts
Number of vertical ports.
std::pair< double, double > GetElementFieldPattern(Angles a, uint8_t polIndex=0) const override
Returns the horizontal and vertical components of the antenna element field pattern at the specified ...
double m_polSlant
the polarization slant angle in radians
uint8_t GetElemPol(size_t elemIndex) const override
Returns the index of polarization to which belongs the antenna element with a specific index.
uint32_t GetNumRows() const override
Get the number of rows of the phased array.
double GetPolSlant() const override
Returns polarization angle of first polarization.
double m_cosBeta
the cosine of Beta
void SetAntennaVerticalSpacing(double s)
Set the vertical spacing for the antenna elements of the phased array This method resets the stored b...
double GetAntennaHorizontalSpacing() const
Get the horizontal spacing for the antenna elements of the phased array.
~UniformPlanarArray() override
Destructor.
uint32_t m_numRows
number of rows
Vector GetElementLocation(uint64_t index) const override
Returns the location of the antenna element with the specified index assuming the left bottom corner ...
uint32_t m_numColumns
number of columns
double m_alpha
the bearing angle in radians
uint16_t GetNumHorizontalPorts() const override
Get the number of horizontal antenna ports.
uint16_t m_numHPorts
Number of horizontal ports.
void SetDualPol(bool isDualPol)
Set the polarization.
size_t GetHElemsPerPort() const override
Get the number of horizontal elements belonging to each port.
void SetNumVerticalPorts(uint16_t nPorts) override
Set the number of vertical antenna ports.
size_t GetVElemsPerPort() const override
Get the number of vertical elements belonging to each port.
uint32_t GetNumColumns() const override
Get the number of columns of the phased array.
void SetNumHorizontalPorts(uint16_t nPorts) override
Set the number of horizontal antenna ports.
std::vector< double > m_cosPolSlant
the cosine of polarization slant angle
double m_sinBeta
the sine of Beta
size_t GetNumElems() const override
Returns the number of total antenna elements.
void SetAntennaHorizontalSpacing(double s)
Set the horizontal spacing for the antenna elements of the phased array This method resets the stored...
double m_beta
the downtilt angle in radians
double m_cosAlpha
the cosine of alpha
size_t GetNumElemsPerPort() const override
Get the total number of elements belonging to each port.
uint8_t GetNumPols() const override
Returns the number of polarizations, 2 in the case that the antenna is dual-polarized,...
std::vector< double > m_sinPolSlant
the sine polarization slant angle
#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
#define NS_ASSERT_MSG(condition, message)
At runtime, in debugging builds, if this condition is not true, the program prints the message to out...
Definition assert.h:75
#define NS_ABORT_MSG_IF(cond, msg)
Abnormal program termination if a condition is true, with a message.
Definition abort.h:97
#define NS_LOG_COMPONENT_DEFINE(name)
Define a Log component with a specific name.
Definition log.h:191
#define NS_LOG_DEBUG(msg)
Use NS_LOG to output a message of level LOG_DEBUG.
Definition log.h:257
#define NS_LOG_FUNCTION(parameters)
If log level LOG_FUNCTION is enabled, this macro will output all input parameters separated by ",...
#define NS_OBJECT_ENSURE_REGISTERED(type)
Register an Object subclass with the TypeId system.
Definition object-base.h:35
Every class exported by the ns3 library is enclosed in the ns3 namespace.
Ptr< const AttributeChecker > MakeBooleanChecker()
Definition boolean.cc:113
Ptr< const AttributeChecker > MakeUintegerChecker()
Definition uinteger.h:85
Ptr< const AttributeAccessor > MakeUintegerAccessor(T1 a1)
Definition uinteger.h:35
Ptr< const AttributeChecker > MakeDoubleChecker()
Definition double.h:82
Ptr< const AttributeAccessor > MakeBooleanAccessor(T1 a1)
Definition boolean.h:70
Ptr< const AttributeAccessor > MakeDoubleAccessor(T1 a1)
Definition double.h:32
double RadiansToDegrees(double radians)
converts radians to degrees
Definition angles.cc:34