Class RNGController

Inheritance Relationships

Base Type

Class Documentation

class RNGController : public virtual random_numbers::Xoroshiro256plus

Contains the functions for random number generation, based on the Xoroshiro256+ algorithm.

Public Functions

RNGController()

Standard constructor.

void setSeed(uint64_t seed)

Sets the seed to the given input. Is only seeded if the seed hasn’t already been provided.

Parameters
  • seed: the input seed.

void wipeSeed()

Clears the seed, if it has already been set. Keeps other simulation parameters, such as sigma and tau.

unsigned long i0(unsigned long max)

Generates a random number uniformly from 0 to the maximum value provided.

Return
an integer of the produced random number.
Parameters
  • max: the maximum number.

double norm()

Generates a normally distributed number Uses the standard normal distribution using the Ziggurat method.

Return
the random number from a normal distribution.

double rayleigh()

Returns a random distance from a 2 dimensional normal distribution, also called the rayleigh distribution.

Return
dispersal distance of a rayleigh distribution

double rayleighMinDist(const double &dist)

Generates a random distance from a rayleigh distribution, given that the distance is more than some minimum.

Return
a random distance greater than the minimum provided
Parameters
  • dist: the minimum distance to generate

double rayleighCDF(const double &dist)

Gets the cumulative probability of a distance from the rayleigh distribution.

Return
the probability of producing the given distance
Parameters
  • dist: the distance to obtain the probability of

void setDispersalParams(const double sigmain, const double tauin)

Sets the dispersal parameters, avoiding requirement to provide these numbers each function call. This is only relevant for fat-tailed dispersal calls.

Parameters
  • sigmain: the fatness of the fat-tailed dispersal kernel.
  • tauin: the width of the fat-tailed dispersal kernel.

double fattail(double z)

Call from the fat-tailed dispersal kernel with the provided sigma.

Return
a random number drawn from the fat-tailed dispersal kernel.
Parameters
  • z: the desired sigma.

double fattailCDF(const double &distance)

Gets the cumulative probability density of travelling the distance.

Return
the probability of dispersing less than or equal to distance
Parameters
  • distance: the distance to obtain the cumulative probability for

double fattailMinDistance(const double &min_distance)

Gets a fat-tailed random distance greater than some minimum.

Return
a fat-tailed distance greater than the minimum
Parameters
  • min_distance: the minimum distance to return

double fattail()

Call from fat-tailed dispersal kernel. This function requires setDispersalParams() has already been called.

Return
a random number drawn from the fat-tailed dispersal kernel.

double fattail_old()

Old version of the function call reparameterised for different nu and sigma.

Return
a random number drawn from the fat-tailed dispersal kernel.

double direction()

Generates a direction in radians.

Return
the direction in radians

bool event(double event_probability)

For a given event probability, returns the probability that the event has occured.

Return
whether or not the event has occured.
Parameters
  • event_probability: the event probability.

double normUniform()

Normal distribution, with percentage chance to choose a uniform distribution instead.

Note
This function will not produce the same output as norm() for the same parameters, even with a zero chance of picking from the uniform distribution (due to random number draws).
Return
normally (or uniformly) distributed number

double normUniformMinDistance(const double &min_distance)

Generates a random distance from a norm-uniform distribution, given that the distance is more than some minimum.

Return
a random distance greater than the minimum provided
Parameters
  • dist: the minimum distance to generate

double uniform()

Draws a random number from a uniform distribution between 0 and cutoff.

Return
a random number in (0, cutoff)

double uniformMinDistance(const double &min_distance)

Generates a random distance from a uniform distribution, given that the distance is more than some minimum.

Return
a random distance greater than the minimum provided
Parameters
  • dist: the minimum distance to generate

double uniformUniform()

Two uniform distributions, the first between 0 and 0.1*cutoff, and the second between 0.9*cutoff and cutoff. Selects from both distributions equally.

Note
The mean for this function should be identical to a uniform distribution between 0 and cutoff.
Return
uniformly distributed number

double uniformUniformMinDistance(const double &min_distance)

Generates a random distance from a uniform-uniform distribution, given that the distance is more than some minimum.

Return
a random distance greater than the minimum provided
Parameters
  • dist: the minimum distance to generate

void setDispersalMethod(const string &dispersal_method, const double &m_probin, const double &cutoffin)

Sets the dispersal method by creating the link between dispersalFunction() and the correct dispersal character.

Parameters
  • dispersal_method: string containing the dispersal type. Can be one of [normal, fat-tail, norm-uniform]
  • m_probin: the probability of drawing from the uniform distribution. Only relevant for uniform dispersals.
  • cutoffin: the maximum value to be drawn from the uniform dispersal. Only relevant for uniform dispersals.

double dispersal()

Runs the dispersal with the allocated dispersal function.

Note
This function will never return a value larger than the size of LONG_MAX to avoid issues of converting doubles to integers. For dispersal distance within coalescence simulations, this is seemed a reasonable assumption, but may cause issues if code is re-used in later projects.
Return
distance the dispersal distance

double dispersalMinDistance(const double &min_distance)

Get a dispersal distance with some minimum.

This function will never return doubles larger than LONG_MAX to avoid integer overflows.

Return
the random dispersal distance greater than or equal to the minimum
Parameters
  • min_distance: the minimum distance to disperse

unsigned long randomLogarithmic(long double alpha)

Sample from a logarithmic distribution.

Uses the LK sampling method for generating random numbers from a logarithmic distribution, as described by Kemp (1981).

Return
the randomly generated logarithmic number
Parameters
  • alpha: alpha parameter for the logarithmic distribution

double randomExponential(double lambda)
uint64_t next()

Generates the next random integer.

Return
a random integer from 0 to max of 2^64

double d01()

Generates a random number in the range [0, 1)

Return
a random double

void jump()

Jumps the generator forwards by the equivalent of 2^128 calls of next() - useful for parallel computations where different random number sequences are required.

Public Static Functions

template<typename T>
static const T exponentialDistribution(const T lambda, const T r)

Protected Attributes

std::array<uint64_t, 4> shuffle_table

Friends

ostream &operator<<(ostream &os, const RNGController &r)

Outputs the NRrand object to the output stream. Used for saving the object to file.

Return
the output stream.
Parameters
  • os: the output stream.
  • r: the NRrand object to output.

istream &operator>>(istream &is, RNGController &r)

Inputs the NRrand object from the input stream. Used for reading the NRrand object from a file.

Return
the input stream.
Parameters
  • is: the input stream.
  • r: the NRrand object to input to.