2330
|
1 |
|
2 |
|
3 |
|
4 |
|
5 |
|
6 |
|
7 |
|
8 |
|
9 |
|
10 |
|
11 |
3188
|
12 RANDLIB |
2330
|
13 |
|
14 Library of Fortran Routines for Random Number Generation |
|
15 |
|
16 |
3188
|
17 Version 1.3 -- August, 1997 |
2330
|
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 |
3188
|
35 Kathy Russell |
|
36 John Venier |
2330
|
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 |
3188
|
55 |
|
56 THANKS TO OUR SUPPORTERS |
|
57 |
|
58 This work was supported in part by grant CA-16672 from the National |
|
59 Cancer Institute. We are grateful to Larry and Pat McNeil of Corpus |
|
60 Cristi for their generous support. Some equipment used in this effort |
|
61 was provided by IBM as part of a cooperative study agreement; we thank |
|
62 them. |
|
63 |
|
64 |
|
65 SUMMARY OF RANDLIB |
2330
|
66 |
|
67 The bottom level routines provide 32 virtual random number generators. |
|
68 Each generator can provide 1,048,576 blocks of numbers, and each block |
|
69 is of length 1,073,741,824. Any generator can be set to the beginning |
|
70 or end of the current block or to its starting value. Packaging is |
|
71 provided so that if these capabilities are not needed, a single |
|
72 generator with period 2.3 X 10^18 is seen. |
|
73 |
|
74 Using 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 |
3188
|
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 |
2330
|
93 character string |
|
94 |
|
95 INSTALLATION |
|
96 |
3188
|
97 Directory src contains the Fortran source. The Fortran code from this |
|
98 directory should be compiled and placed in a library. Directory test |
|
99 contains three test programs for this code. |
|
100 |
|
101 |
|
102 |
|
103 |
|
104 |
2330
|
105 |
|
106 DOCUMENTATION |
|
107 |
|
108 Documentation is on directory doc on the distribution. All of the |
|
109 documentation is in the form of character (ASCII) files. An |
|
110 explanation of the concepts involved in the base generator and details |
|
111 of its implementation are contained in Basegen.doc. A summary of all |
3188
|
112 of the available routines is contained in randlib.chs (chs is an |
2330
|
113 abbreviation of 'cheat sheet'). The 'chs' file will probably be the |
3188
|
114 reference to randlib that is primarily used. The file, randlib.fdoc, |
2330
|
115 contains all comments heading each routine. There is somewhat more |
|
116 information in 'fdoc' than 'chs', but the additional information |
|
117 consists primarily of references to the literature. |
|
118 |
|
119 |
|
120 |
|
121 SOURCES |
|
122 |
|
123 The following routines, which were written by others and lightly |
3188
|
124 modified for consistency in packaging, are included in RANDLIB. |
2330
|
125 |
|
126 Bottom Level Routines |
|
127 |
|
128 These routines are a transliteration of the Pascal in the reference to |
|
129 Fortran. |
|
130 |
|
131 L'Ecuyer, P. and Cote, S. "Implementing a Random Number Package with |
|
132 Splitting Facilities." ACM Transactions on Mathematical Software, |
|
133 17:98-111 (1991) |
|
134 |
|
135 Exponential |
|
136 |
|
137 This code was obtained from Netlib. |
|
138 |
|
139 Ahrens, J.H. and Dieter, U. Computer Methods for Sampling From the |
|
140 Exponential and Normal Distributions. Comm. ACM, 15,10 (Oct. 1972), |
|
141 873 - 882. |
|
142 |
|
143 Gamma |
|
144 |
|
145 (Case R >= 1.0) |
|
146 |
|
147 Ahrens, J.H. and Dieter, U. Generating Gamma Variates by a Modified |
|
148 Rejection Technique. Comm. ACM, 25,1 (Jan. 1982), 47 - 54. |
|
149 Algorithm GD |
|
150 |
|
151 (Case 0.0 <= R <= 1.0) |
|
152 |
|
153 Ahrens, J.H. and Dieter, U. Computer Methods for Sampling from Gamma, |
|
154 Beta, Poisson and Binomial Distributions. Computing, 12 (1974), |
|
155 223-246. Adaptation of algorithm GS. |
3188
|
156 |
|
157 |
|
158 |
|
159 |
|
160 |
2330
|
161 |
|
162 Normal |
|
163 |
|
164 This code was obtained from netlib. |
|
165 |
|
166 Ahrens, J.H. and Dieter, U. Extensions of Forsythe's Method for |
|
167 Random Sampling from the Normal Distribution. Math. Comput., 27,124 |
|
168 (Oct. 1973), 927 - 937. |
|
169 |
|
170 Binomial |
|
171 |
|
172 This code was kindly sent me by Dr. Kachitvichyanukul. |
|
173 |
|
174 Kachitvichyanukul, V. and Schmeiser, B. W. Binomial Random Variate |
|
175 Generation. Communications of the ACM, 31, 2 (February, 1988) 216. |
|
176 |
3188
|
177 |
2330
|
178 Poisson |
|
179 |
|
180 This code was obtained from netlib. |
|
181 |
|
182 Ahrens, J.H. and Dieter, U. Computer Generation of Poisson Deviates |
|
183 From Modified Normal Distributions. ACM Trans. Math. Software, 8, 2 |
|
184 (June 1982),163-179 |
|
185 |
|
186 Beta |
|
187 |
|
188 This code was written by us following the recipe in the following. |
|
189 |
|
190 R. C. H. Cheng Generating Beta Variables with Nonintegral Shape |
|
191 Parameters. Communications of the ACM, 21:317-322 (1978) (Algorithms |
|
192 BB and BC) |
|
193 |
|
194 Linpack |
|
195 |
|
196 Routines SPOFA and SDOT are used to perform the Cholesky decomposition |
|
197 of the covariance matrix in SETGMN (used for the generation of |
|
198 multivariate normal deviates). |
|
199 |
|
200 Dongarra, J. J., Moler, C. B., Bunch, J. R. and Stewart, G. W. |
|
201 Linpack User's Guide. SIAM Press, Philadelphia. (1979) |
3188
|
202 |
|
203 |
2330
|
204 |
|
205 |
|
206 LEGALITIES |
|
207 |
|
208 Code that appeared in an ACM publication is subject to their |
|
209 algorithms 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 |
3188
|
224 We place the Randlib code that we have written in the public domain. |
2330
|
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.) |
3188
|
244 |
|
245 |
|
246 |
|
247 WHAT'S NEW IN VERSION 1.1? |
|
248 |
|
249 |
|
250 Random number generation for the Negative Binomial and Multinomial |
|
251 distributions has been included. |
|
252 |
|
253 Two errors in the code which generates random numbers from the Gamma |
|
254 distribution were fixed. |
|
255 |
|
256 |
|
257 WHAT'S NEW IN VERSION 1.2? |
|
258 |
|
259 We changed the name of the package from 'ranlib' to 'randlib'. This |
|
260 was done so that we can determine who archives it. 'ranlib' is the |
|
261 name of a Unix utility which produces many spurious hits on a web |
|
262 search engine. |
|
263 |
|
264 |
|
265 The linpack routines are now housed in the /src directory. |
|
266 |
|
267 In several routines, some variables were given an explicit SAVE |
|
268 attribute and some dummy initial values were changed to prevent |
|
269 potential errors. |
|
270 'genbet.f' 'ignbin.f' 'ignpoi.f' 'phrtsd.f' 'sexpo.f' 'sgamma.f' |
|
271 'snorm.f' |
|
272 |
|
273 In several routines, argument checking was implemented; the code now |
|
274 breaks 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 |
|
283 For the Non-Central Chi-Squared and Non-Central F distributions, the |
|
284 case DF = 1.0 (DFN = 1.0 for the F) is now allowed. |
|
285 'gennch.f' 'gennf.f' |
|
286 |
|
287 Wherever possible, the user-accessible code now calls the base |
|
288 generators directly. This means improved performance and fewer |
|
289 dependencies, but the routines should work exactly as before from the |
|
290 user's point of view. |
|
291 'genchi.f' 'genf.f' 'gennch.f' 'gennf.f' 'ignnbn.f' |
|
292 |
|
293 Many minor modifications have been made which should make the code |
|
294 more robust, without changing how the code is used. |
|
295 'genbet.f' 'gengam.f' 'ignpoi.f' 'ignuin.f' 'sgamma.f' 'tstmid.f' |
|
296 |
|
297 Finally, five distributions have been added to the mid-level tester, |
|
298 which test the Exponential, Gamma, Multinomial, Negative Binomial, and |
|
299 Normal distributions. |
|
300 'tstmid.f' |
|
301 |
|
302 |
|
303 |
|
304 |
|
305 WHAT'S NOT NEW IN VERSION 1.2 ? |
|
306 |
|
307 No calling sequences have changed. |
|
308 |
|
309 WHAT'S NEW IN VERSION 1.3? |
|
310 |
|
311 The calling sequence of SETGMN has been changed! We added an argument |
|
312 (INTEGER LDCOVM) representing the leading actual dimension of COVM, to |
|
313 allow the user to use this routine in the case that COVM is contained |
|
314 in a larger array. This change also makes the routine more compatible |
|
315 with LINPACK routines. See the following files for details: |
|
316 'setgmn.f' in the /src directory, and 'randlib.fdoc' and 'randlib.chs' |
|
317 in the /doc directory. |
|
318 |
|
319 Briefly, the declaration of SETGMN has been changed |
|
320 from: |
|
321 SUBROUTINE setgmn(meanv,covm,p,parm) |
|
322 to: |
|
323 SUBROUTINE setgmn(meanv,covm,ldcovm,p,parm) |
|
324 |
|
325 The program 'tstgmn.f' (in the /test directory) was changed to reflect |
|
326 the change in the calling sequence of SETGMN. |
|
327 |
|
328 'randlib.fdoc' and 'randlib.chs' in the /doc directory were changed to |
|
329 relect the change in the calling sequence of SETGMN. |
|
330 |
|
331 Minor changes were made in two routines ('sgamma.f' and 'sexpo.f') to |
|
332 fix unusual bugs. |
|
333 |
|
334 The protection from overflow in deviate generation in two routines |
|
335 ('genf.f' and 'gennf.f') was changed to prevent a constant from |
|
336 underflowing at compile time. |
|
337 |
|
338 WHAT'S NOT NEW IN VERSION 1.3 ? |
|
339 |
|
340 No calling sequences (other than SETGMN) have changed. |
|
341 |
|
342 MANY THANKS |
|
343 |
|
344 The authors would like to thank the many users who have reported bugs |
|
345 and suggested improvements; Randlib would not be the same today |
|
346 without them. We heartily encourage others to join them. |