Universal RNG

A collection of efficient pseudo-random number generators (PRNGs) implemented in pure Rust. This crate provides a wide variety of algorithms, ranging from standard Mersenne Twister to modern high-performance generators like Xoshiro and Philox.

Supported Generators

Generators are divided into standard generators, portable wide generators, and AVX-accelerated SIMD generators. Standard generators implement the unified Rng trait (Word = u32 or Word = u64; SIMD/counter-based variants return fixed-size arrays instead). Portable wide generators require the wide feature and expose safe fixed-array bulk APIs. AVX generators expose a bulk-generation API and are listed separately; they require the simd feature.

32-bit Generators (urng::)

64-bit Generators (urng::)

Portable Wide Generators (urng::wide)

Requires the wide feature.

These generators use the portable wide crate and expose safe nextu, nextf, randi, and randf methods returning fixed-size arrays.

Example:

use urng::wide::{WRng, Xoshiro128Ppx16};

let mut rng = Xoshiro128Ppx16::new(1);
let values: [u32; 16] = rng.nextu();
let floats: [f32; 16] = rng.nextf();

SIMD Generators (AVX)

These generators expose a bulk-generation API and require AVX support at runtime.

AVX2 (avx2)

AVX-512 (avx512f)

Sampler

Requires the sampler feature.

Weighted random index selection. Two implementations are provided for each bit-width, both implementing the Sampler trait (urng::Sampler).

SeedGen

Requires the seedgen feature.

Hardware-noise-assisted seed generation. Wraps an existing Rng and mixes in hardware noise (RDSEED/RDRAND on x86/x86_64, timestamp fallback elsewhere) via a Murmur3-style hash.

next_seed_pair() returns (raw, processed) — the raw hardware value and the mixed seed.

Testing

Statistical validation of RNG quality is handled by the external cribler crate, a batteries-included randomness-test toolkit. cribler ships every engine (chi-squared, Monte Carlo π, serial correlation, runs, Kolmogorov–Smirnov, birthday spacing, a NIST SP 800-22 subset, and a paranoid battery aggregator) and offers zero-feature integration: any generator plugs in via a plain FnMut() -> f64 / FnMut() -> u64 sampler closure.

Enable the urng feature on cribler for pre-built typed convenience that works directly against urng's Rng generators:

[dependencies]
urng = "1.0.0"
cribler = { version = "0.3", features = ["urng"] }

The suites construct each named case from a seed, so no generator instance needs to be passed in:

use cribler::Suite;
use urng::Rng;

let results = cribler::Suite::default()
    .from_urng32::<urng::Sfc32>()?
    .from_rand::<rand_sfc::Sfc32>()?
    .run()?;

for r in results.iter() {
    println!("{}", serde_json::to_string_pretty(&r)?);
}

from_urng32::<R>() / from_urng64::<R>() register a urng::Rng<Word = u32> / urng::Rng<Word = u64> R, built from the suite's seed. The rand feature provides from_rand::<R>() for rand_core::Rng types, and from_custom(source) accepts anything else via a WordSource adapter.

Usage Examples

Most generators expose the same basic workflow: create an instance with new, then use nextu, nextf, randi, randf, or choice depending on the output type you need. SIMD and counter-based generators return fixed-size arrays instead of single values.

Scalar generators (both 32-bit and 64-bit; SIMD variants are not included) also implement Default, seeding themselves from a time-based, per-call mix so no explicit seed is required:

use urng::*;

let mut rng = Sfc32::default();
let _ = Rng::nextu(&mut rng);

Basic Usage

use urng::*;

fn main() {
    // 1. Initialize with a seed
    let mut rng = Xoshiro256Pp::new(12345);

    // 2. Generate random numbers
    let val_u64 = rng.nextu();
    println!("u64: {}", val_u64);

    let val_f64 = rng.nextf(); // [0.0, 1.0)
    println!("f64: {}", val_f64);

    // 3. Generate within a range
    let val_range = rng.randi(1, 100);
    println!("Integer (1-100): {}", val_range);

    // 4. Seeding with SplitMix64 (common pattern)
    // If you need to seed a large state generator from a single u64
    let mut sm = SplitMix64::new(9999);
    let seed_val = sm.nextu();
    let mut rng2 = Xoshiro256Pp::new(seed_val);
}

C ABI

This crate exports a C-compatible ABI generic interface. Each generator has corresponding:

• _new
• _free
• _next_uXXs (bulk generation)
• _next_fXXs (bulk generation)
• _rand_iXXs (bulk generation)
• _rand_fXXs (bulk generation)

Example for Mt19937:

void* mt19937_new(uint32_t seed, size_t warm);
void mt19937_next_u32s(void* ptr, uint32_t* out, size_t count);
void mt19937_rand_f32s(void* ptr, float* out, size_t count, float min, float max);
void mt19937_free(void* ptr);