










                                     RANDLIB

            Library of Fortran Routines for Random Number Generation


                          Version 1.3 -- August, 1997




                                     README








                            Compiled and Written by:

                                 Barry W. Brown
                                  James Lovato
                                 Kathy Russell
                                  John Venier









                     Department of Biomathematics, Box 237
                     The University of Texas, M.D. Anderson Cancer Center
                     1515 Holcombe Boulevard
                     Houston, TX      77030


 This work was supported by grant CA-16672 from the National Cancer Institute.



                       THANKS TO OUR SUPPORTERS

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.


                          SUMMARY OF RANDLIB

The bottom level routines provide 32 virtual random number generators.
Each generator can provide 1,048,576 blocks of numbers, and each block
is of length 1,073,741,824.  Any generator can be set to the beginning
or end  of the current  block or to  its starting value.  Packaging is
provided   so  that  if  these capabilities  are not  needed, a single
generator with period 2.3 X 10^18 is seen.

Using this base, routines are provided that return:
    (1)  Beta random deviates
    (2)  Chi-square random deviates
    (3)  Exponential random deviates
    (4)  F random deviates
    (5)  Gamma random deviates
    (6)  Multivariate normal random deviates (mean and covariance
         matrix specified)
    (7)  Noncentral chi-square random deviates
    (8)  Noncentral F random deviates
    (9)  Univariate normal random deviates
    (10) Random permutations of an integer array
    (11) Real uniform random deviates between specified limits
    (12) Binomial random deviates
    (13) Negative Binomial random deviates
    (14) Multinomial random deviates
    (15) Poisson random deviates
    (16) Integer uniform deviates between specified limits
    (17) Seeds for the random number generator calculated from a
         character string

                             INSTALLATION

Directory src contains  the Fortran source.  The  Fortran code from this
directory should be  compiled and placed  in a library.   Directory test
contains three test programs for this code.






                            DOCUMENTATION

Documentation  is  on directory doc on the  distribution.   All of the
documentation is  in the  form   of  character  (ASCII)    files.   An
explanation of the concepts involved in the base generator and details
of its implementation are contained in Basegen.doc.  A summary  of all
of the  available  routines is  contained  in randlib.chs  (chs  is  an
abbreviation of 'cheat sheet').  The 'chs'  file  will probably be the
reference to randlib  that is primarily used.   The  file, randlib.fdoc,
contains all comments heading  each routine.   There is somewhat  more
information   in  'fdoc' than  'chs',  but  the additional information
consists primarily of references to the literature.



                               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.

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 me by Dr. Kachitvichyanukul.

Kachitvichyanukul,  V. and Schmeiser, B.   W.  Binomial Random Variate
Generation.  Communications of the ACM, 31, 2 (February, 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.

R. C.  H.   Cheng Generating  Beta Variables  with  Nonintegral  Shape
Parameters. Communications of  the 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)




                              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.

We place the Randlib code that we have written in the public domain.  

                                 NO WARRANTY
     
     WE PROVIDE ABSOLUTELY  NO WARRANTY  OF ANY  KIND  EITHER  EXPRESSED 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) THE PROGRAM.
     
     (Above NO WARRANTY modified from the GNU NO WARRANTY statement.)



                         WHAT'S NEW IN VERSION 1.1?

  
Random number generation  for  the Negative Binomial  and  Multinomial
distributions has been included.

Two errors in the code  which generates random  numbers from the Gamma
distribution were fixed.


                         WHAT'S NEW IN VERSION 1.2?

We changed the name  of the package  from 'ranlib' to 'randlib'.  This
was done so  that we can determine who  archives it.   'ranlib' is the
name of a Unix utility which produces many spurious hits on a web
search engine.


The linpack routines are now housed in the /src directory.

In  several routines, some   variables were   given an  explicit  SAVE
attribute  and  some  dummy  initial values   were changed to  prevent
potential errors.
'genbet.f' 'ignbin.f'   'ignpoi.f' 'phrtsd.f'   'sexpo.f'   'sgamma.f'
'snorm.f'

In several  routines, argument checking was  implemented; the code now
breaks if inappropriate values are passed to it.
'genbet.f' A and B must be >= 1.0E-37 instead of 0.0
'genexp.f' AV must be >= 0.0
'gengam.f' A and R both must be > 0.0
'gennor.f' SD must be >= 0.0
'ignbin.f' N must be >= 0, and 0.0 <= PP <= 1.0.
'ignnbn.f' N must be > 0, 0.0 < P < 1.0 (previously allowed N = 0)
'ignpoi.f' MU must be >= 0.0

For the Non-Central  Chi-Squared and Non-Central  F distributions, the
case DF = 1.0 (DFN = 1.0 for the F) is now allowed.
'gennch.f' 'gennf.f'

Wherever possible,  the   user-accessible  code  now calls    the base
generators   directly.   This means   improved performance  and  fewer
dependencies, but the routines should work  exactly as before from the
user's point of view.
'genchi.f' 'genf.f' 'gennch.f' 'gennf.f' 'ignnbn.f'

Many minor modifications  have been  made which  should make  the code
more robust, without changing how the code is used.
'genbet.f'   'gengam.f'  'ignpoi.f'  'ignuin.f'  'sgamma.f' 'tstmid.f'

Finally, five distributions have  been added to the  mid-level tester,
which test the Exponential, Gamma, Multinomial, Negative Binomial, and
Normal distributions.
'tstmid.f'




                   WHAT'S NOT NEW IN VERSION 1.2 ?

No calling sequences have changed.

		      WHAT'S NEW IN VERSION 1.3?

The calling sequence of SETGMN has been changed!  We added an argument
(INTEGER LDCOVM) representing the leading actual dimension of COVM, to
allow the user to use this routine in  the case that COVM is contained
in a larger array.  This change also makes the routine more compatible
with  LINPACK    routines.  See  the    following files  for  details:
'setgmn.f' in the /src directory, and 'randlib.fdoc' and 'randlib.chs'
in the /doc directory.

Briefly, the declaration of SETGMN has been changed
from:
      SUBROUTINE setgmn(meanv,covm,p,parm)
to:
      SUBROUTINE setgmn(meanv,covm,ldcovm,p,parm)

The program 'tstgmn.f' (in the /test directory) was changed to reflect
the change in the calling sequence of SETGMN.

'randlib.fdoc' and 'randlib.chs' in the /doc directory were changed to
relect the change in the calling sequence of SETGMN.

Minor changes were made in two routines  ('sgamma.f' and 'sexpo.f') to
fix unusual bugs.

The protection from overflow   in deviate generation in  two  routines
('genf.f'  and 'gennf.f')   was changed to   prevent a  constant  from
underflowing at compile time.

                   WHAT'S NOT NEW IN VERSION 1.3 ?

No calling sequences (other than SETGMN) have changed.

			     MANY THANKS

The authors would like to thank the many users  who have reported bugs
and  suggested improvements; Randlib  would  not  be  the  same  today
without them.  We heartily encourage others to join them.
