1NAME 2 Math::Random::OO - Consistent object-oriented interface for generating 3 random numbers 4 5VERSION 6 version 0.22 7 8SYNOPSIS 9 # Using factory functions 10 use Math::Random::OO qw( Uniform UniformInt ); 11 push @prngs, Uniform(), UniformInt(1,6); 12 13 # Explicit creation of subclasses 14 use Math::Random::OO::Normal; 15 push @prngs, Math::Random::OO::Normal->new(0,2); 16 17 $_->seed(23) for (@prngs); 18 print( $_->next(), "\n") for (@prngs); 19 20DESCRIPTION 21 CPAN contains many modules for generating random numbers in various ways 22 and from various probability distributions using pseudo-random number 23 generation algorithms or other entropy sources. (The "SEE ALSO" section 24 has some examples.) Unfortunately, no standard interface exists across 25 these modules. This module defines an abstract interface for random 26 number generation. Subclasses of this model will implement specific 27 types of random number generators or will wrap existing random number 28 generators. 29 30 This consistency will come at the cost of some efficiency, but will 31 enable generic routines to be written that can manipulate any provided 32 random number generator that adheres to the interface. E.g., a 33 stochastic simulation could take a number of user-supplied parameters, 34 each of which is a Math::Random::OO subclass object and which represent 35 a stochastic variable with a particular probability distribution. 36 37USAGE 38 Factory Functions 39 use Math::Random::OO qw( Uniform UniformInt Normal Bootstrap ); 40 $uniform = Uniform(-1,1); 41 $uni_int = UniformInt(1,6); 42 $normal = Normal(1,1); 43 $boot = Bootstrap( 2, 3, 3, 4, 4, 4, 5, 5, 5 ); 44 45 In addition to defining the abstract interface for subclasses, this 46 module imports subclasses and exports factory functions upon request to 47 simplify creating many random number generators at once without typing 48 "Math::Random::OO::Subclass->new()" each time. The factory function 49 names are the same as the suffix of the subclass following 50 "Math::Random::OO". When called, they pass their arguments directly to 51 the "new" constructor method of the corresponding subclass and return a 52 new object of the subclass type. Supported functions and their 53 subclasses include: 54 55 * "Uniform" -- Math::Random::OO::Uniform (uniform distribution over a 56 range) 57 58 * "UniformInt" -- Math::Random::OO::UniformInt (uniform distribution 59 of integers over a range) 60 61 * "Normal" -- Math::Random::OO::Normal (normal distribution with 62 specified mean and standard deviation) 63 64 * "Bootstrap" -- Math::Random::OO::Bootstrap (bootstrap resampling 65 from a non-parameteric distribution) 66 67INTERFACE 68 All Math::Random::OO subclasses must follow a standard interface. They 69 must provide a "new" method, a "seed" method, and a "next" method. 70 Specific details are left to each interface. 71 72 "new" 73 This is the standard constructor. Each subclass will define parameters 74 specific to the subclass. 75 76 "seed" 77 $prng->seed( @seeds ); 78 79 This method takes seed (or list of seeds) and uses it to set the initial 80 state of the random number generator. As some subclasses may optionally 81 use/require a list of seeds, the interface mandates that a list must be 82 acceptable. Generators requiring a single seed must use the first value 83 in the list. 84 85 As seeds may be passed to the built-in "srand()" function, they may be 86 truncated as integers, so 0.12 and 0.34 would be the same seed. Only 87 positive integers should be used. 88 89 "next" 90 $rnd = $prng->next(); 91 92 This method returns the next random number from the random number 93 generator. It does not take (and must not use) any parameters. 94 95SEE ALSO 96 This is not an exhaustive list -- search CPAN for that -- but represents 97 some of the more common or established random number generators that 98 I've come across. 99 100 Math::Random -- multiple random number generators for different 101 distributions (a port of the C randlib) 102 Math::Rand48 -- perl bindings for the drand48 library (according to 103 perl56delta, this may already be the default after perl 5.005_52 if 104 available) 105 Math::Random::MT -- The Mersenne Twister PRNG (good and fast) 106 Math::TrulyRandom -- an interface to random numbers from interrupt 107 timing discrepancies 108 109SUPPORT 110 Bugs / Feature Requests 111 Please report any bugs or feature requests through the issue tracker at 112 <https://github.com/dagolden/math-random-oo/issues>. You will be 113 notified automatically of any progress on your issue. 114 115 Source Code 116 This is open source software. The code repository is available for 117 public review and contribution under the terms of the license. 118 119 <https://github.com/dagolden/math-random-oo> 120 121 git clone git://github.com/dagolden/math-random-oo.git 122 123AUTHOR 124 David Golden <dagolden@cpan.org> 125 126COPYRIGHT AND LICENSE 127 This software is Copyright (c) 2013 by David Golden. 128 129 This is free software, licensed under: 130 131 The Apache License, Version 2.0, January 2004 132 133