rustmax::rand

Module distr

Source
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::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.

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.

Modules§

  • slice
    Distributions over slices
  • uniform
    A distribution uniformly sampling numbers within a given range.
  • weighted
    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 Bernoulli(p).
  • Iter
    An iterator over a Distribution
  • Map
    A Distribution which maps sampled values to type S
  • 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.
  • StandardUniform
    The Standard Uniform distribution
  • Uniform
    Sample values uniformly between two bounds.

Enums§

Traits§