Module distr 

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::random] 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 Uniform distribution

The StandardUniform distribution is important to mention. This is the distribution used by [Rng::random] 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 StandardUniform for more details.

Implementing [Distribution<T>] for StandardUniform for user types T makes it possible to generate type T with [Rng::random], and by extension also with the random function.

Other standard uniform distributions

[Alphanumeric] is a simple distribution to sample random letters and numbers of the char type; in contrast StandardUniform may sample any valid char.

There’s also an [Alphabetic] distribution which acts similarly to [Alphanumeric] but doesn’t include digits.

For floats (f32, f64), StandardUniform samples from [0, 1). Also provided are [Open01] (samples from (0, 1)) and [OpenClosed01] (samples from (0, 1]). No option is provided to sample from [0, 1]; it is suggested to use one of the above half-open ranges since the failure to sample a value which would have a low chance of being sampled anyway is rarely an issue in practice.

Parameterized Uniform distributions

The Uniform distribution provides uniform sampling over a specified range on a subset of the types supported by the above distributions.

Implementations support single-value-sampling via Rng::random_range(Range). Where a fixed (non-const) range will be sampled many times, it is likely faster to pre-construct a [Distribution] object using Uniform::new, Uniform::new_inclusive or From<Range>.

Non-uniform sampling

Sampling a simple true/false outcome with a given probability has a name: the [Bernoulli] distribution (this is used by [Rng::random_bool]).

For weighted sampling of discrete values see the [weighted] module.

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::Iter;

pub use self::distribution::Map;

pub use self::float::Open01;

pub use self::float::OpenClosed01;

pub use self::other::Alphabetic;

pub use self::other::Alphanumeric;

Modules

hidden_export 👻

slice

Distributions over slices

uniform

A distribution uniformly sampling numbers within a given range.

Structs

StandardUniform

The Standard Uniform distribution

Uniform

Sample values uniformly between two bounds.