1.. include:: replace.txt 2 3 4++++++++++++++++++++ 5Design documentation 6++++++++++++++++++++ 7 8-------- 9Overview 10-------- 11 12The Antenna module provides: 13 14 #. a class (Angles) and utility functions to deal with angles 15 #. a base class (AntennaModel) that provides an interface for the modeling of the radiation pattern of an antenna; 16 #. a set of classes derived from this base class that each models the radiation pattern of different types of antennas; 17 #. a base class (PhasedArrayModel) that provides a flexible interface for modeling a number of Phase Antenna Array (PAA) models 18 #. a class (UniformPlanarArray) derived from this base class, implementing a Uniform Planar Array (UPA) supporting both rectangular and linear lattices 19 20 21------ 22Angles 23------ 24 25The Angles class holds information about an angle in 3D space using spherical coordinates in radian units. 26Specifically, it uses the azimuth-inclination convention, where 27 28* Inclination is the angle between the zenith direction (positive z-axis) and the desired direction. It is included in the range [0, pi] radians. 29* Azimuth is the signed angle measured from the positive x-axis, where a positive direction goes towards the positive y-axis. It is included in the range [-pi, pi) radians. 30 31Multiple constructors are present, supporting the most common ways to encode information on a direction. 32A static boolean variable allows the user to decide whether angles should be printed in radian or degree units. 33 34A number of angle-related utilities are offered, such as radians/degree conversions, for both scalars and vectors, and angle wrapping. 35 36 37------------ 38AntennaModel 39------------ 40 41The AntennaModel uses the coordinate system adopted in [Balanis]_ and 42depicted in Figure :ref:`fig-antenna-coordinate-system`. This system 43is obtained by translating the Cartesian coordinate system used by the 44ns-3 MobilityModel into the new origin :math:`o` which is the location 45of the antenna, and then transforming the coordinates of every generic 46point :math:`p` of the space from Cartesian coordinates 47:math:`(x,y,z)` into spherical coordinates 48:math:`(r, \theta,\phi)`. 49The antenna model neglects the radial component :math:`r`, and 50only considers the angle components :math:`(\theta, \phi)`. An antenna 51radiation pattern is then expressed as a mathematical function 52:math:`g(\theta, \phi) \longrightarrow \mathcal{R}` that returns the 53gain (in dB) for each possible direction of 54transmission/reception. All angles are expressed in radians. 55 56 57.. _fig-antenna-coordinate-system: 58 59.. figure:: figures/antenna-coordinate-system.* 60 :align: center 61 62 Coordinate system of the AntennaModel 63 64--------------------- 65Single antenna models 66--------------------- 67 68In this section we describe the antenna radiation pattern models that 69are included within the antenna module. 70 71 72IsotropicAntennaModel 73+++++++++++++++++++++ 74 75This antenna radiation pattern model provides a unitary gain (0 dB) 76for all direction. 77 78 79 80CosineAntennaModel 81++++++++++++++++++ 82 83This is the cosine model described in [Chunjian]_: the antenna gain is 84determined as: 85 86.. math:: 87 88 g(\phi, \theta) = \cos^{n} \left(\frac{\phi - \phi_{0}}{2} \right) 89 90where :math:`\phi_{0}` is the azimuthal orientation of the antenna 91(i.e., its direction of maximum gain) and the exponential 92 93.. math:: 94 95 n = -\frac{3}{20 \log_{10} \left( \cos \frac{\phi_{3dB}}{4} \right)} 96 97determines the desired 3dB beamwidth :math:`\phi_{3dB}`. Note that 98this radiation pattern is independent of the inclination angle 99:math:`\theta`. 100 101A major difference between the model of [Chunjian]_ and the one 102implemented in the class CosineAntennaModel is that only the element 103factor (i.e., what described by the above formulas) is considered. In 104fact, [Chunjian]_ also considered an additional antenna array 105factor. The reason why the latter is excluded is that we expect that 106the average user would desire to specify a given beamwidth exactly, 107without adding an array factor at a latter stage which would in 108practice alter the effective beamwidth of the resulting radiation 109pattern. 110 111 112 113ParabolicAntennaModel 114+++++++++++++++++++++ 115 116This model is based on the parabolic approximation of the main lobe radiation pattern. It is often used in the context of cellular system to model the radiation pattern of a cell sector, see for instance [R4-092042a]_ and [Calcev]_. The antenna gain in dB is determined as: 117 118.. math:: 119 120 g_{dB}(\phi, \theta) = -\min \left( 12 \left(\frac{\phi - \phi_{0}}{\phi_{3dB}} \right)^2, A_{max} \right) 121 122where :math:`\phi_{0}` is the azimuthal orientation of the antenna 123(i.e., its direction of maximum gain), :math:`\phi_{3dB}` is its 3 dB 124beamwidth, and :math:`A_{max}` is the maximum attenuation in dB of the 125antenna. Note that this radiation pattern is independent of the inclination angle 126:math:`\theta`. 127 128 129 130ThreeGppAntennaModel 131++++++++++++++++++++ 132 133This model implements the antenna element described in [38901]_. 134Parameters are fixed from the technical report, thus no attributes nor setters are provided. 135The model is largely based on the `ParabolicAntennaModel`_. 136 137------------------ 138Phased Array Model 139------------------ 140 141The class PhasedArrayModel has been created with flexibility in mind. 142It abstracts the basic idea of a Phased Antenna Array (PAA) by removing any constraint on the 143position of each element, and instead generalizes the concept of steering and beamforming vectors, 144solely based on the generalized location of the antenna elements. 145For details on Phased Array Antennas see for instance [Mailloux]_. 146 147Derived classes must implement the following functions: 148 149* GetNumberOfElements: returns the number of antenna elements 150* GetElementLocation: returns the location of the antenna element with the specified index, normalized with respect to the wavelength 151* GetElementFieldPattern: returns the horizontal and vertical components of the antenna element field pattern at the specified direction. Same polarization (configurable) for all antenna elements of the array is considered. 152 153The class PhasedArrayModel also assumes that all antenna elements are equal, a typical key assumption which allows to model the PAA field pattern as the sum of the array factor, given by the geometry of the location of the antenna elements, and the element field pattern. 154Any class derived from AntennaModel is a valid antenna element for the PhasedArrayModel, allowing for a great flexibility of the framework. 155 156 157UniformPlanarArray 158++++++++++++++++++ 159 160The class UniformPlanarArray is a generic implementation of Uniform Planar Arrays (UPAs), 161supporting rectangular and linear regular lattices. 162It loosely follows the implementation described in the 3GPP TR 38.901 [38901]_, 163considering only a single a single panel, i.e., :math:`N_{g} = M_{g} = 1`. 164 165By default, the array is orthogonal to the x-axis, pointing towards the positive 166direction, but the orientation can be changed through the attributes "BearingAngle", 167which adjusts the azimuth angle, and "DowntiltAngle", which adjusts the elevation angle. 168The slant angle is instead fixed and assumed to be 0. 169 170The number of antenna elements in the vertical and horizontal directions can be configured 171through the attributes "NumRows" and "NumColumns", while the spacing between the horizontal 172and vertical elements can be configured through the attributes "AntennaHorizontalSpacing" 173and "AntennaVerticalSpacing". 174 175The polarization of each antenna element in the array is determined by the polarization 176slant angle through the attribute "PolSlantAngle", as described in [38901]_ (i.e., :math:`{\zeta}`). 177 178 179.. [Balanis] C.A. Balanis, "Antenna Theory - Analysis and Design", Wiley, 2nd Ed. 180 181.. [Chunjian] Li Chunjian, "Efficient Antenna Patterns for 182 Three-Sector WCDMA Systems", Master of Science Thesis, Chalmers 183 University of Technology, Göteborg, Sweden, 2003 184 185.. [Calcev] George Calcev and Matt Dillon, "Antenna Tilt Control in 186 CDMA Networks", in Proc. of the 2nd Annual International Wireless 187 Internet Conference (WICON), 2006 188 189.. [R4-092042a] 3GPP TSG RAN WG4 (Radio) Meeting #51, R4-092042, Simulation 190 assumptions and parameters for FDD HeNB RF requirements. 191 192.. [38901] 3GPP. 2018. TR 38.901, Study on channel model for frequencies from 0.5 to 100 GHz, V15.0.0. (2018-06). 193 194.. [Mailloux] Robert J. Mailloux, "Phased Array Antenna Handbook", Artech House, 2nd Ed. 195