ARGoS
3
A parallel, multi-engine simulator for swarm robotics
|
The ARGoS random number generator. More...
#include <rng.h>
Classes | |
class | CCategory |
The RNG category. More... | |
class | CRNG |
The RNG. More... | |
Static Public Member Functions | |
static bool | CreateCategory (const std::string &str_category, UInt32 un_seed) |
Creates a new category. | |
static CCategory & | GetCategory (const std::string &str_category) |
Returns a reference to the wanted category. | |
static bool | ExistsCategory (const std::string &str_category) |
Returns true if the given category exists in the pool. | |
static void | RemoveCategory (const std::string &str_category) |
Removes the wanted category. | |
static CRNG * | CreateRNG (const std::string &str_category, const std::string &str_type="mt19937") |
Creates a new RNG inside the given category. | |
static UInt32 | GetSeedOf (const std::string &str_category) |
Returns the seed of the wanted category. | |
static void | SetSeedOf (const std::string &str_category, UInt32 un_seed) |
Sets the new seed of the wanted category. | |
static void | Reset () |
Resets all the RNG categories. |
The ARGoS random number generator.
It is meant to be used not only inside ARGoS, but also from controllers, loop functions as well as external applications.
In general, RNGs have the greatest impact on the reproducibility of experiments. However, once the random seed has been set, the series of random numbers generated by an RNG is fixed. In this way, experiments are reproducible. To further complicate things, ARGoS is a multi-threaded program. Multi-threading and RNGs create issues to reproducibility. In fact, if the RNGs were shared among the threads, it would be impossible to predict the order in which the RNGs are accessed, because thread scheduling is not controllable nor predictable. For this reason, a common solution is to assign a separated RNG to each thread. For ARGoS, this is not a viable method because we want the number of threads to be set by the user and we want the outcome of an experiment to be reproducible no matter how many threads are used.
All these considerations brought us to the design of a RNG with a different approach. The class argos::CRandom is a static factory that creates argos::CRandom::CRNG objects. If a component (sensor, actuator, controller, etc.) needs to get random numbers, it has to first create a local RNG class (typically, at init time). Internally, the factory assigns a seed to it.
To allow for usage from different components (such as ARGoS main code, an evolutionary algorithm, controllers, etc.) RNGs are divided up in categories. The ARGoS core uses the argos
category. When ARGoS is reset, all the RNGs in this category are reset as well, but not the RNGs in other categories. Categories give the user complete power on the RNGs, while ensuring compartmentalization.
If all you want is drawing random numbers inside a controller, you can safely create new argos::CRandom::CRNG objects in the argos
category. If, instead, you intend to wrap ARGoS around an optimization algorithm and want to maintain control of the way random number generators are managed, it is necessary for you to create your own category.
To create a new RNG inside the argos
category, this is enough:
argos::CRandom::CRNG* m_pcRNG = argos::CRandom::CreateRNG("argos");
When you want to use random numbers with a custom category, you need to first call the function providing a label for the category and a base seed:
argos::CRandom::CreateCategory("my_category", my_seed);
Once the category is created, you can get a new RNG with a call to the function
argos::CRandom::CRNG* m_pcRNG = argos::CRandom::CreateRNG("my_category");
bool argos::CRandom::CreateCategory | ( | const std::string & | str_category, |
UInt32 | un_seed | ||
) | [static] |
CRandom::CRNG * argos::CRandom::CreateRNG | ( | const std::string & | str_category, |
const std::string & | str_type = "mt19937" |
||
) | [static] |
Creates a new RNG inside the given category.
str_category | the id of the category. |
str_type | the type of RNG to use. By default, Mersenne Twister is used. For a list of available RNG types, see GetRNGTypes(). |
bool argos::CRandom::ExistsCategory | ( | const std::string & | str_category | ) | [static] |
CRandom::CCategory & argos::CRandom::GetCategory | ( | const std::string & | str_category | ) | [static] |
UInt32 argos::CRandom::GetSeedOf | ( | const std::string & | str_category | ) | [static] |
void argos::CRandom::RemoveCategory | ( | const std::string & | str_category | ) | [static] |
void argos::CRandom::Reset | ( | ) | [static] |
void argos::CRandom::SetSeedOf | ( | const std::string & | str_category, |
UInt32 | un_seed | ||
) | [static] |