Trait Distribution

Source

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) -> Iter<Self, R, T> ⓘ
       where R: Rng,
             Self: Sized { ... }
    fn map<F, S>(self, func: F) -> Map<Self, F, T, S>
       where F: Fn(T) -> S,
             Self: Sized { ... }
}

Expand description

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§

Source

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§

Source

fn sample_iter<R>(self, rng: R) -> Iter<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!");
}

Source

fn map<F, S>(self, func: F) -> Map<Self, F, T, S>
where F: Fn(T) -> S, Self: Sized,

Map sampled values to type S

§Example

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

let die = Uniform::new_inclusive(1, 6).unwrap();
let even_number = die.map(|num| num % 2 == 0);
while !even_number.sample(&mut rand::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.

Trait Distribution Copy item path

Required Methods§

fn sample<R>(&self, rng: &mut R) -> Twhere R: Rng + ?Sized,

Provided Methods§

fn sample_iter<R>(self, rng: R) -> Iter<Self, R, T> ⓘwhere R: Rng, Self: Sized,

§Example

fn map<F, S>(self, func: F) -> Map<Self, F, T, S>where F: Fn(T) -> S, Self: Sized,

§Example

Dyn Compatibility§

Implementations on Foreign Types§

impl<T, D> Distribution<T> for &Dwhere D: Distribution<T> + ?Sized,

fn sample<R>(&self, rng: &mut R) -> Twhere R: Rng + ?Sized,

Implementors§

impl Distribution<bool> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<bool> for Bernoulli

impl Distribution<char> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<f32> for Exp1

impl Distribution<f32> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<f32> for scirs2_core::ndarray_ext::random::StandardNormal

impl Distribution<f32> for scirs2_core::ndarray_ext::random::StandardUniform

impl Distribution<f32> for Open01

impl Distribution<f32> for OpenClosed01

impl Distribution<f32> for scirs2_core::random::StandardNormal

impl Distribution<f64> for Exp1

impl Distribution<f64> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<f64> for scirs2_core::ndarray_ext::random::StandardNormal

impl Distribution<f64> for scirs2_core::ndarray_ext::random::StandardUniform

impl Distribution<f64> for UnifiedBeta

impl Distribution<f64> for UnifiedCauchy

impl Distribution<f64> for UnifiedChiSquared

impl Distribution<f64> for UnifiedExp

impl Distribution<f64> for UnifiedFisherF

impl Distribution<f64> for UnifiedGamma

impl Distribution<f64> for UnifiedLogNormal

impl Distribution<f64> for UnifiedNormal

impl Distribution<f64> for UnifiedPoisson

impl Distribution<f64> for UnifiedStudentT

impl Distribution<f64> for UnifiedWeibull

impl Distribution<f64> for scirs2_core::random::scientific::StandardNormal

impl Distribution<f64> for scirs2_core::random::scientific::StandardUniform

impl Distribution<f64> for Open01

impl Distribution<f64> for OpenClosed01

impl Distribution<f64> for scirs2_core::random::StandardNormal

impl Distribution<i8> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<i16> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<i32> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<i64> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<i128> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<u8> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<u8> for Alphabetic

impl Distribution<u8> for Alphanumeric

impl Distribution<u16> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<u32> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<u64> for StandardGeometric

impl Distribution<u64> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<u64> for UnifiedBinomial

impl Distribution<u64> for Binomial

impl Distribution<u64> for Geometric

impl Distribution<u64> for Hypergeometric

impl Distribution<u128> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<()> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<Vec<f64>> for UnifiedDirichlet

impl Distribution<__m128i> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<__m256i> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<NonZero<i8>> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<NonZero<i16>> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<NonZero<i32>> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<NonZero<i64>> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<NonZero<i128>> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<NonZero<u8>> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<NonZero<u16>> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<NonZero<u32>> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<NonZero<u64>> for scirs2_core::ndarray::distributions::StandardUniform

impl Distribution<NonZero<u128>> for scirs2_core::ndarray::distributions::StandardUniform

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

impl<A> Distribution<(A,)> for scirs2_core::ndarray::distributions::StandardUniformwhere StandardUniform: Distribution<A>,

impl<A, B> Distribution<(A, B)> for scirs2_core::ndarray::distributions::StandardUniformwhere StandardUniform: Distribution<A> + Distribution<B>,

impl<A, B, C> Distribution<(A, B, C)> for scirs2_core::ndarray::distributions::StandardUniformwhere StandardUniform: Distribution<A> + Distribution<B> + Distribution<C>,

impl<A, B, C, D> Distribution<(A, B, C, D)> for scirs2_core::ndarray::distributions::StandardUniformwhere StandardUniform: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D>,

impl<A, B, C, D, E> Distribution<(A, B, C, D, E)> for scirs2_core::ndarray::distributions::StandardUniformwhere StandardUniform: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E>,

Trait Distribution

fn sample<R>(&self, rng: &mut R) -> T
where R: Rng + ?Sized,

fn sample_iter<R>(self, rng: R) -> Iter<Self, R, T> ⓘ
where R: Rng, Self: Sized,

fn map<F, S>(self, func: F) -> Map<Self, F, T, S>
where F: Fn(T) -> S, Self: Sized,

impl<T, D> Distribution<T> for &D
where D: Distribution<T> + ?Sized,

fn sample<R>(&self, rng: &mut R) -> T
where R: Rng + ?Sized,

impl<A> Distribution<(A,)> for scirs2_core::ndarray::distributions::StandardUniform
where StandardUniform: Distribution<A>,

impl<A, B> Distribution<(A, B)> for scirs2_core::ndarray::distributions::StandardUniform
where StandardUniform: Distribution<A> + Distribution<B>,

impl<A, B, C> Distribution<(A, B, C)> for scirs2_core::ndarray::distributions::StandardUniform
where StandardUniform: Distribution<A> + Distribution<B> + Distribution<C>,

impl<A, B, C, D> Distribution<(A, B, C, D)> for scirs2_core::ndarray::distributions::StandardUniform
where StandardUniform: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D>,

impl<A, B, C, D, E> Distribution<(A, B, C, D, E)> for scirs2_core::ndarray::distributions::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 scirs2_core::ndarray::distributions::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 scirs2_core::ndarray::distributions::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 scirs2_core::ndarray::distributions::StandardUniform
where StandardUniform: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F> + Distribution<G> + Distribution<H>,

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

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

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

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

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

impl<F> Distribution<F> for Frechet<F>
where F: Float, OpenClosed01: Distribution<F>,

impl<F> Distribution<F> for Gumbel<F>
where F: Float, OpenClosed01: Distribution<F>,

impl<F> Distribution<F> for NormalInverseGaussian<F>
where F: Float, StandardNormal: Distribution<F>, StandardUniform: Distribution<F>,

impl<F> Distribution<F> for SkewNormal<F>
where F: Float, StandardNormal: 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 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 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>, StandardNormal: Distribution<F>, Exp1: Distribution<F>,

impl<F> Distribution<F> for Beta<F>
where F: Float, Open01: 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 Normal<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<T> Distribution<Wrapping<T>> for scirs2_core::ndarray::distributions::StandardUniform
where StandardUniform: Distribution<T>,

impl<T, const N: usize> Distribution<[T; N]> for scirs2_core::ndarray::distributions::StandardUniform
where StandardUniform: Distribution<T>,

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

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

impl<X> Distribution<usize> for WeightedIndex<X>
where X: SampleUniform + PartialOrd,

impl<X> Distribution<X> for Uniform<X>
where X: SampleUniform,