NAME
Math::Random::MTwist - A fast stateful Mersenne Twister pseudo-random number generator
SYNOPSIS
use Math::Random::MTwist;
my $mt = Math::Random::MTwist->new(); # seed from /dev/urandom
my $int = $mt->irand(); # [0 .. 2^64-1 or 2^32-1]
my $double = $mt->rand(73); # [0 .. 73)
$mt->goodseed(); # seed from /dev/random
$mt->savestate("/tmp/foobar"); # save current state to file
$mt->loadstate("/tmp/foobar"); # load past state from file
my @dist = map $mt->rds_triangular(1, 3, 2), 1 .. 1e3; # triangular dist.DESCRIPTION
Math::Random::MTwist is an object-oriented Perl interface to Geoff Kuenning's mtwist C library. It provides several seeding methods, an independent state per instance and various random number distributions.
Random number generation is significantly faster than with Math::Random::MT (kudos to Geoff).
This module is not fork()/clone() aware, i.e. you have to take care of re-seeding/re-instantiating in new processes/threads yourself.
CONSTRUCTOR
new()
Takes an optional argument specifying the seed. The seed can be a number (will be coerced into an unsigned 32-bit integer), an array reference holding up to 624 such numbers (missing values are padded with zeros, excess values are ignored) or one of the special values MT_TIMESEED, MT_FASTSEED, MT_GOODSEED or MT_BESTSEED that choose one of the corresponding seeding methods (see below). If no seed is given, MT_FASTSEED is assumed.
Each instance maintains an individual PRNG state allowing multiple independent random number streams.
SEEDING
seed32($number)
Seeds the generator with $number. The value will be coerced into an unsigned 32-bit integer. Calls mtwist's mts_seed32new().
seedfull($arrayref)
Seeds the generator with up to 624 numbers from $arrayref. The values are coerced into unsigned 32-bit integers. Missing values are padded with zeros, excess values are ignored. Calls mtwist's mts_seedfull().
timeseed()
Seeds the generator from the current system time obtained with gettimeofday() by calculating seconds * 1e6 + microseconds and coercing the result into an unsigned 32-bit integer.
This method is called by new(MT_TIMESEED).
It doesn't correspond to any of mtwist's functions. The rationale behind it is that mtwist falls back to the system time if neither /dev/urandom nor /dev/random is available. On Windows the time source chosen by mtwist has only millisecond resolution in contrast to microseconds from Time::HiRes::gettimeofday().
fastseed()
Seeds the generator with 4 bytes read from /dev/urandom if available, otherwise from the system time (see details under timeseed()). Calls mtwist's mts_seed().
This method is called by new(MT_FASTSEED).
goodseed()
Seeds the generator with 4 bytes read from /dev/random if available, otherwise from the system time (see details under timeseed()). Calls mtwist's mts_goodseed().
This method is called by new(MT_GOODSEED).
bestseed()
Seeds the generator with 642 integers read from /dev/random if available. This might take a very long time and is probably not worth the waiting. If /dev/random is unavailable or there was a reading error it falls back to goodseed(). Calls mtwist's mts_bestseed().
This method is called by new(MT_BESTSEED).
STATE HANDLING
savestate($filename or $filehandle)
Saves the current state of the generator to a file given either by a filename (file will be truncated) or an open Perl file handle.
Returns 1 on success, 0 on error (you might want to check $! in this case).
loadstate($filename or $filehandle)
Loads the state of the generator from a file given either by a filename or an open Perl file handle.
Returns 1 on success, 0 on error (you might want to check $! in this case).
UNIFORMLY DISTRIBUTED RANDOM NUMBERS
irand()
Returns a random unsigned integer, 64-bit if your system supports it (see irand64()), 32-bit otherwise.
irand32()
Returns a random unsigned 32-bit integer. Calls mtwist's mts_lrand().
irand64()
If your Perl is 64-bit, returns a 64-bit unsigned integer. If your Perl is 32-bit but your OS knows the uint64_t type, returns a 64-bit unsigned integer coerced into a double (so it's the full 64-bit range but with only 52-bit precision). Otherwise it returns undef. Calls mtwist's mts_llrand().
rand($bound)
Returns a random double with 52-bit precision in the range [0, $bound). Calls mtwist's mts_ldrand().
$bound may be negative. If $bound is omitted or zero it defaults to 1.
rand32($bound)
Returns a random double with 32-bit precision in the range [0, $bound). Slightly faster than rand(). Calls mtwist's mts_drand().
$bound may be negative. If $bound is omitted or zero it defaults to 1.
NON-UNIFORMLY DISTRIBUTED RANDOM NUMBERS
The following methods come in two variants: rds_xxx and rds_lxxx. They all return a double but the rds_xxx versions provide 32-bit precision while the rds_lxxx versions provide 52-bit precision at the expense of speed.
rds_(l)exponential(double mean)
Generates an exponential distribution with the given mean.
rds_(l)erlang(int p, double mean)
Generates a p-Erlang distribution with the given mean.
rds_(l)weibull(double shape, double scale)
Generates a Weibull distribution with the given shape and scale.
rds_(l)normal(double mean, double sigma)
Generates a normal (Gaussian) distribution with the given mean and standard deviation sigma.
rds_(l)lognormal(double shape, double scale)
Generates a log-normal distribution with the given shape and scale.
rds_(l)triangular(double lower, double upper, double mode)
Generates a triangular distribution in the range [lower, upper) with the given mode.
EXPORTS
The module exports the constants MT_TIMESEED, MT_FASTSEED, MT_GOODSEED and MT_BESTSEED that can be used as an argument to the constructor.
SEE ALSO
http://www.cs.hmc.edu/~geoff/mtwist.html
AUTHOR
Carsten Gaebler (cgpan ʇɐ gmx ʇop de). I only accept encrypted e-mails, either via SMIME or GPG.
COPYRIGHT
Perl and XS portion: Copyright © 2014 by Carsten Gaebler.
mtwist C library: Copyright © 2001, 2002, 2010, 2012, 2013 by Geoff Kuenning.
LICENSE
Perl and XS portion: Do What The Fuck You Want To Public License.
mtwist C library: LGPL