include/xbt/random.hpp

   1 /* Copyright (c) 2019-2022. 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(const std::string& filename);
  44
  45   /**
  46    * @brief Write the state of the Mersenne-Twister RNG to a file
  47    */
  48   bool write_state(const std::string& filename) const;
  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   using Random::Random;
  89
  90   int uniform_int(int min, int max) override;
  91   double uniform_real(double min, double max) override;
  92   double exponential(double lambda) override;
  93   double normal(double mean, double sd) override;
  94 };
  95
  96 /** A reproducible random number generator.
  97  *
  98  * Uses our own implementation of distributions to ensure reproducibility.
  99  */
 100 class XBT_PUBLIC XbtRandom : public Random {
 101 public:
 102   using Random::Random;
 103
 104   int uniform_int(int min, int max) override;
 105   double uniform_real(double min, double max) override;
 106   double exponential(double lambda) override;
 107   double normal(double mean, double sd) override;
 108 };
 109
 110 /**
 111  * @brief Tells xbt/random to use the ad-hoc distribution implementation.
 112  */
 113 void set_implem_xbt();
 114
 115 /**
 116  * @brief Tells xbt/random to use the standard library distribution implementation.
 117  */
 118 void set_implem_std();
 119
 120 /**
 121  * @brief Sets the seed of the Mersenne-Twister RNG
 122  */
 123 void set_mersenne_seed(int);
 124
 125 /**
 126  * @brief Read the state of the Mersenne-Twister RNG from a file.
 127  */
 128 bool read_mersenne_state(const std::string& filename);
 129
 130 /**
 131  * @brief Write the state of the Mersenne-Twister RNG to a file.
 132  */
 133 bool write_mersenne_state(const std::string& filename);
 134
 135 /**
 136  * @brief Draws an integer number uniformly in range [min, max] (min and max included)
 137  *
 138  * @param min Minimum value
 139  * @param max Maximum value
 140  */
 141 int uniform_int(int min, int max);
 142
 143 /**
 144  * @brief Draws a real number uniformly in range [min, max) (min included, and max excluded)
 145  *
 146  * @param min Minimum value
 147  * @param max Maximum value
 148  */
 149 double uniform_real(double min, double max);
 150
 151 /**
 152  * @brief Draws a real number according to the given exponential distribution
 153  *
 154  * @param lambda Parameter of the exponential law
 155  */
 156 double exponential(double lambda);
 157
 158 /**
 159  * @brief Draws a real number according to the given normal distribution
 160  *
 161  * @param mean Mean of the normal distribution
 162  * @param sd Standard deviation of the normal distribution
 163  */
 164 double normal(double mean, double sd);
 165 } // namespace random
 166 } // namespace xbt
 167 } // namespace simgrid
 168
 169 #endif