src/core/random-variable.h
author Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
Sat, 04 Jul 2009 08:15:48 +0200
changeset 4654 2eaebe77d66b
parent 4579 c86681050541
permissions -rw-r--r--
Added tag ns-3.5 for changeset c975274c9707
tomh@346
     1
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
tomh@346
     2
//
tomh@346
     3
// Copyright (c) 2006 Georgia Tech Research Corporation
tomh@346
     4
//
tomh@346
     5
// This program is free software; you can redistribute it and/or modify
tomh@346
     6
// it under the terms of the GNU General Public License version 2 as
tomh@346
     7
// published by the Free Software Foundation;
tomh@346
     8
//
tomh@346
     9
// This program is distributed in the hope that it will be useful,
tomh@346
    10
// but WITHOUT ANY WARRANTY; without even the implied warranty of
tomh@346
    11
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
tomh@346
    12
// GNU General Public License for more details.
tomh@346
    13
//
tomh@346
    14
// You should have received a copy of the GNU General Public License
tomh@346
    15
// along with this program; if not, write to the Free Software
tomh@346
    16
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
tomh@346
    17
//
tomh@346
    18
// Author: Rajib Bhattacharjea<raj.b@gatech.edu>
raj@4218
    19
// Author: Hadi Arbabi<marbabi@cs.odu.edu>
tomh@346
    20
//
tomh@346
    21
raj@4218
    22
#ifndef __random_variable_h
raj@4218
    23
#define __random_variable_h
tomh@346
    24
tomh@346
    25
#include <vector>
tomh@346
    26
#include <algorithm>
Emmanuelle@676
    27
#include <stdint.h>
mathieu@2409
    28
#include <istream>
mathieu@2409
    29
#include <ostream>
mathieu@2438
    30
#include "attribute.h"
mathieu@2451
    31
#include "attribute-helper.h"
tomh@346
    32
mathieu@396
    33
/**
tomh@2217
    34
 * \ingroup core
mathieu@396
    35
 * \defgroup randomvariable Random Variable Distributions
mathieu@396
    36
 *
mathieu@396
    37
 */
mathieu@396
    38
timo@4317
    39
namespace ns3 {
tomh@346
    40
mathieu@2336
    41
class RandomVariableBase;
tomh@346
    42
raj@4218
    43
class SeedManager
raj@4218
    44
{
raj@4218
    45
public:
raj@4218
    46
	  
raj@4224
    47
  /**
raj@4224
    48
   * \brief set the seed
raj@4224
    49
   * it will duplicate the seed value 6 times
raj@4224
    50
   * \code
raj@4224
    51
   * SeedManger::SetSeed(15);
raj@4224
    52
   * UniformVariable x(2,3);     //these will give the same output everytime
raj@4224
    53
   * ExponentialVariable y(120); //as long as the seed stays the same
raj@4224
    54
   * \endcode
raj@4224
    55
   * \param seed
tomh@4247
    56
   *
tomh@4247
    57
   * Note, while the underlying RNG takes six integer values as a seed;
tomh@4247
    58
   * it is sufficient to set these all to the same integer, so we provide
tomh@4247
    59
   * a simpler interface here that just takes one integer.
raj@4224
    60
   */ 
raj@4224
    61
  static void SetSeed (uint32_t seed);
raj@4218
    62
 
raj@4224
    63
  /**
raj@4224
    64
   * \brief Get the seed value
raj@4234
    65
   * \return the seed value
tomh@4247
    66
   *
tomh@4247
    67
   * Note:  returns the first of the six seed values used in the underlying RNG
raj@4224
    68
   */
raj@4234
    69
   static uint32_t GetSeed ();
raj@4218
    70
 
raj@4224
    71
   /**
raj@4218
    72
    * \brief Set the run number of simulation
raj@4218
    73
    *
raj@4218
    74
    * \code
raj@4218
    75
    * SeedManager::SetSeed(12);
raj@4218
    76
    * int N = atol(argv[1]); //read in run number from command line
raj@4218
    77
    * SeedManager::SetRun(N);
raj@4218
    78
    * UniformVariable x(0,10);
raj@4218
    79
    * ExponentialVariable y(2902);
raj@4218
    80
    * \endcode
raj@4218
    81
    * In this example, N could successivly be equal to 1,2,3, etc. and the user
raj@4218
    82
    * would continue to get independent runs out of the single simulation.  For
raj@4218
    83
    * this simple example, the following might work:
raj@4218
    84
    * \code
raj@4218
    85
    * ./simulation 0
raj@4218
    86
    * ...Results for run 0:...
raj@4218
    87
    *
raj@4218
    88
    * ./simulation 1
raj@4218
    89
    * ...Results for run 1:...
raj@4218
    90
    * \endcode
raj@4218
    91
    */
raj@4224
    92
  static void SetRun (uint32_t run);
raj@4224
    93
  /**
raj@4224
    94
   * \returns the current run number
raj@4224
    95
   * @sa SetRun
raj@4224
    96
   */
raj@4224
    97
  static uint32_t GetRun (void);
raj@4224
    98
  
raj@4224
    99
  /**
raj@4224
   100
   * \brief Check if seed value is valid if wanted to be used as seed
raj@4224
   101
   * \return true if valid and false if invalid
raj@4224
   102
   */
raj@4224
   103
  static bool CheckSeed (uint32_t seed);
raj@4218
   104
};
raj@4218
   105
raj@4218
   106
tomh@346
   107
/**
tomh@346
   108
 * \brief The basic RNG for NS-3.
mathieu@396
   109
 * \ingroup randomvariable
tomh@346
   110
 *
tomh@346
   111
 * Note: The underlying random number generation method used
tomh@346
   112
 * by NS-3 is the RngStream code by Pierre L'Ecuyer at
tomh@346
   113
 * the University of Montreal.
tomh@346
   114
 * 
tomh@346
   115
 * NS-3 has a rich set of  random number generators.
raj@2762
   116
 * Class RandomVariable defines the base class functionalty
tomh@346
   117
 * required for all random number generators.  By default, the underlying
mathieu@4640
   118
 * generator is seeded all the time with the same seed value and run number
mathieu@4640
   119
 * coming from the ns3::GlobalValue \ref GlobalValueRngSeed "RngSeed" and \ref GlobalValueRngRun "RngRun".
tomh@346
   120
 */
mathieu@2336
   121
class RandomVariable
mathieu@2336
   122
{ 
tomh@346
   123
public:
tomh@346
   124
  RandomVariable();
mathieu@2336
   125
  RandomVariable(const RandomVariable&o);
mathieu@2336
   126
  RandomVariable &operator = (const RandomVariable &o);
mathieu@2336
   127
  ~RandomVariable();
tomh@346
   128
  
tomh@346
   129
  /**
tomh@346
   130
   * \brief Returns a random double from the underlying distribution
tomh@346
   131
   * \return A floating point random value
tomh@346
   132
   */
mathieu@2336
   133
  double GetValue (void) const;
tomh@346
   134
tomh@346
   135
  /**
tomh@346
   136
   * \brief Returns a random integer integer from the underlying distribution
tomh@346
   137
   * \return  Integer cast of ::GetValue()
tomh@346
   138
   */
mathieu@2439
   139
  uint32_t GetInteger (void) const;
mathieu@2384
   140
tomh@346
   141
private:
mathieu@2409
   142
  friend std::ostream &operator << (std::ostream &os, const RandomVariable &var);
mathieu@2409
   143
  friend std::istream &operator >> (std::istream &os, RandomVariable &var);
mathieu@2409
   144
mathieu@2336
   145
  RandomVariableBase *m_variable;
tomh@346
   146
protected:
mathieu@2336
   147
  RandomVariable (const RandomVariableBase &variable);
mathieu@2384
   148
  RandomVariableBase *Peek (void) const;
tomh@346
   149
};
tomh@346
   150
tomh@346
   151
/**
tomh@346
   152
 * \brief The uniform distribution RNG for NS-3.
mathieu@396
   153
 * \ingroup randomvariable
mathieu@1872
   154
 *
raj@442
   155
 * This class supports the creation of objects that return random numbers
raj@442
   156
 * from a fixed uniform distribution.  It also supports the generation of 
raj@442
   157
 * single random numbers from various uniform distributions.
mathieu@1872
   158
 *
mathieu@1872
   159
 * The low end of the range is always included and the high end
mathieu@1872
   160
 * of the range is always excluded.
raj@442
   161
 * \code
raj@442
   162
 * UniformVariable x(0,10);
mathieu@1872
   163
 * x.GetValue();  //will always return numbers [0,10)
mathieu@1872
   164
 * UniformVariable::GetSingleValue(100,1000); //returns a value [100,1000)
mathieu@592
   165
 * \endcode
tomh@346
   166
 */
mathieu@2336
   167
class UniformVariable : public RandomVariable 
mathieu@2336
   168
{
tomh@346
   169
public:
tomh@346
   170
  /**
tomh@346
   171
   * Creates a uniform random number generator in the
mathieu@1872
   172
   * range [0.0 .. 1.0).
tomh@346
   173
   */
tomh@346
   174
  UniformVariable();
tomh@346
   175
tomh@346
   176
  /**
tomh@346
   177
   * Creates a uniform random number generator with the specified range
tomh@346
   178
   * \param s Low end of the range
tomh@346
   179
   * \param l High end of the range
tomh@346
   180
   */
tomh@346
   181
  UniformVariable(double s, double l);
raj@4218
   182
raj@442
   183
  /**
mathieu@4242
   184
  * \brief call RandomVariable::GetValue
raj@4218
   185
  * \return A floating point random value
mathieu@4242
   186
  *
mathieu@4242
   187
  * Note: we have to re-implement this method here because the method is 
mathieu@4242
   188
  * overloaded below for the two-argument variant and the c++ name resolution
mathieu@4242
   189
  * rules don't work well with overloads split between parent and child 
mathieu@4242
   190
  * classes.
raj@4218
   191
  */
mathieu@4242
   192
  double GetValue (void) const;
raj@4218
   193
  
raj@4218
   194
  /**
raj@4218
   195
  * \brief Returns a random double with the specified range
raj@4218
   196
  * \param s Low end of the range
raj@4218
   197
  * \param l High end of the range
raj@4218
   198
  * \return A floating point random value
raj@4218
   199
  */
raj@4218
   200
  double GetValue(double s, double l);
raj@4218
   201
timo@4256
   202
  /**
timo@4256
   203
   * \brief Returns a random unsigned integer from the interval [s,l] including both ends.
timo@4256
   204
   * \param s Low end of the range
timo@4256
   205
   * \param l High end of the range
timo@4256
   206
   * \return A random unsigned integer value.
timo@4256
   207
   */
timo@4256
   208
  uint32_t GetInteger (uint32_t s, uint32_t l);
tomh@346
   209
};
tomh@346
   210
tomh@346
   211
/**
tomh@346
   212
 * \brief A random variable that returns a constant
mathieu@396
   213
 * \ingroup randomvariable
raj@360
   214
 *
raj@2762
   215
 * Class ConstantVariable defines a random number generator that
tomh@346
   216
 * returns the same value every sample.
tomh@346
   217
 */
tomh@346
   218
class ConstantVariable : public RandomVariable { 
tomh@346
   219
tomh@346
   220
public:
tomh@346
   221
  /**
raj@2762
   222
   * Construct a ConstantVariable RNG that returns zero every sample
tomh@346
   223
   */
tomh@346
   224
  ConstantVariable();
tomh@346
   225
  
tomh@346
   226
  /**
raj@2762
   227
   * Construct a ConstantVariable RNG that returns the specified value
tomh@346
   228
   * every sample.
tomh@346
   229
   * \param c Unchanging value for this RNG.
tomh@346
   230
   */
tomh@346
   231
  ConstantVariable(double c);
tomh@346
   232
tomh@346
   233
  /**
tomh@346
   234
   * \brief Specify a new constant RNG for this generator.
tomh@346
   235
   * \param c New constant value for this RNG.
tomh@346
   236
   */
mathieu@2336
   237
  void SetConstant(double c);
tomh@346
   238
tomh@346
   239
};
tomh@346
   240
tomh@346
   241
/**
tomh@346
   242
 * \brief Return a sequential list of values
mathieu@396
   243
 * \ingroup randomvariable
raj@360
   244
 *
tomh@346
   245
 * Class SequentialVariable defines a random number generator that
tomh@346
   246
 * returns a sequential sequence.  The sequence monotonically
tomh@346
   247
 * increases for a period, then wraps around to the low value 
tomh@346
   248
 * and begins monotonicaly increasing again.
tomh@346
   249
 */
mathieu@2336
   250
class SequentialVariable : public RandomVariable 
mathieu@2336
   251
{
tomh@346
   252
public:
tomh@346
   253
  /**
raj@2762
   254
   * \brief Constructor for the SequentialVariable RNG.
raj@360
   255
   *
tomh@346
   256
   * The four parameters define the sequence.  For example
raj@2762
   257
   * SequentialVariable(0,5,1,2) creates a RNG that has the sequence
tomh@346
   258
   * 0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 0, 0 ...
tomh@346
   259
   * \param f First value of the sequence.
tomh@346
   260
   * \param l One more than the last value of the sequence.
tomh@346
   261
   * \param i Increment between sequence values
tomh@346
   262
   * \param c Number of times each member of the sequence is repeated
tomh@346
   263
   */
tomh@346
   264
  SequentialVariable(double f, double l, double i = 1, uint32_t c = 1);
tomh@346
   265
tomh@346
   266
  /**
raj@2762
   267
   * \brief Constructor for the SequentialVariable RNG.
raj@360
   268
   *
tomh@346
   269
   * Differs from the first only in that the increment parameter is a
tomh@346
   270
   * random variable
tomh@346
   271
   * \param f First value of the sequence.
tomh@346
   272
   * \param l One more than the last value of the sequence.
raj@2762
   273
   * \param i Reference to a RandomVariable for the sequence increment
tomh@346
   274
   * \param c Number of times each member of the sequence is repeated
tomh@346
   275
   */
tomh@346
   276
  SequentialVariable(double f, double l, const RandomVariable& i, uint32_t c = 1);
tomh@346
   277
tomh@346
   278
};
tomh@346
   279
tomh@346
   280
/**
tomh@346
   281
 * \brief Exponentially Distributed random var
mathieu@396
   282
 * \ingroup randomvariable
mathieu@1872
   283
 *
raj@442
   284
 * This class supports the creation of objects that return random numbers
raj@442
   285
 * from a fixed exponential distribution.  It also supports the generation of 
raj@442
   286
 * single random numbers from various exponential distributions.
mathieu@1872
   287
 *
mathieu@1872
   288
 * The probability density function of an exponential variable 
mathieu@1872
   289
 * is defined over the interval [0, +inf) as:
mathieu@1872
   290
 * \f$ \alpha  e^{-\alpha x} \f$
mathieu@1872
   291
 * where \f$ \alpha = \frac{1}{mean} \f$ 
mathieu@1872
   292
 *
mathieu@1872
   293
 * The bounded version is defined over the internal [0,+inf) as:
mathieu@1872
   294
 * \f$ \left\{ \begin{array}{cl} \alpha  e^{-\alpha x} & x < bound \\ bound & x > bound \end{array}\right. \f$
mathieu@1872
   295
 * 
raj@442
   296
 * \code
raj@2762
   297
 * ExponentialVariable x(3.14);
raj@442
   298
 * x.GetValue();  //will always return with mean 3.14
raj@2762
   299
 * ExponentialVariable::GetSingleValue(20.1); //returns with mean 20.1
raj@2762
   300
 * ExponentialVariable::GetSingleValue(108); //returns with mean 108
raj@442
   301
 * \endcode
raj@360
   302
 *
tomh@346
   303
 */
mathieu@2336
   304
class ExponentialVariable : public RandomVariable 
mathieu@2336
   305
{ 
tomh@346
   306
public:
tomh@346
   307
  /**
tomh@346
   308
   * Constructs an exponential random variable  with a mean
tomh@346
   309
   * value of 1.0.
tomh@346
   310
   */
tomh@346
   311
  ExponentialVariable();
tomh@346
   312
tomh@346
   313
  /**
tomh@346
   314
   * \brief Constructs an exponential random variable with a specified mean
tomh@346
   315
   * \param m Mean value for the random variable
tomh@346
   316
   */
tomh@346
   317
  explicit ExponentialVariable(double m);
tomh@346
   318
tomh@346
   319
  /**
tomh@346
   320
   * \brief Constructs an exponential random variable with spefified
tomh@346
   321
   * \brief mean and upper limit.
raj@360
   322
   *
tomh@346
   323
   * Since exponential distributions can theoretically return unbounded values,
tomh@346
   324
   * it is sometimes useful to specify a fixed upper limit.  Note however when
tomh@346
   325
   * the upper limit is specified, the true mean of the distribution is 
tomh@346
   326
   * slightly smaller than the mean value specified.
tomh@346
   327
   * \param m Mean value of the random variable
tomh@346
   328
   * \param b Upper bound on returned values
tomh@346
   329
   */
tomh@346
   330
  ExponentialVariable(double m, double b);
tomh@346
   331
tomh@346
   332
};
tomh@346
   333
tomh@346
   334
/**
raj@2762
   335
 * \brief ParetoVariable distributed random var
mathieu@396
   336
 * \ingroup randomvariable
mathieu@1872
   337
 *
raj@442
   338
 * This class supports the creation of objects that return random numbers
raj@442
   339
 * from a fixed pareto distribution.  It also supports the generation of 
raj@442
   340
 * single random numbers from various pareto distributions.
mathieu@1872
   341
 *
mathieu@1872
   342
 * The probability density function is defined over the range [\f$x_m\f$,+inf) as:
mathieu@1872
   343
 * \f$ k \frac{x_m^k}{x^{k+1}}\f$ where \f$x_m > 0\f$ is called the location 
mathieu@1872
   344
 * parameter and \f$ k > 0\f$ is called the pareto index or shape.
mathieu@1872
   345
 * 
mathieu@1872
   346
 * The parameter \f$ x_m \f$ can be infered from the mean and the parameter \f$ k \f$
mathieu@1872
   347
 * with the equation \f$ x_m = mean \frac{k-1}{k},  k > 1\f$.
mathieu@1872
   348
 *
raj@442
   349
 * \code
raj@2762
   350
 * ParetoVariable x(3.14);
raj@442
   351
 * x.GetValue();  //will always return with mean 3.14
raj@2762
   352
 * ParetoVariable::GetSingleValue(20.1); //returns with mean 20.1
raj@2762
   353
 * ParetoVariable::GetSingleValue(108); //returns with mean 108
raj@442
   354
 * \endcode
tomh@346
   355
 */
mathieu@2336
   356
class ParetoVariable : public RandomVariable
mathieu@2336
   357
{
tomh@346
   358
public:
tomh@346
   359
  /**
tomh@346
   360
   * Constructs a pareto random variable with a mean of 1 and a shape
tomh@346
   361
   * parameter of 1.5
tomh@346
   362
   */
mathieu@2336
   363
  ParetoVariable ();
tomh@346
   364
tomh@346
   365
  /**
tomh@346
   366
   * Constructs a pareto random variable with specified mean and shape
tomh@346
   367
   * parameter of 1.5
tomh@346
   368
   * \param m Mean value of the distribution
tomh@346
   369
   */
tomh@346
   370
  explicit ParetoVariable(double m);
tomh@346
   371
tomh@346
   372
  /**
tomh@346
   373
   * Constructs a pareto random variable with the specified mean value and
tomh@346
   374
   * shape parameter.
tomh@346
   375
   * \param m Mean value of the distribution
tomh@346
   376
   * \param s Shape parameter for the distribution
tomh@346
   377
   */
tomh@346
   378
  ParetoVariable(double m, double s);
tomh@346
   379
tomh@346
   380
  /**
tomh@346
   381
   * \brief Constructs a pareto random variable with the specified mean
tomh@346
   382
   * \brief value, shape (alpha), and upper bound.
raj@442
   383
   *
tomh@346
   384
   * Since pareto distributions can theoretically return unbounded values,
tomh@346
   385
   * it is sometimes useful to specify a fixed upper limit.  Note however
tomh@346
   386
   * when the upper limit is specified, the true mean of the distribution
tomh@346
   387
   * is slightly smaller than the mean value specified.
tomh@346
   388
   * \param m Mean value
tomh@346
   389
   * \param s Shape parameter
tomh@346
   390
   * \param b Upper limit on returned values
tomh@346
   391
   */
tomh@346
   392
  ParetoVariable(double m, double s, double b);
tomh@346
   393
tomh@346
   394
};
tomh@346
   395
tomh@346
   396
/**
raj@2762
   397
 * \brief WeibullVariable distributed random var
mathieu@396
   398
 * \ingroup randomvariable
mathieu@1872
   399
 *
raj@442
   400
 * This class supports the creation of objects that return random numbers
raj@442
   401
 * from a fixed weibull distribution.  It also supports the generation of 
raj@442
   402
 * single random numbers from various weibull distributions.
mathieu@1872
   403
 *
mathieu@1872
   404
 * The probability density function is defined over the interval [0, +inf]
mathieu@1872
   405
 * as: \f$ \frac{k}{\lambda}\left(\frac{x}{\lambda}\right)^{k-1}e^{-\left(\frac{x}{\lambda}\right)^k} \f$
mathieu@1872
   406
 * where \f$ k > 0\f$ is the shape parameter and \f$ \lambda > 0\f$  is the scale parameter. The
mathieu@1872
   407
 * specified mean is related to the scale and shape parameters by the following relation:
mathieu@1872
   408
 * \f$ mean = \lambda\Gamma\left(1+\frac{1}{k}\right) \f$ where \f$ \Gamma \f$ is the Gamma function.
tomh@346
   409
 */
tomh@346
   410
class WeibullVariable : public RandomVariable {
tomh@346
   411
public:
tomh@346
   412
  /**
tomh@346
   413
   * Constructs a weibull random variable  with a mean
tomh@346
   414
   * value of 1.0 and a shape (alpha) parameter of 1
tomh@346
   415
   */
tomh@346
   416
  WeibullVariable();
tomh@346
   417
tomh@346
   418
tomh@346
   419
  /**
tomh@346
   420
   * Constructs a weibull random variable with the specified mean
tomh@346
   421
   * value and a shape (alpha) parameter of 1.5.
tomh@346
   422
   * \param m mean value of the distribution
tomh@346
   423
   */
timo@4317
   424
  WeibullVariable(double m) ;
tomh@346
   425
tomh@346
   426
  /**
tomh@346
   427
   * Constructs a weibull random variable with the specified mean
tomh@346
   428
   * value and a shape (alpha).
tomh@346
   429
   * \param m Mean value for the distribution.
tomh@346
   430
   * \param s Shape (alpha) parameter for the distribution.
tomh@346
   431
   */
tomh@346
   432
  WeibullVariable(double m, double s);
tomh@346
   433
tomh@346
   434
   /**
tomh@346
   435
   * \brief Constructs a weibull random variable with the specified mean
tomh@346
   436
   * \brief value, shape (alpha), and upper bound.
raj@2762
   437
   * Since WeibullVariable distributions can theoretically return unbounded values,
tomh@346
   438
   * it is sometimes usefull to specify a fixed upper limit.  Note however
tomh@346
   439
   * that when the upper limit is specified, the true mean of the distribution
tomh@346
   440
   * is slightly smaller than the mean value specified.
tomh@346
   441
   * \param m Mean value for the distribution.
tomh@346
   442
   * \param s Shape (alpha) parameter for the distribution.
tomh@346
   443
   * \param b Upper limit on returned values
tomh@346
   444
   */
tomh@346
   445
  WeibullVariable(double m, double s, double b);
raj@4218
   446
tomh@346
   447
};
tomh@346
   448
tomh@346
   449
/**
raj@2762
   450
 * \brief Class NormalVariable defines a random variable with a
tomh@346
   451
 * normal (Gaussian) distribution.
mathieu@1872
   452
 * \ingroup randomvariable
raj@442
   453
 * 
raj@442
   454
 * This class supports the creation of objects that return random numbers
raj@442
   455
 * from a fixed normal distribution.  It also supports the generation of 
raj@442
   456
 * single random numbers from various normal distributions.
mathieu@1872
   457
 *
mathieu@1872
   458
 * The density probability function is defined over the interval (-inf,+inf)
mathieu@1872
   459
 * as: \f$ \frac{1}{\sigma\sqrt{2\pi}} e^{-\frac{(x-\mu)^2}{s\sigma^2}}\f$
mathieu@1872
   460
 * where \f$ mean = \mu \f$ and \f$ variance = \sigma^2 \f$
mathieu@1872
   461
 *
tomh@346
   462
 */
mathieu@2336
   463
class NormalVariable : public RandomVariable
mathieu@2336
   464
{
tomh@346
   465
public:
tomh@346
   466
  /**
tomh@346
   467
   * Constructs an normal random variable  with a mean
tomh@346
   468
   * value of 0 and variance of 1.
tomh@346
   469
   */ 
tomh@346
   470
  NormalVariable();
tomh@346
   471
tomh@346
   472
  /**
raj@4223
   473
   * \brief Construct a normal random variable with specified mean and variance.
raj@4223
   474
   * \param m Mean value
raj@4223
   475
   * \param v Variance
raj@4223
   476
   */ 
raj@4223
   477
  NormalVariable(double m, double v);
raj@4223
   478
raj@4223
   479
  /**
tomh@346
   480
   * \brief Construct a normal random variable with specified mean and variance
tomh@346
   481
   * \param m Mean value
tomh@346
   482
   * \param v Variance
raj@4223
   483
   * \param b Bound.  The NormalVariable is bounded symetrically about the mean
raj@4223
   484
   * [mean-bound,mean+bound]
tomh@346
   485
   */ 
raj@4223
   486
  NormalVariable(double m, double v, double b);
tomh@346
   487
};
tomh@346
   488
tomh@346
   489
/**
raj@2762
   490
 * \brief EmpiricalVariable distribution random var
mathieu@396
   491
 * \ingroup randomvariable
raj@360
   492
 *
tomh@346
   493
 * Defines a random variable  that has a specified, empirical 
tomh@346
   494
 * distribution.  The distribution is specified by a
mathieu@1872
   495
 * series of calls to the CDF member function, specifying a
tomh@346
   496
 * value and the probability that the function value is less than
tomh@346
   497
 * the specified value.  When values are requested,
tomh@346
   498
 * a uniform random variable is used to select a probabililty,
tomh@346
   499
 * and the return value is interpreted linerarly between the
raj@2762
   500
 * two appropriate points in the CDF.  The method is known
raj@2762
   501
 * as inverse transform sampling:
raj@2762
   502
 * (http://en.wikipedia.org/wiki/Inverse_transform_sampling).
tomh@346
   503
 */
tomh@346
   504
class EmpiricalVariable : public RandomVariable {
tomh@346
   505
public:
tomh@346
   506
  /**
raj@2762
   507
   * Constructor for the EmpiricalVariable random variables.
tomh@346
   508
   */
tomh@346
   509
  explicit EmpiricalVariable();
tomh@346
   510
tomh@346
   511
  /**
tomh@346
   512
   * \brief Specifies a point in the empirical distribution
tomh@346
   513
   * \param v The function value for this point
tomh@346
   514
   * \param c Probability that the function is less than or equal to v
tomh@346
   515
   */
mathieu@2336
   516
  void CDF(double v, double c);  // Value, prob <= Value
mathieu@2336
   517
protected:
mathieu@2336
   518
  EmpiricalVariable (const RandomVariableBase &variable);
tomh@346
   519
};
tomh@346
   520
tomh@346
   521
/**
mathieu@396
   522
 * \brief Integer-based empirical distribution
mathieu@396
   523
 * \ingroup randomvariable
mathieu@396
   524
 *
tomh@346
   525
 * Defines an empirical distribution where all values are integers.
raj@2762
   526
 * Indentical to EmpiricalVariable, except that the inverse transform
raj@2762
   527
 * sampling interpolation described in the EmpiricalVariable documentation
raj@2762
   528
 * is modified to only return integers.
tomh@346
   529
 */
mathieu@2336
   530
class IntEmpiricalVariable : public EmpiricalVariable 
mathieu@2336
   531
{
tomh@346
   532
public:
tomh@346
   533
  IntEmpiricalVariable();
tomh@346
   534
};
tomh@346
   535
tomh@346
   536
/**
mathieu@396
   537
 * \brief a non-random variable
mathieu@396
   538
 * \ingroup randomvariable
mathieu@396
   539
 *
mathieu@396
   540
 * Defines a random variable  that has a specified, predetermined
mathieu@396
   541
 * sequence.  This would be useful when trying to force
mathieu@396
   542
 * the RNG to return a known sequence, perhaps to
mathieu@396
   543
 * compare NS-3 to some other simulator
mathieu@396
   544
 */
mathieu@2336
   545
class DeterministicVariable : public RandomVariable
mathieu@2336
   546
{
tomh@346
   547
public:
tomh@346
   548
  /**
tomh@346
   549
   * \brief Constructor
raj@360
   550
   *
tomh@346
   551
   * Creates a generator that returns successive elements of the d array
tomh@346
   552
   * on successive calls to ::Value().  Note that the d pointer is copied
tomh@346
   553
   * for use by the generator (shallow-copy), not its contents, so the 
tomh@346
   554
   * contents of the array d points to have to remain unchanged for the use 
raj@2762
   555
   * of DeterministicVariable to be meaningful.
tomh@346
   556
   * \param d Pointer to array of random values to return in sequence
tomh@346
   557
   * \param c Number of values in the array
tomh@346
   558
   */
tomh@346
   559
  explicit DeterministicVariable(double* d, uint32_t c);
tomh@346
   560
};
tomh@346
   561
raj@438
   562
/**
raj@438
   563
 * \brief Log-normal Distributed random var
raj@438
   564
 * \ingroup randomvariable
mathieu@1872
   565
 *
raj@2762
   566
 * LogNormalVariable defines a random variable with log-normal
raj@438
   567
 * distribution.  If one takes the natural logarithm of random
raj@438
   568
 * variable following the log-normal distribution, the obtained values
raj@438
   569
 * follow a normal distribution.
raj@442
   570
 *  This class supports the creation of objects that return random numbers
raj@442
   571
 * from a fixed lognormal distribution.  It also supports the generation of
raj@442
   572
 * single random numbers from various lognormal distributions.
mathieu@1872
   573
 *
mathieu@1872
   574
 * The probability density function is defined over the interval [0,+inf) as:
mathieu@1872
   575
 * \f$ \frac{1}{x\sigma\sqrt{2\pi}} e^{-\frac{(ln(x) - \mu)^2}{2\sigma^2}}\f$
mathieu@1872
   576
 * where \f$ mean = e^{\mu+\frac{\sigma^2}{2}} \f$ and 
mathieu@1872
   577
 * \f$ variance = (e^{\sigma^2}-1)e^{2\mu+\sigma^2}\f$
mathieu@1872
   578
 *
mathieu@1872
   579
 * The \f$ \mu \f$ and \f$ \sigma \f$ parameters can be calculated from the mean
mathieu@1872
   580
 * and standard deviation with the following equations:
mathieu@1872
   581
 * \f$ \mu = ln(mean) - \frac{1}{2}ln\left(1+\frac{stddev}{mean^2}\right)\f$, and,
mathieu@1872
   582
 * \f$ \sigma = \sqrt{ln\left(1+\frac{stddev}{mean^2}\right)}\f$
raj@438
   583
 */
mathieu@2336
   584
class LogNormalVariable : public RandomVariable 
mathieu@2336
   585
{
raj@438
   586
public:
raj@438
   587
  /**
mathieu@1872
   588
   * \param mu mu parameter of the lognormal distribution
mathieu@1872
   589
   * \param sigma sigma parameter of the lognormal distribution
raj@438
   590
   */
raj@438
   591
  LogNormalVariable (double mu, double sigma);
raj@438
   592
};
raj@438
   593
raj@942
   594
/**
timo@4317
   595
 * \brief Gamma Distributed Random Variable
timo@4317
   596
 * \ingroup randomvariable
timo@4317
   597
 *
timo@4317
   598
 * GammaVariable defines a random variable with gamma distribution. 
timo@4317
   599
 *
timo@4317
   600
 * This class supports the creation of objects that return random numbers
timo@4317
   601
 * from a fixed gamma distribution. It also supports the generation of 
timo@4317
   602
 * single random numbers from various gamma distributions.
timo@4317
   603
 *
timo@4317
   604
 * The probability density function is defined over the interval [0,+inf) as:
timo@4317
   605
 * \f$ x^{\alpha-1} \frac{e^{-\frac{x}{\beta}}}{\beta^\alpha \Gamma(\alpha)}\f$
timo@4317
   606
 * where \f$ mean = \alpha\beta \f$ and 
timo@4317
   607
 * \f$ variance = \alpha \beta^2\f$
timo@4317
   608
 */
timo@4317
   609
class GammaVariable : public RandomVariable 
timo@4317
   610
{
timo@4317
   611
public:
timo@4317
   612
  /**
timo@4317
   613
   * Constructs a gamma random variable with alpha = 1.0 and beta = 1.0
timo@4317
   614
   */
timo@4317
   615
  GammaVariable ();
timo@4317
   616
timo@4317
   617
  /**
timo@4317
   618
   * \param alpha alpha parameter of the gamma distribution
timo@4317
   619
   * \param beta beta parameter of the gamma distribution
timo@4317
   620
   */
timo@4317
   621
  GammaVariable (double alpha, double beta);
timo@4317
   622
timo@4317
   623
  /**
timo@4317
   624
   * \brief call RandomVariable::GetValue
timo@4317
   625
   * \return A floating point random value 
timo@4317
   626
   *
timo@4317
   627
   * Note: we have to re-implement this method here because the method is
timo@4317
   628
   * overloaded below for the two-argument variant and the c++ name resolution
timo@4317
   629
   * rules don't work well with overloads split between parent and child
timo@4317
   630
   * classes.
timo@4317
   631
   */
timo@4317
   632
  double GetValue (void) const;
timo@4317
   633
  
timo@4317
   634
  /**
timo@4317
   635
   * \brief Returns a gamma random distributed double with parameters alpha and beta.
timo@4317
   636
   * \param alpha alpha parameter of the gamma distribution
timo@4317
   637
   * \param beta beta parameter of the gamma distribution
timo@4317
   638
   * \return A floating point random value
timo@4317
   639
   */
timo@4317
   640
  double GetValue(double alpha, double beta) const;
timo@4317
   641
};
timo@4317
   642
timo@4317
   643
/**
timo@4317
   644
 * \brief Erlang Distributed Random Variable
timo@4317
   645
 * \ingroup randomvariable
timo@4317
   646
 *
timo@4317
   647
 * ErlangVariable defines a random variable with Erlang distribution.
timo@4317
   648
 *
timo@4317
   649
 * The Erlang distribution is a special case of the Gamma distribution where k
timo@4317
   650
 * (= alpha) is a non-negative integer. Erlang distributed variables can be
timo@4317
   651
 * generated using a much faster algorithm than gamma variables.
timo@4317
   652
 *
timo@4317
   653
 * This class supports the creation of objects that return random numbers from
timo@4317
   654
 * a fixed Erlang distribution. It also supports the generation of single
timo@4317
   655
 * random numbers from various Erlang distributions.
timo@4317
   656
 *
timo@4317
   657
 * The probability density function is defined over the interval [0,+inf) as:
timo@4317
   658
 * \f$ \frac{x^{k-1} e^{-\frac{x}{\lambda}}}{\lambda^k (k-1)!}\f$
timo@4317
   659
 * where \f$ mean = k \lambda \f$ and 
timo@4317
   660
 * \f$ variance = k \lambda^2\f$
timo@4317
   661
 */
timo@4317
   662
class ErlangVariable : public RandomVariable 
timo@4317
   663
{
timo@4317
   664
public:
timo@4317
   665
  /**
timo@4317
   666
   * Constructs an Erlang random variable with k = 1 and lambda = 1.0
timo@4317
   667
   */
timo@4317
   668
  ErlangVariable ();
timo@4317
   669
timo@4317
   670
  /**
timo@4317
   671
   * \param k k parameter of the Erlang distribution. Must be a non-negative integer.
timo@4317
   672
   * \param lambda lambda parameter of the Erlang distribution
timo@4317
   673
   */
timo@4317
   674
  ErlangVariable (unsigned int k, double lambda);
timo@4317
   675
timo@4317
   676
  /**
timo@4317
   677
   * \brief call RandomVariable::GetValue
timo@4317
   678
   * \return A floating point random value 
timo@4317
   679
   *
timo@4317
   680
   * Note: we have to re-implement this method here because the method is
timo@4317
   681
   * overloaded below for the two-argument variant and the c++ name resolution
timo@4317
   682
   * rules don't work well with overloads split between parent and child
timo@4317
   683
   * classes.
timo@4317
   684
   */
timo@4317
   685
  double GetValue (void) const;
timo@4317
   686
  
timo@4317
   687
  /**
timo@4317
   688
   * \brief Returns an Erlang random distributed double with parameters k and lambda.
timo@4317
   689
   * \param k k parameter of the Erlang distribution. Must be a non-negative integer.
timo@4317
   690
   * \param lambda lambda parameter of the Erlang distribution
timo@4317
   691
   * \return A floating point random value
timo@4317
   692
   */
timo@4317
   693
  double GetValue(unsigned int k, double lambda) const;
timo@4317
   694
};
timo@4317
   695
timo@4317
   696
/**
francesco@4579
   697
 * \brief Zipf Distributed random var (between 1 and n included)
francesco@4579
   698
 * \ingroup randomvariable
francesco@4579
   699
 *
francesco@4579
   700
 */
francesco@4579
   701
class ZipfVariable : public RandomVariable 
francesco@4579
   702
{
francesco@4579
   703
public:
francesco@4579
   704
  /**
francesco@4579
   705
   * \param n the number of possible items
francesco@4579
   706
   * \param alpha the alpha parameter
francesco@4579
   707
   */
francesco@4579
   708
  ZipfVariable (long n, double alpha);
francesco@4579
   709
  /**
francesco@4579
   710
   * A zipf variable with N=1 and alpha=0
francesco@4579
   711
   */
francesco@4579
   712
  ZipfVariable ();
francesco@4579
   713
};
francesco@4579
   714
francesco@4579
   715
/**
raj@942
   716
 * \brief Triangularly Distributed random var
raj@942
   717
 * \ingroup randomvariable
raj@942
   718
 * 
raj@942
   719
 * This distribution is a triangular distribution.  The probablility density
raj@942
   720
 * is in the shape of a triangle.
raj@942
   721
 */
mathieu@2336
   722
class TriangularVariable : public RandomVariable 
mathieu@2336
   723
{
raj@942
   724
public:
raj@942
   725
  /**
raj@942
   726
   * Creates a triangle distribution random number generator in the
raj@942
   727
   * range [0.0 .. 1.0), with mean of 0.5
raj@942
   728
   */
raj@942
   729
  TriangularVariable();
raj@942
   730
raj@942
   731
  /**
raj@942
   732
   * Creates a triangle distribution random number generator with the specified
raj@942
   733
   * range
raj@942
   734
   * \param s Low end of the range
raj@942
   735
   * \param l High end of the range
raj@942
   736
   * \param mean mean of the distribution
raj@942
   737
   */
raj@942
   738
  TriangularVariable(double s, double l, double mean);
raj@4218
   739
raj@942
   740
};
raj@438
   741
mathieu@2409
   742
std::ostream &operator << (std::ostream &os, const RandomVariable &var);
mathieu@2409
   743
std::istream &operator >> (std::istream &os, RandomVariable &var);
mathieu@2384
   744
mathieu@2969
   745
/**
mathieu@2969
   746
 * \class ns3::RandomVariableValue
mathieu@2969
   747
 * \brief hold objects of type ns3::RandomVariable
mathieu@2969
   748
 */
mathieu@2969
   749
mathieu@2445
   750
ATTRIBUTE_VALUE_DEFINE (RandomVariable);
mathieu@2445
   751
ATTRIBUTE_CHECKER_DEFINE (RandomVariable);
mathieu@2445
   752
ATTRIBUTE_ACCESSOR_DEFINE (RandomVariable);
mathieu@2384
   753
tomh@346
   754
}//namespace ns3
mathieu@2384
   755
mathieu@2384
   756
tomh@346
   757
#endif