Mercurial Mercurial > ns-3.24 / changeset
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | raw | zip | gz | bz2 | help
Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[Doxygen] Organize Core/Random Variables
authorPeter D. Barnes, Jr. <barnes26@llnl.gov>
Wed, 24 Jul 2013 17:05:36 -0700
changeset 9970 a613974fffeb
parent 9969 e813ecb3613d
child 9971 d31b6210afc8
[Doxygen] Organize Core/Random Variables
src/core/examples/command-line-example.cc file | annotate | diff | comparison | revisions
src/core/model/random-variable-stream.h file | annotate | diff | comparison | revisions
src/core/model/random-variable.cc file | annotate | diff | comparison | revisions
src/core/model/random-variable.h file | annotate | diff | comparison | revisions
src/core/model/rng-stream.h file | annotate | diff | comparison | revisions 
--- a/src/core/examples/command-line-example.cc	Wed Jul 24 17:03:28 2013 -0700
+++ b/src/core/examples/command-line-example.cc	Wed Jul 24 17:05:36 2013 -0700
@@ -47,13 +47,13 @@
   cmd.Usage ("CommandLine example program.\n"
              "\n"
              "This little program demonstrates how to use CommandLine.");
-  cmd.AddValue ("val1", "an int argument",       val1);
-  cmd.AddValue ("val2", "a bool argument",       val2);
-  cmd.AddValue ("val3", "a string argument",     val3);
+  cmd.AddValue ("val1", "an int argument",          val1);
+  cmd.AddValue ("val2", "a bool argument",          val2);
+  cmd.AddValue ("val3", "a string argument",        val3);
   cmd.AddValue ("val4", "a string via callback", MakeCallback (SetVal4));
   cmd.Parse (argc, argv);
 
-  std::cout << "val1:\t"   << val1 << std::endl;
+  std::cout << "val1:\t" << val1 << std::endl;
   std::cout << "val2:\t"   << std::boolalpha << val2
             << std::noboolalpha << std::endl;
   std::cout << "val3:\t\"" << val3 << "\"" << std::endl;
--- a/src/core/model/random-variable-stream.h	Wed Jul 24 17:03:28 2013 -0700
+++ b/src/core/model/random-variable-stream.h	Wed Jul 24 17:05:36 2013 -0700
@@ -33,6 +33,36 @@
 
 namespace ns3 {
 
+/**
+ * \ingroup core
+ * \defgroup randomvariable Random Variables
+ *
+ * \brief ns-3 random numbers are provided via instances of
+ * ns3::RandomVariableStream.
+ *
+ * - By default, ns-3 simulations use a fixed seed; if there is any
+ *   randomness in the simulation, each run of the program will yield
+ *   identical results unless the seed and/or run number is changed.
+ * - In ns-3.3 and earlier, ns-3 simulations used a random seed by default;
+ *   this marks a change in policy starting with ns-3.4.
+ * - In ns-3.14 and earlier, ns-3 simulations used a different wrapper
+ *   class called ns3::RandomVariable.  This implementation is documented
+ *   above under Legacy Random Variables. As of ns-3.15, this class has 
+ *   been replaced by ns3::RandomVariableStream; the underlying 
+ *   pseudo-random number generator has not changed.
+ * - To obtain randomness across multiple simulation runs, you must
+ *   either set the seed differently or set the run number differently.
+ *   To set a seed, call ns3::RngSeedManager::SetSeed() at the beginning
+ *   of the program; to set a run number with the same seed, call 
+ *   ns3::RngSeedManager::SetRun() at the beginning of the program.
+ * - Each RandomVariableStream used in ns-3 has a virtual random number 
+ *   generator associated with it; all random variables use either 
+ *   a fixed or random seed based on the use of the global seed. 
+ * - If you intend to perform multiple runs of the same scenario, 
+ *   with different random numbers, please be sure to read the manual 
+ *   section on how to perform independent replications.
+ */
+  
 class RngStream;
 
 /**
@@ -1982,6 +2012,10 @@
 
   /// The upper bound on values that can be returned by this RNG stream.
   double m_max;
+
+  /// It's easier to work with the mode internally instead of the
+  /// mean.  They are related by the simple: mean = (min+max+mode)/3.
+  double m_mode;
 };
 
 /**
--- a/src/core/model/random-variable.cc	Wed Jul 24 17:03:28 2013 -0700
+++ b/src/core/model/random-variable.cc	Wed Jul 24 17:05:36 2013 -0700
@@ -46,6 +46,7 @@
 
 NS_LOG_COMPONENT_DEFINE ("RandomVariable");
 
+/** \ingroup legacyrandom */
 class RandomVariableBase
 {
 public:
@@ -163,6 +164,7 @@
 // -----------------------------------------------------------------------------
 // UniformVariableImpl
 
+/** \ingroup legacyrandom */
 class UniformVariableImpl : public RandomVariableBase
 {
 public:
@@ -291,6 +293,7 @@
 // -----------------------------------------------------------------------------
 // ConstantVariableImpl methods
 
+/** \ingroup legacyrandom */
 class ConstantVariableImpl : public RandomVariableBase
 {
 
@@ -391,6 +394,7 @@
 // SequentialVariableImpl methods
 
 
+/** \ingroup legacyrandom */
 class SequentialVariableImpl : public RandomVariableBase
 {
 
@@ -513,6 +517,7 @@
 // -----------------------------------------------------------------------------
 // ExponentialVariableImpl methods
 
+/** \ingroup legacyrandom */
 class ExponentialVariableImpl : public RandomVariableBase
 {
 public:
@@ -624,6 +629,7 @@
 // -----------------------------------------------------------------------------
 // -----------------------------------------------------------------------------
 // ParetoVariableImpl methods
+/** \ingroup legacyrandom */
 class ParetoVariableImpl : public RandomVariableBase
 {
 public:
@@ -813,6 +819,7 @@
 // -----------------------------------------------------------------------------
 // WeibullVariableImpl methods
 
+/** \ingroup legacyrandom */
 class WeibullVariableImpl : public RandomVariableBase
 {
 public:
@@ -948,6 +955,7 @@
 // -----------------------------------------------------------------------------
 // NormalVariableImpl methods
 
+/** \ingroup legacyrandom */
 class NormalVariableImpl : public RandomVariableBase   // Normally Distributed random var
 
 {
@@ -1103,6 +1111,7 @@
 
 // -----------------------------------------------------------------------------
 // -----------------------------------------------------------------------------
+/** \ingroup legacyrandom */
 class EmpiricalVariableImpl : public RandomVariableBase
 {
 public:
@@ -1294,6 +1303,7 @@
 // -----------------------------------------------------------------------------
 // -----------------------------------------------------------------------------
 // IntegerValue EmpiricalVariableImpl methods
+/** \ingroup legacyrandom */
 class IntEmpiricalVariableImpl : public EmpiricalVariableImpl
 {
 public:
@@ -1342,6 +1352,7 @@
 // -----------------------------------------------------------------------------
 // -----------------------------------------------------------------------------
 // DeterministicVariableImpl
+/** \ingroup legacyrandom */
 class DeterministicVariableImpl : public RandomVariableBase
 {
 
@@ -1409,6 +1420,7 @@
 // -----------------------------------------------------------------------------
 // -----------------------------------------------------------------------------
 // LogNormalVariableImpl
+/** \ingroup legacyrandom */
 class LogNormalVariableImpl : public RandomVariableBase
 {
 public:
@@ -1504,6 +1516,7 @@
 // -----------------------------------------------------------------------------
 // -----------------------------------------------------------------------------
 // GammaVariableImpl
+/** \ingroup legacyrandom */
 class GammaVariableImpl : public RandomVariableBase
 {
 public:
@@ -1637,6 +1650,7 @@
 // -----------------------------------------------------------------------------
 // ErlangVariableImpl
 
+/** \ingroup legacyrandom */
 class ErlangVariableImpl : public RandomVariableBase
 {
 public:
@@ -1741,6 +1755,7 @@
 // -----------------------------------------------------------------------------
 // -----------------------------------------------------------------------------
 // TriangularVariableImpl methods
+/** \ingroup legacyrandom */
 class TriangularVariableImpl : public RandomVariableBase
 {
 public:
@@ -1834,6 +1849,7 @@
 // -----------------------------------------------------------------------------
 // -----------------------------------------------------------------------------
 // ZipfVariableImpl
+/** \ingroup legacyrandom */
 class ZipfVariableImpl : public RandomVariableBase
 {
 public:
@@ -1926,6 +1942,7 @@
 // -----------------------------------------------------------------------------
 // -----------------------------------------------------------------------------
 // ZetaVariableImpl
+/** \ingroup legacyrandom */
 class ZetaVariableImpl : public RandomVariableBase
 {
 public:
--- a/src/core/model/random-variable.h	Wed Jul 24 17:03:28 2013 -0700
+++ b/src/core/model/random-variable.h	Wed Jul 24 17:05:36 2013 -0700
@@ -32,18 +32,20 @@
 #include "rng-seed-manager.h"
 
 /**
- * \ingroup core
- * \defgroup randomvariable Random Variable Distributions
- *
+ * \ingroup randomvariable
+ * \defgroup legacyrandom Legacy Random Variables
  */
 
 namespace ns3 {
 
+/**
+ * \ingroup legacyrandom
+ */
 class RandomVariableBase;
 
 /**
  * \brief The basic RNG for NS-3.
- * \ingroup randomvariable
+ * \ingroup legacyrandom
  *
  * Note: The underlying random number generation method used
  * by NS-3 is the RngStream code by Pierre L'Ecuyer at
@@ -87,7 +89,7 @@
 
 /**
  * \brief The uniform distribution RNG for NS-3.
- * \ingroup randomvariable
+ * \ingroup legacyrandom
  *
  * This class supports the creation of objects that return random numbers
  * from a fixed uniform distribution.  It also supports the generation of
@@ -146,7 +148,7 @@
 
 /**
  * \brief A random variable that returns a constant
- * \ingroup randomvariable
+ * \ingroup legacyrandom
  *
  * Class ConstantVariable defines a random number generator that
  * returns the same value every sample.
@@ -177,7 +179,7 @@
 
 /**
  * \brief Return a sequential list of values
- * \ingroup randomvariable
+ * \ingroup legacyrandom
  *
  * Class SequentialVariable defines a random number generator that
  * returns a sequential sequence.  The sequence monotonically
@@ -216,7 +218,7 @@
 
 /**
  * \brief Exponentially Distributed random var
- * \ingroup randomvariable
+ * \ingroup legacyrandom
  *
  * This class supports the creation of objects that return random numbers
  * from a fixed exponential distribution.  It also supports the generation of
@@ -269,7 +271,7 @@
 
 /**
  * \brief ParetoVariable distributed random var
- * \ingroup randomvariable
+ * \ingroup legacyrandom
  *
  * This class supports the creation of objects that return random numbers
  * from a fixed pareto distribution.  It also supports the generation of
@@ -353,7 +355,7 @@
 
 /**
  * \brief WeibullVariable distributed random var
- * \ingroup randomvariable
+ * \ingroup legacyrandom
  *
  * This class supports the creation of objects that return random numbers
  * from a fixed weibull distribution.  It also supports the generation of
@@ -408,7 +410,7 @@
 /**
  * \brief Class NormalVariable defines a random variable with a
  * normal (Gaussian) distribution.
- * \ingroup randomvariable
+ * \ingroup legacyrandom
  *
  * This class supports the creation of objects that return random numbers
  * from a fixed normal distribution.  It also supports the generation of
@@ -447,7 +449,7 @@
 
 /**
  * \brief EmpiricalVariable distribution random var
- * \ingroup randomvariable
+ * \ingroup legacyrandom
  *
  * Defines a random variable  that has a specified, empirical
  * distribution.  The distribution is specified by a
@@ -480,7 +482,7 @@
 
 /**
  * \brief Integer-based empirical distribution
- * \ingroup randomvariable
+ * \ingroup legacyrandom
  *
  * Defines an empirical distribution where all values are integers.
  * Indentical to EmpiricalVariable, except that the inverse transform
@@ -495,7 +497,7 @@
 
 /**
  * \brief a non-random variable
- * \ingroup randomvariable
+ * \ingroup legacyrandom
  *
  * Defines a random variable  that has a specified, predetermined
  * sequence.  This would be useful when trying to force
@@ -521,7 +523,7 @@
 
 /**
  * \brief Log-normal Distributed random var
- * \ingroup randomvariable
+ * \ingroup legacyrandom
  *
  * LogNormalVariable defines a random variable with log-normal
  * distribution.  If one takes the natural logarithm of random
@@ -553,7 +555,7 @@
 
 /**
  * \brief Gamma Distributed Random Variable
- * \ingroup randomvariable
+ * \ingroup legacyrandom
  *
  * GammaVariable defines a random variable with gamma distribution.
  *
@@ -602,7 +604,7 @@
 
 /**
  * \brief Erlang Distributed Random Variable
- * \ingroup randomvariable
+ * \ingroup legacyrandom
  *
  * ErlangVariable defines a random variable with Erlang distribution.
  *
@@ -655,7 +657,7 @@
 
 /**
  * \brief Zipf Distributed Random Variable
- * \ingroup randomvariable
+ * \ingroup legacyrandom
  *
  * ZipfVariable defines a discrete random variable with Zipf distribution.
  *
@@ -685,7 +687,7 @@
 
 /**
  * \brief Zeta Distributed Distributed Random Variable
- * \ingroup randomvariable
+ * \ingroup legacyrandom
  *
  * ZetaVariable defines a discrete random variable with Zeta distribution.
  *
@@ -711,7 +713,7 @@
 
 /**
  * \brief Triangularly Distributed random var
- * \ingroup randomvariable
+ * \ingroup legacyrandom
  *
  * This distribution is a triangular distribution.  The probability density
  * is in the shape of a triangle.
--- a/src/core/model/rng-stream.h	Wed Jul 24 17:03:28 2013 -0700
+++ b/src/core/model/rng-stream.h	Wed Jul 24 17:05:36 2013 -0700
@@ -25,7 +25,6 @@
 namespace ns3 {
 
 /**
- * \ingroup core
  * \ingroup randomvariable 
  *
  * \brief Combined Multiple-Recursive Generator MRG32k3a
ns-3.24