/ 
Math-Random-MT-Auto-1.34
River stage two • 7 direct dependents • 16 total dependents
/ Math::Random::MT::Auto

NAME

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

SYNOPSIS

use Math::Random::MT::Auto qw/rand irand gaussian/,
                           '/dev/urandom' => 256,
                           'random_org';

# Functional interface
my $die_roll = 1 + int(rand(6));

my $coin_flip = (irand() & 1) ? 'heads' : 'tails';

my $rand_IQ = 100 + gaussian(15);

# OO interface
my $prng = Math::Random::MT::Auto->new('SOURCE' => '/dev/random');

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

my $rand_height = 69 + $prng->gaussian(3);

DESCRIPTION

The Mersenne Twister is a fast pseudo-random number generator (PRNG) that is capable of providing large volumes (> 10^6004) of "high quality" pseudo-random 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 for generating multiple PRNG objects. The PRNGs are self-seeding, automatically acquiring a (19968-bit) random seed from user-selectable sources.

This module is thread-safe with respect to its OO interface for Perl v5.7.2 and beyond. The standalone PRNG is not thread-safe.

For Perl compiled to support 64-bit integers, this module will use a 64-bit version of the Mersenne Twister algorithm, thus providing 64-bit random integers (and 53-bit random doubles). (32-bits otherwise.)

The code for this module has been optimized for speed. Under Windows, it's 2.5 times faster than Math::Random::MT for the functional interface, and 2 times faster for the OO interface. Under Solaris, it's 4x and 3.5x faster, respectively.

Quickstart

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

use Math::Random::MT::Auto qw/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 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.

64-bit Support

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. Otherwise, 32-bit integers will be used. The size of integers returned by "irand", and used by "seed" will be sized accordingly.

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

use Config;

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

Seeding Sources

Starting the PRNGs with a 19968-bit random seed (312 64-bit integers or 624 32-bit integers) takes advantage of their full range of possible internal vectors states. This module attempts to acquire such seeds using several user-selectable sources.

Random Devices

Most OSs offer some sort of device for acquiring random numbers. The most common are /dev/urandom and /dev/random. You can specify the use of these devices for acquiring the seed for the PRNG when you declare this module:

use Math::Random::MT::Auto '/dev/urandom';
  # or
my $prng = Math::Random::MT::Auto->new('SOURCE' => '/dev/random');

or they can be specified when using the "srand" function.

srand('/dev/random');
  # or
$prng->srand('/dev/urandom');

The devices are accessed in non-blocking mode so that if there is insufficient data when they are read, the application will not hang waiting for more.

File of Binary Data

Since the above devices are just files as far as Perl is concerned, you can also use random data previously stored in files (in binary format).

srand('C:\\Temp\\RANDOM.DAT');
  # or
$prng->srand('/tmp/random.dat');
Internet Sites

This module provides support for acquiring seed data from two Internet sites: random.org and HotBits. An Internet connection and LWP::UserAgent are required to utilize these sources.

use Math::Random::MT::Auto 'random_org';
  # or
use Math::Random::MT::Auto 'hotbits';

If you connect to the Internet through an HTTP proxy, then you must set the http_proxy variable in your environment when using this source. (See "Proxy attributes" in LWP::UserAgent.)

The HotBits site will only provide a maximum of 2048 bytes of data per request. If you want to get the full seed from HotBits, then specify the hotbits source twice in the module declaration.

my $prng = Math::Random::MT::Auto->new(
                      'SOURCE' => ['hotbits',
                                   'hotbits' => 448 / $Config{'uvsize'}] );
Windows XP Random Data

On Windows XP, you can acquire random seed data from the system.

use Math::Random::MT::Auto 'win32';

To utilize this option, you must have the Win32::API::Prototype module installed.

The default list of seeding sources is determined when the module is loaded (actually when the import function is called). On Windows XP, win32 is added to the list. Otherwise, /dev/urandom and then /dev/random are checked. The first one found is added to the list. Finally, random_org is added.

For the functional interface to the standalone PRNG, these defaults can be overriden by specifying the desired sources when the module is declared, or through the use of the "srand" function. Similarly for the OO interface, they can be overridden in the "new" method when the PRNG is created, or later using the "srand" method.

Optionally, the maximum number of integers (64- or 32-bits as the case may be) to be used from a source may be specified:

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

(I would be interested to hear about other random data sources if they could easily be included in future versions of this module.)

Functional Interface to the Standalone PRNG

The functional interface to the standalone PRNG is faster than the OO interface for obtaining pseudo-random numbers.

By default, this module does not automatically export any of its functions. If you want to use the standalone PRNG, then you should specify the functions you want to use when you declare the module:

use Math::Random::MT::Auto
          qw/rand irand gaussian srand seed state warnings/;

Without the above declarations, it is still possible to use the standalone PRNG by accessing the functions using their full module paths, as described 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.)

This function may also be accessed using the full path Math::Random::MT::Auto::mt_rand (note the mt_ prefix). (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 method for obtaining pseudo-random numbers with this module.

This function may also be accessed using the full path Math::Random::MT::Auto::mt_irand (note the mt_ prefix).

gaussian
my $gn = gaussian();
my $gn = gaussian($num);

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

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

This (re)seeds the PRNG. It should definitely be called when the :!auto option is used. Additionally, it may be called anytime reseeding of the PRNG is desired (although this should normally not be needed).

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. (These will be saved and used again if "srand" is subsequently called without arguments).

srand('hotbits', '/dev/random');

If called with a subroutine reference, then the subroutine will be called to acquire the seeding data. The subroutine will be passed two arguments: A array reference where seed data is to be added, and the number of integers (64- or 32-bit as the case may be) needed.

sub MySeeder
{
    my $seed = $_[0];
    my $need = $_[1];

    while ($need--) {
        my $data = ...;      # Get seed data from your source
        push(@$seed, $data);
    }
}

# Call MySeeder for 200 integers, and
#  then get the rest from random.org.
srand(\&MySeeder => 200, 'random_org');

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

This function may also be accessed using the full path Math::Random::MT::Auto::srand. (NOTE: If you still need to access Perl's built-in srand function, you can do so using CORE::srand($seed).)

seed
my $seed = seed();
seed($seed);
seed(@seed);
seed(\@seed);

When called without arguments, this function will return an array reference containing the seed last sent to the PRNG. NOTE: Changing the data in the referenced array will not cause any changes in the PRNG (i.e., it will not reseed it).

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

Together, this function may be useful for setting up identical sequences of random numbers based on the same seed.

This function may also be accessed using the full path Math::Random::MT::Auto::seed.

state
my $state = state();
state($state);

When called without arguments, this function returns an array reference containing the current state vector of the PRNG.

To reset the PRNG to a previous state, call this function with a previously obtained state-vector array reference.

# Get the current state of the PRNG
my $state = state();

# Run the PRNG some more
my $rand1 = irand();

# Restore the previous state of the PRNG
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, but I'll say it anyway: "You should not modify the values in the state vector." 'Nough said.

This function may also be accessed using the full path Math::Random::MT::Auto::state.

In conjunction with Data::Dumper and do(file), this function can be used to save and then reload the state vector between application runs. (See "EXAMPLES" below.)

warnings
my @warnings = warnings();
my @warnings = warnings(1);

This function returns an array containing any error messages that were generated while trying to acquire seed data for the standalone PRNG. It can be called after the module is loaded, or after calling "srand" to see if there where any problems getting the seed.

If called with a true argument, the stored error messages will also be erased.

This function may also be accessed using the full path Math::Random::MT::Auto::warnings.

Delayed Seeding

Normally, the standalone PRNG is automatically seeded when the module is loaded. This behavior can be modified by supplying the :!auto (or :noauto) flag when the module is declared. (The PRNG will still be seeded using time and PID just in case.) When the :!auto option is used, the "srand" function should be imported, and then run before calling "rand" or "irand".

use Math::Random::MT::Auto qw/rand srand :!auto/;
  ...
srand();
  ...
my $rn = rand(10);

OO Interface

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

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.

'STATE' => $prng_state

Sets the newly created PRNG to the specified state. The PRNG will then function as a clone of the RPNG that the state was obtained from (at the point when then state was obtained).

When the STATE option is used, any other options are just stored (i.e., they are not acted upon).

'SEED' => $seed_array_ref

When the STATE option is not used, this options seeds the newly created PRNG using the supplied seed data. Otherwise, the seed data is just copied to the new opject.

'SOURCE' => 'source'
'SOURCE' => ['source', ...]

Specifies the seeding source(s) for the PRNG. If the STATE and SEED options are not used, then seed data will be immediately fetched using the specified sources and used to seed the PRNG.

The source list is retained for later use with the seed method. The source list may be replaced by using the srand method.

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

Creates a new PRNG, optionally using attributes from the referenced PRNG.

With no options, the new PRNG will be a complete clone of the referenced PRNG.

When the STATE option is provided, it will be used to set the new PRNG's state vector. The referenced PRNG's seed is not copied to the new PRNG in this case.

When provided, the SEED and SOURCE options behave as described above.

$obj->rand
my $rn = $prng->rand();
my $rn = $prng->rand($num);

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

$obj->irand
my $int = $prng->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 method for obtaining pseudo-random numbers

$obj->gaussian
my $gn = $prng->gaussian();
my $gn = $prng->gaussian($num);

Operates like the "gaussian" function described above, returning floating-point random numbers from a Guassian (normal) distribution distributed about 0 and having a standard deviation of 1 (no args), or $num.

$obj->srand
$prng->srand();
$prng->srand('source', ...);

Operates like the "srand" function described above, reseeding the PRNG.

When called without arguments, the previously-used seeding source(s) will be accessed.

Optionally, seeding sources may be supplied as arguments. (These will be saved and used again if the srand method is subsequently called without arguments).

If called with integer data (single value or an array), or a reference to an array of integers, these data will be passed to the seed method for use in reseeding the PRNG.

$obj->seed
my $seed = $prgn->seed();
$prgn->seed($seed);
$prgn->seed(@seed);
$prgn->seed(\@seed);

Operates like the "seed" function described above, retrieving the PRNG's seed, or setting the PRNG to the supplied seed.

If the PRNG object was created from another PRNG object using the STATE option, then this method may return undef.

$obj->state
my $state = $prgn->state();
$prgn->state($state);

Operates like the "state" function described above, retrieving the PRNG's state, or setting the PRNG to the supplied state.

$obj->warnings
my @warnings = $prng->warnings();
my @warnings = $prng->warnings(1);

Operates like the "warnings" function described above, retrieving any error messages that were generated while trying to acquire seed data for the PRNG. It can be called after the object is created, or after calling the "srand" method to see if there where any problems getting the seed.

If called with a true argument, the stored error messages will also be erased.

Thread Support

This module is thread-safe for PRNGs created through the OO interface for Perl v5.7.2 and beyond.

For Perl v5.8.7 and later, when a thread is created, any PRNG objects are cloned: A parent's PRNG object and its child's cloned copy will work independently from one another, and will return identical random numbers from the point of cloning.

For v5.7.2 through v5.8.6, when a thread is created, any PRNG objects are carried over to the new thread, but they are not cloned. Cloning can be accomplished with the following workaround: Prior to calling threads-create()>, execute the following for every PRNG object to be used inside the thread:

$prng->{'STATE'} = $prng->state();

When the STATE attribute is found (after the thread is created), it is used to make the thread's copy of the PRNG a clone of the parent's. If not found, then the thread's copy of the PRNG is re-seeded either with the existing SEED attribute if found, or with a newly acquired seed.

Prior to v5.7.2, the PRNG objects created in the parent will be broken in the thread once it is created. Therefore, new PRNG objects must be created in the thread.

The standalone PRNG, however, is not thread-safe, and hence should not be used in threaded applications.

NOTE: Due to limitations in the Perl threading model, blessed objects (i.e., objects create through OO interfaces) cannot be shared between threads. The docs on this are not worded very clearly, but here's the gist:

    When a thread is created, any blessed objects that exist will be cloned between the parent and child threads such that the two copies of the object then function independent of one another.

    However, the threading model does not support sharing blessed objects (via use threads::shared) between threads such that an object appears to be a single copy whereby changes to the object made in the one thread are visible in another thhread.

Thus, the following will generate a runtime error:

use Math::Random::MT::Auto;
use threads;
use threads::shared;

my $prng;
share($prng);

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

and if you try turning things around a bit:

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

you don't get an error message, but all the internals of your object are wiped out. (In this case $prng is now just a reference to an empty hash - the data placed inside it when it was created have been removed.)

(Just to be perfectly clear: This is not a deficiency in this module, but an issue with Perl's threading model in general.)

Delayed Importation

When this module is imported via use, the standalone PRNG is initialized via an INIT block that is executed right after the module is loaded.

However, if you want to delay the importation of this module using require and want to use the standlone PRNG, then you must import "srand", and execute it so that the PRNG gets initialized:

eval {
    require Math::Random::MT::Auto;
    # Add other symbols to the import call, as desired.
    import Math::Random::MT::Auto qw/srand/;
    # Add seed sources to the srand() call, as desired.
    srand();
};

If you're only going to use the OO interface, then the following is sufficient:

eval {
    require Math::Random::MT::Auto;
    # Add seed sources to the import call, as desired.
    import Math::Random::MT::Auto;
};

Creating Subclasses

In order to create a subclass of this module, you must implement your constructor along these lines:

use Math::Random::MT::Auto;
our @ISA = qw(Math::Random::MT::AUto);

# Create a new object
sub new
{
    my $thing = shift;
    my $class = ref($thing) || $thing;

    my $self = {};
    bless($self, $class)

    if (! $self->_init($thing, @_)) {
        # Failed to initialize
        # Throw some sort of error, or
        return;   # Returns 'undef'
    }

    return ($self);
}

And you need an initialization routine that provides for proper use of the parent class's intialization routine:

# Initialize a new object
sub _init
{
    my $self  = shift;
    my $thing = shift;

    # Separate '@_' into args for parent class and args for this subclass
    my @parent_args = ...;
    my @my_args     = ...;

    # Perform parent class initialization
    if (! $self->SUPER::_init($thing, @parent_args)) {
        # Parent class initialization failed
        return (0);
    }

    # Perform subclass initialization
    # Making use of '@my_args', if any
    if (ref($thing)) {
        # $thing->new( ... ) was called
        # Make use of '@my_args', if any
        # And make use of object's data, if applicable

    } else {
        # CLASS->new( ... ) was called
        # Make use of '@my_args', if any
    }

    return (1);
}

EXAMPLES

Cloning the standalone PRNG to an object
use Math::Random::MT::Auto qw/rand irand state/;

my $prng = Math::Random::MT::Auto->new('STATE' => state());

The standalone PRNG and the PRNG object will now return the same sequence of pseudo-random numbers.

Save state to file
use Data::Dumper;
use Math::Random::MT::Auto qw/rand irand state/;

my $state = state();
if (open(my $FH, '>/tmp/rand_state_data.tmp')) {
    print($FH Data::Dumper->Dump([$state], ['state']));
    print($FH "1;\n");
    close($FH);
}
Use state as stored above
use Math::Random::MT::Auto qw/rand irand state/;

our $state;
my $rc = do('/tmp/rand_state_data.tmp');
unlink('/tmp/rand_state_data.tmp');
if ($rc) {
    state($state);
}

DIAGNOSTICS

This module sets a 10 second timeout for Internet connections so that if something goes awry when trying to get seed data from an Internet source, your application will not hang for an inordinate amount of time.

If you connect to the Internet through an HTTP proxy, then you must set the http_proxy variable in your environment when using the Internet seed sources. (See "Proxy attributes" in LWP::UserAgent.)

The HotBits site has a quota on the amount of data you can request in a 24-hour period. (I don't know how big the quota is.) Therefore, this source may fail to provide any data if used too often.

If the module cannot acquire any seed data from the specified sources, then the time() and PID will be used to seed the PRNG. Use "warnings" to check for seed acquisition problems.

It is possible to seed the PRNG with more than 19968 bits of data (through the use of a seeding subroutine supplied to "srand", or by supplying a large array ref of data to "seed"). However, doing so does not make the PRNG "more random" as 19968 bits more than covers all the possible PRNG state vectors.

PERFORMANCE

Under Windows, this module is 2.5 times faster than Math::Random::MT for the functional interface to the standalone PRNG, and 2 times faster for the OO interface. Under Solaris, it's 4x and 3.5x faster, respectively. The file samples/random, included in this module's distribution, can be used to compare timing results.

Depending on your connnection speed, acquiring seed data from the Internet may take up to couple of seconds. This delay might be apparent when your application is first started, or after creating a new PRNG object. This is especially true if you specify the hotbits source twice (so as to get the full seed from the HotBits site) as this results in two 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.)

SEE ALSO

The Mersenne Twister is the (current) quintessential pseudo-random 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

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/

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

Gaussian distribution function code: http://home.online.no/~pjacklam/notes/invnorm/

Creating subclasses: perlobj and http://www.perlmonks.org/?node_id=8177

LWP::UserAgent

Math::Random::MT

Net::Random

AUTHOR

Jerry D. Hedden, <jdhedden AT 1979 DOT usna DOT com>

COPYRIGHT AND LICENSE

- Mersenne Twister PRNG -

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 Jerry D. Hedden <jdhedden AT 1979 DOT usna DOT com>

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

- Gaussian Function Code -

Author: Peter J. Acklam
http://home.online.no/~pjacklam/notes/invnorm/
C implementation by V. Natarajan
Released to public domain