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.