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 <fstream>
  11 #include <iostream>
  12 #include <random>
  13 #include <string>
  14
  15 namespace simgrid {
  16 namespace xbt {
  17 namespace random {
  18
  19 /** A random number generator.
  20  *
  21  * It uses a std::mersenne_twister_engine (std::mt19937) and provides several distributions.
  22  * This interface is implemented by StdRandom and XbtRandom.
  23  */
  24 class XBT_PUBLIC Random {
  25 public:
  26   std::mt19937 mt19937_gen; // the random number engine
  27
  28   /** @brief Build a new random number generator with default seed */
  29   Random() = default;
  30   /** @brief Build a new random number generator with given seed */
  31   explicit Random(int seed) : mt19937_gen(seed) {}
  32
  33   virtual ~Random() = default;
  34
  35   /**
  36    * @brief Sets the seed of the Mersenne-Twister RNG
  37    */
  38   void set_seed(int seed) { mt19937_gen.seed(seed); }
  39
  40   /**
  41    * @brief Read the state of the Mersenne-Twister RNG from a file
  42    */
  43   void read_state(std::string filename)
  44   {
  45     std::ifstream file(filename);
  46     file >> mt19937_gen;
  47   }
  48
  49   /**
  50    * @brief Write the state of the Mersenne-Twister RNG to a file
  51    */
  52   void write_state(std::string filename)
  53   {
  54     std::ofstream file(filename);
  55     file << mt19937_gen;
  56   }
  57
  58   /**
  59    * @brief Draws an integer number uniformly in range [min, max] (min and max included)
  60    *
  61    * @param min Minimum value
  62    * @param max Maximum value
  63    */
  64   virtual int uniform_int(int min, int max) = 0;
  65
  66   /**
  67    * @brief Draws a real number uniformly in range [min, max) (min included, and max excluded)
  68    *
  69    * @param min Minimum value
  70    * @param max Maximum value
  71    */
  72   virtual double uniform_real(double min, double max) = 0;
  73
  74   /**
  75    * @brief Draws a real number according to the given exponential distribution
  76    *
  77    * @param lambda Parameter of the exponential law
  78    */
  79   virtual double exponential(double lambda) = 0;
  80
  81   /**
  82    * @brief Draws a real number according to the given normal distribution
  83    *
  84    * @param mean Mean of the normal distribution
  85    * @param sd Standard deviation of the normal distribution
  86    */
  87   virtual double normal(double mean, double sd) = 0;
  88 };
  89
  90 /** A random number generator using the C++ standard library.
  91  *
  92  * Caution: reproducibility is not guaranteed across different implementations.
  93  */
  94 class XBT_PUBLIC StdRandom : public Random {
  95 public:
  96   StdRandom() = default;
  97   explicit StdRandom(int seed) : Random(seed) {}
  98
  99   int uniform_int(int min, int max) override;
 100   double uniform_real(double min, double max) override;
 101   double exponential(double lambda) override;
 102   double normal(double mean, double sd) override;
 103 };
 104
 105 /** A reproducible random number generator.
 106  *
 107  * Uses our own implementation of distributions to ensure reproducibility.
 108  */
 109 class XBT_PUBLIC XbtRandom : public Random {
 110 public:
 111   XbtRandom() = default;
 112   explicit XbtRandom(int seed) : Random(seed) {}
 113
 114   int uniform_int(int min, int max) override;
 115   double uniform_real(double min, double max) override;
 116   double exponential(double lambda) override;
 117   double normal(double mean, double sd) override;
 118 };
 119
 120 /**
 121  * @brief Tells xbt/random to use the ad-hoc distribution implementation.
 122  */
 123 void set_implem_xbt();
 124
 125 /**
 126  * @brief Tells xbt/random to use the standard library distribution implementation.
 127  */
 128 void set_implem_std();
 129
 130 /**
 131  * @brief Sets the seed of the Mersenne-Twister RNG
 132  */
 133 void set_mersenne_seed(int);
 134
 135 /**
 136  * @brief Read the state of the Mersenne-Twister RNG from a file
 137  */
 138 void read_mersenne_state(std::string filename);
 139
 140 /**
 141  * @brief Write the state of the Mersenne-Twister RNG to a file
 142  */
 143 void write_mersenne_state(std::string filename);
 144
 145 /**
 146  * @brief Draws an integer number uniformly in range [min, max] (min and max included)
 147  *
 148  * @param min Minimum value
 149  * @param max Maximum value
 150  */
 151 int uniform_int(int min, int max);
 152
 153 /**
 154  * @brief Draws a real number uniformly in range [min, max) (min included, and max excluded)
 155  *
 156  * @param min Minimum value
 157  * @param max Maximum value
 158  */
 159 double uniform_real(double min, double max);
 160
 161 /**
 162  * @brief Draws a real number according to the given exponential distribution
 163  *
 164  * @param lambda Parameter of the exponential law
 165  */
 166 double exponential(double lambda);
 167
 168 /**
 169  * @brief Draws a real number according to the given normal distribution
 170  *
 171  * @param mean Mean of the normal distribution
 172  * @param sd Standard deviation of the normal distribution
 173  */
 174 double normal(double mean, double sd);
 175 } // namespace random
 176 } // namespace xbt
 177 } // namespace simgrid
 178
 179 #endif