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