Warning: include(php/utility.php): Failed to open stream: No such file or directory in /home/argos/argos3/doc/api/embedded/a02406.php on line 2

Warning: include(): Failed opening 'php/utility.php' for inclusion (include_path='.:/usr/lib64/php') in /home/argos/argos3/doc/api/embedded/a02406.php on line 2
The ARGoS Website

argos::CRandom Class Reference

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. More...
 
static CCategoryGetCategory (const std::string &str_category)
 Returns a reference to the wanted category. More...
 
static bool ExistsCategory (const std::string &str_category)
 Returns true if the given category exists in the pool. More...
 
static void RemoveCategory (const std::string &str_category)
 Removes the wanted category. More...
 
static CRNGCreateRNG (const std::string &str_category)
 Creates a new RNG inside the given category. More...
 
static UInt32 GetSeedOf (const std::string &str_category)
 Returns the seed of the wanted category. More...
 
static void SetSeedOf (const std::string &str_category, UInt32 un_seed)
 Sets the new seed of the wanted category. More...
 
static void Reset ()
 Resets all the RNG categories. More...
 

Detailed Description

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");

Definition at line 81 of file rng.h.

Member Function Documentation

◆ CreateCategory()

bool argos::CRandom::CreateCategory ( const std::string &  str_category,
UInt32  un_seed 
)
static

Creates a new category.

Parameters
str_categorythe id of the category.
un_seedthe base seed of the category.
Returns
true if the category was created; false if a category with the passed id exists already.

Definition at line 298 of file rng.cpp.

◆ CreateRNG()

CRandom::CRNG * argos::CRandom::CreateRNG ( const std::string &  str_category)
static

Creates a new RNG inside the given category.

Parameters
str_categorythe id of the category.
Returns
the pointer to a new RNG inside this category.

Definition at line 347 of file rng.cpp.

◆ ExistsCategory()

bool argos::CRandom::ExistsCategory ( const std::string &  str_category)
static

Returns true if the given category exists in the pool.

Parameters
str_categorythe id of the category.
Returns
true if the given category exists in the pool.

Definition at line 325 of file rng.cpp.

◆ GetCategory()

CRandom::CCategory & argos::CRandom::GetCategory ( const std::string &  str_category)
static

Returns a reference to the wanted category.

Parameters
str_categorythe id of the category.
Returns
a reference to the wanted category.

Definition at line 317 of file rng.cpp.

◆ GetSeedOf()

UInt32 argos::CRandom::GetSeedOf ( const std::string &  str_category)
static

Returns the seed of the wanted category.

Parameters
str_categorythe id of the category.
Returns
the seed of the wanted category.

Definition at line 355 of file rng.cpp.

◆ RemoveCategory()

void argos::CRandom::RemoveCategory ( const std::string &  str_category)
static

Removes the wanted category.

Parameters
str_categorythe id of the category.

Definition at line 338 of file rng.cpp.

◆ Reset()

void argos::CRandom::Reset ( )
static

Resets all the RNG categories.

Definition at line 372 of file rng.cpp.

◆ SetSeedOf()

void argos::CRandom::SetSeedOf ( const std::string &  str_category,
UInt32  un_seed 
)
static

Sets the new seed of the wanted category.

This method does not reset the RNGs. You must call Reset() explicitly.

Parameters
str_categorythe id of the category.
un_seedthe new seed of the wanted category.
See also
Reset()

Definition at line 363 of file rng.cpp.