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(
64 "BearingAngle",
65 "The bearing angle in radians",
66 DoubleValue(0.0),
68 MakeDoubleChecker<double>(-M_PI, M_PI))
69 .AddAttribute(
70 "DowntiltAngle",
71 "The downtilt angle in radians",
72 DoubleValue(0.0),
74 MakeDoubleChecker<double>(-M_PI, M_PI))
75 .AddAttribute("PolSlantAngle",
76 "The polarization slant angle in radians",
77 DoubleValue(0.0),
80 MakeDoubleChecker<double>(-M_PI, M_PI))
81 .AddAttribute("NumVerticalPorts",
82 "Vertical number of ports",
87 .AddAttribute("NumHorizontalPorts",
88 "Horizontal number of ports",
93 .AddAttribute("IsDualPolarized",
94 "If true, dual polarized antenna",
95 BooleanValue(false),
99 return tid;
100}
101
102void
104{
105 NS_LOG_FUNCTION(this << n);
106 if (n != m_numColumns)
107 {
108 m_isBfVectorValid = false;
110 }
111 m_numColumns = n;
112}
113
119
120void
122{
123 NS_LOG_FUNCTION(this << n);
124 if (n != m_numRows)
125 {
126 m_isBfVectorValid = false;
128 }
129 m_numRows = n;
130}
131
134{
135 return m_numRows;
136}
137
138void
140{
141 m_alpha = alpha;
142 m_cosAlpha = cos(m_alpha);
143 m_sinAlpha = sin(m_alpha);
145}
146
147void
149{
150 m_beta = beta;
151 m_cosBeta = cos(m_beta);
152 m_sinBeta = sin(m_beta);
154}
155
156void
158{
159 m_polSlant = polSlant;
160 m_cosPolSlant[0] = cos(m_polSlant);
161 m_sinPolSlant[0] = sin(m_polSlant);
163}
164
165void
167{
168 NS_LOG_FUNCTION(this << s);
169 NS_ABORT_MSG_IF(s <= 0, "Trying to set an invalid spacing: " << s);
170
171 if (s != m_disH)
172 {
173 m_isBfVectorValid = false;
175 }
176 m_disH = s;
177}
178
179double
184
185void
187{
188 NS_LOG_FUNCTION(this << s);
189 NS_ABORT_MSG_IF(s <= 0, "Trying to set an invalid spacing: " << s);
190
191 if (s != m_disV)
192 {
193 m_isBfVectorValid = false;
195 }
196 m_disV = s;
197}
198
199double
204
205std::pair<double, double>
207{
208 NS_LOG_FUNCTION(this << a);
209 NS_ASSERT_MSG(polIndex < GetNumPols(), "Polarization index can be 0 or 1.");
210
211 // convert the theta and phi angles from GCS to LCS using eq. 7.1-7 and 7.1-8 in 3GPP TR 38.901
212 // NOTE we assume a fixed slant angle of 0 degrees
213 double inclination = a.GetInclination();
214 double azimuth = a.GetAzimuth();
215 double cosIncl = cos(inclination);
216 double sinIncl = sin(inclination);
217 double cosAzim = cos(azimuth - m_alpha);
218 double sinAzim = sin(azimuth - m_alpha);
219 double thetaPrime = std::acos(m_cosBeta * cosIncl + m_sinBeta * cosAzim * sinIncl);
220 double phiPrime =
221 std::arg(std::complex<double>(m_cosBeta * sinIncl * cosAzim - m_sinBeta * cosIncl,
222 sinAzim * sinIncl));
223 Angles aPrime(phiPrime, thetaPrime);
224 NS_LOG_DEBUG(a << " -> " << aPrime);
225
226 // compute the antenna element field patterns using eq. 7.3-4 and 7.3-5 in 3GPP TR 38.901,
227 // using the configured polarization slant angle (m_polSlant)
228 // NOTE: the slant angle (assumed to be 0) differs from the polarization slant angle
229 // (m_polSlant, given by the attribute), in 3GPP TR 38.901
230 double aPrimeDb = m_antennaElement->GetGainDb(aPrime);
231 double fieldThetaPrime =
232 pow(10, aPrimeDb / 20) * m_cosPolSlant[polIndex]; // convert to linear magnitude
233 double fieldPhiPrime =
234 pow(10, aPrimeDb / 20) * m_sinPolSlant[polIndex]; // convert to linear magnitude
235
236 // compute psi using eq. 7.1-15 in 3GPP TR 38.901, assuming that the slant
237 // angle (gamma) is 0
238 double psi = std::arg(std::complex<double>(m_cosBeta * sinIncl - m_sinBeta * cosIncl * cosAzim,
239 m_sinBeta * sinAzim));
240 NS_LOG_DEBUG("psi " << psi);
241
242 // convert the antenna element field pattern to GCS using eq. 7.1-11
243 // in 3GPP TR 38.901
244 double fieldTheta = cos(psi) * fieldThetaPrime - sin(psi) * fieldPhiPrime;
245 double fieldPhi = sin(psi) * fieldThetaPrime + cos(psi) * fieldPhiPrime;
247 << " " << RadiansToDegrees(a.GetInclination()) << " "
248 << fieldTheta * fieldTheta + fieldPhi * fieldPhi);
249
250 return std::make_pair(fieldPhi, fieldTheta);
251}
252
253Vector
255{
256 NS_LOG_FUNCTION(this << index);
257 uint64_t tmpIndex = index;
258 // for dual polarization, the top half corresponds to one polarization and
259 // lower half corresponds to the other polarization
260 if (m_isDualPolarized && tmpIndex >= m_numRows * m_numColumns)
261 {
262 tmpIndex -= m_numRows * m_numColumns;
263 }
264 // compute the element coordinates in the LCS
265 // assume the left bottom corner is (0,0,0), and the rectangular antenna array is on the y-z
266 // plane.
267 double xPrime = 0;
268 double yPrime = m_disH * (tmpIndex % m_numColumns);
269 double zPrime = m_disV * floor(tmpIndex / m_numColumns);
270
271 // convert the coordinates to the GCS using the rotation matrix 7.1-4 in 3GPP
272 // TR 38.901
273 Vector loc;
274 loc.x = m_cosAlpha * m_cosBeta * xPrime - m_sinAlpha * yPrime + m_cosAlpha * m_sinBeta * zPrime;
275 loc.y = m_sinAlpha * m_cosBeta * xPrime + m_cosAlpha * yPrime + m_sinAlpha * m_sinBeta * zPrime;
276 loc.z = -m_sinBeta * xPrime + m_cosBeta * zPrime;
277 return loc;
278}
279
280uint8_t
282{
283 return m_isDualPolarized ? 2 : 1;
284}
285
286size_t
288{
289 // From 38.901 [M, N, P, Mg, Ng] = [m_numRows, m_numColumns, 2, 1, 1]
290 return GetNumPols() * m_numRows * m_numColumns;
291 // with dual polarization, the number of antenna elements double up
292}
293
294void
296{
297 NS_LOG_FUNCTION(this);
298 NS_ASSERT_MSG(nPorts > 0, "Ports should be greater than 0");
299 NS_ASSERT_MSG(((m_numRows % nPorts) == 0),
300 "The number of vertical ports must divide number of rows");
301 m_numVPorts = nPorts;
303}
304
305void
307{
308 NS_ASSERT_MSG(nPorts > 0, "Ports should be greater than 0");
309 NS_ASSERT_MSG(((m_numColumns % nPorts) == 0),
310 "The number of horizontal ports must divide number of columns");
311 m_numHPorts = nPorts;
313}
314
315uint16_t
320
321uint16_t
326
327uint16_t
332
333size_t
338
339size_t
344
345size_t
347{
348 // Multiply the number of rows and number of columns belonging to one antenna port.
349 // This also holds for dual polarization, where each polarization belongs to a separate port.
351}
352
353uint16_t
354UniformPlanarArray::ArrayIndexFromPortIndex(uint16_t portIndex, uint16_t subElementIndex) const
355{
356 NS_ASSERT_MSG(portIndex < GetNumPorts(), "Port should be less than total Ports");
357 NS_ASSERT(subElementIndex < (GetHElemsPerPort() * GetVElemsPerPort()));
358
359 // In case the array is dual-polarized, change to the index that belongs to the first
360 // polarization
361 auto firstPolPortIdx = portIndex;
362 auto polarizationOffset = 0;
363 auto arraySize = GetNumHorizontalPorts() * GetNumVerticalPorts();
364 if (firstPolPortIdx >= arraySize)
365 {
366 firstPolPortIdx = portIndex - arraySize;
367 polarizationOffset = GetNumColumns() * GetNumRows();
368 }
369 // column-major indexing
370 auto hPortIdx = firstPolPortIdx / GetNumVerticalPorts();
371 auto vPortIdx = firstPolPortIdx % GetNumVerticalPorts();
372 auto hElemIdx = (hPortIdx * GetHElemsPerPort()) + (subElementIndex % GetHElemsPerPort());
373 auto vElemIdx = (vPortIdx * GetVElemsPerPort()) + (subElementIndex / GetHElemsPerPort());
374 return (vElemIdx * GetNumColumns() + hElemIdx + polarizationOffset);
375}
376
377bool
382
383void
385{
386 m_isDualPolarized = isDualPol;
387 if (isDualPol)
388 {
389 m_cosPolSlant[1] = cos(m_polSlant - M_PI / 2);
390 m_sinPolSlant[1] = sin(m_polSlant - M_PI / 2);
391 }
393}
394
395double
397{
398 return m_alpha;
399}
400
401double
403{
404 return m_beta;
405}
406
407double
409{
410 return m_polSlant;
411}
412
413uint8_t
414UniformPlanarArray::GetElemPol(size_t elemIndex) const
415{
416 NS_ASSERT(elemIndex < GetNumElems());
417 return (elemIndex < GetNumRows() * GetNumColumns()) ? 0 : 1;
418}
419
420} /* 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
void InvalidateChannels() const
After changing the antenna settings, InvalidateChannels() should be called to mark up-to-date channel...
a unique identifier for an interface.
Definition type-id.h:49
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 GetAlpha() const
Returns bearing angle of first polarization.
double GetBeta() const
Returns downtilt angle of first polarization.
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