Random distributions

For maximum flexibility when producing random values, we define the Distribution trait:


# #![allow(unused_variables)]
#fn main() {
// a producer of data of type T:
pub trait Distribution<T> {
    // the key function:
    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> T;

    // a convenience function defined using sample:
    fn sample_iter<'a, R>(&'a self, rng: &'a mut R) -> DistIter<'a, Self, R, T>
    where
        Self: Sized,
        R: Rng,
    { ... }
}
#}

Rand provides implementations of many different distributions; for the full list see the distributions module; the most common are highlighted below.

Uniform distributions

The most obvious type of distribution is the one we already discussed: one without pattern, where each value or range of values is equally likely. This is known as uniform.

Rand actually has several variants of this:

  • Standard requires no parameters and produces uniformly distributed values over the entire range of the output type (for bool and integers) or over the range from 0 to 1 (for floats) or over valid Unicode code points. It also has extensions to tuples, array types and Option.
  • Uniform is parametrised with low and high points, and produces values uniformly distributed within this range.
  • Alphanumeric is uniform over the values 0-9A-Za-z
  • Open01 and OpenClosed01 are variations of Standard for floating point numbers between 0 and 1 (partially) exclusive of end points.

For convenience, Rng::gen and random are short-cuts to Standard, and Rng::gen_range is a short-cut to Uniform, allowing things like:


# #![allow(unused_variables)]
#fn main() {
# extern crate rand;
# use rand::prelude::*;
let mut rng = thread_rng();
let coord: (f64, f64) = rng.gen();
let die_roll = rng.gen_range(1, 7);
#}

More continuous distributions

The exponential distribution, Exp, simulates time until decay, assuming a fixed rate of decay (i.e. exponential decay).

The Normal distribution (also known as Gaussian) simulates sampling from the Normal distribution ("Bell curve") with the given mean and standard deviation. The LogNormal is related: for sample X from the log-normal distribution, log(X) is normally distributed; this "skews" the normal distribution to avoid negative values and to have a long positive tail.

The UnitCircle and UnitSphereSurface distributions simulate uniform sampling from the edge of a circle or surface of a sphere.

The Cauchy distribution (also known as the Lorentz distribution) is the distribution of the x-intercept of a ray from point (x0, γ) with uniformly distributed angle.

The Beta distribution is a two-parameter probability distribution, whose output values lie between 0 and 1. The Dirichlet distribution is a generalisation to any positive number of parameters.

Discrete distributions

The Bernoulli distribution is very simple: given a probability p (or a ratio num / denom), a boolean value is produced with the given probability of being true (simulating a trial with probability p of success).

For convenience, Rng::gen_bool and Rng::gen_ratio are short-cuts to Bernoulli.

The Binomial distribution is related: given a probability p and a number n, this distribution simulates running n Bernoulli trials and tells you the number which were successful.

The Poisson distribution expresses the expected number of events occurring within a fixed interval, given that events occur with fixed rate λ.

Weighted sampling

Finally, WeightedIndex is a discrete distribution sampling from a finite selection of choices each with given weight.