Construct version 5.3.9
An agent based modeling framework
Random Class Reference

Manages all random number generation in Construct. More...

Public Member Functions

void set_seed (unsigned int seed) noexcept
 
float uniform () noexcept
 Generates a U(0,1) as a float. More...
 
float uniform (float min, float max) noexcept
 Generates a U(min,max) as a float. More...
 
unsigned int integer (unsigned int max)
 Generates a random integer ∈[0,max). More...
 
unsigned int poisson_number (float lambda)
 Generates a random integer from a poisson distribution. More...
 
bool randombool (float probability=.5)
 Generates a random boolean. More...
 
float normal (float mean, float variance)
 Generates a random value from a normal distribution. More...
 
float exponential (float mean)
 Generates a random value from an exponential distribution. More...
 
template<typename T >
void vector_shuffle (std::vector< T > &A) noexcept
 Shuffles a vector so that each element is moved to another random element. More...
 
unsigned int find_dist_index (std::vector< float > &pdf)
 An element index is selected based on the submitted probability distribution function vector. More...
 
std::vector< unsigned int > order_by_pdf (std::vector< float > &pdf)
 Creates a vector of unique indexes ordered based on the submitted probability distribution function. More...
 

Detailed Description

Manages all random number generation in Construct.

The central location for all random functions. No model or Manager should generate random numbers independently of this class.

Member Function Documentation

◆ exponential()

float Random::exponential ( float  mean)

Generates a random value from an exponential distribution.

Uses the standard library exponential_distribution

Parameters
meanThe mean of the distribution.
Returns
The value sampled from the associated distribution

Example

Random* random = construct->random;
const int nrolls = 10000; // number of experiments
const int nstars = 100; // maximum number of stars to distribute
const int nintervals = 10; // number of intervals
int p[nintervals] = {};
for (int i = 0; i < nrolls; ++i) {
float number = random->exponential(3.5);
if (number < 1.0) ++p[int(nintervals * number)];
}
std::cout << "exponential_distribution (3.5):" << std::endl;
std::cout << std::fixed; std::cout.precision(1);
for (int i = 0; i < nintervals; ++i) {
std::cout << float(i) / nintervals << "-" << float(i + 1) / nintervals << ": ";
std::cout << std::string(p[i] * nstars / nrolls, '*') << std::endl;
}
Manages all random number generation in Construct.
Definition: RandomManager.h:21
float exponential(float mean)
Generates a random value from an exponential distribution.
Definition: RandomManager.cpp:51

Output:

exponential_distribution(3.5) :
0.0 - 0.1 : *****************************
0.1 - 0.2 : *********************
0.2 - 0.3 : **************
0.3 - 0.4 : *********
0.4 - 0.5 : *******
0.5 - 0.6 : *****
0.6 - 0.7 : ***
0.7 - 0.8 : **
0.8 - 0.9 : *
0.9 - 1.0 : *

Complexity

Constant

Exception Safety

If a negative value is given for the mean, an assertion is raised.

◆ find_dist_index()

unsigned int Random::find_dist_index ( std::vector< float > &  pdf)

An element index is selected based on the submitted probability distribution function vector.

Uses the standard library discrete_distribution

Parameters
pdfThe probability distribution from which sampling will take place.
Returns
The index as sampled from the pdf.

Example

Random* random = construct->random;
std::vector<float> pdf;
pdf.push_back(1);
pdf.push_back(3);
pdf.push_back(7);
std::cout << "generating random indexes based on custom pdf" << std::endl;
for(int i = 0; i < 10; i++) std::cout << random->find_dist_index(pdf) <<std::endl;
unsigned int find_dist_index(std::vector< float > &pdf)
An element index is selected based on the submitted probability distribution function vector.
Definition: RandomManager.cpp:63

Output:

generating random indexes based on custom cdf
2
1
0
2
2
2
2
0
2
2

Complexity

Linear is size of the submitted pdf.

Iterator validity

No Changes.

Exception Safety

An assertion is raised if any values in pdf are less than zero or if all elements are zero.

Here is the caller graph for this function:

◆ integer()

unsigned int Random::integer ( unsigned int  max)

Generates a random integer ∈[0,max).

Parameters
maxThe largest but non-inclusive value in the range of the distribution.
Returns
The value sampled from the associated distribution

Example

Random* random = construct->random;
std::cout << "some random numbers between 0 and 10" << std::endl;
for(int i = 0; i < 10; i++) {
std::cout << random->integer(10) << std::endl;
}
unsigned int integer(unsigned int max)
Generates a random integer ∈[0,max).
Definition: RandomManager.cpp:24

Output:

some random numbers between 0 and 10
0
7
3
1
3
1
8
9
2
9

Complexity

Constant

Exception Safety

An assertion is raised if max is equal to zero.

Here is the caller graph for this function:

◆ normal()

float Random::normal ( float  mean,
float  variance 
)

Generates a random value from a normal distribution.

Uses the standard library normal_distribution

Parameters
meanThe mean of the distribution.
varianceThe variance of the distribution.
Returns
The value sampled from the associated distribution

Example

Random* random = construct->random;
const int nrolls = 10000; // number of experiments
const int nstars = 100; // maximum number of stars to distribute
int p[10] = {};
for (int i = 0; i < nrolls; ++i) {
float number = random->normal(5.0, 2.0);
if ((number >= 0.0) && (number < 10.0)) ++p[int(number)];
}
std::cout << "normal_distribution (5.0,2.0):" << std::endl;
for (int i = 0; i < 10; ++i) {
std::cout << i << "-" << (i + 1) << ": ";
std::cout << std::string(p[i] * nstars / nrolls, '*') << std::endl;
}
float normal(float mean, float variance)
Generates a random value from a normal distribution.
Definition: RandomManager.cpp:45

Output:

normal_distribution (5.0,2.0):
0 - 1 : *
1 - 2 : ****
2 - 3 : *********
3 - 4 : ***************
4 - 5 : ******************
5 - 6 : *******************
6 - 7 : ***************
7 - 8 : ********
8 - 9 : ****
9 - 10 : *

Complexity

Constant

Exception Safety

If a negative value is given for the variance, an assertion is raised.

◆ order_by_pdf()

std::vector< unsigned int > Random::order_by_pdf ( std::vector< float > &  pdf)

Creates a vector of unique indexes ordered based on the submitted probability distribution function.

The first element of the vector is selected based on the unmodified pdf. After an index is saved, that element in the pdf is removed and the next element is slected based on the new pdf. This continues until no elements are left in the pdf.

If pdf elements are zero, those elements are automatically removed before the ordered vector is created.

Parameters
pdfThe probability distribution for which the unique vector of indexes is ordered upon.
Returns
A vector of unique indexes. Elements at the beginning of the array correlate most strongly with the indexes in the pdf that are the largest and vice versa.

Example

Random* random = construct->random;
std::vector<float> pdf = { 1,5,2,1,3 };
std::vector<unsigned int> ordered_indexes = random->order_by_pdf(pdf);
std::cout << "Probabilistically ordered indexes are" << std::endl;
for(auto it = ordered_index.begin(); it != ordered_index.end(); ++it) {
std::cout << *it << std::endl;
}
std::vector< unsigned int > order_by_pdf(std::vector< float > &pdf)
Creates a vector of unique indexes ordered based on the submitted probability distribution function.
Definition: RandomManager.cpp:78

Output:

Probabilistically ordered indexes are
1
4
0
2
3

Complexity

Number of non-zero elements in the pdf squared.

Iterator validity

No changes

Exception Safety

An assertion is raised if any values in pdf are less than zero or if all elements are zero.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ poisson_number()

unsigned int Random::poisson_number ( float  lambda)

Generates a random integer from a poisson distribution.

Uses the standard library poisson_distribution

Parameters
lambdaThe mean of the distribution.
Returns
The value sampled from the associated distribution

Example

Random* random = construct->random;
const int nrolls = 10000; // number of experiments
const int nstars = 100; // maximum number of stars to distribute
int p[10] = {};
for (int i = 0; i < nrolls; ++i) {
unsigned int number = random->poisson(4.1);
if (number < 10) ++p[number];
}
std::cout << "poisson_distribution (mean=4.1):" << std::endl;
for (int i = 0; i < 10; ++i)
std::cout << i << ": " << std::string(p[i] * nstars / nrolls, '*') << std::endl;
}

Output:

poisson_distribution (mean=4.1):
0 : *
1 : ******
2 : *************
3 : *******************
4 : *******************
5 : ***************
6 : ***********
7 : ******
8 : ***
9 : *

Complexity

Constant

Exception Safety

If a negative value is given for the mean, an assertion is raised.

◆ randombool()

bool Random::randombool ( float  probability = .5)

Generates a random boolean.

Parameters
probabilityThe probability the boolean is true. Default value is 0.5.
Returns
The value sampled from the associated distribution

Example

Random* random = construct->random;
std::cout << "random booleans with 70 percent true" << std::endl;
for(int i = 0; i < 10; i++) {
std::cout << random->randombool(.7) << std::endl;
}
bool randombool(float probability=.5)
Generates a random boolean.
Definition: RandomManager.cpp:57

Output:

some random numbers between 0 and 10
0
0
1
1
1
1
1
1
1
0

Complexity

Constant

Exception Safety

If a negative value is given for the probability, an assertion is raised.

Here is the call graph for this function:

◆ uniform() [1/2]

float Random::uniform ( )
noexcept

Generates a U(0,1) as a float.

Uses the standard library uniform_real_distribution

Returns
The value sampled from the associated distribution

Example

const int nrolls = 10000;
const int nstarts = 95;
const int nintervals = 10;
int p[nintervals]={};
Random* random = construct->random;
for (int i = 0; i < nrolls; ++i) ++p[int(nintervals * random->uniform())];
std::cout << "uniform distribution" << std::endl;
for (int i = 0; i < nintervals; ++i) {
std::cout << float(i) / nintervals << "-" << float(i + 1) / nintervals << ": ";
std::cout << std::string(p[i] * nstars / nrolls, '*') << std::endl;
}
float uniform() noexcept
Generates a U(0,1) as a float.
Definition: RandomManager.cpp:7

Output:

uniform distribution
0.0 - 0.1 : *********
0.1 - 0.2 : *********
0.2 - 0.3 : *********
0.3 - 0.4 : *********
0.4 - 0.5 : *********
0.5 - 0.6 : *********
0.6 - 0.7 : *********
0.7 - 0.8 : *********
0.8 - 0.9 : *********
0.9 - 1.0 : *********

Complexity

Constant.

Exception Safety

Strong Guarantee: This function never throws an exception.

Here is the caller graph for this function:

◆ uniform() [2/2]

float Random::uniform ( float  min,
float  max 
)
noexcept

Generates a U(min,max) as a float.

Parameters
minThe smallest value in the range of the uniform distribution.
maxThe largest but non-inclusive value in the range of the uniform distribution.
Returns
The value sampled from the associated distribution

Example

Random* random = construct->random;
std::cout << "some random numbers between -5 and 10" << std::endl;
for(int i = 0; i < 10; i++) {
std::cout << random->uniform(-5,10) << std::endl;
}

Output:

some random numbers between -5 and 10
-4.11045
6.32127
7.68560
9.96905
0.62124
3.94087
5.23497
4.11221
2.00376
2.58868

Complexity

Constant

Exception Safety

Strong Guarantee: This function never throws an exception.

◆ vector_shuffle()

template<typename T >
void Random::vector_shuffle ( std::vector< T > &  A)
inlinenoexcept

Shuffles a vector so that each element is moved to another random element.

A non-zero chance exists that the element does not change position.

Parameters
AVector of elements that are to be shuffled.

Example

Random* random = construct->random;
std::vector<int> numbers;
for(int i = 0; i < 10; i++) numbers.push_back(i);
random->vector_shuffle(numbers);
std::cout << "shuffled list of numbers" << std::endl;
for(int i =0; i < 10; i++) std::cout << numbers[i] << std::endl;
void vector_shuffle(std::vector< T > &A) noexcept
Shuffles a vector so that each element is moved to another random element.
Definition: RandomManager.h:476

Output:

shuffled list of numbers
6
9
4
2
3
1
7
8
0
5

Complexity

Linear in size of vector.

Iterator validity

Iterators remain valid, however the elements they point to have been modified.

Exception Safety

Strong Guarantee: This function never throws an exception.