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, 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.

Re-exports

• pub use self::bernoulli::Bernoulli;
• pub use self::bernoulli::BernoulliError;
• pub use self::distribution::Distribution;
• pub use self::distribution::DistIter;
• pub use self::distribution::DistMap;
• pub use self::float::Open01;
• pub use self::float::OpenClosed01;
• pub use self::other::Alphanumeric;
• pub use self::slice::Slice;

Modules

• hidden_export 👻
• uniform
  A distribution uniformly sampling numbers within a given range.

Structs

• 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.