NAME
Math::Random::MTwist - A fast stateful Mersenne Twister pseudo-random number generator.
SYNOPSIS
# object-oriented inteface
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->rd_triangular(1, 3, 2), 1 .. 1e3; # triangular dist.
# function-oriented interface (OO interface may be used in parallel)
use Math::Random::MTwist qw(seed32 seedfull
timeseed fastseed goodseed bestseed);
use Math::Random::MTwist qw(:seed) # gives you all of the above
use Math::Random::MTwist qw(srand rand rand32 irand irand32 irand64);
use Math::Random::MTwist qw(:rand); # gives you all of the above
use Math::Random::MTwist qw(rd_exponential rd_triangular rd_normal ...);
use Math::Random::MTwist qw(:dist); # gives you all of the above
use Math::Random::MTwist qw(savestate loadstate);
use Math::Random::MTwist qw(:state); # gives you all of the aboveDESCRIPTION
Math::Random::MTwist is a Perl interface to Geoff Kuenning's mtwist C library. It provides several seeding methods, an independent state per OO instance and various random number distributions.
All functions are available through a function-oriented interface and an object-oriented interface. If you use the function-oriented interface the generator maintains a single global state while with the OO interface each instance has its individual state.
The function-oriented interface provides drop-in replacements for Perl's built-in rand() and srand() functions. If you use the module with an import list srand() is called once automatically. If you need the MT_ constants too you must import them through the tag :DEFAULT.
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(). Returns the seed.
srand($number)
Calls seed32 if $number is given, fastseed() otherwise. Returns the seed.
seedfull($seeds)
Seeds the generator with up to 624 numbers from the array reference $seeds. 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. Returns the seed.
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(). Returns the 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(). Returns the seed.
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(). Returns the seed.
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: rd_xxx and rd_lxxx. They all return a double but the rd_xxx versions provide 32-bit precision while the rd_lxxx versions provide 52-bit precision at the expense of speed.
Despite their names they call mtwist's rds_xxx functions if used with the OO interface.
rd_(l)exponential(double mean)
Generates an exponential distribution with the given mean.
rd_(l)erlang(int k, double mean)
Generates an Erlang-k distribution with the given mean.
rd_(l)weibull(double shape, double scale)
Generates a Weibull distribution with the given shape and scale.
rd_(l)normal(double mean, double sigma)
Generates a normal (Gaussian) distribution with the given mean and standard deviation sigma.
rd_(l)lognormal(double shape, double scale)
Generates a log-normal distribution with the given shape and scale.
rd_(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
Math::Random::MT and Math::Random::MT::Auto are significantly slower than Math::Random::MTwist. On the other hand MRMA has some additional sophisticated features.
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: WTFPL.
mtwist C library: LGPL