fixed bug 1421 - Frequency dependent propagation loss models need uniform Frequency / Lambda attribute

CHANGES.html

@@ -88,6 +88,14 @@ us a note on ns-developers mailing list.</p>
 <li>New Tag, PacketSocketTag, to carry the dest address of a packet and the packet type</li>
 <li>New Tag, DeviceNameTag, to carry the ns3 device name from where a packet is coming</li>
 <li>New Error Model, BurstError model, to determine which bursts of packets are errored corresponding to an underlying distribution, burst rate, and burst size</li>
+<li>To make the API more uniform across the various
+  PropagationLossModel classes, the Set/GetLambda methods of the
+  FriisPropagationLossModel and TwoRayGroundPropagationLossModel
+  classes have been changed to Set/GetFrequency, and now a Frequency
+  attribute is exported which replaces the pre-existing Lambda
+  attribute. Any previous user code setting a value for Lambda should
+  be changed to set instead a value of Frequency = C / Lambda, with C
+  = 299792458.0. </li>
 </ul>
 
 <h2>Changes to existing API:</h2>

RELEASE_NOTES

@@ -38,6 +38,7 @@ Bugs fixed
 - bug 1256 - Unnecessary SND.NXT advance, missing ACK for Out of Order segments
 - bug 1318 - Ipv6L3Protocol::LocalDeliver can get stuck in an infinte loop
 - bug 1409 - Add an attribute "SystemId" to configure the ID for MPI
+- bug 1421 - Frequency dependent propagation loss models need uniform Frequency / Lambda attribute
 - bug 1434 - DSR throughput not comparable to other protocols for manet example
 - bug 1502 - Shutdown on tcp socket seems to misbehave
 - bug 1503 - BlockAckManager infine loop

src/propagation/model/propagation-loss-model.cc

@@ -148,10 +148,11 @@ FriisPropagationLossModel::GetTypeId (void)
   static TypeId tid = TypeId ("ns3::FriisPropagationLossModel")
     .SetParent<PropagationLossModel> ()
     .AddConstructor<FriisPropagationLossModel> ()
-    .AddAttribute ("Lambda", 
-                   "The wavelength  (default is 5.15 GHz at 300 000 km/s).",
-                   DoubleValue (300000000.0 / 5.150e9),
-                   MakeDoubleAccessor (&FriisPropagationLossModel::m_lambda),
+    .AddAttribute ("Frequency", 
+                   "The carrier frequency (in Hz) at which propagation occurs  (default is 5.15 GHz).",
+                   DoubleValue (5.150e9),
+                   MakeDoubleAccessor (&FriisPropagationLossModel::SetFrequency,
+                                       &FriisPropagationLossModel::GetFrequency),
                    MakeDoubleChecker<double> ())
     .AddAttribute ("SystemLoss", "The system loss",
                    DoubleValue (1.0),
@@ -190,20 +191,19 @@ FriisPropagationLossModel::GetMinDistance (void) const
 {
   return m_minDistance;
 }
+
 void
-FriisPropagationLossModel::SetLambda (double frequency, double speed)
+FriisPropagationLossModel::SetFrequency (double frequency)
 {
-  m_lambda = speed / frequency;
-}
-void
-FriisPropagationLossModel::SetLambda (double lambda)
-{
-  m_lambda = lambda;
+  m_frequency = frequency;
+  static const double C = 299792458.0; // speed of light in vacuum
+  m_lambda = C / frequency;
 }
+
 double
-FriisPropagationLossModel::GetLambda (void) const
+FriisPropagationLossModel::GetFrequency (void) const
 {
-  return m_lambda;
+  return m_frequency;
 }
 
 double
@@ -285,10 +285,11 @@ TwoRayGroundPropagationLossModel::GetTypeId (void)
   static TypeId tid = TypeId ("ns3::TwoRayGroundPropagationLossModel")
     .SetParent<PropagationLossModel> ()
     .AddConstructor<TwoRayGroundPropagationLossModel> ()
-    .AddAttribute ("Lambda",
-                   "The wavelength  (default is 5.15 GHz at 300 000 km/s).",
-                   DoubleValue (300000000.0 / 5.150e9),
-                   MakeDoubleAccessor (&TwoRayGroundPropagationLossModel::m_lambda),
+    .AddAttribute ("Frequency", 
+                   "The carrier frequency (in Hz) at which propagation occurs  (default is 5.15 GHz).",
+                   DoubleValue (5.150e9),
+                   MakeDoubleAccessor (&TwoRayGroundPropagationLossModel::SetFrequency,
+                                       &TwoRayGroundPropagationLossModel::GetFrequency),
                    MakeDoubleChecker<double> ())
     .AddAttribute ("SystemLoss", "The system loss",
                    DoubleValue (1.0),
@@ -337,20 +338,19 @@ TwoRayGroundPropagationLossModel::SetHeightAboveZ (double heightAboveZ)
 {
   m_heightAboveZ = heightAboveZ;
 }
-void 
-TwoRayGroundPropagationLossModel::SetLambda (double frequency, double speed)
+
+void
+TwoRayGroundPropagationLossModel::SetFrequency (double frequency)
 {
-  m_lambda = speed / frequency;
+  m_frequency = frequency;
+  static const double C = 299792458.0; // speed of light in vacuum
+  m_lambda = C / frequency;
 }
-void 
-TwoRayGroundPropagationLossModel::SetLambda (double lambda)
+
+double
+TwoRayGroundPropagationLossModel::GetFrequency (void) const
 {
-  m_lambda = lambda;
-}
-double 
-TwoRayGroundPropagationLossModel::GetLambda (void) const
-{
-  return m_lambda;
+  return m_frequency;
 }
 
 double 
@@ -415,7 +415,7 @@ TwoRayGroundPropagationLossModel::DoCalcRxPower (double txPowerDbm,
    *
    */
 
-  double dCross = (4 * PI * txAntHeight * rxAntHeight) / GetLambda ();
+  double dCross = (4 * PI * txAntHeight * rxAntHeight) / m_lambda;
   double tmp = 0;
   if (distance <= dCross)
     {

src/propagation/model/propagation-loss-model.h

@@ -171,6 +171,11 @@ private:
  * This model is invalid for small distance values.
  * The current implementation returns the txpower as the rxpower
  * for any distance smaller than MinDistance.
+ * 
+ * In the implementation,  \f$ \lambda \f$ is calculated as 
+ * \f$ \frac{C}{f} \f$, where  \f$ C = 299792458\f$ m/s is the speed of light in
+ * vacuum, and \f$ f \f$ is the frequency in Hz which can be configured by
+ * the user via the Frequency attribute.
  */
 class FriisPropagationLossModel : public PropagationLossModel
 {
@@ -179,19 +184,11 @@ public:
   FriisPropagationLossModel ();
   /**
    * \param frequency (Hz)
-   * \param speed (m/s)
    *
-   * Set the main wavelength used in the Friis model 
+   * Set the carrier frequency used in the Friis model 
    * calculation.
    */
-  void SetLambda (double frequency, double speed);
-  /**
-   * \param lambda (m) the wavelength
-   *
-   * Set the main wavelength used in the Friis model 
-   * calculation.
-   */
-  void SetLambda (double lambda);
+  void SetFrequency (double frequency);
   /**
    * \param systemLoss (dimension-less)
    *
@@ -213,9 +210,9 @@ public:
   double GetMinDistance (void) const;
 
   /**
-   * \returns the current wavelength (m)
+   * \returns the current frequency (Hz)
    */
-  double GetLambda (void) const;
+  double GetFrequency (void) const;
   /**
    * \returns the current system loss (dimension-less)
    */
@@ -233,6 +230,7 @@ private:
 
   static const double PI;
   double m_lambda;
+  double m_frequency;
   double m_systemLoss;
   double m_minDistance;
 };
@@ -259,27 +257,26 @@ private:
  * The crossover distance, below which Friis is used, is calculated as follows:
  *
  * \f$ dCross = \frac{(4 * pi * Ht * Hr)}{lambda} \f$
+ *
+ * In the implementation,  \f$ \lambda \f$ is calculated as 
+ * \f$ \frac{C}{f} \f$, where  \f$ C = 299792458\f$ m/s is the speed of light in
+ * vacuum, and \f$ f \f$ is the frequency in Hz which can be configured by
+ * the user via the Frequency attribute.
  */
 class TwoRayGroundPropagationLossModel : public PropagationLossModel
 {
 public:
   static TypeId GetTypeId (void);
   TwoRayGroundPropagationLossModel ();
+
   /**
    * \param frequency (Hz)
-   * \param speed (m/s)
    *
-   * Set the main wavelength used in the TwoRayGround model 
+   * Set the carrier frequency used in the TwoRayGround model 
    * calculation.
    */
-  void SetLambda (double frequency, double speed);
-  /**
-   * \param lambda (m) the wavelength
-   *
-   * Set the main wavelength used in the TwoRayGround model 
-   * calculation.
-   */
-  void SetLambda (double lambda);
+  void SetFrequency (double frequency);
+
   /**
    * \param systemLoss (dimension-less)
    *
@@ -297,10 +294,12 @@ public:
    * \returns the minimum distance.
    */
   double GetMinDistance (void) const;
+
   /**
-   * \returns the current wavelength (m)
+   * \returns the current frequency (Hz)
    */
-  double GetLambda (void) const;
+  double GetFrequency (void) const;
+
   /**
    * \returns the current system loss (dimension-less)
    */
@@ -324,6 +323,7 @@ private:
 
   static const double PI;
   double m_lambda;
+  double m_frequency;
   double m_systemLoss;
   double m_minDistance;
   double m_heightAboveZ;

src/propagation/test/propagation-loss-model-test-suite.cc

@@ -68,8 +68,9 @@ FriisPropagationLossModelTestCase::DoRun (void)
   // The ns-3 testing manual gives more background on the values selected
   // for this test.  First, set a few defaults. 
 
-  // wavelength at 2.4 GHz is 0.125m
-  Config::SetDefault ("ns3::FriisPropagationLossModel::Lambda", DoubleValue (0.125));
+  // the test vectors have been determined for a wavelength of 0.125 m 
+  // which corresponds to a frequency of 2398339664.0 Hz in the vacuum
+  Config::SetDefault ("ns3::FriisPropagationLossModel::Frequency", DoubleValue (2398339664.0));
   Config::SetDefault ("ns3::FriisPropagationLossModel::SystemLoss", DoubleValue (1.0));
 
   // Select a reference transmit power
@@ -164,8 +165,9 @@ TwoRayGroundPropagationLossModelTestCase::~TwoRayGroundPropagationLossModelTestC
 void
 TwoRayGroundPropagationLossModelTestCase::DoRun (void)
 {
-  // wavelength at 2.4 GHz is 0.125m
-  Config::SetDefault ("ns3::TwoRayGroundPropagationLossModel::Lambda", DoubleValue (0.125));
+  // the test vectors have been determined for a wavelength of 0.125 m 
+  // which corresponds to a frequency of 2398339664.0 Hz in the vacuum
+  Config::SetDefault ("ns3::TwoRayGroundPropagationLossModel::Frequency", DoubleValue (2398339664.0));
   Config::SetDefault ("ns3::TwoRayGroundPropagationLossModel::SystemLoss", DoubleValue (1.0));
 
   // set antenna height to 1.5m above z coordinate