NAME

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

SYNOPSIS

use Math::Random::MT::Auto qw/rand32 rand/,
                           'dev_random' => 500,
                           'random_org';

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

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

DESCRIPTION

This module provides a two random number functions that are based on the Mersenne Twister pseudorandom number generator (PRNG).

The PRNG is self-seeding, automatically acquiring a 624-long-int random seed when the module is loaded.

Seeding Methods

dev_random

This reads random data from /dev/random (if it exists). There is a (very slight) possibility that there may not be sufficient data available from this device.

dev_urandom

This reads random data from /dev/urandom (if it exists). This device provides data first from /dev/random, and then if needed, will satisfy the rest of the request using data from its own PRNG.

random_org

This reads random data from the random.org web site. An Internet connection and LWP::UserAgent are required to utilize this source.

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.)

hotbits

This reads random data from the HotBits web site. An Internet connection and LWP::UserAgent are required to utilize this source.

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 512 long-ints of data per request. If you want to get the full seed from HotBits, then specify the hotbits method twice in the module declaration.

Example

use Math::Random::MT::Auto qw/hotbits hotbits dev_urandom/;

Seeding methods may be specified when the module is declared. Optionally, the maximum number of long-ints to be used from that source may be specified.

Seeding methods may also be specified though the srand function if reseeding of the PRNG is desired.

Example

use Math::Random::MT::Auto 'random_org' => 500, 'dev_urandom';

This acquires at most 500 long-ints from random.org, and then finishes the rest of the seed using data from /dev/urandom.

use Math::Random::MT::Auto qw/dev_random random_org hotbits dev_urandom/;

This acquires the seed from the sources specified, in order, until the full seed is acquired. (This is the default.)

Auto-seeding

Normally, the PRNG is seeded in a INIT block that is run right after the module is loaded. This behavior can be modified by supplying the :!auto (or :noauto) flag when the module is declared. (Even in this case, the PRNG will still be seeded using time and PID.) When the :!auto option is used, the srand function should be imported and then run before using rand or rand32.

Example

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

Functions

rand($num)

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

rand32()

Returns a 32-bit random integer between 0 and 2^32-1 inclusive.

srand()

This reseeds the PRNG. It should be called when the :!auto option is used.

Optionally, seed aquisition methods may be supplied as arguments. (These will be saved and used again if srand is subsequently called without arguments).

Example

srand('dev_random');

This will attempt to fill the seed with data from /dev/random only.

seed(@seeds)

This will seed the PRNG with the supplied values. This can be used to set up the PRNG with a pre-determined seed, or to make use of some other source of random seed data. (I would be interested to hear about such sources if they could easily be included in future versions of this module.)

Module Data

@Math::Random::MT::Auto::seed

This array contains the seed that was last used to intialize the PRNG. It may be of use in setting up repeatable sequences of random numbers.

@Math::Random::MT::Auto::errors

This array contains information related to any problem encountered while trying to acquire seed data. It can be examined after the module is loaded, or after srand is called when :!auto is used.

DIAGNOSTICS

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 a full seed from the specified sources, then the time() and PID will be added to whatever seed data is acquired so far.

PERFORMANCE

This module is 50% faster than Math::Random::MT. The file samples/random included with this module can be used to compare timing results.

Depending on your connnection speed, acquiring seed data from the Internet may take a couple of seconds. This delay might be apparent when your application is first started. This is especially true if you specify the hotbits method twice so as to get the full seed from the HotBits site as this results in two accesses to the Internet. (If /dev/random 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 pseudorandom number generator. It is fast, and has a period of 2^19937 - 1 (> 10^6000). The Mersenne Twister algorithm was developed by Makoto Matsumoto and Takuji Nishimura. 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/

Man pages for /dev/random and /dev/urandom. http://www.die.net/doc/linux/man/man4/random.4.html

LWP::UserAgent

Math::Random::MT

Random::Net

AUTHOR

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

COPYRIGHT AND LICENSE

A C-program for MT19937, with initialization improved 2002/1/26. Coded by Takuji Nishimura and Makoto Matsumoto, and including Shawn Cokus's optimizations.

Copyright (C) 1997 - 2002, 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

cpanm Math::Random::MT::Auto

perl -MCPAN -e shell
install Math::Random::MT::Auto