| 1 |
// Copyright 2018 Developers of the Rand project. |
| 2 |
// Copyright 2013-2017 The Rust Project Developers. |
| 3 |
// |
| 4 |
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or |
| 5 |
// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license |
| 6 |
// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your |
| 7 |
// option. This file may not be copied, modified, or distributed |
| 8 |
// except according to those terms. |
| 9 |
|
| 10 |
//! Generating random samples from probability distributions |
| 11 |
//! |
| 12 |
//! This module is the home of the [`Distribution`] trait and several of its |
| 13 |
//! implementations. It is the workhorse behind some of the convenient |
| 14 |
//! functionality of the [`Rng`] trait, e.g. [`Rng::random`] and of course |
| 15 |
//! [`Rng::sample`]. |
| 16 |
//! |
| 17 |
//! Abstractly, a [probability distribution] describes the probability of |
| 18 |
//! occurrence of each value in its sample space. |
| 19 |
//! |
| 20 |
//! More concretely, an implementation of `Distribution<T>` for type `X` is an |
| 21 |
//! algorithm for choosing values from the sample space (a subset of `T`) |
| 22 |
//! according to the distribution `X` represents, using an external source of |
| 23 |
//! randomness (an RNG supplied to the `sample` function). |
| 24 |
//! |
| 25 |
//! A type `X` may implement `Distribution<T>` for multiple types `T`. |
| 26 |
//! Any type implementing [`Distribution`] is stateless (i.e. immutable), |
| 27 |
//! but it may have internal parameters set at construction time (for example, |
| 28 |
//! [`Uniform`] allows specification of its sample space as a range within `T`). |
| 29 |
//! |
| 30 |
//! |
| 31 |
//! # The Standard Uniform distribution |
| 32 |
//! |
| 33 |
//! The [`StandardUniform`] distribution is important to mention. This is the |
| 34 |
//! distribution used by [`Rng::random`] and represents the "default" way to |
| 35 |
//! produce a random value for many different types, including most primitive |
| 36 |
//! types, tuples, arrays, and a few derived types. See the documentation of |
| 37 |
//! [`StandardUniform`] for more details. |
| 38 |
//! |
| 39 |
//! Implementing [`Distribution<T>`] for [`StandardUniform`] for user types `T` makes it |
| 40 |
//! possible to generate type `T` with [`Rng::random`], and by extension also |
| 41 |
//! with the [`random`] function. |
| 42 |
//! |
| 43 |
//! ## Other standard uniform distributions |
| 44 |
//! |
| 45 |
//! [`Alphanumeric`] is a simple distribution to sample random letters and |
| 46 |
//! numbers of the `char` type; in contrast [`StandardUniform`] may sample any valid |
| 47 |
//! `char`. |
| 48 |
//! |
| 49 |
//! There's also an [`Alphabetic`] distribution which acts similarly to [`Alphanumeric`] but |
| 50 |
//! doesn't include digits. |
| 51 |
//! |
| 52 |
//! For floats (`f32`, `f64`), [`StandardUniform`] samples from `[0, 1)`. Also |
| 53 |
//! provided are [`Open01`] (samples from `(0, 1)`) and [`OpenClosed01`] |
| 54 |
//! (samples from `(0, 1]`). No option is provided to sample from `[0, 1]`; it |
| 55 |
//! is suggested to use one of the above half-open ranges since the failure to |
| 56 |
//! sample a value which would have a low chance of being sampled anyway is |
| 57 |
//! rarely an issue in practice. |
| 58 |
//! |
| 59 |
//! # Parameterized Uniform distributions |
| 60 |
//! |
| 61 |
//! The [`Uniform`] distribution provides uniform sampling over a specified |
| 62 |
//! range on a subset of the types supported by the above distributions. |
| 63 |
//! |
| 64 |
//! Implementations support single-value-sampling via |
| 65 |
//! [`Rng::random_range(Range)`](Rng::random_range). |
| 66 |
//! Where a fixed (non-`const`) range will be sampled many times, it is likely |
| 67 |
//! faster to pre-construct a [`Distribution`] object using |
| 68 |
//! [`Uniform::new`], [`Uniform::new_inclusive`] or `From<Range>`. |
| 69 |
//! |
| 70 |
//! # Non-uniform sampling |
| 71 |
//! |
| 72 |
//! Sampling a simple true/false outcome with a given probability has a name: |
| 73 |
//! the [`Bernoulli`] distribution (this is used by [`Rng::random_bool`]). |
| 74 |
//! |
| 75 |
//! For weighted sampling of discrete values see the [`weighted`] module. |
| 76 |
//! |
| 77 |
//! This crate no longer includes other non-uniform distributions; instead |
| 78 |
//! it is recommended that you use either [`rand_distr`] or [`statrs`]. |
| 79 |
//! |
| 80 |
//! |
| 81 |
//! [probability distribution]: https://en.wikipedia.org/wiki/Probability_distribution |
| 82 |
//! [`rand_distr`]: https://crates.io/crates/rand_distr |
| 83 |
//! [`statrs`]: https://crates.io/crates/statrs |
| 84 |
|
| 85 |
//! [`random`]: crate::random |
| 86 |
//! [`rand_distr`]: https://crates.io/crates/rand_distr |
| 87 |
//! [`statrs`]: https://crates.io/crates/statrs |
| 88 |
|
| 89 |
mod bernoulli; |
| 90 |
mod distribution; |
| 91 |
mod float; |
| 92 |
mod integer; |
| 93 |
mod other; |
| 94 |
mod utils; |
| 95 |
|
| 96 |
#[doc(hidden)] |
| 97 |
pub mod hidden_export { |
| 98 |
pub use super::float::IntoFloat; // used by rand_distr |
| 99 |
} |
| 100 |
pub mod slice; |
| 101 |
pub mod uniform; |
| 102 |
#[cfg(feature = "alloc")] |
| 103 |
pub mod weighted; |
| 104 |
|
| 105 |
pub use self::bernoulli::{Bernoulli, BernoulliError}; |
| 106 |
#[cfg(feature = "alloc")] |
| 107 |
pub use self::distribution::SampleString; |
| 108 |
pub use self::distribution::{Distribution, Iter, Map}; |
| 109 |
pub use self::float::{Open01, OpenClosed01}; |
| 110 |
pub use self::other::{Alphabetic, Alphanumeric}; |
| 111 |
#[doc(inline)] |
| 112 |
pub use self::uniform::Uniform; |
| 113 |
|
| 114 |
#[allow(unused)] |
| 115 |
use crate::Rng; |
| 116 |
|
| 117 |
/// The Standard Uniform distribution |
| 118 |
/// |
| 119 |
/// This [`Distribution`] is the *standard* parameterization of [`Uniform`]. Bounds |
| 120 |
/// are selected according to the output type. |
| 121 |
/// |
| 122 |
/// Assuming the provided `Rng` is well-behaved, these implementations |
| 123 |
/// generate values with the following ranges and distributions: |
| 124 |
/// |
| 125 |
/// * Integers (`i8`, `i32`, `u64`, etc.) are uniformly distributed |
| 126 |
/// over the whole range of the type (thus each possible value may be sampled |
| 127 |
/// with equal probability). |
| 128 |
/// * `char` is uniformly distributed over all Unicode scalar values, i.e. all |
| 129 |
/// code points in the range `0...0x10_FFFF`, except for the range |
| 130 |
/// `0xD800...0xDFFF` (the surrogate code points). This includes |
| 131 |
/// unassigned/reserved code points. |
| 132 |
/// For some uses, the [`Alphanumeric`] or [`Alphabetic`] distribution will be more |
| 133 |
/// appropriate. |
| 134 |
/// * `bool` samples `false` or `true`, each with probability 0.5. |
| 135 |
/// * Floating point types (`f32` and `f64`) are uniformly distributed in the |
| 136 |
/// half-open range `[0, 1)`. See also the [notes below](#floating-point-implementation). |
| 137 |
/// * Wrapping integers ([`Wrapping<T>`]), besides the type identical to their |
| 138 |
/// normal integer variants. |
| 139 |
/// * Non-zero integers ([`NonZeroU8`]), which are like their normal integer |
| 140 |
/// variants but cannot sample zero. |
| 141 |
/// |
| 142 |
/// The `StandardUniform` distribution also supports generation of the following |
| 143 |
/// compound types where all component types are supported: |
| 144 |
/// |
| 145 |
/// * Tuples (up to 12 elements): each element is sampled sequentially and |
| 146 |
/// independently (thus, assuming a well-behaved RNG, there is no correlation |
| 147 |
/// between elements). |
| 148 |
/// * Arrays `[T; n]` where `T` is supported. Each element is sampled |
| 149 |
/// sequentially and independently. Note that for small `T` this usually |
| 150 |
/// results in the RNG discarding random bits; see also [`Rng::fill`] which |
| 151 |
/// offers a more efficient approach to filling an array of integer types |
| 152 |
/// with random data. |
| 153 |
/// * SIMD types (requires [`simd_support`] feature) like x86's [`__m128i`] |
| 154 |
/// and `std::simd`'s [`u32x4`], [`f32x4`] and [`mask32x4`] types are |
| 155 |
/// effectively arrays of integer or floating-point types. Each lane is |
| 156 |
/// sampled independently, potentially with more efficient random-bit-usage |
| 157 |
/// (and a different resulting value) than would be achieved with sequential |
| 158 |
/// sampling (as with the array types above). |
| 159 |
/// |
| 160 |
/// ## Custom implementations |
| 161 |
/// |
| 162 |
/// The [`StandardUniform`] distribution may be implemented for user types as follows: |
| 163 |
/// |
| 164 |
/// ``` |
| 165 |
/// # #![allow(dead_code)] |
| 166 |
/// use rand::Rng; |
| 167 |
/// use rand::distr::{Distribution, StandardUniform}; |
| 168 |
/// |
| 169 |
/// struct MyF32 { |
| 170 |
/// x: f32, |
| 171 |
/// } |
| 172 |
/// |
| 173 |
/// impl Distribution<MyF32> for StandardUniform { |
| 174 |
/// fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> MyF32 { |
| 175 |
/// MyF32 { x: rng.random() } |
| 176 |
/// } |
| 177 |
/// } |
| 178 |
/// ``` |
| 179 |
/// |
| 180 |
/// ## Example usage |
| 181 |
/// ``` |
| 182 |
/// use rand::prelude::*; |
| 183 |
/// use rand::distr::StandardUniform; |
| 184 |
/// |
| 185 |
/// let val: f32 = rand::rng().sample(StandardUniform); |
| 186 |
/// println!("f32 from [0, 1): {}", val); |
| 187 |
/// ``` |
| 188 |
/// |
| 189 |
/// # Floating point implementation |
| 190 |
/// The floating point implementations for `StandardUniform` generate a random value in |
| 191 |
/// the half-open interval `[0, 1)`, i.e. including 0 but not 1. |
| 192 |
/// |
| 193 |
/// All values that can be generated are of the form `n * ε/2`. For `f32` |
| 194 |
/// the 24 most significant random bits of a `u32` are used and for `f64` the |
| 195 |
/// 53 most significant bits of a `u64` are used. The conversion uses the |
| 196 |
/// multiplicative method: `(rng.gen::<$uty>() >> N) as $ty * (ε/2)`. |
| 197 |
/// |
| 198 |
/// See also: [`Open01`] which samples from `(0, 1)`, [`OpenClosed01`] which |
| 199 |
/// samples from `(0, 1]` and `Rng::random_range(0..1)` which also samples from |
| 200 |
/// `[0, 1)`. Note that `Open01` uses transmute-based methods which yield 1 bit |
| 201 |
/// less precision but may perform faster on some architectures (on modern Intel |
| 202 |
/// CPUs all methods have approximately equal performance). |
| 203 |
/// |
| 204 |
/// [`Uniform`]: uniform::Uniform |
| 205 |
/// [`Wrapping<T>`]: std::num::Wrapping |
| 206 |
/// [`NonZeroU8`]: std::num::NonZeroU8 |
| 207 |
/// [`__m128i`]: https://doc.rust-lang.org/core/arch/x86/struct.__m128i.html |
| 208 |
/// [`u32x4`]: std::simd::u32x4 |
| 209 |
/// [`f32x4`]: std::simd::f32x4 |
| 210 |
/// [`mask32x4`]: std::simd::mask32x4 |
| 211 |
/// [`simd_support`]: https://github.com/rust-random/rand#crate-features |
| 212 |
#[derive(Clone, Copy, Debug, Default)] |
| 213 |
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] |
| 214 |
pub struct StandardUniform; |