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.
