From 9041f3ed1f39335d6e0eae103fef1ae2b6880757 Mon Sep 17 00:00:00 2001
From: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
Date: Mon, 5 Nov 2007 14:54:40 +0100
Subject: [PATCH] Document the friis propagation model.

---
 src/devices/wifi/propagation-loss-model.cc |  9 +++++++
 src/devices/wifi/propagation-loss-model.h  | 30 +++++++++++++++++++++-
 2 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/src/devices/wifi/propagation-loss-model.cc b/src/devices/wifi/propagation-loss-model.cc
index 635209ba2..8c45a0855 100644
--- a/src/devices/wifi/propagation-loss-model.cc
+++ b/src/devices/wifi/propagation-loss-model.cc
@@ -52,6 +52,10 @@ static NumericDefaultValue<double> g_friisSystemLoss
 ("FriisPropagationLossSystemLoss",
  "The system loss to use by default for every FriisPropagationLossModel",
  1.0);
+static NumericDefaultValue<double> g_friisPropagationLossMinDistance
+("FriisPropagationLossMinDistance",
+ "The distance under which the propagation model refuses to give results (m)",
+ 0.5);
 
 static RandomVariableDefaultValue g_random
 ("RandomPropagationLossDistribution",
@@ -198,6 +202,11 @@ FriisPropagationLossModel::GetRxPower (double txPowerDbm,
    * lambda: wavelength (m)
    */
   double distance = a->GetDistanceFrom (b);
+  if (distance <= g_friisPropagationLossMinDistance.GetValue ())
+    {
+      NS_FATAL_ERROR ("The friis propagation loss model is invalid when d="<<
+                      distance<<"m << "<<g_friisPropagationLossMinDistance.GetValue ()<<"m");
+    }
   double numerator = m_lambda * m_lambda;
   double denominator = 16 * PI * PI * distance * distance * m_systemLoss;
   double pr = log (numerator / denominator) * 10 / log (10);
diff --git a/src/devices/wifi/propagation-loss-model.h b/src/devices/wifi/propagation-loss-model.h
index 55f9fb077..27514afcf 100644
--- a/src/devices/wifi/propagation-loss-model.h
+++ b/src/devices/wifi/propagation-loss-model.h
@@ -82,7 +82,35 @@ private:
 /**
  * \brief a Friis propagation loss model
  *
- * XXX: link to model description.
+ * The Friis propagation loss model was first described in
+ * "A Note on a Simple Transmission Formula", by 
+ * "Harald T. Friis".
+ * 
+ * The original equation was described as:
+ *  \f$ \frac{P_r}{P_t} = \frac{A_r A_t}{d^2\lambda^2} \f$
+ *  with the following equation for the case of an
+ *  isotropic antenna with no heat loss:
+ *  \f$ A_{isotr.} = \frac{\lambda^2}{4\pi} \f$
+ *
+ * The final equation becomes:
+ * \f$ \frac{P_r}{P_t} = \frac{\lambda^2}{(4 \pi d)^2} \f$
+ *
+ * Modern extensions to this original equation are:
+ * \f$ P_r = \frac{P_t G_t G_r \lambda^2}{(4 \pi d)^2 L}\f$
+ *
+ * With:
+ *  - \f$ P_r \f$ : reception power (W)
+ *  - \f$ P_t \f$ : transmission power (W)
+ *  - \f$ G_t \f$ : transmission gain (unit-less)
+ *  - \f$ G_r \f$ : reception gain (unit-less)
+ *  - \f$ \lambda \f$ : wavelength (m)
+ *  - \f$ d \f$ : distance (m)
+ *  - \f$ L \f$ : system loss (unit-less)
+ *
+ * This model is obviously valid only when \f$ d \gg \frac{2 a^2}{\lambda} \f$ 
+ * which means that the model is invalid for small distance values.
+ * The current implementation rejects any distance smaller than 
+ * \valueref{FriisPropagationLossMinDistance}.
  */
 class FriisPropagationLossModel : public PropagationLossModel
 {