1
2
3
4
5
6
7
8
9
10
11
12 RANDLIB.C
13
14 Library of C Routines for Random Number Generation
15
16
17 Version 1.3 -- August, 1997
18
19
20
21
22
23 README
24
25
26
27
28
29
30
31
32 Compiled and Written by:
33
34 Barry W. Brown
35 James Lovato
36 Kathy Russell
37 John Venier
38
39
40
41
42
43
44
45
46
47
48 Department of Biomathematics, Box 237
49 The University of Texas, M.D. Anderson Cancer Center
50 1515 Holcombe Boulevard
51 Houston, TX 77030
52
53
54 This work was supported by grant CA-16672 from the National Cancer Institute.
55
56
57
58
59 THANKS TO OUR SUPPORTERS
60
61This work was supported in part by grant CA-16672 from the National
62Cancer Institute. We are grateful to Larry and Pat McNeil of Corpus
63Cristi for their generous support. Some equipment used in this effort
64was provided by IBM as part of a cooperative study agreement; we thank
65them.
66
67 SUMMARY OF RANDLIB
68
69The bottom level routines provide 32 virtual random number generators.
70Each generator can provide 1,048,576 blocks of numbers, and each block
71is of length 1,073,741,824. Any generator can be set to the beginning
72or end of the current block or to its starting value. Packaging is
73provided so that if these capabilities are not needed, a single
74generator with period 2.3 X 10^18 is seen.
75
76Using this base, routines are provided that return:
77 (1) Beta random deviates
78 (2) Chi-square random deviates
79 (3) Exponential random deviates
80 (4) F random deviates
81 (5) Gamma random deviates
82 (6) Multivariate normal random deviates (mean and covariance
83 matrix specified)
84 (7) Noncentral chi-square random deviates
85 (8) Noncentral F random deviates
86 (9) Univariate normal random deviates
87 (10) Random permutations of an integer array
88 (11) Real uniform random deviates between specified limits
89 (12) Binomial random deviates
90 (13) Negative Binomial random deviates
91 (14) Multinomial random deviates
92 (15) Poisson random deviates
93 (16) Integer uniform deviates between specified limits
94 (17) Seeds for the random number generator calculated from a
95 character string
96
97
98
99
100 COMMENTS ON THE C VERSION OF RANDLIB
101
102The C version was obtained by converting the original Fortran RANDLIB
103to C using PROMULA.FORTRAN and performing some hand crafting of the
104result. Information on PROMULA.FORTRAN can be obtained from
105
106 PROMULA Development Corporation
107 3620 N. High Street, Suite 301
108 Columbus, Ohio 43214
109 (614) 263-5454
110
111RANDLIB.C was tested using the xlc compiler under AIX 3.1 on an IBM
112RS/6000. The code was also examined with lint on the same system.
113The RANDLIB test programs were also successfully run using the gcc
114compiler (see below) on a Solbourne.
115
116RANDLIB.C can be obtained from statlib. Send mail whose message is
117'send randlib.c.shar from general' to statlib@lib.stat.cmu.edu.
118
119RANDLIB.C can also be obtained by anonymous ftp to odin.mdacc.tmc.edu
120(143.111.62.32) where is is available as
121 /pub/source/randlib.c-1.2.tar.Z
122
123For obvious reasons, the original RANDLIB (in Fortran) has
124been renamed to
125 /pub/source/randlib.f-1.2.tar.Z
126on the same machine.
127
128
129
130
131
132
133 CAVEAT
134
135RANDLIB.C is written in ANSI C and makes heavy use of prototypes. It
136will not compile under old style (KR) C compilers (such as the default
137Sun cc compiler). The decision to distribute in ANSI C was mine; the
138version of Promula that was used -- 2.0 -- writes old style headers.
139Converting RANDLIB to old style C is not a totally trivial task; the
140type of many arguments to functions will have to be changed from float
141to double. Also note that all ints have been changed to longs. This
142is a result of my being a Fortraner, a novice at C, and knowing that
143the underlying generators require at least a 32 bit integer.
144
145I don't recommend conversion to an obsolete C dialect. Instead, get
146the Free Software Foundation's excellent ANSI C compiler, gcc. It
147compiles KR C as well as ANSI C. A version of gcc that runs on many
148varieties of Unix is available by anonymous ftp as
149 /pub/gnu/gcc-1.40.tar.Z
150at prep.ai.mit.edu (18.71.0.38). A Vax version is also present on
151/pub/gnu. The compilers are also available on tape. Write the Free
152Software Foundation at:
153
154 Free Software Foundation, Inc.
155 675 Massachusetts Avenue
156 Cambridge, MA 02139
157 Phone: (617) 876-3296
158
159A MSDOS port of gcc, performed by DJ Delorie is also available by ftp.
160
161File location:
162
163 host: grape.ecs.clarkson.edu
164 login: ftp
165 password: send your e-mail address
166 directory: ~ftp/pub/msdos/djgcc
167
168File in .ZIP format - djgpp.zip - one 2.2M file, contains everything.
169
170
171
172
173
174 INSTALLATION
175
176Directory src contains the C source for most of the routines. The
177files com.c and randlib.c constitute RANDLIB. The file randlib.h
178contains prototypes for the RANDLIB routines that should be used (and
179not for a few internal routines). The C code from these directories
180should be compiled and placed in a library. Directory test contains
181three test programs for this code. The file randlib.h in directory
182test is a copy of that in src.
183
184
185
186 DOCUMENTATION
187
188Documentation is in directory doc on the distribution. All of the
189documentation is in the form of character (ASCII) files. An
190explanation of the concepts involved in the base generator and details
191of its implementation are contained in Basegen.doc. A summary of all
192of the available routines is contained in randlib.chs (chs is an
193abbreviation of 'cheat sheet'). The 'chs' file will probably be the
194reference to randlib that is primarily used. The file, randlib.fdoc,
195contains all comments heading each routine. There is somewhat more
196information in 'fdoc' than 'chs', but the additional information
197consists primarily of references to the literature.
198
199
200 SOURCES
201
202The following routines, which were written by others and lightly
203modified for consistency in packaging, are included in RANDLIB.
204
205 Bottom Level Routines
206
207These routines are a transliteration of the Pascal in the reference to
208Fortran.
209
210L'Ecuyer, P. and Cote, S. "Implementing a Random Number Package with
211Splitting Facilities." ACM Transactions on Mathematical Software,
21217:98-111 (1991)
213
214
215
216
217 Exponential
218
219This code was obtained from Netlib.
220
221Ahrens, J.H. and Dieter, U. Computer Methods for Sampling From the
222Exponential and Normal Distributions. Comm. ACM, 15,10 (Oct. 1972),
223873 - 882.
224
225 Gamma
226
227(Case R >= 1.0)
228
229Ahrens, J.H. and Dieter, U. Generating Gamma Variates by a Modified
230Rejection Technique. Comm. ACM, 25,1 (Jan. 1982), 47 - 54.
231Algorithm GD
232
233(Case 0.0 <= R <= 1.0)
234
235Ahrens, J.H. and Dieter, U. Computer Methods for Sampling from Gamma,
236Beta, Poisson and Binomial Distributions. Computing, 12 (1974),
237223-246. Adaptation of algorithm GS.
238
239 Normal
240
241This code was obtained from netlib.
242
243Ahrens, J.H. and Dieter, U. Extensions of Forsythe's Method for
244Random Sampling from the Normal Distribution. Math. Comput., 27,124
245(Oct. 1973), 927 - 937.
246
247 Binomial
248
249This code was kindly sent me by Dr. Kachitvichyanukul.
250
251Kachitvichyanukul, V. and Schmeiser, B. W. Binomial Random Variate
252Generation. Communications of the ACM, 31, 2 (February, 1988) 216.
253
254 Poisson
255
256This code was obtained from netlib.
257
258Ahrens, J.H. and Dieter, U. Computer Generation of Poisson Deviates
259From Modified Normal Distributions. ACM Trans. Math. Software, 8, 2
260(June 1982),163-179
261
262
263
264
265 Beta
266
267This code was written by us following the recipe in the following.
268
269R. C. H. Cheng Generating Beta Variables with Nonintegral Shape
270Parameters. Communications of the ACM, 21:317-322 (1978) (Algorithms
271BB and BC)
272
273 Linpack
274
275Routines SPOFA and SDOT are used to perform the Cholesky decomposition
276of the covariance matrix in SETGMN (used for the generation of
277multivariate normal deviates).
278
279Dongarra, J. J., Moler, C. B., Bunch, J. R. and Stewart, G. W.
280Linpack User's Guide. SIAM Press, Philadelphia. (1979)
281
282
283
284
285
286
287
288 LEGALITIES
289
290Code that appeared in an ACM publication is subject to their
291algorithms policy:
292
293 Submittal of an algorithm for publication in one of the ACM
294 Transactions implies that unrestricted use of the algorithm within a
295 computer is permissible. General permission to copy and distribute
296 the algorithm without fee is granted provided that the copies are not
297 made or distributed for direct commercial advantage. The ACM
298 copyright notice and the title of the publication and its date appear,
299 and notice is given that copying is by permission of the Association
300 for Computing Machinery. To copy otherwise, or to republish, requires
301 a fee and/or specific permission.
302
303 Krogh, F. Algorithms Policy. ACM Tran. Math. Softw. 13(1987),
304 183-186.
305
306We place the Randlib code that we have written in the public domain.
307
308 NO WARRANTY
309
310 WE PROVIDE ABSOLUTELY NO WARRANTY OF ANY KIND EITHER EXPRESSED OR
311 IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
312 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK
313 AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD
314 THIS PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
315 SERVICING, REPAIR OR CORRECTION.
316
317 IN NO EVENT SHALL THE UNIVERSITY OF TEXAS OR ANY OF ITS COMPONENT
318 INSTITUTIONS INCLUDING M. D. ANDERSON HOSPITAL BE LIABLE TO YOU FOR
319 DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER SPECIAL,
320 INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
321 INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA OR
322 ITS ANALYSIS BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD
323 PARTIES) THE PROGRAM.
324
325 (Above NO WARRANTY modified from the GNU NO WARRANTY statement.)
326
327
328
329
330
331
332 WHAT'S NEW IN VERSION 1.1?
333
334
335Random number generation for the Negative Binomial and Multinomial
336distributions has been included.
337
338Two errors in the code which generates random numbers from the Gamma
339distribution were fixed.
340
341
342
343
344
345
346 WHAT'S NEW IN VERSION 1.2?
347
348We changed the name of the package from 'ranlib' to 'randlib'. This
349was done so that we can determine who archives it. 'ranlib' is the
350name of a Unix utility which produces many spurious hits on a web
351search engine.
352
353The linpack file is now housed in the /src directory.
354
355In several routines, argument checking was implemented; the code now
356breaks if inappropriate values are passed to it.
357In 'randlib.c':
358genbet: A and B must be >= 1.0E-37 instead of 0.0
359genexp: AV must be >= 0.0
360gengam: A and R both must be > 0.0
361gennor: SD must be >= 0.0
362ignbin: N must be >= 0, and 0.0 <= PP <= 1.0.
363ignnbn: N must be > 0, 0.0 < P < 1.0 (previously allowed N = 0)
364ignpoi: MU must be >= 0.0
365
366For the Non-Central Chi-Squared and Non-Central F distributions, the
367case DF = 1.0 (DFN = 1.0 for the F) is now allowed.
368Functions gennch and gennf in 'randlib.c'
369
370The phrase-to-seed function (phrtsd in 'randlib.c') was changed to
371produce seeds which are the same as those generated by the Fortran
372version, for consistency between implementations. As a result, it
373produces seeds which are in general different from those produced
374before the change.
375
376Wherever possible, the user-accessible code now calls the base
377generators directly. This means improved performance and fewer
378dependencies, but the routines should work exactly as before from the
379user's point of view.
380Functions genchi, genf, gennch, gennf, and ignnbn in 'randlib.c'
381
382Many minor modifications have been made which should make the code
383more robust, without changing how the code is used.
384Functions genbet, ignbin, ignpoi, phrtsd and ignuin in 'randlib.c'
385'com.c' 'tstmid.c' 'tstgmn.c'
386
387Finally, five distributions have been added to the mid-level tester,
388which test the Exponential, Gamma, Multinomial, Negative Binomial, and
389Normal distributions.
390'tstmid.c'
391
392 WHAT'S NOT NEW IN VERSION 1.2 ?
393
394No calling sequences have changed.
395
396
397
398
399
400
401 WHAT'S NEW IN VERSION 1.3?
402
403Minor changes were made in two routines (sgamma and sexpo in
404'randlib.c') to fix unusual bugs.
405
406The protection from overflow in deviate generation in two routines
407(genf and gennf in 'randlib.c') was changed to prevent a constant from
408underflowing at compile time.
409
410 WHAT'S NOT NEW IN VERSION 1.3 ?
411
412No calling sequences have changed.
413
414 MANY THANKS
415
416The authors would like to thank the many users who have reported bugs
417and suggested improvements; Randlib would not be the same today
418without them. We heartily encourage others to join them.
419
420