Module rand::distributions[−][src]

Generating random samples from probability distributions.

This module is the home of the Distribution trait and several of its implementations. It is the workhorse behind some of the convenient functionality of the Rng trait, including gen, gen_range and of course sample.

Abstractly, a probability distribution describes the probability of occurance of each value in its sample space.

More concretely, an implementation of Distribution<T> for type X is an algorithm for choosing values from the sample space (a subset of T) according to the distribution X represents, using an external source of randomness (an RNG supplied to the sample function).

A type X may implement Distribution<T> for multiple types T. Any type implementing Distribution is stateless (i.e. immutable), but it may have internal parameters set at construction time (for example, Uniform allows specification of its sample space as a range within T).

The `Standard` distribution

The Standard distribution is important to mention. This is the distribution used by Rng::gen() and represents the "default" way to produce a random value for many different types, including most primitive types, tuples, arrays, and a few derived types. See the documentation of Standard for more details.

Implementing Distribution<T> for Standard for user types T makes it possible to generate type T with Rng::gen(), and by extension also with the random() function.

Distribution to sample from a `Uniform` range

The Uniform distribution is more flexible than Standard, but also more specialised: it supports fewer target types, but allows the sample space to be specified as an arbitrary range within its target type T. Both Standard and Uniform are in some sense uniform distributions.

Values may be sampled from this distribution using Rng::gen_range or by creating a distribution object with Uniform::new, Uniform::new_inclusive or From<Range>. When the range limits are not known at compile time it is typically faster to reuse an existing distribution object than to call Rng::gen_range.

User types T may also implement Distribution<T> for Uniform, although this is less straightforward than for Standard (see the documentation in the uniform module. Doing so enables generation of values of type T with Rng::gen_range.

Other distributions

There are surprisingly many ways to uniformly generate random floats. A range between 0 and 1 is standard, but the exact bounds (open vs closed) and accuracy differ. In addition to the Standard distribution Rand offers Open01 and OpenClosed01. See Floating point implementation for more details.

Alphanumeric is a simple distribution to sample random letters and numbers of the char type; in contrast Standard may sample any valid char.

Non-uniform probability distributions

Rand currently provides the following probability distributions:

Related to real-valued quantities that grow linearly (e.g. errors, offsets):
- Normal distribution, and StandardNormal as a primitive
- Cauchy distribution
Related to Bernoulli trials (yes/no events, with a given probability):
- Binomial distribution
- Bernoulli distribution, similar to Rng::gen_bool.
Related to positive real-valued quantities that grow exponentially (e.g. prices, incomes, populations):
- LogNormal distribution
Related to the occurrence of independent events at a given rate:
- Poisson distribution
- Exponential distribution, and Exp1 as a primitive
Gamma and derived distributions:
- Gamma distribution
- ChiSquared distribution
- StudentT distribution
- FisherF distribution

Examples

Sampling from a distribution:

use rand::{thread_rng, Rng};
use rand::distributions::Exp;

let exp = Exp::new(2.0);
let v = thread_rng().sample(exp);
println!("{} is from an Exp(2) distribution", v);

Implementing the Standard distribution for a user type:

use rand::Rng;
use rand::distributions::{Distribution, Standard};

struct MyF32 {
    x: f32,
}

impl Distribution<MyF32> for Standard {
    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> MyF32 {
        MyF32 { x: rng.gen() }
    }
}

Re-exports

pub use self::uniform::Uniform as Range;

Modules

range	[ Deprecated ] DEPRECATED: Use `distributions::uniform` instead.
uniform	A distribution uniformly sampling numbers within a given range.

Structs

Alphanumeric	Sample a `char`, uniformly distributed over ASCII letters and numbers: a-z, A-Z and 0-9.
Bernoulli	The Bernoulli distribution.
Binomial	The binomial distribution `Binomial(n, p)`.
Cauchy	The Cauchy distribution `Cauchy(median, scale)`.
ChiSquared	The chi-squared distribution `χ²(k)`, where `k` is the degrees of freedom.
DistIter	An iterator that generates random values of `T` with distribution `D`, using `R` as the source of randomness.
Exp	The exponential distribution `Exp(lambda)`.
Exp1	Samples floating-point numbers according to the exponential distribution, with rate parameter `λ = 1`. This is equivalent to `Exp::new(1.0)` or sampling with `-rng.gen::<f64>().ln()`, but faster.
FisherF	The Fisher F distribution `F(m, n)`.
Gamma	The Gamma distribution `Gamma(shape, scale)` distribution.
LogNormal	The log-normal distribution `ln N(mean, std_dev**2)`.
Normal	The normal distribution `N(mean, std_dev**2)`.
Open01	A distribution to sample floating point numbers uniformly in the open interval `(0, 1)`, i.e. not including either endpoint.
OpenClosed01	A distribution to sample floating point numbers uniformly in the half-open interval `(0, 1]`, i.e. including 1 but not 0.
Pareto	Samples floating-point numbers according to the Pareto distribution
Poisson	The Poisson distribution `Poisson(lambda)`.
Standard	A generic random value distribution, implemented for many primitive types. Usually generates values with a numerically uniform distribution, and with a range appropriate to the type.
StandardNormal	Samples floating-point numbers according to the normal distribution `N(0, 1)` (a.k.a. a standard normal, or Gaussian). This is equivalent to `Normal::new(0.0, 1.0)` but faster.
StudentT	The Student t distribution, `t(nu)`, where `nu` is the degrees of freedom.
Uniform	Sample values uniformly between two bounds.
Weighted	A value with a particular weight for use with `WeightedChoice`.
WeightedChoice	A distribution that selects from a finite collection of weighted items.

Traits

Distribution	Types (distributions) that can be used to create a random instance of `T`.
IndependentSample	[ Deprecated ] `Sample`s that do not require keeping track of state.
Sample	[ Deprecated ] Types that can be used to create a random instance of `Support`.