include/xbt/random.hpp

   1 /* Copyright (c) 2019-2020. The SimGrid Team. All rights reserved.               */
   2
   3 /* This program is free software; you can redistribute it and/or modify it
   4  * under the terms of the license (GNU LGPL) which comes with this package. */
   5
   6 #ifndef SIMGRID_XBT_RANDOM_HPP
   7 #define SIMGRID_XBT_RANDOM_HPP
   8
   9 #include "xbt/base.h"
  10 #include <random>
  11
  12 namespace simgrid {
  13 namespace xbt {
  14 namespace random {
  15
  16 /** A random number generator.
  17  *
  18  * It uses a std::mersenne_twister_engine (std::mt19937) and provides several distributions.
  19  * This interface is implemented by StdRandom and XbtRandom.
  20  */
  21 class XBT_PUBLIC Random {
  22 public:
  23   std::mt19937 mt19937_gen; // the random number engine
  24
  25   /** @brief Build a new random number generator with default seed */
  26   Random() = default;
  27   /** @brief Build a new random number generator with given seed */
  28   explicit Random(int seed) : mt19937_gen(seed) {}
  29
  30   virtual ~Random() = default;
  31
  32   /**
  33    * @brief Sets the seed of the Mersenne-Twister RNG
  34    */
  35   void set_seed(int seed) { mt19937_gen.seed(seed); }
  36
  37   /**
  38    * @brief Draws an integer number uniformly in range [min, max] (min and max included)
  39    *
  40    * @param min Minimum value
  41    * @param max Maximum value
  42    */
  43   virtual int uniform_int(int min, int max) = 0;
  44
  45   /**
  46    * @brief Draws a real number uniformly in range [min, max) (min included, and max excluded)
  47    *
  48    * @param min Minimum value
  49    * @param max Maximum value
  50    */
  51   virtual double uniform_real(double min, double max) = 0;
  52
  53   /**
  54    * @brief Draws a real number according to the given exponential distribution
  55    *
  56    * @param lambda Parameter of the exponential law
  57    */
  58   virtual double exponential(double lambda) = 0;
  59
  60   /**
  61    * @brief Draws a real number according to the given normal distribution
  62    *
  63    * @param mean Mean of the normal distribution
  64    * @param sd Standard deviation of the normal distribution
  65    */
  66   virtual double normal(double mean, double sd) = 0;
  67 };
  68
  69 /** A random number generator using the C++ standard library.
  70  *
  71  * Caution: reproducibility is not guaranteed across different implementations.
  72  */
  73 class XBT_PUBLIC StdRandom : public Random {
  74 public:
  75   StdRandom() = default;
  76   explicit StdRandom(int seed) : Random(seed) {}
  77
  78   int uniform_int(int min, int max) override;
  79   double uniform_real(double min, double max) override;
  80   double exponential(double lambda) override;
  81   double normal(double mean, double sd) override;
  82 };
  83
  84 /** A reproducible random number generator.
  85  *
  86  * Uses our own implementation of distributions to ensure reproducibility.
  87  */
  88 class XBT_PUBLIC XbtRandom : public Random {
  89 public:
  90   XbtRandom() = default;
  91   explicit XbtRandom(int seed) : Random(seed) {}
  92
  93   int uniform_int(int min, int max) override;
  94   double uniform_real(double min, double max) override;
  95   double exponential(double lambda) override;
  96   double normal(double mean, double sd) override;
  97 };
  98
  99 /**
 100  * @brief Tells xbt/random to use the ad-hoc distribution implementation.
 101  */
 102 void set_implem_xbt();
 103
 104 /**
 105  * @brief Tells xbt/random to use the standard library distribution implementation.
 106  */
 107 void set_implem_std();
 108
 109 /**
 110  * @brief Sets the seed of the Mersenne-Twister RNG
 111  */
 112 void set_mersenne_seed(int);
 113
 114 /**
 115  * @brief Draws an integer number uniformly in range [min, max] (min and max included)
 116  *
 117  * @param min Minimum value
 118  * @param max Maximum value
 119  */
 120 int uniform_int(int min, int max);
 121
 122 /**
 123  * @brief Draws a real number uniformly in range [min, max) (min included, and max excluded)
 124  *
 125  * @param min Minimum value
 126  * @param max Maximum value
 127  */
 128 double uniform_real(double min, double max);
 129
 130 /**
 131  * @brief Draws a real number according to the given exponential distribution
 132  *
 133  * @param lambda Parameter of the exponential law
 134  */
 135 double exponential(double lambda);
 136
 137 /**
 138  * @brief Draws a real number according to the given normal distribution
 139  *
 140  * @param mean Mean of the normal distribution
 141  * @param sd Standard deviation of the normal distribution
 142  */
 143 double normal(double mean, double sd);
 144 } // namespace random
 145 } // namespace xbt
 146 } // namespace simgrid
 147
 148 #endif