antenna: Extend UniformPlanarArray to have a configurable polarization slant angle

see MR !674

src/antenna/doc/source/antenna-design.rst

@@ -148,7 +148,7 @@ Derived classes must implement the following functions:
 
 * GetNumberOfElements: returns the number of antenna elements
 * GetElementLocation: returns the location of the antenna element with the specified index, normalized with respect to the wavelength
-* GetElementFieldPattern: returns the horizontal and vertical components of the antenna element field pattern at the specified direction. Only vertical polarization is considered.
+* 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.
 
 The 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.
 Any class derived from AntennaModel is a valid antenna element for the PhasedArrayModel, allowing for a great flexibility of the framework.
@@ -172,7 +172,8 @@ through the attributes "NumRows" and "NumColumns", while the spacing between the
 and vertical elements can be configured through the attributes "AntennaHorizontalSpacing"
 and "AntennaVerticalSpacing". 
 
-Note: vertical polarization is assumed for each antenna element, as described in [38901]_ (i.e., :math:`{\zeta = 0}`).
+The polarization of each antenna element in the array is determined by the polarization
+slant angle through the attribute "PolSlantAngle", as described in [38901]_ (i.e., :math:`{\zeta}`).
 
 
 .. [Balanis] C.A. Balanis, "Antenna Theory - Analysis and Design",  Wiley, 2nd Ed.

src/antenna/model/phased-array-model.h

@@ -55,7 +55,7 @@ public:
 
   /**
    * Returns the horizontal and vertical components of the antenna element field
-   * pattern at the specified direction. Only vertical polarization is considered.
+   * pattern at the specified direction. Single polarization is considered.
    * \param a the angle indicating the interested direction
    * \return a pair in which the first element is the horizontal component
    *         of the field pattern and the second element is the vertical

src/antenna/model/uniform-planar-array.cc

@@ -38,7 +38,8 @@ UniformPlanarArray::UniformPlanarArray ()
     m_disV {0.5},
     m_disH {0.5},
     m_alpha {0},
-    m_beta {0}
+    m_beta {0},
+    m_polSlant {0.0}
 {}
 
 UniformPlanarArray::~UniformPlanarArray ()
@@ -85,6 +86,11 @@ UniformPlanarArray::GetTypeId (void)
                    DoubleValue (0.0),
                    MakeDoubleAccessor (&UniformPlanarArray::m_beta),
                    MakeDoubleChecker<double> (-M_PI, M_PI))
+    .AddAttribute ("PolSlantAngle",
+                   "The polarization slant angle in radians",
+                   DoubleValue (0.0),
+                   MakeDoubleAccessor (&UniformPlanarArray::m_polSlant),
+                   MakeDoubleChecker<double> (-M_PI, M_PI))
   ;
   return tid;
 }
@@ -182,12 +188,13 @@ UniformPlanarArray::GetElementFieldPattern (Angles a) const
   Angles aPrime (phiPrime, thetaPrime);
   NS_LOG_DEBUG (a << " -> " << aPrime);
 
-  // compute the antenna element field pattern in the vertical polarization using
-  // eq. 7.3-4 in 3GPP TR 38.901
-  // NOTE we assume vertical polarization, hence the field pattern in the
-  // horizontal polarization is 0
+  // compute the antenna element field patterns using eq. 7.3-4 and 7.3-5 in 3GPP TR 38.901,
+  // using the configured polarization slant angle (m_polSlant)
+  // NOTE: the slant angle (assumed to be 0) differs from the polarization slant angle
+  // (m_polSlant, given by the attribute), in 3GPP TR 38.901
   double aPrimeDb = m_antennaElement->GetGainDb (aPrime);
-  double fieldThetaPrime = pow (10, aPrimeDb / 20); // convert to linear magnitude
+  double fieldThetaPrime = pow (10, aPrimeDb / 20) * cos (m_polSlant); // convert to linear magnitude
+  double fieldPhiPrime = pow (10, aPrimeDb / 20) * sin (m_polSlant); // convert to linear magnitude
 
   // compute psi using eq. 7.1-15 in 3GPP TR 38.901, assuming that the slant
   // angle (gamma) is 0
@@ -196,8 +203,8 @@ UniformPlanarArray::GetElementFieldPattern (Angles a) const
 
   // convert the antenna element field pattern to GCS using eq. 7.1-11
   // in 3GPP TR 38.901
-  double fieldTheta = cos (psi) * fieldThetaPrime;
-  double fieldPhi = sin (psi) * fieldThetaPrime;
+  double fieldTheta = cos (psi) * fieldThetaPrime - sin (psi) * fieldPhiPrime;
+  double fieldPhi = sin (psi) * fieldThetaPrime + cos (psi) * fieldPhiPrime;
   NS_LOG_DEBUG (RadiansToDegrees (a.GetAzimuth ()) << " " << RadiansToDegrees (a.GetInclination ()) << " " << fieldTheta * fieldTheta + fieldPhi * fieldPhi);
 
   return std::make_pair (fieldPhi, fieldTheta);

src/antenna/model/uniform-planar-array.h

@@ -33,7 +33,7 @@ namespace ns3 {
  * \brief Class implementing Uniform Planar Array (UPA) model.
  *
  * \note the current implementation supports the modeling of antenna arrays
- * composed of a single panel and with single (vertical) polarization.
+ * composed of a single panel and with single (configured) polarization.
  */
 class UniformPlanarArray : public PhasedArrayModel
 {
@@ -56,7 +56,7 @@ public:
 
   /**
    * Returns the horizontal and vertical components of the antenna element field
-   * pattern at the specified direction. Only vertical polarization is considered.
+   * pattern at the specified direction. Single polarization is considered.
    * \param a the angle indicating the interested direction
    * \return a pair in which the first element is the horizontal component
    *         of the field pattern and the second element is the vertical
@@ -158,7 +158,7 @@ private:
   double m_disH; //!< antenna spacing in the horizontal direction in multiples of wave length
   double m_alpha; //!< the bearing angle in radians
   double m_beta; //!< the downtilt angle in radians
-
+  double m_polSlant; //!< the polarization slant angle in radians
 };
 
 } /* namespace ns3 */

src/spectrum/model/three-gpp-channel-model.cc

@@ -1551,7 +1551,8 @@ ThreeGppChannelModel::GetNewChannel (Vector locUT, Ptr<const ChannelCondition> c
 
           for (uint8_t nIndex = 0; nIndex < numReducedCluster; nIndex++)
             {
-              //Compute the N-2 weakest cluster, only vertical polarization. (7.5-22)
+              //Compute the N-2 weakest cluster, assuming 0 slant angle and a
+              //polarization slant angle configured in the array (7.5-22)
               if (nIndex != cluster1st && nIndex != cluster2nd)
                 {
                   std::complex<double> rays (0,0);