Mercurial > octave

comparison libcruft/ranlib/Basegen.doc @ 2330:12ff450cbb1f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[project @ 1996-07-19 01:39:22 by jwe] Initial revision
author jwe
date Fri, 19 Jul 1996 01:49:31 +0000
parents
children df7c57a6639d
comparison
equal deleted inserted replaced
2329:30c606bec7a8 2330:12ff450cbb1f
1
2
3
4
5
6
7
8
9
10
11
12 RANLIB
13
14 Library of Fortran Routines for Random Number Generation
15
16
17
18
19
20
21
22
23 Base Generator Documentation
24
25
26
27
28
29
30
31
32 Compiled and Written by:
33
34 Barry W. Brown
35 James Lovato
36
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
57 Base Random Number Generator
58
59
60
61 I. OVERVIEW AND DEFAULT BEHAVIOR
62
63 This set of programs contains 32 virtual random number generators.
64 Each generator can provide 1,048,576 blocks of numbers, and each block
65 is of length 1,073,741,824. Any generator can be set to the beginning
66 or end of the current block or to its starting value. The methods are
67 from the paper cited immediately below, and most of the code is a
68 transliteration from the Pascal of the paper into Fortran.
69
70 P. L'Ecuyer and S. Cote. Implementing a Random Number Package with
71 Splitting Facilities. ACM Transactions on Mathematical Software 17:1,
72 pp 98-111.
73
74 Most users won't need the sophisticated capabilities of this package,
75 and will desire a single generator. This single generator (which will
76 have a non-repeating length of 2.3 X 10^18 numbers) is the default.
77 In order to accommodate this use, the concept of the current generator
78 is added to those of the cited paper; references to a generator are
79 always to the current generator. The current generator is initially
80 generator number 1; it can be changed by SETCGN, and the ordinal
81 number of the current generator can be obtained from GETCGN.
82
83 The user of the default can set the initial values of the two integer
84 seeds with SETALL. If the user does not set the seeds, the random
85 number generation will use the default values, 1234567890 and
86 123456789. The values of the current seeds can be achieved by a call
87 to GETSD. Random number may be obtained as integers ranging from 1 to
88 a large integer by reference to function IGNLGI or as a floating point
89 number between 0 and 1 by a reference to function RANF. These are the
90 only routines needed by a user desiring a single stream of random
91 numbers.
92
93 II. CONCEPTS
94
95 A stream of pseudo-random numbers is a sequence, each member of which
96 can be obtained either as an integer in the range 1..2,147,483,563 or
97 as a floating point number in the range [0..1]. The user is in charge
98 of which representation is desired.
99
100 The method contains an algorithm for generating a stream with a very
101 long period, 2.3 X 10^18. This stream in partitioned into G (=32)
102 virtual generators. Each virtual generator contains 2^20 (=1,048,576)
103 blocks of non-overlapping random numbers. Each block is 2^30
104 (=1,073,741,824) in length.
105
106
107
108 Base Random Number Generator Page 2
109
110
111 The state of a generator is determined by two integers called seeds.
112 The seeds can be initialized by the user; the initial values of the
113 first must lie between 1 and 2,147,483,562, that of the second between
114 1 and 2,147,483,398. Each time a number is generated, the values of
115 the seeds change. Three values of seeds are remembered by the
116 generators at all times: the value with which the generator was
117 initialized, the value at the beginning of the current block, and the
118 value at the beginning of the next block. The seeds of any generator
119 can be set to any of these three values at any time.
120
121 Of the 32 virtual generators, exactly one will be the current
122 generator, i.e., that one will be used to generate values for IGNLGI
123 and RANDF. Initially, the current generator is set to number one.
124 The current generator may be changed by calling SETCGN, and the number
125 of the current generator can be obtained using GETCGN.
126
127 III. AN EXAMPLE
128
129 An example of the need for these capabilities is as follows. Two
130 statistical techniques are being compared on data of different sizes.
131 The first technique uses bootstrapping and is thought to be as
132 accurate using less data than the second method which employs only
133 brute force.
134
135 For the first method, a data set of size uniformly distributed between
136 25 and 50 will be generated. Then the data set of the specified size
137 will be generated and alalyzed. The second method will choose a data
138 set size between 100 and 200, generate the data and alalyze it. This
139 process will be repeated 1000 times.
140
141 For variance reduction, we want the random numbers used in the two
142 methods to be the same for each of the 1000 comparisons. But method
143 two will use more random numbers than method one and without this
144 package, synchronization might be difficult.
145
146 With the package, it is a snap. Use generator 1 to obtain the sample
147 size for method one and generator 2 to obtain the data. Then reset
148 the state to the beginning of the current block and do the same for
149 the second method. This assures that the initial data for method two
150 is that used by method one. When both have concluded, advance the
151 block for both generators.
152
153 IV. THE INTERFACE
154
155 A random number is obtained either as a random integer between 1 and
156 2,147,483,562 by invoking integer function IGNLGI (I GeNerate LarGe
157 Integer) or as a random floating point number between 0 and 1 by
158 invoking real function RANF. Neither function has arguments.
159
160 The seed of the first generator can be set by invoking subroutine
161 SETALL; the values of the seeds of the other 31 generators are
162 calculated from this value.
163
164
165
166 Base Random Number Generator Page 3
167
168
169 The number of the current generator can be set by calling subroutine
170 SETCGN, which takes a single argument, the integer generator number in
171 the range 1..32. The number of the current generator can be obtained
172 by invoking subroutine GETCGN which returns the number in its single
173 integer argument.
174
175
176 V. CALLING SEQUENCES
177
178 A. SETTING THE SEED OF ALL GENERATORS
179
180 C**********************************************************************
181 C
182 C SUBROUTINE SETALL(ISEED1,ISEED2)
183 C SET ALL random number generators
184 C
185 C Sets the initial seed of generator 1 to ISEED1 and ISEED2. The
186 C initial seeds of the other generators are set accordingly, and
187 C all generators states are set to these seeds.
188 C
189 C Arguments
190 C
191 C
192 C ISEED1 -> First of two integer seeds
193 C INTEGER ISEED1
194 C
195 C ISEED2 -> Second of two integer seeds
196 C INTEGER ISEED1
197 C
198 C**********************************************************************
199
200
201 B. OBTAINING RANDOM NUMBERS
202
203 C**********************************************************************
204 C
205 C INTEGER FUNCTION IGNLGI()
206 C GeNerate LarGe Integer
207 C
208 C Returns a random integer following a uniform distribution over
209 C (1, 2147483562) using the current generator.
210 C
211 C**********************************************************************
212
213 C**********************************************************************
214 C
215 C REAL FUNCTION RANF()
216 C RANDom number generator as a Function
217 C
218 C Returns a random floating point number from a uniform distribution
219 C over 0 - 1 (endpoints of this interval are not returned) using the
220 C current generator
221 C
222 C**********************************************************************
223
224
225
226 Base Random Number Generator Page 4
227
228
229 C. SETTING AND OBTAINING THE NUMBER OF THE CURRENT GENERATOR
230
231 C**********************************************************************
232 C
233 C SUBROUTINE SETCGN( G )
234 C Set GeNerator
235 C
236 C Sets the current generator to G. All references to a generator
237 C are to the current generator.
238 C
239 C Arguments
240 C
241 C G --> Number of the current random number generator (1..32)
242 C INTEGER G
243 C
244 C**********************************************************************
245
246 C**********************************************************************
247 C
248 C SUBROUTINE GETCGN(G)
249 C Get GeNerator
250 C
251 C Returns in G the number of the current random number generator
252 C
253 C Arguments
254 C
255 C G <-- Number of the current random number generator (1..32)
256 C INTEGER G
257 C
258 C**********************************************************************
259
260 D. OBTAINING OR CHANGING SEEDS IN CURRENT GENERATOR
261
262 C**********************************************************************
263 C
264 C SUBROUTINE ADVNST(K)
265 C ADV-a-N-ce ST-ate
266 C
267 C Advances the state of the current generator by 2^K values and
268 C resets the initial seed to that value.
269 C
270 C Arguments
271 C
272 C
273 C K -> The generator is advanced by 2^K values
274 C INTEGER K
275 C
276 C**********************************************************************
277
278
279
280 Base Random Number Generator Page 5
281
282
283 C**********************************************************************
284 C
285 C SUBROUTINE GETSD(ISEED1,ISEED2)
286 C GET SeeD
287 C
288 C Returns the value of two integer seeds of the current generator
289 C
290 C Arguments
291 C
292 C
293 C
294 C ISEED1 <- First integer seed of generator G
295 C INTEGER ISEED1
296 C
297 C ISEED2 <- Second integer seed of generator G
298 C INTEGER ISEED1
299 C
300 C**********************************************************************
301
302 C**********************************************************************
303 C
304 C SUBROUTINE INITGN(ISDTYP)
305 C INIT-ialize current G-e-N-erator
306 C
307 C Reinitializes the state of the current generator
308 C
309 C Arguments
310 C
311 C
312 C ISDTYP -> The state to which the generator is to be set
313 C ISDTYP = -1 => sets the seeds to their initial value
314 C ISDTYP = 0 => sets the seeds to the first value of
315 C the current block
316 C ISDTYP = 1 => sets the seeds to the first value of
317 C the next block
318 C
319 C INTEGER ISDTYP
320 C
321 C**********************************************************************
322
323 C**********************************************************************
324 C
325 C SUBROUTINE SETSD(ISEED1,ISEED2)
326 C SET S-ee-D of current generator
327 C
328 C Resets the initial seed of the current generator to ISEED1 and
329 C ISEED2. The seeds of the other generators remain unchanged.
330 C
331 C Arguments
332 C
333 C
334 C ISEED1 -> First integer seed
335 C INTEGER ISEED1
336 C
337 C ISEED2 -> Second integer seed
338 C INTEGER ISEED1
339 C
340 C**********************************************************************
341
342
343
344 Base Random Number Generator Page 6
345
346
347 E. MISCELLANY
348
349 C**********************************************************************
350 C
351 C INTEGER FUNCTION MLTMOD(A,S,M)
352 C
353 C Returns (A*S) MOD M
354 C
355 C Arguments
356 C
357 C
358 C A, S, M -->
359 C INTEGER A,S,M
360 C
361 C**********************************************************************
362
363 C**********************************************************************
364 C
365 C SUBROUTINE SETANT(QVALUE)
366 C SET ANTithetic
367 C
368 C Sets whether the current generator produces antithetic values. If
369 C X is the value normally returned from a uniform [0,1] random
370 C number generator then 1 - X is the antithetic value. If X is the
371 C value normally returned from a uniform [0,N] random number
372 C generator then N - 1 - X is the antithetic value.
373 C
374 C All generators are initialized to NOT generate antithetic values.
375 C
376 C Arguments
377 C
378 C QVALUE -> .TRUE. if generator G is to generating antithetic
379 C values, otherwise .FALSE.
380 C LOGICAL QVALUE
381 C
382 C**********************************************************************