artichoke / rand_mt

🌪 Mersenne Twister implementation backed by rand_core

rand_mt

Implements a selection of Mersenne Twister random number generators.

A very fast random number generator of period 2¹⁹⁹³⁷-1. (Makoto Matsumoto, 1997).

The Mersenne Twister algorithms are not suitable for cryptographic uses, but are ubiquitous. See the Mersenne Twister website. A variant of Mersenne Twister is the default PRNG in Ruby.

This crate optionally depends on rand_core and implements RngCore on the RNGs in this crate.

Usage

Add this to your Cargo.toml:

[dependencies]
rand_mt = "4.2.2"

Then create a RNG like:

use rand_mt::Mt64;

let mut rng = Mt64::new_unseeded();
assert_ne!(rng.next_u64(), rng.next_u64());

Crate Features

rand_mt is no_std compatible. rand_mt has several optional features that are enabled by default:

• rand-traits - Enables a dependency on rand_core. Activating this feature implements RngCore and SeedableRng on the RNGs in this crate.
• std - Enables a dependency on the Rust Standard Library. Activating this feature enables std::error::Error impls on error types in this crate.

Mersenne Twister requires approximately 2.5 kilobytes of internal state. To make the RNGs implemented in this crate practical to embed in other structs, you may wish to store the RNG in a Box.

Minimum Supported Rust Version

This crate requires at least Rust 1.47.0. This version can be bumped in minor releases.

License

rand_mt is distributed under the terms of either the MIT License or the Apache License (Version 2.0).

rand_mt is derived from rust-mersenne-twister @ 1.1.1 which is Copyright (c) 2015 rust-mersenne-twister developers.

rand_mt's Issues

Replace hand-rolled chunks loop in `fill_bytes` with `chunks_exact_mut`

Both Mt::fill_bytes and Mt64::fill_bytes use a handrolled implementation of [u8]::chunks_exact_mut.

Replace these while loops with use of the ChunksExactMut iterator.

rand_mt/src/mt.rs

Lines 306 to 317 in 7123536

	let mut left = dest;
	while left.len() >= CHUNK {
	let (next, remainder) = left.split_at_mut(CHUNK);
	left = remainder;
	let chunk: [u8; CHUNK] = self.next_u32().to_le_bytes();
	next.copy_from_slice(&chunk);
	}
	let n = left.len();
	if n > 0 {
	let chunk: [u8; CHUNK] = self.next_u32().to_le_bytes();
	left.copy_from_slice(&chunk[..n]);
	}

rand_mt/src/mt64.rs

Lines 289 to 300 in 7123536

	let mut left = dest;
	while left.len() >= CHUNK {
	let (next, remainder) = left.split_at_mut(CHUNK);
	left = remainder;
	let chunk: [u8; CHUNK] = self.next_u64().to_le_bytes();
	next.copy_from_slice(&chunk);
	}
	let n = left.len();
	if n > 0 {
	let chunk: [u8; CHUNK] = self.next_u64().to_le_bytes();
	left.copy_from_slice(&chunk[..n]);
	}

Add cargo-spellcheck config

See this example PR in intaglio:

• artichoke/intaglio#142

Random number generated

I have a code in python that uses the random.py file Random class. In python when generating numbers with the Random class and seed 123 I receive a number 261662301160200998434711212977610535782, but when I try to reproduce the same in Rust it gives me this result 258431468044781239883754362733579478088.
Code example:

let mut rng = mt::MT19937::MT19937::from_seed(123i32.to_le_bytes());
let mut bytes:[u8;16] = [0;16]; 
let res:u128 = rng.gen();

Can you help solve this issue

Add tests for `impl Default` for `Mt` and `Mt64`

• impl Default for Mt19937GenRand64 – uncovered https://codecov.artichokeruby.org/rand_mt/src/mt64.rs.html#66
• impl Default for Mt19937GenRand32 – https://codecov.artichokeruby.org/rand_mt/src/mt.rs.html#69

Consider supporting CPython's random compatibility

In order to support CPython there are only a couple small changes required. I would like to suggest a MtPython struct that would generate values according to the CPython source code.

I am willing to write the code myself and submit a PR.

If you think that this doesn't suit your library, please consider at least adding this information to the README or the documentation.

Rust reference implementation:

use rand_mt::Mt;

const SEED: u32 = 2137;

fn main() {
    // Every python seed is converted, and initialized as a key: https://github.com/python/cpython/blob/ce558e69d4087dd3653207de78345fbb8a2c7835/Modules/_randommodule.c#LL355C8-L355C8
    let mut rng = Mt::new_with_key([SEED]);

    // CPython does this to get 64 bit float: https://github.com/python/cpython/blob/ce558e69d4087dd3653207de78345fbb8a2c7835/Modules/_randommodule.c#L181
    let a = rng.next_u32() >> 5;
    let b = rng.next_u32() >> 6;
    let n_rust = (a as f64 * 67108864.0 + b as f64) * (1.0 / 9007199254740992.0);

    // Python:
    // #!/bin/python3
    // import random
    //
    // SEED = 2137
    //
    // random.seed(SEED)
    // n_python = random.random()
    // assert n_python == 0.571786152497536
    let n_python = 0.571786152497536;

    assert_eq!(n_rust, n_python);
}

CPython random seed using bytearray: https://github.com/python/cpython/blob/ce558e69d4087dd3653207de78345fbb8a2c7835/Modules/_randommodule.c#LL355C8-L355C8
CPython random.random() implementation: https://github.com/python/cpython/blob/ce558e69d4087dd3653207de78345fbb8a2c7835/Modules/_randommodule.c#L181

Related to #192

Naming convention

Not really an issue, just a suggestion (Or a bikeshedding, sorry).
Mt19937GenRand32 and Mt19937GenRand64 are too long, I agree. But Mt and Mt64 are somewhat non-conventional. Maybe it would be better to pick names like Mt19937b32 and Mt19937b64?