include/xbt/random.hpp

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