1 2 3 4 5 6 7 8 9 10 11 12 RANDLIB 13 14 Library of Fortran Routines for Random Number Generation 15 16 17 Version 1.3 -- August, 1997 18 19 20 21 22 README 23 24 25 26 27 28 29 30 31 Compiled and Written by: 32 33 Barry W. Brown 34 James Lovato 35 Kathy Russell 36 John Venier 37 38 39 40 41 42 43 44 45 46 Department of Biomathematics, Box 237 47 The University of Texas, M.D. Anderson Cancer Center 48 1515 Holcombe Boulevard 49 Houston, TX 77030 50 51 52 This work was supported by grant CA-16672 from the National Cancer Institute. 53 54 55 56 THANKS TO OUR SUPPORTERS 57 58This work was supported in part by grant CA-16672 from the National 59Cancer Institute. We are grateful to Larry and Pat McNeil of Corpus 60Cristi for their generous support. Some equipment used in this effort 61was provided by IBM as part of a cooperative study agreement; we thank 62them. 63 64 65 SUMMARY OF RANDLIB 66 67The bottom level routines provide 32 virtual random number generators. 68Each generator can provide 1,048,576 blocks of numbers, and each block 69is of length 1,073,741,824. Any generator can be set to the beginning 70or end of the current block or to its starting value. Packaging is 71provided so that if these capabilities are not needed, a single 72generator with period 2.3 X 10^18 is seen. 73 74Using this base, routines are provided that return: 75 (1) Beta random deviates 76 (2) Chi-square random deviates 77 (3) Exponential random deviates 78 (4) F random deviates 79 (5) Gamma random deviates 80 (6) Multivariate normal random deviates (mean and covariance 81 matrix specified) 82 (7) Noncentral chi-square random deviates 83 (8) Noncentral F random deviates 84 (9) Univariate normal random deviates 85 (10) Random permutations of an integer array 86 (11) Real uniform random deviates between specified limits 87 (12) Binomial random deviates 88 (13) Negative Binomial random deviates 89 (14) Multinomial random deviates 90 (15) Poisson random deviates 91 (16) Integer uniform deviates between specified limits 92 (17) Seeds for the random number generator calculated from a 93 character string 94 95 INSTALLATION 96 97Directory src contains the Fortran source. The Fortran code from this 98directory should be compiled and placed in a library. Directory test 99contains three test programs for this code. 100 101 102 103 104 105 106 DOCUMENTATION 107 108Documentation is on directory doc on the distribution. All of the 109documentation is in the form of character (ASCII) files. An 110explanation of the concepts involved in the base generator and details 111of its implementation are contained in Basegen.doc. A summary of all 112of the available routines is contained in randlib.chs (chs is an 113abbreviation of 'cheat sheet'). The 'chs' file will probably be the 114reference to randlib that is primarily used. The file, randlib.fdoc, 115contains all comments heading each routine. There is somewhat more 116information in 'fdoc' than 'chs', but the additional information 117consists primarily of references to the literature. 118 119 120 121 SOURCES 122 123The following routines, which were written by others and lightly 124modified for consistency in packaging, are included in RANDLIB. 125 126 Bottom Level Routines 127 128These routines are a transliteration of the Pascal in the reference to 129Fortran. 130 131L'Ecuyer, P. and Cote, S. "Implementing a Random Number Package with 132Splitting Facilities." ACM Transactions on Mathematical Software, 13317:98-111 (1991) 134 135 Exponential 136 137This code was obtained from Netlib. 138 139Ahrens, J.H. and Dieter, U. Computer Methods for Sampling From the 140Exponential and Normal Distributions. Comm. ACM, 15,10 (Oct. 1972), 141873 - 882. 142 143 Gamma 144 145(Case R >= 1.0) 146 147Ahrens, J.H. and Dieter, U. Generating Gamma Variates by a Modified 148Rejection Technique. Comm. ACM, 25,1 (Jan. 1982), 47 - 54. 149Algorithm GD 150 151(Case 0.0 <= R <= 1.0) 152 153Ahrens, J.H. and Dieter, U. Computer Methods for Sampling from Gamma, 154Beta, Poisson and Binomial Distributions. Computing, 12 (1974), 155223-246. Adaptation of algorithm GS. 156 157 158 159 160 161 162 Normal 163 164This code was obtained from netlib. 165 166Ahrens, J.H. and Dieter, U. Extensions of Forsythe's Method for 167Random Sampling from the Normal Distribution. Math. Comput., 27,124 168(Oct. 1973), 927 - 937. 169 170 Binomial 171 172This code was kindly sent me by Dr. Kachitvichyanukul. 173 174Kachitvichyanukul, V. and Schmeiser, B. W. Binomial Random Variate 175Generation. Communications of the ACM, 31, 2 (February, 1988) 216. 176 177 178 Poisson 179 180This code was obtained from netlib. 181 182Ahrens, J.H. and Dieter, U. Computer Generation of Poisson Deviates 183From Modified Normal Distributions. ACM Trans. Math. Software, 8, 2 184(June 1982),163-179 185 186 Beta 187 188This code was written by us following the recipe in the following. 189 190R. C. H. Cheng Generating Beta Variables with Nonintegral Shape 191Parameters. Communications of the ACM, 21:317-322 (1978) (Algorithms 192BB and BC) 193 194 Linpack 195 196Routines SPOFA and SDOT are used to perform the Cholesky decomposition 197of the covariance matrix in SETGMN (used for the generation of 198multivariate normal deviates). 199 200Dongarra, J. J., Moler, C. B., Bunch, J. R. and Stewart, G. W. 201Linpack User's Guide. SIAM Press, Philadelphia. (1979) 202 203 204 205 206 LEGALITIES 207 208Code that appeared in an ACM publication is subject to their 209algorithms policy: 210 211 Submittal of an algorithm for publication in one of the ACM 212 Transactions implies that unrestricted use of the algorithm within a 213 computer is permissible. General permission to copy and distribute 214 the algorithm without fee is granted provided that the copies are not 215 made or distributed for direct commercial advantage. The ACM 216 copyright notice and the title of the publication and its date appear, 217 and notice is given that copying is by permission of the Association 218 for Computing Machinery. To copy otherwise, or to republish, requires 219 a fee and/or specific permission. 220 221 Krogh, F. Algorithms Policy. ACM Tran. Math. Softw. 13(1987), 222 183-186. 223 224We place the Randlib code that we have written in the public domain. 225 226 NO WARRANTY 227 228 WE PROVIDE ABSOLUTELY NO WARRANTY OF ANY KIND EITHER EXPRESSED OR 229 IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 230 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK 231 AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD 232 THIS PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY 233 SERVICING, REPAIR OR CORRECTION. 234 235 IN NO EVENT SHALL THE UNIVERSITY OF TEXAS OR ANY OF ITS COMPONENT 236 INSTITUTIONS INCLUDING M. D. ANDERSON HOSPITAL BE LIABLE TO YOU FOR 237 DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER SPECIAL, 238 INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR 239 INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA OR 240 ITS ANALYSIS BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD 241 PARTIES) THE PROGRAM. 242 243 (Above NO WARRANTY modified from the GNU NO WARRANTY statement.) 244 245 246 247 WHAT'S NEW IN VERSION 1.1? 248 249 250Random number generation for the Negative Binomial and Multinomial 251distributions has been included. 252 253Two errors in the code which generates random numbers from the Gamma 254distribution were fixed. 255 256 257 WHAT'S NEW IN VERSION 1.2? 258 259We changed the name of the package from 'ranlib' to 'randlib'. This 260was done so that we can determine who archives it. 'ranlib' is the 261name of a Unix utility which produces many spurious hits on a web 262search engine. 263 264 265The linpack routines are now housed in the /src directory. 266 267In several routines, some variables were given an explicit SAVE 268attribute and some dummy initial values were changed to prevent 269potential errors. 270'genbet.f' 'ignbin.f' 'ignpoi.f' 'phrtsd.f' 'sexpo.f' 'sgamma.f' 271'snorm.f' 272 273In several routines, argument checking was implemented; the code now 274breaks if inappropriate values are passed to it. 275'genbet.f' A and B must be >= 1.0E-37 instead of 0.0 276'genexp.f' AV must be >= 0.0 277'gengam.f' A and R both must be > 0.0 278'gennor.f' SD must be >= 0.0 279'ignbin.f' N must be >= 0, and 0.0 <= PP <= 1.0. 280'ignnbn.f' N must be > 0, 0.0 < P < 1.0 (previously allowed N = 0) 281'ignpoi.f' MU must be >= 0.0 282 283For the Non-Central Chi-Squared and Non-Central F distributions, the 284case DF = 1.0 (DFN = 1.0 for the F) is now allowed. 285'gennch.f' 'gennf.f' 286 287Wherever possible, the user-accessible code now calls the base 288generators directly. This means improved performance and fewer 289dependencies, but the routines should work exactly as before from the 290user's point of view. 291'genchi.f' 'genf.f' 'gennch.f' 'gennf.f' 'ignnbn.f' 292 293Many minor modifications have been made which should make the code 294more robust, without changing how the code is used. 295'genbet.f' 'gengam.f' 'ignpoi.f' 'ignuin.f' 'sgamma.f' 'tstmid.f' 296 297Finally, five distributions have been added to the mid-level tester, 298which test the Exponential, Gamma, Multinomial, Negative Binomial, and 299Normal distributions. 300'tstmid.f' 301 302 303 304 305 WHAT'S NOT NEW IN VERSION 1.2 ? 306 307No calling sequences have changed. 308 309 WHAT'S NEW IN VERSION 1.3? 310 311The calling sequence of SETGMN has been changed! We added an argument 312(INTEGER LDCOVM) representing the leading actual dimension of COVM, to 313allow the user to use this routine in the case that COVM is contained 314in a larger array. This change also makes the routine more compatible 315with LINPACK routines. See the following files for details: 316'setgmn.f' in the /src directory, and 'randlib.fdoc' and 'randlib.chs' 317in the /doc directory. 318 319Briefly, the declaration of SETGMN has been changed 320from: 321 SUBROUTINE setgmn(meanv,covm,p,parm) 322to: 323 SUBROUTINE setgmn(meanv,covm,ldcovm,p,parm) 324 325The program 'tstgmn.f' (in the /test directory) was changed to reflect 326the change in the calling sequence of SETGMN. 327 328'randlib.fdoc' and 'randlib.chs' in the /doc directory were changed to 329relect the change in the calling sequence of SETGMN. 330 331Minor changes were made in two routines ('sgamma.f' and 'sexpo.f') to 332fix unusual bugs. 333 334The protection from overflow in deviate generation in two routines 335('genf.f' and 'gennf.f') was changed to prevent a constant from 336underflowing at compile time. 337 338 WHAT'S NOT NEW IN VERSION 1.3 ? 339 340No calling sequences (other than SETGMN) have changed. 341 342 MANY THANKS 343 344The authors would like to thank the many users who have reported bugs 345and suggested improvements; Randlib would not be the same today 346without them. We heartily encourage others to join them. 347