Crate rand [−] [src]
Utilities for random number generation
The key functions are random()
and Rng::gen()
. These are polymorphic and
so can be used to generate any type that implements Rand
. Type inference
means that often a simple call to rand::random()
or rng.gen()
will
suffice, but sometimes an annotation is required, e.g.
rand::random::<f64>()
.
See the distributions
submodule for sampling random numbers from
distributions like normal and exponential.
Usage
This crate is on crates.io and can be
used by adding rand
to the dependencies in your project's Cargo.toml
.
[dependencies]
rand = "0.4"
and this to your crate root:
extern crate rand;
Thread-local RNG
There is built-in support for a RNG associated with each thread stored
in thread-local storage. This RNG can be accessed via thread_rng
, or
used implicitly via random
. This RNG is normally randomly seeded
from an operating-system source of randomness, e.g. /dev/urandom
on
Unix systems, and will automatically reseed itself from this source
after generating 32 KiB of random data.
Cryptographic security
An application that requires an entropy source for cryptographic purposes
must use OsRng
, which reads randomness from the source that the operating
system provides (e.g. /dev/urandom
on Unixes or CryptGenRandom()
on
Windows).
The other random number generators provided by this module are not suitable
for such purposes.
Note: many Unix systems provide /dev/random
as well as /dev/urandom
.
This module uses /dev/urandom
for the following reasons:
- On Linux,
/dev/random
may block if entropy pool is empty;/dev/urandom
will not block. This does not mean that/dev/random
provides better output than/dev/urandom
; the kernel internally runs a cryptographically secure pseudorandom number generator (CSPRNG) based on entropy pool for random number generation, so the "quality" of/dev/random
is not better than/dev/urandom
in most cases. However, this means that/dev/urandom
can yield somewhat predictable randomness if the entropy pool is very small, such as immediately after first booting. Linux 3.17 added thegetrandom(2)
system call which solves the issue: it blocks if entropy pool is not initialized yet, but it does not block once initialized.OsRng
tries to usegetrandom(2)
if available, and use/dev/urandom
fallback if not. If an application does not havegetrandom
and likely to be run soon after first booting, or on a system with very few entropy sources, one should consider using/dev/random
viaReadRng
. - On some systems (e.g. FreeBSD, OpenBSD and Mac OS X) there is no
difference between the two sources. (Also note that, on some systems
e.g. FreeBSD, both
/dev/random
and/dev/urandom
may block once if the CSPRNG has not seeded yet.)
Examples
use rand::Rng; let mut rng = rand::thread_rng(); if rng.gen() { // random bool println!("i32: {}, u32: {}", rng.gen::<i32>(), rng.gen::<u32>()) }
let tuple = rand::random::<(f64, char)>(); println!("{:?}", tuple)
Monte Carlo estimation of π
For this example, imagine we have a square with sides of length 2 and a unit circle, both centered at the origin. Since the area of a unit circle is π, we have:
(area of unit circle) / (area of square) = π / 4
So if we sample many points randomly from the square, roughly π / 4 of them should be inside the circle.
We can use the above fact to estimate the value of π: pick many points in the square at random, calculate the fraction that fall within the circle, and multiply this fraction by 4.
use rand::distributions::{IndependentSample, Range}; fn main() { let between = Range::new(-1f64, 1.); let mut rng = rand::thread_rng(); let total = 1_000_000; let mut in_circle = 0; for _ in 0..total { let a = between.ind_sample(&mut rng); let b = between.ind_sample(&mut rng); if a*a + b*b <= 1. { in_circle += 1; } } // prints something close to 3.14159... println!("{}", 4. * (in_circle as f64) / (total as f64)); }
Monty Hall Problem
This is a simulation of the Monty Hall Problem:
Suppose you're on a game show, and you're given the choice of three doors: Behind one door is a car; behind the others, goats. You pick a door, say No. 1, and the host, who knows what's behind the doors, opens another door, say No. 3, which has a goat. He then says to you, "Do you want to pick door No. 2?" Is it to your advantage to switch your choice?
The rather unintuitive answer is that you will have a 2/3 chance of winning if you switch and a 1/3 chance of winning if you don't, so it's better to switch.
This program will simulate the game show and with large enough simulation steps it will indeed confirm that it is better to switch.
use rand::Rng; use rand::distributions::{IndependentSample, Range}; struct SimulationResult { win: bool, switch: bool, } // Run a single simulation of the Monty Hall problem. fn simulate<R: Rng>(random_door: &Range<u32>, rng: &mut R) -> SimulationResult { let car = random_door.ind_sample(rng); // This is our initial choice let mut choice = random_door.ind_sample(rng); // The game host opens a door let open = game_host_open(car, choice, rng); // Shall we switch? let switch = rng.gen(); if switch { choice = switch_door(choice, open); } SimulationResult { win: choice == car, switch: switch } } // Returns the door the game host opens given our choice and knowledge of // where the car is. The game host will never open the door with the car. fn game_host_open<R: Rng>(car: u32, choice: u32, rng: &mut R) -> u32 { let choices = free_doors(&[car, choice]); rand::seq::sample_slice(rng, &choices, 1)[0] } // Returns the door we switch to, given our current choice and // the open door. There will only be one valid door. fn switch_door(choice: u32, open: u32) -> u32 { free_doors(&[choice, open])[0] } fn free_doors(blocked: &[u32]) -> Vec<u32> { (0..3).filter(|x| !blocked.contains(x)).collect() } fn main() { // The estimation will be more accurate with more simulations let num_simulations = 10000; let mut rng = rand::thread_rng(); let random_door = Range::new(0, 3); let (mut switch_wins, mut switch_losses) = (0, 0); let (mut keep_wins, mut keep_losses) = (0, 0); println!("Running {} simulations...", num_simulations); for _ in 0..num_simulations { let result = simulate(&random_door, &mut rng); match (result.win, result.switch) { (true, true) => switch_wins += 1, (true, false) => keep_wins += 1, (false, true) => switch_losses += 1, (false, false) => keep_losses += 1, } } let total_switches = switch_wins + switch_losses; let total_keeps = keep_wins + keep_losses; println!("Switched door {} times with {} wins and {} losses", total_switches, switch_wins, switch_losses); println!("Kept our choice {} times with {} wins and {} losses", total_keeps, keep_wins, keep_losses); // With a large number of simulations, the values should converge to // 0.667 and 0.333 respectively. println!("Estimated chance to win if we switch: {}", switch_wins as f32 / total_switches as f32); println!("Estimated chance to win if we don't: {}", keep_wins as f32 / total_keeps as f32); }
Reexports
pub use jitter::JitterRng; |
pub use os::OsRng; |
Modules
chacha |
The ChaCha random number generator. |
distributions |
Sampling from random distributions. |
isaac |
The ISAAC random number generator. |
jitter |
Non-physical true random number generator based on timing jitter. |
os |
Interfaces to the operating system provided random number generators. |
read |
A wrapper around any Read to treat it as an RNG. |
reseeding |
A wrapper around another RNG that reseeds it after it generates a certain number of random bytes. |
seq |
Functions for randomly accessing and sampling sequences. |
Structs
AsciiGenerator |
Iterator which will continuously generate random ascii characters. |
ChaChaRng |
A random number generator that uses the ChaCha20 algorithm [1]. |
Closed01 |
A wrapper for generating floating point numbers uniformly in the
closed interval |
Generator |
Iterator which will generate a stream of random items. |
Isaac64Rng |
A random number generator that uses ISAAC-64[1], the 64-bit variant of the ISAAC algorithm. |
IsaacRng |
A random number generator that uses the ISAAC algorithm[1]. |
Open01 |
A wrapper for generating floating point numbers uniformly in the
open interval |
StdRng |
The standard RNG. This is designed to be efficient on the current platform. |
ThreadRng |
The thread-local RNG. |
XorShiftRng |
An Xorshift[1] random number generator. |
Traits
Rand |
A type that can be randomly generated using an |
Rng |
A random number generator. |
SeedableRng |
A random number generator that can be explicitly seeded to produce the same stream of randomness multiple times. |
Functions
random |
Generates a random value using the thread-local random number generator. |
sample |
[ Deprecated ] DEPRECATED: use |
thread_rng |
Retrieve the lazily-initialized thread-local random number
generator, seeded by the system. Intended to be used in method
chaining style, e.g. |
weak_rng |
Create a weak random number generator with a default algorithm and seed. |