|
|
| |
Random(3) |
User Contributed Perl Documentation |
Random(3) |
Math::Random - Random Number Generators
-
use Math::Random;
Exports the following routines by default (see "Default
Routines"):
random_set_seed_from_phrase
random_get_seed
random_seed_from_phrase
random_set_seed
random_uniform
random_uniform_integer
random_permutation
random_permuted_index
random_normal
In this case the extended routines (see "Extended
Routines") can be used by qualifying them explicitly with
"Math::Random::", for example:
"$stdexp =
Math::Random::random_exponential();"
-
use Math::Random qw(random_beta
random_chi_square
random_exponential
random_f
random_gamma
random_multivariate_normal
random_multinomial
random_noncentral_chi_square
random_noncentral_f
random_normal
random_permutation
random_permuted_index
random_uniform
random_poisson
random_uniform_integer
random_negative_binomial
random_binomial
random_seed_from_phrase
random_get_seed
random_set_seed_from_phrase
random_set_seed );
Exports all the routines explicitly. Use a subset of the list
for the routines you want.
-
use Math::Random qw(:all);
Exports all the routines, as well.
Math::Random is a Perl port of the C version of
randlib, which is a suite of routines for generating random deviates.
See "RANDLIB" for more information.
This port supports all of the distributions from which the
Fortran and C versions generate deviates. The major
functionalities that are excluded are the multiple generators/splitting
facility and antithetic random number generation. These facilities, along
with some of the distributions which are included, are probably not
of interest except to the very sophisticated user. If there is sufficient
interest, the excluded facilities will be included in a future release. The
code to perform the excluded facilities is available as randlib in
Fortran and C source.
The routines which are exported by default are the only ones that the average
Perl programmer is likely to need.
- "random_set_seed_from_phrase($phrase)"
- Sets the seed of the base generator to a value determined by
$phrase. If the module is installed with the default
option, the value depends on the machine collating sequence. It should,
however, be the same for 7-bit ASCII character strings on all ASCII
machines. In the original randlib, the value generated for a given
$phrase was consistent from implementation to
implementation (it did not rely on the machine collating sequence). Check
with your Perl administrator to see if the module was installed with the
original seed generator. Note: When the Perl processor loads
package Math::Random the seed is set to a value based on the
current time. The seed changes each time Math::Random generates
something random.
The ability to set the seed is useful for debugging, or for
those who like reproducible runs.
- "random_get_seed()"
- Returns an array of length two which contains the two integers
constituting the seed (assuming a call in array context). An invocation in
a scalar context returns the integer 2, which is probably not useful.
- "random_seed_from_phrase($phrase)"
- Returns an array of length two which contains the two integers
constituting the seed (assuming a call in array context). An invocation in
a scalar context returns the integer 2, which is probably not useful. The
seed generated is the seed used to set the seed in a call to
"random_set_seed_from_phrase".
Note: the following two calls (for the same
$phrase) are equivalent:
random_set_seed(random_seed_from_phrase($phrase));
and
random_set_seed_from_phrase($phrase);
- "random_set_seed(@seed)"
- Sets the seed of the base generator to the value
@seed[0,1]. Usually, the argument
@seed should be the result of a call to
"random_get_seed" or
"random_seed_from_phrase".
@seed[0,1] must be two integers in the range
(1, 1) to (2147483562, 2147483398), inclusive.
- "random_uniform($n, $low, $high)"
- "random_uniform($n)"
- "random_uniform()"
- When called in an array context, returns an array of
$n deviates generated from a
uniform($low, $high) distribution. When
called in a scalar context, generates and returns only one such deviate as
a scalar, regardless of the value of $n.
Argument restrictions: $low must be less
than or equal to $high.
Defaults are (1, 0, 1). Note:
$high must be specified if
$low is specified.
- "random_uniform_integer($n, $low, $high)"
- When called in an array context, returns an array of
$n integer deviates generated from a
uniform($low, $high) distribution on
the integers. When called in a scalar context, generates and returns only
one such deviate as a scalar, regardless of the value of
$n.
Argument restrictions: $low and
$high are first rounded using
"int()"; the resulting
$low must be less than or equal to
$high , and the resulting range ($high -
$low) must not be greater than 2147483561.
There are no defaults; all three arguments must be
provided.
- "random_permutation(@array)"
- Returns @array, randomly permuted.
- "random_permuted_index($n)"
- Returns an array of array indices, randomly permuted. The indices used are
(0, ... ,($n - 1)).
This produces the indices used by
"random_permutation" for a given seed,
without passing arrays.
Note: the following are equivalent:
random_set_seed_from_phrase('jjv');
random_permutation(@array);
and
random_set_seed_from_phrase('jjv');
@array[(random_permuted_index(scalar(@array)))];
- "random_normal($n, $av, $sd)"
- "random_normal($n, $av)"
- "random_normal($n)"
- "random_normal()"
- When called in an array context, returns an array of
$n deviates generated from a normal($av,
$sd^2) distribution. When called in a scalar context,
generates and returns only one such deviate as a scalar, regardless of the
value of $n.
Argument restrictions: $sd must be
non-negative.
Defaults are (1, 0, 1).
These routines generate deviates from many other distributions.
Note: The parameterizations of these deviates are standard
(insofar as there is a standard ... ) but particular attention should
be paid to the distributions of the beta and gamma deviates
(noted in "random_beta" and
"random_gamma" below).
- "random_beta($n, $aa, $bb)"
- When called in an array context, returns an array of
$n deviates generated from the beta
distribution with parameters $aa and
$bb . The density of the beta is:
X^($aa - 1) * (1 -
X)^($bb - 1) / B($aa ,
$bb) for 0 < X < 1.
When called in a scalar context, generates and returns only
one such deviate as a scalar, regardless of the value of
$n .
Argument restrictions: Both $aa and
$bb must not be less than
"1.0E-37".
There are no defaults; all three arguments must be
provided.
- "random_binomial($n, $nt, $p)"
- When called in an array context, returns an array of
$n outcomes generated from the binomial
distribution with number of trials $nt and
probability of an event in each trial $p. When called
in a scalar context, generates and returns only one such outcome as a
scalar, regardless of the value of $n.
Argument restrictions: $nt is rounded
using "int()"; the result must be
non-negative. $p must be between 0 and 1
inclusive.
There are no defaults; both arguments must be provided.
- "random_chi_square($n, $df)"
- When called in an array context, returns an array of
$n deviates generated from the chi-square
distribution with $df degrees of freedom. When called
in a scalar context, generates and returns only one such deviate as a
scalar, regardless of the value of $n.
Argument restrictions: $df must be
positive.
There are no defaults; both arguments must be provided.
- "random_exponential($n, $av)"
- "random_exponential($n)"
- "random_exponential()"
- When called in an array context, returns an array of
$n deviates generated from the exponential
distribution with mean $av. When called in a scalar
context, generates and returns only one such deviate as a scalar,
regardless of the value of $n.
Argument restrictions: $av must be
non-negative.
Defaults are (1, 1).
- "random_f($n, $dfn, $dfd)"
- When called in an array context, returns an array of
$n deviates generated from the F (variance
ratio) distribution with degrees of freedom $dfn
(numerator) and $dfd (denominator). When called in a
scalar context, generates and returns only one such deviate as a scalar,
regardless of the value of $n.
Argument restrictions: Both $dfn and
$dfd must be positive.
There are no defaults; all three arguments must be
provided.
- "random_gamma($n, $a, $r)"
- When called in an array context, returns an array of
$n deviates generated from the gamma
distribution with parameters $a and
$r. The density of the gamma is:
($a**$r) /
Gamma( $r) * X**($r - 1) *
Exp(-$a*X)
When called in a scalar context, generates and returns only
one such deviate as a scalar, regardless of the value of
$n .
Argument restrictions: Both $a and
$r must be positive.
There are no defaults; all three arguments must be
provided.
- "random_multinomial($n, @p)"
- When called in an array context, returns single observation from the
multinomial distribution, with $n events
classified into as many categories as the length of
@p. The probability of an event being classified into
category i is given by the ith element of
@p. The observation is an array with length equal to
@p, so when called in a scalar context it returns the
length of @p. The sum of the elements of the
observation is equal to $n.
Argument restrictions: $n is rounded with
"int()" before it is used; the result
must be non-negative. @p must have length at least
2. All elements of @p except the last must be
between 0 and 1 inclusive, and sum to no more than 0.99999. Note:
The last element of @p is a dummy to indicate the
number of categories, and it is adjusted to bring the sum of the
elements of @p to 1.
There are no defaults; both arguments must be provided.
- "random_multivariate_normal($n, @mean, @covar)"
- When called in an array context, returns an array of
$n deviates (each deviate being an array reference)
generated from the multivariate normal distribution with mean
vector @mean and variance-covariance matrix
@covar. When called in a scalar context, generates
and returns only one such deviate as an array reference, regardless of the
value of $n.
Argument restrictions: If the dimension of the deviate to be
generated is p, @mean should be a length
p array of real numbers. @covar should be a
length p array of references to length p arrays of real
numbers (i.e. a p by p matrix). Further,
@covar should be a symmetric positive-definite
matrix, although the Perl code does not check
positive-definiteness, and the underlying C code assumes the
matrix is symmetric. Given that the variance-covariance matrix is
symmetric, it doesn't matter if the references refer to rows or columns.
If a non-positive definite matrix is passed to the function, it will
abort with the following message:
COVM not positive definite in SETGMN
Also, a non-symmetric @covar may produce
deviates without complaint, although they may not be from the expected
distribution. For these reasons, you are encouraged to verify the
arguments passed.
The Perl code does check the dimensionality of
@mean and @covar for
consistency. It does so by checking that the length of the argument
vector passed is odd, that what should be the last element of
@mean and the first element of
@covar look like they are a number followed by an
array reference respectively, and that the arrays referred to in
@covar are as long as
@mean.
There are no defaults; all three arguments must be
provided.
- "random_negative_binomial($n, $ne, $p)"
- When called in an array context, returns an array of
$n outcomes generated from the negative
binomial distribution with number of events $ne
and probability of an event in each trial $p. When
called in a scalar context, generates and returns only one such outcome as
a scalar, regardless of the value of $n.
Argument restrictions: $ne is rounded
using "int()", the result must be
positive. $p must be between 0 and 1 exclusive.
There are no defaults; both arguments must be provided.
- "random_noncentral_chi_square($n, $df, $nonc)"
- When called in an array context, returns an array of
$n deviates generated from the noncentral
chi-square distribution with $df degrees of
freedom and noncentrality parameter $nonc. When
called in a scalar context, generates and returns only one such deviate as
a scalar, regardless of the value of $n.
Argument restrictions: $df must be at
least 1, $nonc must be non-negative.
There are no defaults; all three arguments must be
provided.
- "random_noncentral_f($n, $dfn, $dfd, $nonc)"
- When called in an array context, returns an array of
$n deviates generated from the noncentral F
(variance ratio) distribution with degrees of freedom
$dfn (numerator) and $dfd
(denominator); and noncentrality parameter $nonc.
When called in a scalar context, generates and returns only one such
deviate as a scalar, regardless of the value of $n.
Argument restrictions: $dfn must be at
least 1, $dfd must be positive, and
$nonc must be non-negative.
There are no defaults; all four arguments must be
provided.
- "random_poisson($n, $mu)"
- When called in an array context, returns an array of
$n outcomes generated from the Poisson
distribution with mean $mu. When called in a scalar
context, generates and returns only one such outcome as a scalar,
regardless of the value of $n.
Argument restrictions: $mu must be
non-negative.
There are no defaults; both arguments must be provided.
The Perl code should "croak" if bad
arguments are passed or if the underlying C code cannot allocate the
necessary memory. The only error which should kill the job without
"croak"ing is a non-positive definite
variance-covariance matrix passed to
"random_multivarite_normal" (see
"Extended Routines").
randlib is available in Fortran and C source form, and will
soon be available in Fortran90 source as well. randlib.c can be
obtained from statlib. Send mail whose message is 'send
randlib.c.shar from general' to:
statlib@lib.stat.cmu.edu
randlib.c can also be obtained by anonymous ftp
to:
odin.mdacc.tmc.edu (143.111.62.32)
where it is available as
/pub/source/randlib.c-1.3.tar.gz
For obvious reasons, the original randlib (in
Fortran) has been renamed to
/pub/source/randlib.f-1.3.tar.gz
on the same machine.
Our FTP index is on file
"./pub/index".
If you have Internet access and a browser you might note the
following web site addresses:
University of Texas M. D. Anderson Cancer Center Home Page:
http://www.mdanderson.org/
Department of Biomathematics Home Page:
http://odin.mdacc.tmc.edu/
Available software:
http://biostatistics.mdanderson.org/SoftwareDownload/
This work was supported in part by grant CA-16672 from the National Cancer
Institute. We are grateful to Larry and Pat McNeil of Corpus Cristi for their
generous support. Some equipment used in this effort was provided by IBM as
part of a cooperative study agreement; we thank them.
The C version of randlib was obtained by translating the original
Fortran randlib using PROMULA.FORTRAN, and performing
some hand crafting of the result.
Information on PROMULA.FORTRAN can be obtained from:
PROMULA Development Corporation
3620 N. High Street, Suite 301
Columbus, Ohio 43214
(614) 263-5454
wrapper.c (now obsolete) was created by using SWIG,
and performing some modification of the result. SWIG also produced
the skeleton of Random.pm.
Information on SWIG can be obtained from:
http://www.swig.org
The following routines, which were written by others and lightly modified for
consistency in packaging, are included in randlib.
- Bottom Level Routines
- These routines are a transliteration of the Pascal in the reference
to Fortran, and thence to C.
L'Ecuyer, P., and Cote, S. "Implementing a Random Number
Package with Splitting Facilities." ACM Transactions on
Mathematical Software, 17:98-111 (1991).
- Exponential
- This code was obtained from Netlib.
Ahrens, J. H., and Dieter, U. "Computer Methods for
Sampling from the Exponential and Normal Distributions." Comm. ACM,
15,10 (Oct. 1972), 873-882.
- Gamma
- (Case R >= 1.0)
Ahrens, J. H., and Dieter, U. "Generating Gamma Variates
by a Modified Rejection Technique." Comm. ACM, 25,1 (Jan. 1982),
47-54. Algorithm GD
(Case 0.0 <= R <= 1.0)
Ahrens, J. H., and Dieter, U. "Computer Methods for
Sampling from Gamma, Beta, Poisson and Binomial Distributions."
Computing, 12 (1974), 223-246. Adaptation of algorithm GS.
- Normal
- This code was obtained from netlib.
Ahrens, J. H., and Dieter, U. "Extensions of Forsythe's
Method for Random Sampling from the Normal Distribution." Math.
Comput., 27,124 (Oct. 1973), 927-937.
- Binomial
- This code was kindly sent to Dr. Brown by Dr. Kachitvichyanukul.
Kachitvichyanukul, V., and Schmeiser, B. W. "Binomial
Random Variate Generation." Comm. ACM, 31, 2 (Feb. 1988), 216.
- Poisson
- This code was obtained from netlib.
Ahrens, J. H., and Dieter, U. "Computer Generation of
Poisson Deviates from Modified Normal Distributions." ACM Trans.
Math. Software, 8, 2 (June 1982), 163-179.
- Beta
- This code was written by us following the recipe in the following.
Cheng, R. C. H. "Generating Beta Variables with
Nonintegral Shape Parameters." Comm. ACM, 21:317-322 (1978).
(Algorithms BB and BC)
- Linpack
- Routines "SPOFA" and
"SDOT" are used to perform the Cholesky
decomposition of the covariance matrix in
"SETGMN" (used for the generation of
multivariate normal deviates).
Dongarra, J. J., Moler, C. B., Bunch, J. R., and Stewart, G.
W. Linpack User's Guide. SIAM Press, Philadelphia. (1979)
- Multinomial
- The algorithm is from page 559 of Devroye, Luc Non-Uniform Random Variate
Generation. New York: Springer-Verlag, 1986.
- Negative Binomial
- The algorithm is from page 480 of Devroye, Luc Non-Uniform Random Variate
Generation. New York: Springer-Verlag, 1986.
This POD documents Math::Random version 0.71.
- Math::Random (the Perl port of Randlib) was put
together by John Venier and Barry W. Brown with help from SWIG. For
version 0.61, Geoffrey Rommel made various cosmetic changes. Version 0.64
uses plain vanilla XS rather than SWIG.
- randlib was compiled and written by Barry W. Brown, James Lovato,
Kathy Russell, and John Venier.
- Correspondence regarding Math::Random or randlib should be
addressed to John Venier by email to
jvenier@mdanderson.org
- Our address is:
Department of Biomathematics, Box 237
The University of Texas, M.D. Anderson Cancer Center
1515 Holcombe Boulevard
Houston, TX 77030
- Geoffrey Rommel may be reached at grommel [at] cpan [dot] org.
- The programs in the Perl code distributed with Math::Random
and in the C code helper.c, as well as the documentation,
are copyright by John Venier and Barry W. Brown for the University of
Texas M. D. Anderson Cancer Center in 1997. They may be distributed and
used under the same conditions as Perl.
- randlib.c, com.c, and randlib.h are from
randlib (See "RANDLIB") and are distributed with the
following legalities.
Code that appeared in an ACM publication is subject to their
algorithms policy:
Submittal of an algorithm for publication in one of the ACM
Transactions implies that unrestricted use of the algorithm within a
computer is permissible. General permission to copy and distribute the
algorithm without fee is granted provided that the copies are not made
or distributed for direct commercial advantage. The ACM copyright notice
and the title of the publication and its date appear, and notice is
given that copying is by permission of the Association for Computing
Machinery. To copy otherwise, or to republish, requires a fee and/or
specific permission.
Krogh, F. "Algorithms Policy." ACM Tran. Math.
Softw. 13 (1987), 183-186.
Note, however, that only the particular expression of an
algorithm can be copyrighted, not the algorithm per se; see 17 USC
102(b).
We place the Randlib code that we have written in the public
domain.
- Math::Randlib and randlib are distributed with NO
WARRANTY. See "NO WARRANTY".
WE PROVIDE ABSOLUTELY NO WARRANTY OF ANY KIND EITHER EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THIS PROGRAM PROVE DEFECTIVE,
YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
IN NO EVENT SHALL THE UNIVERSITY OF TEXAS OR ANY OF ITS COMPONENT
INSTITUTIONS INCLUDING M. D. ANDERSON HOSPITAL BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE (INCLUDING
BUT NOT LIMITED TO LOSS OF DATA OR DATA OR ITS ANALYSIS BEING RENDERED
INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES FROM) THE PROGRAM.
(Above NO WARRANTY modified from the GNU NO WARRANTY
statement.)
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc. |