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   bool read_state(std::string filename);
  44
  45   /**
  46    * @brief Write the state of the Mersenne-Twister RNG to a file
  47    */
  48   bool write_state(std::string filename);
  49
  50   /**
  51    * @brief Draws an integer number uniformly in range [min, max] (min and max included)
  52    *
  53    * @param min Minimum value
  54    * @param max Maximum value
  55    */
  56   virtual int uniform_int(int min, int max) = 0;
  57
  58   /**
  59    * @brief Draws a real number uniformly in range [min, max) (min included, and max excluded)
  60    *
  61    * @param min Minimum value
  62    * @param max Maximum value
  63    */
  64   virtual double uniform_real(double min, double max) = 0;
  65
  66   /**
  67    * @brief Draws a real number according to the given exponential distribution
  68    *
  69    * @param lambda Parameter of the exponential law
  70    */
  71   virtual double exponential(double lambda) = 0;
  72
  73   /**
  74    * @brief Draws a real number according to the given normal distribution
  75    *
  76    * @param mean Mean of the normal distribution
  77    * @param sd Standard deviation of the normal distribution
  78    */
  79   virtual double normal(double mean, double sd) = 0;
  80 };
  81
  82 /** A random number generator using the C++ standard library.
  83  *
  84  * Caution: reproducibility is not guaranteed across different implementations.
  85  */
  86 class XBT_PUBLIC StdRandom : public Random {
  87 public:
  88   StdRandom() = default;
  89   explicit StdRandom(int seed) : Random(seed) {}
  90
  91   int uniform_int(int min, int max) override;
  92   double uniform_real(double min, double max) override;
  93   double exponential(double lambda) override;
  94   double normal(double mean, double sd) override;
  95 };
  96
  97 /** A reproducible random number generator.
  98  *
  99  * Uses our own implementation of distributions to ensure reproducibility.
 100  */
 101 class XBT_PUBLIC XbtRandom : public Random {
 102 public:
 103   XbtRandom() = default;
 104   explicit XbtRandom(int seed) : Random(seed) {}
 105
 106   int uniform_int(int min, int max) override;
 107   double uniform_real(double min, double max) override;
 108   double exponential(double lambda) override;
 109   double normal(double mean, double sd) override;
 110 };
 111
 112 /**
 113  * @brief Tells xbt/random to use the ad-hoc distribution implementation.
 114  */
 115 void set_implem_xbt();
 116
 117 /**
 118  * @brief Tells xbt/random to use the standard library distribution implementation.
 119  */
 120 void set_implem_std();
 121
 122 /**
 123  * @brief Sets the seed of the Mersenne-Twister RNG
 124  */
 125 void set_mersenne_seed(int);
 126
 127 /**
 128  * @brief Read the state of the Mersenne-Twister RNG from a file.
 129  */
 130 bool read_mersenne_state(std::string filename);
 131
 132 /**
 133  * @brief Write the state of the Mersenne-Twister RNG to a file.
 134  */
 135 bool write_mersenne_state(std::string filename);
 136
 137 /**
 138  * @brief Draws an integer number uniformly in range [min, max] (min and max included)
 139  *
 140  * @param min Minimum value
 141  * @param max Maximum value
 142  */
 143 int uniform_int(int min, int max);
 144
 145 /**
 146  * @brief Draws a real number uniformly in range [min, max) (min included, and max excluded)
 147  *
 148  * @param min Minimum value
 149  * @param max Maximum value
 150  */
 151 double uniform_real(double min, double max);
 152
 153 /**
 154  * @brief Draws a real number according to the given exponential distribution
 155  *
 156  * @param lambda Parameter of the exponential law
 157  */
 158 double exponential(double lambda);
 159
 160 /**
 161  * @brief Draws a real number according to the given normal distribution
 162  *
 163  * @param mean Mean of the normal distribution
 164  * @param sd Standard deviation of the normal distribution
 165  */
 166 double normal(double mean, double sd);
 167 } // namespace random
 168 } // namespace xbt
 169 } // namespace simgrid
 170
 171 #endif