### randlib-1.3 README file

                                       RANDLIB.C

                   Library of C 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

                     COMMENTS ON THE C VERSION OF RANDLIB

    The C version was  obtained by converting the original  Fortran RANDLIB
    to C 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

    RANDLIB.C  was tested  using the xlc  compiler under AIX  3.1 on an IBM
    RS/6000.  The code  was  also examined  with lint  on the same system.
    The RANDLIB test  programs were also  successfully run using   the  gcc
    compiler (see below) on a Solbourne.

    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 is is available as
                            /pub/source/randlib.c-1.2.tar.Z

    For  obvious   reasons, the   original   RANDLIB  (in    Fortran)   has
    been renamed to
                            /pub/source/randlib.f-1.2.tar.Z
    on the same machine.

                                     CAVEAT

    RANDLIB.C is written in ANSI C and makes  heavy use  of prototypes.  It
    will not compile under old style (KR) C compilers (such as the default
    Sun cc compiler). The decision to  distribute in  ANSI C was mine; the
    version of Promula that was used --  2.0 --  writes old style headers.
    Converting RANDLIB to  old style C  is not a  totally trivial task; the
    type of many arguments to functions will have to be changed from float
    to double.  Also note that all ints have been changed  to longs.  This
    is a result of my being a Fortraner,  a  novice at C, and knowing that
    the underlying generators require at least a 32 bit integer.

    I don't  recommend conversion to an  obsolete C dialect.  Instead, get
    the  Free  Software Foundation's  excellent  ANSI C compiler,  gcc. It
    compiles KR C as well as  ANSI C. A  version of gcc that  runs on many
    varieties of Unix is available by anonymous ftp as
                            /pub/gnu/gcc-1.40.tar.Z
    at prep.ai.mit.edu  (18.71.0.38).   A Vax version  is also  present on
    /pub/gnu.  The compilers  are also available  on tape.  Write the Free
    Software Foundation at:

                        Free Software Foundation, Inc.
                           675 Massachusetts Avenue
                             Cambridge, MA  02139
                            Phone: (617) 876-3296

    A MSDOS port of gcc, performed by DJ Delorie is also available by ftp.

    File location:

        host:      grape.ecs.clarkson.edu
        login:     ftp
        password:  send your e-mail address
        directory: ~ftp/pub/msdos/djgcc

    File in .ZIP format - djgpp.zip - one 2.2M file, contains everything.

                                 INSTALLATION

    Directory src  contains  the C source for  most  of the routines.  The
    files com.c   and  randlib.c constitute  RANDLIB.   The  file randlib.h
    contains  prototypes for the RANDLIB  routines that should be used (and
    not for a  few internal routines).  The  C code from these directories
    should be  compiled and placed  in a library.  Directory test contains
    three test  programs for this code.   The file  randlib.h in directory
    test is a copy of that in src.

                                DOCUMENTATION

    Documentation  is  in 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 file is now housed in the /src directory.

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

    The   phrase-to-seed function (phrtsd  in  'randlib.c')  was changed to
    produce seeds which  are the same   as those generated by the  Fortran
    version, for consistency between  implementations.   As a  result,  it
    produces  seeds  which are in general   different  from those produced
    before the change.

    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.
    Functions genchi, genf, gennch, gennf, and ignnbn in 'randlib.c'

    Many minor modifications  have been  made which  should make  the code
    more robust, without changing how the code is used.
    Functions genbet, ignbin, ignpoi, phrtsd and ignuin in 'randlib.c'
    'com.c' 'tstmid.c' 'tstgmn.c'

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

                            WHAT'S NOT NEW IN VERSION 1.2 ?

    No calling sequences have changed.

                               WHAT'S NEW IN VERSION 1.3?

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

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

                            WHAT'S NOT NEW IN VERSION 1.3 ?

    No calling sequences 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.