Module rand::distributions
source · [−]Expand description
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” section of
Standard documentation 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.
WeightedIndex can be used to do weighted sampling from a set of items,
such as from an array.
Non-uniform probability distributions
Rand currently provides the following probability distributions:
- Related to real-valued quantities that grow linearly
(e.g. errors, offsets):
Normaldistribution, andStandardNormalas a primitiveCauchydistribution
- Related to Bernoulli trials (yes/no events, with a given probability):
BinomialdistributionBernoullidistribution, similar toRng::gen_bool.
- Related to positive real-valued quantities that grow exponentially
(e.g. prices, incomes, populations):
LogNormaldistribution
- Related to the occurrence of independent events at a given rate:
- Gamma and derived distributions:
GammadistributionChiSquareddistributionStudentTdistributionFisherFdistribution
- Triangular distribution:
BetadistributionTriangulardistribution
- Multivariate probability distributions
DirichletdistributionUnitSphereSurfacedistributionUnitCircledistribution
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() }
}
}Modules
A distribution uniformly sampling numbers within a given range.
Structs
Sample a char, uniformly distributed over ASCII letters and numbers:
a-z, A-Z and 0-9.
The Bernoulli distribution.
The Beta distribution with shape parameters alpha and beta.
The binomial distribution Binomial(n, p).
The Cauchy distribution Cauchy(median, scale).
The chi-squared distribution χ²(k), where k is the degrees of
freedom.
The dirichelet distribution Dirichlet(alpha).
An iterator that generates random values of T with distribution D,
using R as the source of randomness.
The exponential distribution Exp(lambda).
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.
The Fisher F distribution F(m, n).
The Gamma distribution Gamma(shape, scale) distribution.
The log-normal distribution ln N(mean, std_dev**2).
The normal distribution N(mean, std_dev**2).
A distribution to sample floating point numbers uniformly in the open
interval (0, 1), i.e. not including either endpoint.
A distribution to sample floating point numbers uniformly in the half-open
interval (0, 1], i.e. including 1 but not 0.
Samples floating-point numbers according to the Pareto distribution
The Poisson distribution Poisson(lambda).
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.
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.
The Student t distribution, t(nu), where nu is the degrees of
freedom.
The triangular distribution.
Sample values uniformly between two bounds.
Samples uniformly from the edge of the unit circle in two dimensions.
Samples uniformly from the surface of the unit sphere in three dimensions.
Samples floating-point numbers according to the Weibull distribution
A value with a particular weight for use with WeightedChoice.
A distribution that selects from a finite collection of weighted items.
A distribution using weighted sampling to pick a discretely selected item.
Enums
Error type returned from WeightedIndex::new.
Traits
Types (distributions) that can be used to create a random instance of T.