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.