Arc<Mutex>

Guides

Rust walkthroughs

← Back to all guides

How does rand::rngs::StdRng::seed_from_u64 enable reproducible random number generation across runs?

seed_from_u64 initializes a random number generator from a single 64-bit seed, guaranteeing that the same seed produces the same sequence of random numbers across different program executions, enabling deterministic simulations, reproducible tests, and consistent procedurally generated content. This deterministic behavior is essential for debugging, scientific reproducibility, and any scenario where you need to replay the exact same sequence of "random" events.

Basic Seeding for Reproducibility

use rand::rngs::StdRng;
use rand::Rng;
use rand::SeedableRng;
 
fn basic_seeding() {
    // Create RNG with a fixed seed
    let mut rng1 = StdRng::seed_from_u64(42);
    
    // Generate some values
    let v1_a: u32 = rng1.gen();
    let v1_b: u32 = rng1.gen();
    let v1_c: u32 = rng1.gen();
    
    // Create a new RNG with the same seed
    let mut rng2 = StdRng::seed_from_u64(42);
    
    // Generate the same sequence
    let v2_a: u32 = rng2.gen();
    let v2_b: u32 = rng2.gen();
    let v2_c: u32 = rng2.gen();
    
    assert_eq!(v1_a, v2_a);
    assert_eq!(v1_b, v2_b);
    assert_eq!(v1_c, v2_c);
    
    println!("Same seed produces same sequence!");
}

Identical seeds produce identical sequences, guaranteeing reproducibility.

Reproducibility Across Program Runs

use rand::rngs::StdRng;
use rand::Rng;
use rand::SeedableRng;
use std::fs;
 
fn cross_run_reproducibility() {
    // First run: generate and save results
    fn run_simulation(seed: u64) -> Vec<u32> {
        let mut rng = StdRng::seed_from_u64(seed);
        let mut results = Vec::new();
        for _ in 0..5 {
            results.push(rng.gen());
        }
        results
    }
    
    let results1 = run_simulation(12345);
    let results2 = run_simulation(12345);
    
    // Both runs produce identical results
    assert_eq!(results1, results2);
    
    // This works across different process executions:
    // Run 1: seed 12345 -> [A, B, C, D, E]
    // Run 2: seed 12345 -> [A, B, C, D, E] (identical)
}

The same seed in different process executions produces identical sequences.

The SeedableRng Trait

use rand::SeedableRng;
use rand::rngs::StdRng;
 
fn seedable_rng_trait() {
    // seed_from_u64 comes from the SeedableRng trait
    // It's a convenience method that wraps from_seed
    
    // seed_from_u64 is defined as:
    // fn seed_from_u64(seed: u64) -> Self;
    
    // It expands the 64-bit seed into the RNG's internal state
    // For StdRng (which uses ChaCha), this initializes the
    // internal state deterministically
    
    // Alternative: from_seed with explicit state
    let mut rng = StdRng::from_seed([0u8; 32]);
    // from_seed takes the full internal state (32 bytes for StdRng)
    
    // seed_from_u64 is more convenient when you just need a
    // simple seed value
}

seed_from_u64 is a convenience over the lower-level from_seed method.

Use Case: Deterministic Simulations

use rand::rngs::StdRng;
use rand::Rng;
use rand::SeedableRng;
 
struct Simulation {
    rng: StdRng,
    particles: Vec<Particle>,
}
 
#[derive(Clone, Copy, Debug)]
struct Particle {
    x: f64,
    y: f64,
    vx: f64,
    vy: f64,
}
 
impl Simulation {
    fn new(seed: u64) -> Self {
        Simulation {
            rng: StdRng::seed_from_u64(seed),
            particles: Vec::new(),
        }
    }
    
    fn add_random_particle(&mut self) {
        let x = self.rng.gen::<f64>() * 100.0;
        let y = self.rng.gen::<f64>() * 100.0;
        let vx = self.rng.gen::<f64>() * 2.0 - 1.0;
        let vy = self.rng.gen::<f64>() * 2.0 - 1.0;
        self.particles.push(Particle { x, y, vx, vy });
    }
    
    fn step(&mut self) {
        // Deterministic random decisions
        for particle in &mut self.particles {
            // Add small random perturbation
            particle.vx += self.rng.gen::<f64>() * 0.1 - 0.05;
            particle.vy += self.rng.gen::<f64>() * 0.1 - 0.05;
            
            particle.x += particle.vx;
            particle.y += particle.vy;
        }
    }
}
 
fn simulation_example() {
    // Two simulations with same seed
    let mut sim1 = Simulation::new(42);
    let mut sim2 = Simulation::new(42);
    
    // Both add particles in same positions
    for _ in 0..10 {
        sim1.add_random_particle();
        sim2.add_random_particle();
    }
    
    // Both step deterministically
    for _ in 0..100 {
        sim1.step();
        sim2.step();
    }
    
    // Both end in same state
    assert_eq!(sim1.particles.len(), sim2.particles.len());
    for (p1, p2) in sim1.particles.iter().zip(sim2.particles.iter()) {
        assert!((p1.x - p2.x).abs() < 1e-10);
        assert!((p1.y - p2.y).abs() < 1e-10);
    }
}

Simulations become reproducible for debugging and scientific validation.

Use Case: Reproducible Testing

use rand::rngs::StdRng;
use rand::Rng;
use rand::SeedableRng;
 
#[cfg(test)]
mod tests {
    use super::*;
    
    fn generate_test_data(rng: &mut StdRng) -> Vec<i32> {
        (0..100).map(|_| rng.gen_range(0..1000)).collect()
    }
    
    fn algorithm_under_test(data: &[i32]) -> i32 {
        data.iter().sum()
    }
    
    #[test]
    fn test_deterministic() {
        // Fixed seed ensures reproducible test
        let mut rng = StdRng::seed_from_u64(12345);
        
        let data = generate_test_data(&mut rng);
        let result = algorithm_under_test(&data);
        
        // Test assertion is deterministic
        assert_eq!(result, 49758);
        
        // If test fails, you can reproduce exact scenario
        // by using same seed
    }
    
    #[test]
    fn test_with_logged_seed() {
        // Log the seed for debugging
        let seed: u64 = 12345;
        println!("Test seed: {}", seed);
        
        let mut rng = StdRng::seed_from_u64(seed);
        // ... test code ...
    }
}

Tests with random data can be reproduced exactly for debugging failures.

Use Case: Procedural Generation

use rand::rngs::StdRng;
use rand::Rng;
use rand::SeedableRng;
 
struct WorldMap {
    seed: u64,
    terrain: Vec<Vec<Terrain>>,
}
 
#[derive(Clone, Copy, Debug, PartialEq)]
enum Terrain {
    Water,
    Grass,
    Mountain,
    Forest,
}
 
impl WorldMap {
    fn generate(seed: u64, width: usize, height: usize) -> Self {
        let mut rng = StdRng::seed_from_u64(seed);
        
        let mut terrain = vec
![vec
![Terrain::Grass; width]; height];
        
        // Deterministic terrain generation
        for y in 0..height {
            for x in 0..width {
                terrain[y][x] = match rng.gen_range(0..4) {
                    0 => Terrain::Water,
                    1 => Terrain::Grass,
                    2 => Terrain::Mountain,
                    3 => Terrain::Forest,
                    _ => unreachable!(),
                };
            }
        }
        
        WorldMap { seed, terrain }
    }
    
    fn regenerate(&self) -> Self {
        // Same seed produces same map
        Self::generate(self.seed, self.terrain[0].len(), self.terrain.len())
    }
}
 
fn procedural_generation() {
    // Generate world from seed
    let world1 = WorldMap::generate(98765, 100, 100);
    let world2 = WorldMap::generate(98765, 100, 100);
    
    // Both worlds are identical
    assert_eq!(world1.terrain, world2.terrain);
    
    // Players can share seeds to generate identical worlds
    println!("Share seed 98765 for this world!");
}

Games can share seeds for identical procedurally generated content.

Seed Derivation Strategies

use rand::rngs::StdRng;
use rand::SeedableRng;
 
fn seed_derivation() {
    // From a simple number
    let rng1 = StdRng::seed_from_u64(42);
    
    // From a hash of string
    use std::hash::{Hash, Hasher};
    use std::collections::hash_map::DefaultHasher;
    
    fn hash_string(s: &str) -> u64 {
        let mut hasher = DefaultHasher::new();
        s.hash(&mut hasher);
        hasher.finish()
    }
    
    let seed = hash_string("my-reproducible-seed");
    let rng2 = StdRng::seed_from_u64(seed);
    
    // From multiple values
    fn combine_seeds(a: u64, b: u64, c: u64) -> u64 {
        // Simple combination (not cryptographic!)
        a ^ b.wrapping_mul(31) ^ c.wrapping_mul(37)
    }
    
    let seed = combine_seeds(100, 200, 300);
    let rng3 = StdRng::seed_from_u64(seed);
    
    // From timestamp (not reproducible!)
    // let non_reproducible_seed = SystemTime::now()
    //     .duration_since(UNIX_EPOCH).unwrap().as_nanos() as u64;
    // This would give different seeds each run
}

Seeds can be derived from various sources, but fixed values ensure reproducibility.

Storing and Restoring RNG State

use rand::rngs::StdRng;
use rand::{Rng, SeedableRng};
 
fn save_restore_state() {
    let mut rng = StdRng::seed_from_u64(42);
    
    // Generate some values
    let _ = rng.gen::<u32>();
    let _ = rng.gen::<u32>();
    
    // Save current state
    let state = rng.clone();  // StdRng is Clone
    
    // Generate more
    let v1 = rng.gen::<u32>();
    let v2 = rng.gen::<u32>();
    
    // Restore to saved state
    let mut rng = state;
    
    // Now we get the same sequence
    let v1_again = rng.gen::<u32>();
    let v2_again = rng.gen::<u32>();
    
    assert_eq!(v1, v1_again);
    assert_eq!(v2, v2_again);
}

Cloning the RNG captures its full state for later resumption.

StdRng Internal State

use rand::rngs::StdRng;
use rand::SeedableRng;
 
fn internal_state() {
    // StdRng uses ChaCha algorithm
    // Internal state is 32 bytes (256 bits)
    
    // seed_from_u64 expands 64 bits to 256 bits
    let rng = StdRng::seed_from_u64(42);
    
    // You can also use from_seed with full 32-byte state
    let custom_state = [1u8; 32];
    let rng = StdRng::from_seed(custom_state);
    
    // Get the seed back (for serialization)
    // Note: get_seed() is not available, but you can clone
    let rng_backup = rng.clone();
    
    // This allows saving/restoring state in applications
    // where you need to checkpoint and resume
}

StdRng uses ChaCha internally with a 256-bit state.

ThreadRng vs StdRng

use rand::rngs::{StdRng, ThreadRng};
use rand::{Rng, SeedableRng, thread_rng};
 
fn thread_rng_vs_std_rng() {
    // ThreadRng: NOT reproducible
    // Uses system entropy, seeded differently each run
    let mut thread_rng = thread_rng();
    let v1: u32 = thread_rng.gen();
    // v1 is different each program execution
    
    // StdRng with seed: REPRODUCIBLE
    let mut std_rng = StdRng::seed_from_u64(42);
    let v2: u32 = std_rng.gen();
    // v2 is same each program execution with seed 42
    
    // When to use each:
    // - ThreadRng: Security, unpredictability needed
    // - StdRng + seed: Reproducibility, testing, debugging
}
 
fn convert_thread_to_std() {
    // You can seed StdRng from ThreadRng when you need
    // reproducibility from a random starting point
    
    use rand::Rng;
    
    let mut thread_rng = thread_rng();
    let random_seed: u64 = thread_rng.gen();
    
    // Now use that seed for reproducibility
    let mut std_rng = StdRng::seed_from_u64(random_seed);
    
    println!("Using seed: {}", random_seed);
    // If you need to reproduce, log the seed
}

ThreadRng provides unpredictability; StdRng with a fixed seed provides reproducibility.

Cross-Platform Reproducibility

use rand::rngs::StdRng;
use rand::{Rng, SeedableRng};
 
fn cross_platform() {
    // StdRng (ChaCha) is designed for cross-platform reproducibility
    // Same seed produces same sequence on:
    // - Different operating systems
    // - Different CPU architectures
    // - Different Rust versions (within semver compatibility)
    
    let mut rng = StdRng::seed_from_u64(12345);
    
    // These values should be identical across platforms
    let a: u32 = rng.gen();
    let b: u64 = rng.gen();
    let c: f64 = rng.gen();
    
    // ChaCha is a well-defined, portable algorithm
    // Unlike hardware RNG or system-dependent sources
}

StdRng uses ChaCha for portable, cross-platform reproducibility.

Seeding Multiple Independent Generators

use rand::rngs::StdRng;
use rand::{Rng, SeedableRng};
 
fn multiple_generators() {
    // Different seeds for independent generators
    let mut rng_a = StdRng::seed_from_u64(1);
    let mut rng_b = StdRng::seed_from_u64(2);
    
    // These sequences are independent
    let a_vals: Vec<u32> = (0..5).map(|_| rng_a.gen()).collect();
    let b_vals: Vec<u32> = (0..5).map(|_| rng_b.gen()).collect();
    
    // Different sequences
    assert_ne!(a_vals, b_vals);
    
    // For truly independent generators, use master seed
    // to derive sub-seeds:
    fn derive_seeds(master: u64, count: usize) -> Vec<u64> {
        let mut rng = StdRng::seed_from_u64(master);
        (0..count).map(|_| rng.gen()).collect()
    }
    
    let seeds = derive_seeds(999, 3);
    let mut rng1 = StdRng::seed_from_u64(seeds[0]);
    let mut rng2 = StdRng::seed_from_u64(seeds[1]);
    let mut rng3 = StdRng::seed_from_u64(seeds[2]);
}

Different seeds produce independent sequences from the same algorithm.

Practical Pattern: Seedable Test Harness

use rand::rngs::StdRng;
use rand::{Rng, SeedableRng};
 
struct TestHarness {
    rng: StdRng,
    seed: u64,
}
 
impl TestHarness {
    fn new(seed: u64) -> Self {
        TestHarness {
            rng: StdRng::seed_from_u64(seed),
            seed,
        }
    }
    
    fn random<T: rand::distributions::uniform::SampleUniform>(&mut self, range: std::ops::Range<T>) -> T {
        self.rng.gen_range(range)
    }
    
    fn reset(&mut self) {
        // Reset to original seed
        self.rng = StdRng::seed_from_u64(self.seed);
    }
    
    fn fork(&self) -> Self {
        // Create independent harness
        TestHarness::new(self.rng.gen())
    }
    
    fn state(&self) -> String {
        // For debugging: show seed and current position hint
        format!("seed={}", self.seed)
    }
}
 
fn test_harness_example() {
    let mut harness = TestHarness::new(42);
    
    // Use harness for random operations
    let v1 = harness.random(0..100);
    let v2 = harness.random(0..100);
    
    // Reset to reproduce sequence
    harness.reset();
    let v1_again = harness.random(0..100);
    let v2_again = harness.random(0..100);
    
    assert_eq!(v1, v1_again);
    assert_eq!(v2, v2_again);
}

A test harness with seed management enables controlled randomness.

Debugging with Deterministic Seeds

use rand::rngs::StdRng;
use rand::{Rng, SeedableRng};
 
fn debug_pattern() {
    // Pattern for debugging with seeded RNG
    
    // 1. Start with environment-variable controlled seed
    let seed = std::env::var("RNG_SEED")
        .map(|s| s.parse::<u64>().unwrap())
        .unwrap_or(42);  // Default deterministic seed
    
    let mut rng = StdRng::seed_from_u64(seed);
    
    // 2. Log the seed at start
    eprintln!("Using RNG seed: {}", seed);
    
    // 3. Run with randomness
    let data: Vec<i32> = (0..10).map(|_| rng.gen_range(0..100)).collect();
    
    // 4. When bug occurs, you can reproduce with same seed
    // RNG_SEED=42 cargo run
    
    // This pattern enables:
    // - Reproducible bug reports
    // - CI runs with logged seeds
    // - Easy reproduction of random failures
}

Logging seeds enables reproduction of random behavior in production.

Limitations and Considerations

use rand::rngs::StdRng;
use rand::{Rng, SeedableRng};
 
fn limitations() {
    // 1. seed_from_u64 is NOT cryptographically secure
    // Don't use for passwords, keys, security tokens
    
    // 2. 64-bit seed space (limited entropy)
    // 2^64 possible seeds vs 2^256 for full state
    
    // 3. Version stability
    // Same Rust/rand version required for identical sequences
    // Future versions might change algorithm
    
    // 4. Thread safety
    // StdRng is not thread-safe; use separate instances per thread
    
    // 5. Seed quality matters for uniform distribution
    // Poor seeds might not distribute evenly
    let mut rng = StdRng::seed_from_u64(0);  // All zeros
    // Works but conceptually less entropy
    
    // For cryptographic use:
    // use rand::rngs::OsRng;  // Secure but not reproducible
}

Understand limitations for appropriate use cases.

Summary Table

fn summary_table() {
    // ┌─────────────────────────────────────────────────────────────────────────┐
    // │ Aspect           │ seed_from_u64              │ ThreadRng             │
    // ├─────────────────────────────────────────────────────────────────────────┤
    // │ Reproducible     │ Yes (with same seed)       │ No                    │
    // │ Seed source      │ User-provided u64          │ System entropy        │
    // │ Cross-run        │ Identical sequences        │ Different sequences   │
    // │ Cross-platform   │ Identical (ChaCha)         │ Platform-dependent    │
    // │ Use case         │ Tests, simulations         │ Security, unpredict   │
    // │ State control    │ Full control               │ No control            │
    // │ Serialization    │ Seed is 64-bit integer     │ Cannot serialize     │
    // └─────────────────────────────────────────────────────────────────────────┘
}

Key Points Summary

fn key_points() {
    // 1. seed_from_u64 creates deterministic RNG from 64-bit seed
    // 2. Same seed produces identical sequence across runs
    // 3. Essential for reproducible tests and simulations
    // 4. Enables debugging by logging seed values
    // 5. StdRng uses ChaCha for cross-platform consistency
    // 6. Different from ThreadRng which uses system entropy
    // 7. Not for cryptographic security purposes
    // 8. 64-bit seed space (limited vs full 256-bit state)
    // 9. Clone RNG to save/restore state mid-sequence
    // 10. Derive multiple seeds from master for independent generators
    // 11. Log seeds for reproduction in production debugging
    // 12. Reset with same seed to replay exact sequence
}

Key insight: seed_from_u64 transforms randomness into controlled determinism. The same 64-bit seed always produces the same sequence of "random" numbers, which is invaluable for debugging (reproduce exact failure scenarios), testing (deterministic tests with random data), scientific computing (reproducible experiments), and game development (shareable procedural content seeds). This is fundamentally different from ThreadRng which provides true unpredictability at the cost of reproducibility. The choice between them is about whether you need consistency across runs (use StdRng::seed_from_u64) or unpredictability (use ThreadRng).