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, e.g. Rng::gen
and of course
Rng::sample
.
Abstractly, a probability distribution describes the probability of occurrence 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.
Random characters
Alphanumeric
is a simple distribution to sample random letters and
numbers of the char
type; in contrast Standard
may sample any valid
char
.
Uniform numeric ranges
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::sample(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
Uniform
object than to call [Rng::sample(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::sample(Range)
].
Open and half-open ranges
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.
Non-uniform sampling
Sampling a simple true/false outcome with a given probability has a name:
the Bernoulli
distribution (this is used by Rng::gen_bool
).
For weighted sampling from a sequence of discrete values, use the
WeightedIndex
distribution.
This crate no longer includes other non-uniform distributions; instead
it is recommended that you use either rand_distr
or statrs
.
Modules
- A distribution uniformly sampling numbers within a given range.
- Weighted index sampling
Structs
- Sample a
u8
, uniformly distributed over ASCII letters and numbers: a-z, A-Z and 0-9. - The Bernoulli distribution.
- An iterator that generates random values of
T
with distributionD
, usingR
as the source of randomness. - A distribution of values of type
S
derived from the distributionD
by mapping its output of typeT
through the closureF
. - 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. - A distribution to sample items uniformly from a slice.
- 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.
- Sample values uniformly between two bounds.
- WeightedIndex
alloc
A distribution using weighted sampling of discrete items
Enums
- Error type returned from
Bernoulli::new
. - WeightedError
alloc
Error type returned fromWeightedIndex::new
.
Traits
String
sampler- Types (distributions) that can be used to create a random instance of
T
.