NAME

Math::Random::MT::Auto - Auto-seeded Mersenne Twister PRNGs

VERSION

This documentation refers to Math::Random::MT::Auto version 6.23

SYNOPSIS

 use strict;
 use warnings;
 use Math::Random::MT::Auto qw(rand irand shuffle gaussian),
                            '/dev/urandom' => 256,
                            'random_org';
 # Functional interface
 my $die_roll = 1 + int(rand(6));
 my $coin_flip = (irand() & 1) ? 'heads' : 'tails';
 my @deck = shuffle(1 .. 52);
 my $rand_IQ = gaussian(15, 100);
 # OO interface
 my $prng = Math::Random::MT::Auto->new('SOURCE' => '/dev/random');
 my $angle = $prng->rand(360);
 my $decay_interval = $prng->exponential(12.4);

DESCRIPTION

The Mersenne Twister is a fast pseudorandom number generator (PRNG) that is capable of providing large volumes (> 10^6004) of "high quality" pseudorandom data to applications that may exhaust available "truly" random data sources or system-provided PRNGs such as rand.

This module provides PRNGs that are based on the Mersenne Twister. There is a functional interface to a single, standalone PRNG, and an OO interface (based on the inside-out object model as implemented by the Object::InsideOut module) for generating multiple PRNG objects. The PRNGs are normally self-seeding, automatically acquiring a (19968-bit) random seed from user-selectable sources. (Manual seeding is optionally available.)

Random Number Deviates

In addition to integer and floating-point uniformly-distributed random number deviates (i.e., "irand" and "rand"), this module implements the following non-uniform deviates as found in Numerical Recipes in C:

Shuffling

This module also provides a subroutine/method for shuffling data based on the Fisher-Yates shuffling algorithm.

Support for 64-bit Integers

If Perl has been compiled to support 64-bit integers (do perl -V and look for "use64bitint=define"), then this module will use a 64-bit-integer version of the Mersenne Twister, thus providing 64-bit random integers and 52-bit random doubles. The size of integers returned by "irand", and used by "get_seed" and "set_seed" will be sized accordingly.

Programmatically, the size of Perl's integers can be determined using the "Config" module:

 use Config;
 print("Integers are $Config{'uvsize'} bytes in length\n");
    

The code for this module has been optimized for speed. Under Cygwin, it's 2.5 times faster than Math::Random::MT, and under Solaris, it's more than four times faster. (Math::Random::MT fails to build under Windows.)

QUICKSTART

To use this module as a drop-in replacement for Perl's built-in rand function, just add the following to the top of your application code:

 use strict;
 use warnings;
 use Math::Random::MT::Auto 'rand';

and then just use "rand" as you would normally. You don't even need to bother seeding the PRNG (i.e., you don't need to call "srand"), as that gets done automatically when the module is loaded by Perl.

If you need multiple PRNGs, then use the OO interface:

 use strict;
 use warnings;
 use Math::Random::MT::Auto;
 my $prng1 = Math::Random::MT::Auto->new();
 my $prng2 = Math::Random::MT::Auto->new();
 my $rand_num = $prng1->rand();
 my $rand_int = $prng2->irand();

CAUTION: If you want to require this module, see the "Delayed Importation" section for important information.

MODULE DECLARATION

The module must always be declared such that its "->import()" method gets called:

 use Math::Random::MT::Auto;            # Correct
 #use Math::Random::MT::Auto ();        # Does not work because
                                        #   ->import() does not get invoked

 use Math::Random::MT::Auto qw(rand irand shuffle gaussian
                               exponential erlang poisson binomial
                               srand get_seed set_seed get_state set_state);

 my $rand = Math::Random::MT::Auto::rand();

 # Get at most 1024 bytes from random.org
 # Finish the seed using data from /dev/urandom
 use Math::Random::MT::Auto 'random_org' => (1024 / $Config{'uvsize'}),
                            '/dev/urandom';

 eval {
     require Math::Random::MT::Auto;
     # You may add options to the import call, if desired.
     Math::Random::MT::Auto->import();
 };

STANDALONE PRNG OBJECT

my $obj = $MRMA::PRNG;

$MRMA::PRNG is the object that represents the standalone PRNG.

OBJECT CREATION

The OO interface for this module allows you to create multiple, independent PRNGs.

If your application will only be using the OO interface, then declare this module using the :!auto flag to forestall the automatic seeding of the standalone PRNG:

 use Math::Random::MT::Auto ':!auto';

Math::Random::MT::Auto->new

 my $prng = Math::Random::MT::Auto->new( %options );
    

Creates a new PRNG. With no options, the PRNG is seeded using the default sources that were determined when the module was loaded, or that were last supplied to the "srand" subroutine.

$obj->new

 my $prng2 = $prng1->new( %options );
    

Creates a new PRNG in the same manner as "Math::Random::MT::Auto->new".

$obj->clone

 my $prng2 = $prng1->clone();
    

Creates a new PRNG that is a copy of the referenced PRNG.

SUBROUTINES/METHODS

When any of the functions listed below are invoked as subroutines, they operates with respect to the standalone PRNG. For example:

 my $rand = rand();

When invoked as methods, they operate on the referenced PRNG object:

 my $rand = $prng->rand();

For brevity, only usage examples for the functional interface are given below.

rand

 my $rn = rand();
 my $rn = rand($num);
    

Behaves exactly like Perl's built-in rand, returning a number uniformly distributed in [0, $num). ($num defaults to 1.)

NOTE: If you still need to access Perl's built-in rand function, you can do so using "CORE::rand()".

irand

 my $int = irand();
    

Returns a random integer. For 32-bit integer Perl, the range is 0 to 2^32-1 (0xFFFFFFFF) inclusive. For 64-bit integer Perl, it's 0 to 2^64-1 inclusive.

This is the fastest way to obtain random numbers using this module.

shuffle

 my @shuffled = shuffle($data, ...);
 my @shuffled = shuffle(@data);
    

Returns an array of the random ordering of the supplied arguments (i.e., shuffled) by using the Fisher-Yates shuffling algorithm. It can also be called to return an array reference:

 my $shuffled = shuffle($data, ...);
 my $shuffled = shuffle(@data);
    

If called with a single array reference (fastest method), the contents of the array are shuffled in situ:

 shuffle(\@data);
    

gaussian

 my $gn = gaussian();
 my $gn = gaussian($sd);
 my $gn = gaussian($sd, $mean);
    

Returns floating-point random numbers from a Gaussian (normal) distribution (i.e., numbers that fit a bell curve). If called with no arguments, the distribution uses a standard deviation of 1, and a mean of 0. Otherwise, the supplied argument(s) will be used for the standard deviation, and the mean.

exponential

 my $xn = exponential();
 my $xn = exponential($mean);
    

Returns floating-point random numbers from an exponential distribution. If called with no arguments, the distribution uses a mean of 1. Otherwise, the supplied argument will be used for the mean.

An example of an exponential distribution is the time interval between independent Poisson-random events such as radioactive decay. In this case, the mean is the average time between events. This is called the mean life for radioactive decay, and its inverse is the decay constant (which represents the expected number of events per unit time). The well known term half-life is given by "mean * ln(2)".

erlang

 my $en = erlang($order);
 my $en = erlang($order, $mean);
    

Returns floating-point random numbers from an Erlang distribution of specified order. The order must be a positive integer (> 0). The mean, if not specified, defaults to 1.

The Erlang distribution is the distribution of the sum of $order independent identically distributed random variables each having an exponential distribution. (It is a special case of the gamma distribution for which $order is a positive integer.) When "$order = 1", it is just the exponential distribution. It is named after A. K. Erlang who developed it to predict waiting times in queuing systems.

poisson

 my $pn = poisson($mean);
 my $pn = poisson($rate, $time);
    

Returns integer random numbers (>= 0) from a Poisson distribution of specified mean (rate * time = mean). The mean must be a positive value (> 0).

The Poisson distribution predicts the probability of the number of Poisson-random events occurring in a fixed time if these events occur with a known average rate. Examples of events that can be modeled as Poisson distributions include:

binomial

 my $bn = binomial($prob, $trials);
    

Returns integer random numbers (>= 0) from a binomial distribution. The probability ($prob) must be between 0.0 and 1.0 (inclusive), and the number of trials must be >= 0.

The binomial distribution is the discrete probability distribution of the number of successes in a sequence of $trials independent Bernoulli trials (i.e., yes/no experiments), each of which yields success with probability $prob.

If the number of trials is very large, the binomial distribution may be approximated by a Gaussian distribution. If the average number of successes is small ("$prob * $trials < 1"), then the binomial distribution can be approximated by a Poisson distribution.

srand

 srand();
 srand('source', ...);
    

This (re)seeds the PRNG. It may be called anytime reseeding of the PRNG is desired (although this should normally not be needed).

When the :!auto flag is used, the "srand" subroutine should be called before any other access to the standalone PRNG.

When called without arguments, the previously determined/specified seeding source(s) will be used to seed the PRNG.

Optionally, seeding sources may be supplied as arguments as when using the 'SOURCE' option. (These sources will be saved and used again if "srand" is subsequently called without arguments).

 # Get 250 integers of seed data from Hotbits,
 #  and then get the rest from /dev/random
 srand('hotbits' => 250, '/dev/random');
    

If called with integer data (a list of one or more value, or an array of values), or a reference to an array of integers, these data will be passed to "set_seed" for use in reseeding the PRNG.

NOTE: If you still need to access Perl's built-in srand function, you can do so using "CORE::srand($seed)".

get_seed

 my @seed = get_seed();
   # or
 my $seed = get_seed();
    

Returns an array or an array reference containing the seed last sent to the PRNG.

NOTE: Changing the data in the array will not cause any changes in the PRNG (i.e., it will not reseed it). You need to use "srand" or "set_seed" for that.

set_seed

 set_seed($seed, ...);
 set_seed(@seed);
 set_seed(\@seed);
    

When called with integer data (a list of one or more value, or an array of values), or a reference to an array of integers, these data will be used to reseed the PRNG.

Together with "get_seed", "set_seed" may be useful for setting up identical sequences of random numbers based on the same seed.

It is possible to seed the PRNG with more than 19968 bits of data (312 64-bit integers or 624 32-bit integers). However, doing so does not make the PRNG "more random" as 19968 bits more than covers all the possible PRNG state vectors.

get_state

 my @state = get_state();
   # or
 my $state = get_state();
    

Returns an array (for list context) or an array reference (for scalar context) containing the current state vector of the PRNG.

Note that the state vector is not a full serialization of the PRNG. (See "Serialization" below.)

set_state

 set_state(@state);
   # or
 set_state($state);
    

Sets a PRNG to the state contained in an array or array reference containing the state previously obtained using "get_state".

 # Get the current state of the PRNG
 my @state = get_state();
 # Run the PRNG some more
 my $rand1 = irand();
 # Restore the previous state of the PRNG
 set_state(@state);
 # Get another random number
 my $rand2 = irand();
 # $rand1 and $rand2 will be equal.
    

CAUTION: It should go without saying that you should not modify the values in the state vector obtained from "get_state". Doing so and then feeding it to "set_state" would be (to say the least) naughty.

INSIDE-OUT OBJECTS

By using Object::InsideOut, Math::Random::MT::Auto's PRNG objects support the following capabilities:

 my $prng2 = $prng->clone();

 my $array_ref = $prng->dump();
   # or
 my $string = $prng->dump(1);

 my $prng2 = Object::InsideOut->pump($array_ref);

 use Storable qw(freeze thaw);
 BEGIN {
     $Math::Random::MT::Auto::storable = 1;
 }
 use Math::Random::MT::Auto ...;
 my $prng = Math::Random::MT::Auto->new();
 my $tmp = $prng->freeze();
 my $prng2 = thaw($tmp);

 my $prng = Math::Random::MT::Auto->new();
 print("Here's a random integer: $prng\n");

 my $neg_rand = 0 - $prng;

 if ($prng) {
     print("Heads - I win!\n");
 } else {
     print("Tails - You lose.\n");
 }

 my @rands = @{$prng};

 # Get 20 random integers
 my @rands = @{$prng->array(20)};

 my $rand = \&{$prng};
 my $int = &$rand;

 use threads;
 use threads::shared;
 BEGIN {
     $Math::Random::MT::Auto::shared = 1;
 }
 use Math::Random::MT::Auto ...;

 use threads;
 use Math::Random:MT::Auto qw(irand srand);
 my $prng = Math::Random:MT::Auto->new();
 sub thr_code
 {
     srand();
     $prng->srand();
     ....
 }

EXAMPLES

Cloning the standalone PRNG to an object

 use Math::Random::MT::Auto qw(get_state);
 my $prng = Math::Random::MT::Auto->new('STATE' => scalar(get_state()));
    

or using the standalone PRNG object directly:

 my $prng = $Math::Random::MT::Auto::SA_PRNG->clone();
    

The standalone PRNG and the PRNG object will now return the same sequence of pseudorandom numbers.

Included in this module's distribution are several sample programs (located in the samples sub-directory) that illustrate the use of the various random number deviates and other features supported by this module.

DIAGNOSTICS

 my @WARNINGS;
 BEGIN {
     $SIG{__WARN__} = sub { push(@WARNINGS, @_); };
 }
 use Math::Random::MT::Auto;
 # Check for standalone PRNG warnings
 if (@WARNINGS) {
     # Handle warnings as desired
     ...
     # Clear warnings
     undef(@WARNINGS);
 }
 my $prng = Math::Random::MT::Auto->new();
 # Check for PRNG object warnings
 if (@WARNINGS) {
     # Handle warnings as desired
     ...
     # Clear warnings
     undef(@WARNINGS);
 }

 my $obj;
 eval { $obj = Math::Random::MT::Auto->new(); };
 if (my $e = OIO->caught()) {
     print(STDERR "Failure creating new PRNG: $e\n");
     exit(1);
 }

PERFORMANCE

Under Cygwin, this module is 2.5 times faster than Math::Random::MT, and under Solaris, it's more than four times faster. (Math::Random::MT fails to build under Windows.) The file samples/timings.pl, included in this module's distribution, can be used to compare timing results.

If you connect to the Internet via a phone modem, acquiring seed data may take a second or so. This delay might be apparent when your application is first started, or when creating a new PRNG object. This is especially true if you specify multiple "Internet Sites" (so as to get the full seed from them) as this results in multiple accesses to the Internet. (If /dev/urandom is available on your machine, then you should definitely consider using the Internet sources only as a secondary source.)

DEPENDENCIES

BUGS AND LIMITATIONS

This module does not support multiple inheritance.

For Perl prior to 5.10, there is a bug in the overload code associated with 64-bit integers that causes the integer returned by the "->irand()" call to be coerced into a floating-point number. The workaround in this case is to call "->irand()" directly:

 # my $neg_rand = 0 - $prng;          # Result is a floating-point number
 my $neg_rand = 0 - $prng->irand();   # Result is an integer number

The transfer of state vector arrays and serialized objects between 32- and 64-bit integer versions of Perl is not supported, and will produce an 'Invalid state vector' error.

Please submit any bugs, problems, suggestions, patches, etc. to: <http://rt.cpan.org/Public/Dist/Display.html?Name=Math-Random-MT-Auto>

SEE ALSO

Math::Random::MT::Auto on MetaCPAN: <https://metacpan.org/release/Math-Random-MT-Auto>

Code repository: <https://github.com/jdhedden/Math-Random-MT-Auto>

Sample code in the examples directory of this distribution on CPAN.

The Mersenne Twister is the (current) quintessential pseudorandom number generator. It is fast, and has a period of 2^19937 - 1. The Mersenne Twister algorithm was developed by Makoto Matsumoto and Takuji Nishimura. It is available in 32- and 64-bit integer versions. <http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html>

Wikipedia entries on the Mersenne Twister and pseudorandom number generators, in general: <http://en.wikipedia.org/wiki/Mersenne_twister>, and <http://en.wikipedia.org/wiki/Pseudorandom_number_generator>

random.org generates random numbers from radio frequency noise. <http://random.org/>

HotBits generates random number from a radioactive decay source. <http://www.fourmilab.ch/hotbits/>

RandomNumbers.info generates random number from a quantum optical source. <http://www.randomnumbers.info/>

OpenBSD random devices: <http://www.openbsd.org/cgi-bin/man.cgi?query=arandom&sektion=4&apropos=0&manpath=OpenBSD+Current&arch=>

FreeBSD random devices: <http://www.freebsd.org/cgi/man.cgi?query=random&sektion=4&apropos=0&manpath=FreeBSD+5.3-RELEASE+and+Ports>

Man pages for /dev/random and /dev/urandom on Unix/Linux/Cygwin/Solaris: <http://www.die.net/doc/linux/man/man4/random.4.html>

Windows XP random data source: <http://blogs.msdn.com/michael_howard/archive/2005/01/14/353379.aspx>

Fisher-Yates Shuffling Algorithm: <http://en.wikipedia.org/wiki/Shuffling_playing_cards#Shuffling_algorithms>, and shuffle() in List::Util

Non-uniform random number deviates in Numerical Recipes in C, Chapters 7.2 and 7.3: <http://www.library.cornell.edu/nr/bookcpdf.html>

Inside-out Object Model: Object::InsideOut

Math::Random::MT::Auto::Range - Subclass of Math::Random::MT::Auto that creates range-valued PRNGs

LWP::UserAgent

Math::Random::MT

Net::Random

AUTHOR

Jerry D. Hedden, <jdhedden AT cpan DOT org>

COPYRIGHT AND LICENSE

A C-Program for MT19937 (32- and 64-bit versions), with initialization improved 2002/1/26. Coded by Takuji Nishimura and Makoto Matsumoto, and including Shawn Cokus's optimizations.

 Copyright (C) 1997 - 2004, Makoto Matsumoto and Takuji Nishimura,
  All rights reserved.
 Copyright (C) 2005, Mutsuo Saito, All rights reserved.
 Copyright 2005 - 2009 Jerry D. Hedden <jdhedden AT cpan DOT org>

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

3. The names of its contributors may not be used to endorse or promote
products derived from this software without specific prior written
permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 Any feedback is very welcome.
 m-mat AT math DOT sci DOT hiroshima-u DOT ac DOT jp
 http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html