From 655455bf04bc9c2364476e824f66bdae2d93bb55 Mon Sep 17 00:00:00 2001
From: Tom Henderson <tomh@tomh.org>
Date: Fri, 29 Mar 2024 18:20:26 -0700
Subject: [PATCH] propagation: Clarify units and range on Friis SystemLoss
 attribute

---
 src/propagation/model/propagation-loss-model.cc | 12 ++++++++----
 src/propagation/model/propagation-loss-model.h  | 16 ++++++++++------
 2 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/src/propagation/model/propagation-loss-model.cc b/src/propagation/model/propagation-loss-model.cc
index 05aab96ea..6d1ecb5df 100644
--- a/src/propagation/model/propagation-loss-model.cc
+++ b/src/propagation/model/propagation-loss-model.cc
@@ -161,9 +161,10 @@ FriisPropagationLossModel::GetTypeId()
                                    &FriisPropagationLossModel::GetFrequency),
                 MakeDoubleChecker<double>())
             .AddAttribute("SystemLoss",
-                          "The system loss",
+                          "The system loss (linear factor >= 1, not in dB)",
                           DoubleValue(1.0),
-                          MakeDoubleAccessor(&FriisPropagationLossModel::m_systemLoss),
+                          MakeDoubleAccessor(&FriisPropagationLossModel::SetSystemLoss,
+                                             &FriisPropagationLossModel::GetSystemLoss),
                           MakeDoubleChecker<double>())
             .AddAttribute("MinLoss",
                           "The minimum value (dB) of the total loss, used at short ranges.",
@@ -181,6 +182,7 @@ FriisPropagationLossModel::FriisPropagationLossModel()
 void
 FriisPropagationLossModel::SetSystemLoss(double systemLoss)
 {
+    NS_ABORT_MSG_UNLESS(systemLoss >= 1, "System loss less than 1 corresponds to gain");
     m_systemLoss = systemLoss;
 }
 
@@ -308,9 +310,10 @@ TwoRayGroundPropagationLossModel::GetTypeId()
                                    &TwoRayGroundPropagationLossModel::GetFrequency),
                 MakeDoubleChecker<double>())
             .AddAttribute("SystemLoss",
-                          "The system loss",
+                          "The system loss (linear factor >= 1, not in dB)",
                           DoubleValue(1.0),
-                          MakeDoubleAccessor(&TwoRayGroundPropagationLossModel::m_systemLoss),
+                          MakeDoubleAccessor(&TwoRayGroundPropagationLossModel::SetSystemLoss,
+                                             &TwoRayGroundPropagationLossModel::GetSystemLoss),
                           MakeDoubleChecker<double>())
             .AddAttribute(
                 "MinDistance",
@@ -334,6 +337,7 @@ TwoRayGroundPropagationLossModel::TwoRayGroundPropagationLossModel()
 void
 TwoRayGroundPropagationLossModel::SetSystemLoss(double systemLoss)
 {
+    NS_ABORT_MSG_UNLESS(systemLoss >= 1, "System loss less than 1 corresponds to gain");
     m_systemLoss = systemLoss;
 }
 
diff --git a/src/propagation/model/propagation-loss-model.h b/src/propagation/model/propagation-loss-model.h
index b445a896a..4ae454042 100644
--- a/src/propagation/model/propagation-loss-model.h
+++ b/src/propagation/model/propagation-loss-model.h
@@ -271,9 +271,11 @@ class FriisPropagationLossModel : public PropagationLossModel
      */
     void SetFrequency(double frequency);
     /**
-     * \param systemLoss (dimension-less)
+     * \param systemLoss (linear factor, dimension-less)
      *
      * Set the system loss used by the Friis propagation model.
+     * Value should be greater than or equal to 1; the default of 1
+     * corresponds to no system loss.
      */
     void SetSystemLoss(double systemLoss);
 
@@ -295,7 +297,7 @@ class FriisPropagationLossModel : public PropagationLossModel
      */
     double GetFrequency() const;
     /**
-     * \returns the current system loss (dimension-less)
+     * \returns the current system loss (linear factor, dimension-less)
      */
     double GetSystemLoss() const;
 
@@ -321,7 +323,7 @@ class FriisPropagationLossModel : public PropagationLossModel
 
     double m_lambda;     //!< the carrier wavelength
     double m_frequency;  //!< the carrier frequency
-    double m_systemLoss; //!< the system loss
+    double m_systemLoss; //!< the system loss (linear factor)
     double m_minLoss;    //!< the minimum loss
 };
 
@@ -376,9 +378,11 @@ class TwoRayGroundPropagationLossModel : public PropagationLossModel
     void SetFrequency(double frequency);
 
     /**
-     * \param systemLoss (dimension-less)
+     * \param systemLoss (linear factor, dimension-less)
      *
      * Set the system loss used by the TwoRayGround propagation model.
+     * Value should be greater than or equal to 1; the default of 1
+     * corresponds to no system loss.
      */
     void SetSystemLoss(double systemLoss);
     /**
@@ -399,7 +403,7 @@ class TwoRayGroundPropagationLossModel : public PropagationLossModel
     double GetFrequency() const;
 
     /**
-     * \returns the current system loss (dimension-less)
+     * \returns the current system loss (linear factor, dimension-less)
      */
     double GetSystemLoss() const;
     /**
@@ -431,7 +435,7 @@ class TwoRayGroundPropagationLossModel : public PropagationLossModel
 
     double m_lambda;       //!< the carrier wavelength
     double m_frequency;    //!< the carrier frequency
-    double m_systemLoss;   //!< the system loss
+    double m_systemLoss;   //!< the system loss (linear factor)
     double m_minDistance;  //!< minimum distance for the model
     double m_heightAboveZ; //!< antenna height above the node's Z coordinate
 };