easy_randist.h File Reference

The random number distributions API. More...

Typedefs
typedef struct _easy_ran_discrete_t	easy_ran_discrete_t

Functions
double	easy_ran_gaussian (const easy_rng *r, double sigma)
double	easy_ran_gaussian_ziggurat (const easy_rng *r, double sigma)
double	easy_ran_gaussian_ratio_method (const easy_rng *r, double sigma)
double	easy_ran_ugaussian (const easy_rng *r)
double	easy_ran_ugaussian_ratio_method (const easy_rng *r)
double	easy_ran_exponential (const easy_rng *r, double mu)
double	easy_ran_cauchy (const easy_rng *r, double a)
double	easy_ran_gamma (const easy_rng *r, double k, double theta)
double	easy_ran_flat (const easy_rng *r, double a, double b)
double	easy_ran_lognormal (const easy_rng *r, double mu, double sigma)
double	easy_ran_chisq (const easy_rng *r, double k)
double	easy_ran_fdist (const easy_rng *r, double d_1, double d_2)
double	easy_ran_tdist (const easy_rng *r, double nu)
double	easy_ran_weibull (const easy_rng *r, double lambda, double k)
easy_ran_discrete_t *	easy_ran_discrete_preproc (size_t K, const double *P)
size_t	easy_ran_discrete (const easy_rng *r, const easy_ran_discrete_t *g)
void	easy_ran_discrete_free (easy_ran_discrete_t *g)
unsigned int	easy_ran_poisson (const easy_rng *r, double lambda)
unsigned int	easy_ran_bernoulli (const easy_rng *r, double p)
unsigned int	easy_ran_binomial (const easy_rng *r, double p, unsigned int n)
unsigned int	easy_ran_negative_binomial (const easy_rng *r, double p, unsigned int n)
unsigned int	easy_ran_geometric (const easy_rng *r, double p)

Detailed Description

The random number distributions API.

Author

Tom Schoonjans

This header provides wrappers around the random number distributions that are offered by C++11's random templates. GSL's random number distributions, upon which this API is based, offers considerably more types of distributions. In case one of these (rather exotic) distributions is needed, the user is recommended to use GSL instead of this library.

Note

The functions outlined here are fully equivalent to their GSL counterparts. This means that in some cases, arguments passed to or values returned by the C++11 random number distributions were changed in order to obtain identical distributions. The main consequence is that one should not rely on the C++11 standard and its implementations to explain the output of these methods.

The documentation on this page, including the equations of the probability density functions, was sourced from Wikipedia. Links to the relevant pages have been included for each method.

Typedef Documentation

easy_ran_discrete_t

typedef struct _easy_ran_discrete_t easy_ran_discrete_t

An intentionally opaque structure containing a lookup table of a discrete distribution

Instances will only be available through pointers, and should be obtained and freed after usage through easy_ran_discrete_preproc() and easy_ran_discrete_free(), respectively.

Function Documentation

easy_ran_gaussian()

double easy_ran_gaussian	(	const easy_rng *	r,
		double	sigma
	)

Generate double precision real numbers according to a normal distribution

The probability density function of the normal distribution is defined as:

\[ f(x; \sigma) = \frac{1}{\sigma\sqrt{2\pi}}\exp\left(-\frac{1}{2}\left(\frac{x}{\sigma}\right)^2\right) \]

with \(\sigma\) the standard deviation.

Warning

Since the C++11 standard does not specify which algorithm should be used to implement this distribution, easy_ran_gaussian_ziggurat() and easy_ran_gaussian_ratio_method() map to this function.

Parameters

r	The random number generator instance
sigma	The standard deviation of the normal distribution

Returns

A double precision real number, sampled from a normal distribution

easy_ran_gaussian_ziggurat()

double easy_ran_gaussian_ziggurat	(	const easy_rng *	r,
		double	sigma
	)

Generate double precision real numbers according to a normal distribution

Warning

Since the C++11 standard does not specify which algorithm should be used to implement this distribution, this function maps to easy_ran_gaussian().

Parameters

r	The random number generator instance
sigma	The standard deviation of the normal distribution

Returns

A double precision real number, sampled from a normal distribution

easy_ran_gaussian_ratio_method()

double easy_ran_gaussian_ratio_method	(	const easy_rng *	r,
		double	sigma
	)

Generate double precision real numbers according to a normal distribution

Warning

Since the C++11 standard does not specify which algorithm should be used to implement this distribution, this function maps to easy_ran_gaussian().

Parameters

r	The random number generator instance
sigma	The standard deviation of the normal distribution

Returns

A double precision real number, sampled from a normal distribution

easy_ran_ugaussian()

double easy_ran_ugaussian

(

const easy_rng *

r

)

Generate double precision real numbers according to a unit normal distribution

The probability density function of the unit (or standard) normal distribution is defined as:

\[ f(x) = \frac{1}{\sqrt{2\pi}}\exp\left(-\frac{x^2}{2}\right) \]

Warning

Since the C++11 standard does not specify which algorithm should be used to implement this distribution, easy_ran_ugaussian_ratio_method() map to this function.

Parameters

r	The random number generator instance

Returns

A double precision real number, sampled from a unit normal distribution

easy_ran_ugaussian_ratio_method()

double easy_ran_ugaussian_ratio_method

(

const easy_rng *

r

)

Generate double precision real numbers according to a unit normal distribution

Warning

Since the C++11 standard does not specify which algorithm should be used to implement this distribution, this function maps to easy_ran_ugaussian().

Parameters

r	The random number generator instance

Returns

A double precision real number, sampled from a unit normal distribution

easy_ran_exponential()

double easy_ran_exponential	(	const easy_rng *	r,
		double	mu
	)

Generate double precision random numbers according to an exponential distribution

The probability density function of the exponential distribution is defined as:

\[ f(x;\mu) = \frac{1}{\mu}\exp\left(-\frac{x}{\mu}\right) \]

with \(\mu\) the inverse rate (also the distribution mean or scale factor) for positive \(x\)

Parameters

r	The random number generator instance
mu	The inverse rate

Returns

A positive double precision real number, sampled from an exponential distribution

easy_ran_cauchy()

double easy_ran_cauchy	(	const easy_rng *	r,
		double	a
	)

Generate double precision random numbers according to a Cauchy distribution

The probability density function of the Cauchy (or Lorentz, as it is widely known in spectroscopy) distribution is defined as:

\[ f(x;a) = \frac{1}{\pi a\left[1 + \left(\frac{x}{a}\right)^2\right]} \]

with \(a\) the scale parameter

Parameters

r	The random number generator instance
a	The scale parameter

Returns

A double precision real number, sampled from a Cauchy distribution

easy_ran_gamma()

double easy_ran_gamma	(	const easy_rng *	r,
		double	k,
		double	theta
	)

Generate double precision random numbers according to a Gamma distribution

The probability density function of the Gamma distribution is defined as:

\[ f(x;k,\theta) = \frac{1}{\Gamma(k) \theta^k} x^{k-1} \exp\left(-\frac{x}{\theta}\right) \]

with \(k\) the shape parameter and \(\theta\) for positive \(x\)

Parameters

r	The random number generator instance
k	The shape parameter (must be strictly positive)
theta	The scale parameter (must be strictly positive)

Returns

A positive double precision real number, sampled from a Gamma distribution

easy_ran_flat()

double easy_ran_flat	(	const easy_rng *	r,
		double	a,
		double	b
	)

Generate double precision random numbers according to a flat distribution

The probability density function of the flat (uniform) distribution is defined as:

\[ f(x;a,b) = \frac{1}{b - a} \]

with \(a\) and \(b\) the minimum and maximum values of the interval respectively.

Parameters

r	The random number generator instance
a	The minimum value of the sampling interval
b	The maximum value of the sampling interval

Returns

A double precision real number, sampled from a flat distribution

easy_ran_lognormal()

double easy_ran_lognormal	(	const easy_rng *	r,
		double	mu,
		double	sigma
	)

Generate double precision random numbers according to a log-normal distribution

The probability density function of the log-normal distribution is defined as:

\[ f(x;\mu,\sigma) = \frac{1}{x \sigma \sqrt{2 \pi}} \exp\left(-\frac{(\ln(x) - \mu)^2}{2 \sigma^2}\right) \]

with \(\mu\) the location parameter and \(\sigma\) the scale factor, for positive \(x\)

Parameters

r	The random number generator instance
mu	The position parameter
sigma	The scale parameter (must be strictly positive)

Returns

A positive double precision real number, sampled from a log-normal distribution

easy_ran_chisq()

double easy_ran_chisq	(	const easy_rng *	r,
		double	k
	)

Generate double precision random numbers according to a chi-squared distribution

The probability density function of the chi-squared distribution is defined as:

\[ f(x;k) = \frac{1}{2^{\frac{k}{2}}\Gamma\left(\frac{k}{2}\right)}x^{\frac{k}{2}-1}\exp\left(-\frac{x}{2}\right) \]

with \(k\) the degrees of freedom, for positive \(x\)

Parameters

r	The random number generator instance
k	The degrees of freedom

Returns

A positive double precision real number, sampled from a chi-squared distribution

easy_ran_fdist()

double easy_ran_fdist	(	const easy_rng *	r,
		double	d_1,
		double	d_2
	)

Generate double precision random numbers according to an F distribution

The probability density function of the F-distribution is defined as:

\[ f(x;d_1,d_2) = \frac{\sqrt{\frac{(d_1x)^{d_1}d_2^{d_2}}{(d_1x+d_2)^{(d_1+d_2)}}}}{xB\left(\frac{d_1}{2},\frac{d_2}{2}\right)} \]

with \(d_1\) and \(d_2\) the degrees of freedom and B the Beta function, for positive \(x\)

Parameters

r	The random number generator instance
d_1	The first degrees of freedom
d_2	The second degrees of freedom

Returns

A positive double precision real number, sampled from a F-distribution

easy_ran_tdist()

double easy_ran_tdist	(	const easy_rng *	r,
		double	nu
	)

Generate double precision random numbers according to a [Student's t-distribution](https://en.wikipedia.org/wiki/Student's_t-distribution)

The probability density function of the Student's t-distribution is defined as:

\[ f(x;\nu) = \frac{\Gamma\left(\frac{\nu+1}{2}\right)}{\sqrt{\nu\pi}\Gamma\left(\frac{\nu}{2}\right)}\left(1+\frac{x^2}{\nu}\right)^{-\frac{\nu+1}{2}} \]

with \(\nu\) the degrees of freedom.

Parameters

r	The random number generator instance
nu	The degrees of freedom

Returns

A double precision real number, sampled from a Student's t-distribution

easy_ran_weibull()

double easy_ran_weibull	(	const easy_rng *	r,
		double	lambda,
		double	k
	)

Generate double precision random numbers according to a Weibull distribution

The probability density function of the Weibull distribution is defined as:

\[ f(x;\lambda,k) = \frac{k}{\lambda}\left(\frac{x}{\lambda}\right)^{k-1}\exp\left(-\left(\frac{x}{\lambda}\right)^k\right) \]

with \(\lambda\) the scale parameter and \(k\) the shape parameter, for positive \(x\)

Parameters

r	The random number generator instance
lambda	The scale parameter
k	The shape parameter

Returns

A double precision real number, sampled from a Weibull distribution

easy_ran_discrete_preproc()

easy_ran_discrete_t* easy_ran_discrete_preproc	(	size_t	K,
		const double *	P
	)

Generate a lookup table for a discrete distribution

Free this table after usage with easy_ran_discrete_free()

Parameters

K	The length of the array P
P	An array of length K, containing the (positive) weights of the events

Returns

The lookup table. Pass this variable to easy_ran_discrete() to generate discrete random numbers based on the contents of P

Warning

The Fortran API drops the K argument as the size of the P array can be determined from the variable itself.

easy_ran_discrete()

size_t easy_ran_discrete	(	const easy_rng *	r,
		const easy_ran_discrete_t *	g
	)

Generate positive integers according to a discrete distribution

Parameters

r	The random number generator instance
g	The lookup table

Returns

A positive integer, sampled from a discrete distribution

easy_ran_discrete_free()

void easy_ran_discrete_free

(

easy_ran_discrete_t *

g

)

Frees the memory associated with a discrete distribution lookup table

Parameters

g	The lookup table

easy_ran_poisson()

unsigned int easy_ran_poisson	(	const easy_rng *	r,
		double	lambda
	)

Generate positive integers according to a Poisson distribution

The probability function of the Poisson distribution is defined as:

\[ f(k;\lambda) = \frac{\lambda^k\exp(-\lambda)}{k!} \]

with \(\lambda\) the average number of events in an interval, for positive integers \(k\)

Parameters

r	The random number generator instance
lambda	The average number of events in an interval

Returns

A positive integer, sampled from a Poisson distribution

easy_ran_bernoulli()

unsigned int easy_ran_bernoulli	(	const easy_rng *	r,
		double	p
	)

Generate zeroes and ones according to a Bernoulli distribution

The probability function of the Bernoulli distribution is defined as:

\[ f(k;p) = p^k(1-p)^{1-k} \]

with \(p\) the success probability between 0 and 1, for integers \(k\) restricted to 0 and 1

Parameters

r	The random number generator instance
p	The success probability

Returns

0 or 1, sampled from a Bernoulli distribution

easy_ran_binomial()

unsigned int easy_ran_binomial	(	const easy_rng *	r,
		double	p,
		unsigned int	n
	)

Generate positive integers according to a binomial distribution

The probability function of the binomial distribution is defined as:

\[ f(k;p,n) = {{n}\choose{k}}p^k(1-p)^{n-k} \]

with \(p\) the success probability between 0 and 1 for each trial, and \(n\) the number of trials, for positive integers \(k\)

Parameters

r	The random number generator instance
p	The success probability for each trial
n	The number of trials

Returns

A positive integer, sampled from a binomial distribution

easy_ran_negative_binomial()

unsigned int easy_ran_negative_binomial	(	const easy_rng *	r,
		double	p,
		unsigned int	n
	)

Generate positive integers according to a negative binomial distribution

The probability function of the negative binomial distribution is defined as:

\[ f(k;p,n) = {{n+k-1}\choose{k}}p^n(1-p)^k \]

with \(p\) the success probability between 0 and 1 for each trial, and \(n\) the number of successful trials, for positive integers \(k\), the number of failures

Warning

C++11 allows only for integer n's, unlike GSL where n is double

Parameters

r	The random number generator instance
p	The success probability for each trial
n	The number of successful trials

Returns

A positive integer, sampled from a negative binomial distribution

easy_ran_geometric()

unsigned int easy_ran_geometric	(	const easy_rng *	r,
		double	p
	)

Generate positive integers according to a geometric distribution

The probability function of the geometric distribution is defined as:

\[ f(k;p) = (1-p)^{k-1}p \]

with \(p\) the success probability between 0 and 1 for each trial, for positive integers \(k\) greater than one.

Parameters

r	The random number generator instance
p	The success probability for each trial

Returns

A positive integer, sampled from a geometric distribution