Provided by: libmath-random-perl_0.71-3build2_amd64 bug

NAME

       Math::Random - Random Number Generators

SYNOPSIS

       •

            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.

DESCRIPTION

       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.

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

   Extended Routines
       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.

ERROR HANDLING

       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

       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/

SUPPORT

       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.

CODE MANIPULATION

       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

SOURCES

       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.

VERSION

       This POD documents Math::Random version 0.71.

AUTHORS

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.

LEGALITIES

       •   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".

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