[−][src]Module rand::distributions
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):
Normal
distribution, andStandardNormal
as a primitiveCauchy
distribution
- Related to Bernoulli trials (yes/no events, with a given probability):
- 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:
- Gamma and derived distributions:
Gamma
distributionChiSquared
distributionStudentT
distributionFisherF
distribution
- Triangular distribution:
Beta
distributionTriangular
distribution
- Multivariate probability distributions
Dirichlet
distributionUnitSphereSurface
distributionUnitCircle
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() } } }
Modules
uniform | A distribution uniformly sampling numbers within a given range. |
Structs
Alphanumeric | Sample a |
Bernoulli | The Bernoulli distribution. |
Beta | The Beta distribution with shape parameters |
Binomial | The binomial distribution |
Cauchy | The Cauchy distribution |
ChiSquared | The chi-squared distribution |
Dirichlet | The dirichelet distribution |
DistIter | An iterator that generates random values of |
Exp | The exponential distribution |
Exp1 | Samples floating-point numbers according to the exponential distribution,
with rate parameter |
FisherF | The Fisher F distribution |
Gamma | The Gamma distribution |
LogNormal | The log-normal distribution |
Normal | The normal distribution |
Open01 | A distribution to sample floating point numbers uniformly in the open
interval |
OpenClosed01 | A distribution to sample floating point numbers uniformly in the half-open
interval |
Pareto | Samples floating-point numbers according to the Pareto distribution |
Poisson | The Poisson distribution |
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
|
StudentT | The Student t distribution, |
Triangular | The triangular distribution. |
Uniform | Sample values uniformly between two bounds. |
UnitCircle | Samples uniformly from the edge of the unit circle in two dimensions. |
UnitSphereSurface | Samples uniformly from the surface of the unit sphere in three dimensions. |
Weibull | Samples floating-point numbers according to the Weibull distribution |
Weighted | Deprecated A value with a particular weight for use with |
WeightedChoice | Deprecated A distribution that selects from a finite collection of weighted items. |
WeightedIndex | A distribution using weighted sampling to pick a discretely selected item. |
Enums
WeightedError | Error type returned from |
Traits
Distribution | Types (distributions) that can be used to create a random instance of |