Trait Distribution

pub trait Distribution<T> {
    // Required method
    fn sample<R>(&self, rng: &mut R) -> T
       where R: Rng + ?Sized;

    // Provided methods
    fn sample_iter<R>(self, rng: R) -> DistIter<Self, R, T> 
       where R: Rng,
             Self: Sized { ... }
    fn map<F, S>(self, func: F) -> DistMap<Self, F, T, S>
       where F: Fn(T) -> S,
             Self: Sized { ... }
}

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

It is possible to sample from a distribution through both the Distribution and Rng traits, via distr.sample(&mut rng) and rng.sample(distr). They also both offer the sample_iter method, which produces an iterator that samples from the distribution.

All implementations are expected to be immutable; this has the significant advantage of not needing to consider thread safety, and for most distributions efficient state-less sampling algorithms are available.

Implementations are typically expected to be portable with reproducible results when used with a PRNG with fixed seed; see the portability chapter of The Rust Rand Book. In some cases this does not apply, e.g. the usize type requires different sampling on 32-bit and 64-bit machines.

Required Methods

fn sample<R>(&self, rng: &mut R) -> T

where R: Rng + ?Sized,

Generate a random value of T, using rng as the source of randomness.

Provided Methods

fn sample_iter<R>(self, rng: R) -> DistIter<Self, R, T>

where R: Rng, Self: Sized,

Create an iterator that generates random values of T, using rng as the source of randomness.

Note that this function takes self by value. This works since Distribution<T> is impl’d for &D where D: Distribution<T>, however borrowing is not automatic hence distr.sample_iter(...) may need to be replaced with (&distr).sample_iter(...) to borrow or (&*distr).sample_iter(...) to reborrow an existing reference.

Example

use rand::distr::{Distribution, Alphanumeric, Uniform, StandardUniform};

let mut rng = rand::rng();

// Vec of 16 x f32:
let v: Vec<f32> = StandardUniform.sample_iter(&mut rng).take(16).collect();

// String:
let s: String = Alphanumeric
    .sample_iter(&mut rng)
    .take(7)
    .map(char::from)
    .collect();

// Dice-rolling:
let die_range = Uniform::new_inclusive(1, 6).unwrap();
let mut roll_die = die_range.sample_iter(&mut rng);
while roll_die.next().unwrap() != 6 {
    println!("Not a 6; rolling again!");
}

fn map<F, S>(self, func: F) -> DistMap<Self, F, T, S>

where F: Fn(T) -> S, Self: Sized,

Create a distribution of values of ‘S’ by mapping the output of Self through the closure F

Example

use rand::distr::{Distribution, Uniform};

let mut rng = rand::rng();

let die = Uniform::new_inclusive(1, 6).unwrap();
let even_number = die.map(|num| num % 2 == 0);
while !even_number.sample(&mut rng) {
    println!("Still odd; rolling again!");
}

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl<T, D> Distribution<T> for &D

where D: Distribution<T> + ?Sized,

fn sample<R>(&self, rng: &mut R) -> T

where R: Rng + ?Sized,

Implementors

impl Distribution<bool> for Bernoulli

impl Distribution<bool> for StandardUniform

impl Distribution<char> for StandardUniform

impl Distribution<f32> for Exp1

impl Distribution<f32> for Open01

impl Distribution<f32> for OpenClosed01

impl Distribution<f32> for StandardNormal

impl Distribution<f32> for StandardUniform

impl Distribution<f64> for Exp1

impl Distribution<f64> for Open01

impl Distribution<f64> for OpenClosed01

impl Distribution<f64> for StandardNormal

impl Distribution<f64> for StandardUniform

impl Distribution<i8> for StandardUniform

impl Distribution<i16> for StandardUniform

impl Distribution<i32> for StandardUniform

impl Distribution<i64> for StandardUniform

impl Distribution<i128> for StandardUniform

impl Distribution<u8> for Alphanumeric

impl Distribution<u8> for StandardUniform

impl Distribution<u16> for StandardUniform

impl Distribution<u32> for StandardUniform

impl Distribution<u64> for Binomial

impl Distribution<u64> for Geometric

impl Distribution<u64> for Hypergeometric

impl Distribution<u64> for StandardGeometric

impl Distribution<u64> for StandardUniform

impl Distribution<u128> for StandardUniform

impl Distribution<()> for StandardUniform

impl Distribution<__m128i> for StandardUniform

impl Distribution<__m256i> for StandardUniform

impl Distribution<__m512i> for StandardUniform

impl Distribution<Simd<f32, 2>> for Open01

impl Distribution<Simd<f32, 2>> for OpenClosed01

impl Distribution<Simd<f32, 2>> for StandardUniform

impl Distribution<Simd<f32, 4>> for Open01

impl Distribution<Simd<f32, 4>> for OpenClosed01

impl Distribution<Simd<f32, 4>> for StandardUniform

impl Distribution<Simd<f32, 8>> for Open01

impl Distribution<Simd<f32, 8>> for OpenClosed01

impl Distribution<Simd<f32, 8>> for StandardUniform

impl Distribution<Simd<f32, 16>> for Open01

impl Distribution<Simd<f32, 16>> for OpenClosed01

impl Distribution<Simd<f32, 16>> for StandardUniform

impl Distribution<Simd<f64, 2>> for Open01

impl Distribution<Simd<f64, 2>> for OpenClosed01

impl Distribution<Simd<f64, 2>> for StandardUniform

impl Distribution<Simd<f64, 4>> for Open01

impl Distribution<Simd<f64, 4>> for OpenClosed01

impl Distribution<Simd<f64, 4>> for StandardUniform

impl Distribution<Simd<f64, 8>> for Open01

impl Distribution<Simd<f64, 8>> for OpenClosed01

impl Distribution<Simd<f64, 8>> for StandardUniform

impl Distribution<NonZero<i8>> for StandardUniform

impl Distribution<NonZero<i16>> for StandardUniform

impl Distribution<NonZero<i32>> for StandardUniform

impl Distribution<NonZero<i64>> for StandardUniform

impl Distribution<NonZero<i128>> for StandardUniform

impl Distribution<NonZero<u8>> for StandardUniform

impl Distribution<NonZero<u16>> for StandardUniform

impl Distribution<NonZero<u32>> for StandardUniform

impl Distribution<NonZero<u64>> for StandardUniform

impl Distribution<NonZero<u128>> for StandardUniform

impl<'a, T> Distribution<&'a T> for Slice<'a, T>

impl<A> Distribution<(A,)> for StandardUniform

where StandardUniform: Distribution<A>,

impl<A, B> Distribution<(A, B)> for StandardUniform

where StandardUniform: Distribution<A> + Distribution<B>,

impl<A, B, C> Distribution<(A, B, C)> for StandardUniform

where StandardUniform: Distribution<A> + Distribution<B> + Distribution<C>,

impl<A, B, C, D> Distribution<(A, B, C, D)> for StandardUniform

where StandardUniform: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D>,

impl<A, B, C, D, E> Distribution<(A, B, C, D, E)> for StandardUniform

where StandardUniform: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E>,

impl<A, B, C, D, E, F> Distribution<(A, B, C, D, E, F)> for StandardUniform

where StandardUniform: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F>,

impl<A, B, C, D, E, F, G> Distribution<(A, B, C, D, E, F, G)> for StandardUniform

where StandardUniform: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F> + Distribution<G>,

impl<A, B, C, D, E, F, G, H> Distribution<(A, B, C, D, E, F, G, H)> for StandardUniform

where StandardUniform: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F> + Distribution<G> + Distribution<H>,

impl<A, B, C, D, E, F, G, H, I> Distribution<(A, B, C, D, E, F, G, H, I)> for StandardUniform

where StandardUniform: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F> + Distribution<G> + Distribution<H> + Distribution<I>,

impl<A, B, C, D, E, F, G, H, I, J> Distribution<(A, B, C, D, E, F, G, H, I, J)> for StandardUniform

where StandardUniform: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F> + Distribution<G> + Distribution<H> + Distribution<I> + Distribution<J>,

impl<A, B, C, D, E, F, G, H, I, J, K> Distribution<(A, B, C, D, E, F, G, H, I, J, K)> for StandardUniform

where StandardUniform: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F> + Distribution<G> + Distribution<H> + Distribution<I> + Distribution<J> + Distribution<K>,

impl<A, B, C, D, E, F, G, H, I, J, K, L> Distribution<(A, B, C, D, E, F, G, H, I, J, K, L)> for StandardUniform

where StandardUniform: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F> + Distribution<G> + Distribution<H> + Distribution<I> + Distribution<J> + Distribution<K> + Distribution<L>,

impl<D, F, T, S> Distribution<S> for DistMap<D, F, T, S>

where D: Distribution<T>, F: Fn(T) -> S,

impl<F> Distribution<F> for Beta<F>

where F: Float, Open01: Distribution<F>,

impl<F> Distribution<F> for Cauchy<F>

where F: Float + FloatConst, StandardUniform: Distribution<F>,

impl<F> Distribution<F> for ChiSquared<F>

where F: Float, StandardNormal: Distribution<F>, Exp1: Distribution<F>, Open01: Distribution<F>,

impl<F> Distribution<F> for Exp<F>

where F: Float, Exp1: Distribution<F>,

impl<F> Distribution<F> for FisherF<F>

where F: Float, StandardNormal: Distribution<F>, Exp1: Distribution<F>, Open01: Distribution<F>,

impl<F> Distribution<F> for Frechet<F>

where F: Float, OpenClosed01: Distribution<F>,

impl<F> Distribution<F> for Gamma<F>

where F: Float, StandardNormal: Distribution<F>, Exp1: Distribution<F>, Open01: Distribution<F>,

impl<F> Distribution<F> for Gumbel<F>

where F: Float, OpenClosed01: Distribution<F>,

impl<F> Distribution<F> for InverseGaussian<F>

where F: Float, StandardNormal: Distribution<F>, StandardUniform: Distribution<F>,

impl<F> Distribution<F> for LogNormal<F>

where F: Float, StandardNormal: Distribution<F>,

impl<F> Distribution<F> for Normal<F>

where F: Float, StandardNormal: Distribution<F>,

impl<F> Distribution<F> for NormalInverseGaussian<F>

where F: Float, StandardNormal: Distribution<F>, StandardUniform: Distribution<F>,

impl<F> Distribution<F> for Pareto<F>

where F: Float, OpenClosed01: Distribution<F>,

impl<F> Distribution<F> for Pert<F>

where F: Float, StandardNormal: Distribution<F>, Exp1: Distribution<F>, Open01: Distribution<F>,

impl<F> Distribution<F> for Poisson<F>

where F: Float + FloatConst, StandardUniform: Distribution<F>,

impl<F> Distribution<F> for SkewNormal<F>

where F: Float, StandardNormal: Distribution<F>,

impl<F> Distribution<F> for StudentT<F>

where F: Float, StandardNormal: Distribution<F>, Exp1: Distribution<F>, Open01: Distribution<F>,

impl<F> Distribution<F> for Triangular<F>

where F: Float, StandardUniform: Distribution<F>,

impl<F> Distribution<F> for Weibull<F>

where F: Float, OpenClosed01: Distribution<F>,

impl<F> Distribution<F> for Zeta<F>

where F: Float, StandardUniform: Distribution<F>, OpenClosed01: Distribution<F>,

impl<F> Distribution<F> for Zipf<F>

where F: Float, StandardUniform: Distribution<F>,

impl<F, const N: usize> Distribution<[F; N]> for Dirichlet<F, N>

where F: Float, StandardNormal: Distribution<F>, Exp1: Distribution<F>, Open01: Distribution<F>,

impl<F: Float + SampleUniform> Distribution<[F; 2]> for UnitCircle

impl<F: Float + SampleUniform> Distribution<[F; 2]> for UnitDisc

impl<F: Float + SampleUniform> Distribution<[F; 3]> for UnitBall

impl<F: Float + SampleUniform> Distribution<[F; 3]> for UnitSphere

impl<T> Distribution<Wrapping<T>> for StandardUniform

where StandardUniform: Distribution<T>,

impl<T, const LANES: usize> Distribution<Mask<T, LANES>> for StandardUniform

where T: MaskElement + Default, LaneCount<LANES>: SupportedLaneCount, StandardUniform: Distribution<Simd<T, LANES>>, Simd<T, LANES>: SimdPartialOrd<Mask = Mask<T, LANES>>,

Note that on some hardware like x86/64 mask operations like _mm_blendv_epi8 only care about a single bit. This means that you could use uniform random bits directly:

// this may be faster...
let x = unsafe { _mm_blendv_epi8(a.into(), b.into(), rng.random::<__m128i>()) };

// ...than this
let x = rng.random::<mask8x16>().select(b, a);

Since most bits are unused you could also generate only as many bits as you need, i.e.:

#![feature(portable_simd)]
use std::simd::prelude::*;
use rand::prelude::*;
let mut rng = rand::rng();

let x = u16x8::splat(rng.random::<u8>() as u16);
let mask = u16x8::splat(1) << u16x8::from([0, 1, 2, 3, 4, 5, 6, 7]);
let rand_mask = (x & mask).simd_eq(mask);

impl<T, const N: usize> Distribution<[T; N]> for StandardUniform

where StandardUniform: Distribution<T>,

impl<W: Clone + PartialEq + PartialOrd + SampleUniform + SubAssign<W> + Weight> Distribution<usize> for WeightedTreeIndex<W>

Samples a randomly selected index from the weighted distribution.

Caution: This method panics if there are no elements or all weights are zero. However, it is guaranteed that this method will not panic if a call to WeightedTreeIndex::is_valid returns true.

impl<W: AliasableWeight> Distribution<usize> for WeightedAliasIndex<W>

impl<X> Distribution<usize> for WeightedIndex<X>

where X: SampleUniform + PartialOrd,

impl<X> Distribution<X> for Uniform<X>

where X: SampleUniform,

impl<const LANES: usize> Distribution<Simd<i8, LANES>> for StandardUniform

where LaneCount<LANES>: SupportedLaneCount,

Requires nightly Rust and the simd_support feature

impl<const LANES: usize> Distribution<Simd<i16, LANES>> for StandardUniform

where LaneCount<LANES>: SupportedLaneCount,

Requires nightly Rust and the simd_support feature

impl<const LANES: usize> Distribution<Simd<i32, LANES>> for StandardUniform

where LaneCount<LANES>: SupportedLaneCount,

Requires nightly Rust and the simd_support feature

impl<const LANES: usize> Distribution<Simd<i64, LANES>> for StandardUniform

where LaneCount<LANES>: SupportedLaneCount,

Requires nightly Rust and the simd_support feature

impl<const LANES: usize> Distribution<Simd<u8, LANES>> for StandardUniform

where LaneCount<LANES>: SupportedLaneCount,

Requires nightly Rust and the simd_support feature

impl<const LANES: usize> Distribution<Simd<u16, LANES>> for StandardUniform

where LaneCount<LANES>: SupportedLaneCount,

Requires nightly Rust and the simd_support feature

impl<const LANES: usize> Distribution<Simd<u32, LANES>> for StandardUniform

where LaneCount<LANES>: SupportedLaneCount,

Requires nightly Rust and the simd_support feature

impl<const LANES: usize> Distribution<Simd<u64, LANES>> for StandardUniform

where LaneCount<LANES>: SupportedLaneCount,

Requires nightly Rust and the simd_support feature