Module rand::distributions

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

uniform

A distribution uniformly sampling numbers within a given range.

weightedDeprecated

Weighted index sampling

Structs

Alphanumeric

Sample a u8, uniformly distributed over ASCII letters and numbers: +a-z, A-Z and 0-9.

Bernoulli

The Bernoulli distribution.

DistIter

An iterator that generates random values of T with distribution D, +using R as the source of randomness.

DistMap

A distribution of values of type S derived from the distribution D +by mapping its output of type T through the closure F.

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.

Slice

A distribution to sample items uniformly from a slice.

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.

Uniform

Sample values uniformly between two bounds.

WeightedIndex

A distribution using weighted sampling of discrete items

Enums

BernoulliError

Error type returned from Bernoulli::new.

WeightedError

Error type returned from WeightedIndex::new.

Traits

DistString

String sampler

Distribution

Types (distributions) that can be used to create a random instance of T.