The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

NAME

Math::Random::MT::Perl - Pure Perl Mersenne Twister Random Number Generator

SYNOPSIS

## Object-oriented interface:
use Math::Random::MT::Perl;
$gen = Math::Random::MT->new()        # or...
$gen = Math::Random::MT->new($seed);  # or...
$gen = Math::Random::MT->new(@seeds);
$seed = $gen->get_seed();             # seed generating the random numbers
$rand = $gen->rand(42);               # random number in the interval [0, 42)
$dice = int($gen->rand(6)+1);         # random integer between 1 and 6
$coin = $gen->rand() < 0.5 ?          # flip a coin
  "heads" : "tails"
$int = $gen->irand();                 # random integer in [0, 2^32-1]

## Function-oriented interface
use Math::Random::MT::Perl qw(srand rand irand);
# now use srand() and rand() as you usually do in Perl

DESCRIPTION

Pure Perl implementation of the Mersenne Twister algorithm. Mersenne Twister is a 32 bit pseudorandom number generator developed by Makoto Matsumoto and Takuji Nishimura. The algorithm is characterised by a very uniform distribution but is not cryptographically secure. What this means in real terms is that it is fine for modeling but no good for crypto.

Internally, unsigned 32 bit integers are used. The range of possible values for such integers is 0 .. 4,294,967,295 (0..2**32-1). The generator takes a random integer from within this range and multiplies it by (1.0/4294967296.0). As a result the range of possible return values is 0 .. 0.999999999767169. This number is then multiplied by the argument passed to rand (default=1). In other words the maximum return value from rand will always be slightly less than the argument - it will never equal that argument. Only the first 10 digits of the returned float are mathematically significant.

Math::Random::MT::Perl implements the same pseudorandom number generator found in Math::Random::MT (implemented in C/XS): their interface and output should be identical.

Object-oriented interface

new()

Creates a new generator. It can be provided with a single unsigned 32-bit integer, an array of them, or nothing. If no argument is passed, it is automatically seeded with a random seed.

set_seed()

Seeds the generator and returns the seed used. It takes the same arguments as new().

get_seed()

Retrieves the value of the seed used.

rand($num)

Behaves exactly like Perl's builtin rand(), returning a number uniformly distributed in [0, $num) ($num defaults to 1), except that the underlying complexity is 32 bits rather than a fraction of it (~15).

irand()

Returns a 32-bit integer, i.e. an integer uniformly distributed in [0, 2^32-1].

Functional interface

srand()

Seed the random number generator. It takes the same arguments as new(), but returns the seed used. It is strongly recommended that you call srand() explicitly before you call rand() for the first time.

rand($num)

Behaves exactly like Perl's builtin rand(), returning a number uniformly distributed in [0, $num) ($num defaults to 1), except that the underlying complexity is 32 bits rather than a fraction of it (~15).

irand()

Returns a 32-bit integer, i.e. an integer uniformly distributed in [0, 2^32-1].

Export

Nothing by default. rand() and srand() on demand.

SPEED

Runs around 1/3 as fast as the C code of Math::Random::MT, however that still means a random number generation speed of 100,000/sec on modest hardware.

SEE ALSO

Math::Random::MT

http://www.math.keio.ac.jp/~matumoto/emt.html

BUGS

Please report bugs at http://rt.cpan.org/Dist/Display.html?Name=Math-Random-MT-Perl.

The latest development code can be obtained from the git repository git://github.com/fangly/Math-Random-MT-Perl.git.

AUTHOR

Dr James Freeman <airmedical [at] gmail [dot] com>

MAINTAINER

Florent Angly <florent.angly@gmail.com>

CREDITS

almut from perlmonks for 64 bit debug and fix.

Abhijit Menon-Sen, Philip Newton and Sean M. Burke who contributed to Math::Random::MT as this module is mostly a translation.

COPYRIGHT AND LICENSE

(c) Dr James Freeman 2000-08. All rights reserved.

This package is free software and is provided "as is" without express or implied warranty. It may be used, redistributed and/or modified under the terms of the Artistic License 2.0. A copy is included in this distribution.