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`, `Rng::gen_range` and of course `Rng::sample`.

Abstractly, a probability distribution describes the probability of occurance 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::gen_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 distribution object than to call `Rng::gen_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::gen_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 `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::weighted::WeightedError;`
`pub use self::weighted::WeightedIndex;`

Modules

The Bernoulli distribution.

The binomial distribution.

The Cauchy distribution.

The dirichlet distribution.

The exponential distribution.

Basic floating-point number distributions

The Gamma and derived distributions.

The implementations of the `Standard` distribution for integer types.

The normal and derived distributions.

The implementations of the `Standard` distribution for other built-in types.

The Pareto distribution.

The Poisson distribution.

The triangular distribution.

A distribution uniformly sampling numbers within a given range.

Math helper functions

The Weibull distribution.

Weighted index sampling

Structs

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

The Bernoulli distribution.

The Beta distribution with shape parameters `alpha` and `beta`.

BinomialDeprecated

The binomial distribution `Binomial(n, p)`.

CauchyDeprecated

The Cauchy distribution `Cauchy(median, scale)`.

ChiSquaredDeprecated

The chi-squared distribution `χ²(k)`, where `k` is the degrees of freedom.

DirichletDeprecated

The dirichelet distribution `Dirichlet(alpha)`.

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

ExpDeprecated

The exponential distribution `Exp(lambda)`.

Exp1Deprecated

Samples floating-point numbers according to the exponential distribution, with rate parameter `λ = 1`. This is equivalent to `Exp::new(1.0)` or sampling with `-rng.gen::<f64>().ln()`, but faster.

FisherFDeprecated

The Fisher F distribution `F(m, n)`.

The Gamma distribution `Gamma(shape, scale)` distribution.

LogNormalDeprecated

The log-normal distribution `ln N(mean, std_dev**2)`.

NormalDeprecated

The normal distribution `N(mean, std_dev**2)`.

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.

ParetoDeprecated

Samples floating-point numbers according to the Pareto distribution

PoissonDeprecated

The Poisson distribution `Poisson(lambda)`.

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.

StandardNormalDeprecated

Samples floating-point numbers according to the normal distribution `N(0, 1)` (a.k.a. a standard normal, or Gaussian). This is equivalent to `Normal::new(0.0, 1.0)` but faster.

StudentTDeprecated

The Student t distribution, `t(nu)`, where `nu` is the degrees of freedom.

TriangularDeprecated

The triangular distribution.

Sample values uniformly between two bounds.

UnitCircleDeprecated

Samples uniformly from the edge of the unit circle in two dimensions.

Samples uniformly from the surface of the unit sphere in three dimensions.

WeibullDeprecated

Samples floating-point numbers according to the Weibull distribution

Enums

Error type returned from `Bernoulli::new`.

Traits

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