...one of the most highly
regarded and expertly designed C++ library projects in the
world.

— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards

This is the documentation for a snapshot of the develop branch, built from commit 1aeed45f05.

Want to calculate the PDF (Probability Density Function) of a distribution? No problem, just use:

pdf(my_dist, x); // Returns PDF (density) at point x of distribution my_dist.

Or how about the CDF (Cumulative Distribution Function):

cdf(my_dist, x); // Returns CDF (integral from -infinity to point x) // of distribution my_dist.

And quantiles are just the same:

quantile(my_dist, p); // Returns the value of the random variable x // such that cdf(my_dist, x) == p.

If you're wondering why these aren't member functions, it's to make the
library more easily extensible: if you want to add additional generic operations
- let's say the *n'th moment* - then all you have to
do is add the appropriate non-member functions, overloaded for each implemented
distribution type.

Tip | |
---|---|

If you want random numbers that are distributed in a specific way, for example in a uniform, normal or triangular, see Boost.Random. Whilst in principal there's nothing to prevent you from using the quantile function to convert a uniformly distributed random number to another distribution, in practice there are much more efficient algorithms available that are specific to random number generation. |

For example, the binomial distribution has two parameters: n (the number of trials) and p (the probability of success on any one trial).

The `binomial_distribution`

constructor therefore has two parameters:

```
binomial_distribution(RealType n, RealType
p);
```

For this distribution the random
variate is k: the number of successes observed. The probability
density/mass function (pdf) is therefore written as *f(k; n, p)*.

Note | |
---|---|

The concept of a random
variable is closely linked to the term random
variate: a random variate is a particular value (outcome) of
a random variable. and distribution
parameters are conventionally distinguished (for example in Wikipedia
and Wolfram MathWorld) by placing a semi-colon or vertical bar)
For example, the binomial distribution probability distribution function
(PDF) is written as |

Note | |
---|---|

By convention, random
variate are lower case, usually k is integral, x if real, and
random variable
are upper case, K if integral, X if real. But this implementation treats
all as floating point values |

As noted above the non-member function `pdf`

has one parameter for the distribution object, and a second for the random
variate. So taking our binomial distribution example, we would write:

`pdf(binomial_distribution<RealType>(n, p), k);`

The ranges of random
variate values that are permitted and are supported can be tested
by using two functions `range`

and `support`

.

The distribution (effectively the random variate) is said to be 'supported' over a range that is "the smallest closed set whose complement has probability zero". MathWorld uses the word 'defined' for this range. Non-mathematicians might say it means the 'interesting' smallest range of random variate x that has the cdf going from zero to unity. Outside are uninteresting zones where the pdf is zero, and the cdf zero or unity.

For most distributions, with probability distribution functions one might
describe as 'well-behaved', we have decided that it is most useful for
the supported range to **exclude** random
variate values like exact zero **if the end point is
discontinuous**. For example, the Weibull (scale 1, shape 1) distribution
smoothly heads for unity as the random variate x declines towards zero.
But at x = zero, the value of the pdf is suddenly exactly zero, by definition.
If you are plotting the PDF, or otherwise calculating, zero is not the
most useful value for the lower limit of supported, as we discovered. So
for this, and similar distributions, we have decided it is most numerically
useful to use the closest value to zero, min_value, for the limit of the
supported range. (The `range`

remains from zero, so you will still get ```
pdf(weibull, 0)
== 0
```

).
(Exponential and gamma distributions have similarly discontinuous functions).

Mathematically, the functions may make sense with an (+ or -) infinite
value, but except for a few special cases (in the Normal and Cauchy distributions)
this implementation limits random variates to finite values from the `max`

to `min`

for the `RealType`

. (See
Handling
of Floating-Point Infinity for rationale).

Note | |
---|---|

Note that the discrete
distributions, including the binomial, negative binomial, Poisson
& Bernoulli, are all mathematically defined as discrete functions:
that is to say the functions However, because the method of calculation often uses continuous functions it is convenient to treat them as if they were continuous functions, and permit non-integral values of their parameters.
Users wanting to enforce a strict mathematical model may use
The quantile functions for these distributions are hard to specify in
a manner that will satisfy everyone all of the time. The default behaviour
is to return an integer result, that has been rounded This behaviour can be changed so that the quantile functions are rounded differently, or return a real-valued result using Policies. It is strongly recommended that you read the tutorial Understanding Quantiles of Discrete Distributions before using the quantile function on a discrete distribution. The reference docs describe how to change the rounding policy for these distributions. For similar reasons continuous distributions with parameters like "degrees of freedom" that might appear to be integral, are treated as real values (and are promoted from integer to floating-point if necessary). In this case however, there are a small number of situations where non-integral degrees of freedom do have a genuine meaning. |