Mercurial > hg > octave-nkf
view libcruft/ranlib/Basegen.doc @ 5915:b2e1be30c8e9 ss-2-9-7
[project @ 2006-07-28 18:08:56 by jwe]
| author | jwe |
|---|---|
| date | Fri, 28 Jul 2006 18:08:56 +0000 |
| parents | df7c57a6639d |
| children |
line wrap: on
line source
RANDLIB Library of Fortran Routines for Random Number Generation Base Generator Documentation Compiled and Written by: Barry W. Brown James Lovato Department of Biomathematics, Box 237 The University of Texas, M.D. Anderson Cancer Center 1515 Holcombe Boulevard Houston, TX 77030 This work was supported by grant CA-16672 from the National Cancer Institute. Base Random Number Generator I. OVERVIEW AND DEFAULT BEHAVIOR This set of programs contains 32 virtual random number generators. Each generator can provide 1,048,576 blocks of numbers, and each block is of length 1,073,741,824. Any generator can be set to the beginning or end of the current block or to its starting value. The methods are from the paper cited immediately below, and most of the code is a transliteration from the Pascal of the paper into Fortran. P. L'Ecuyer and S. Cote. Implementing a Random Number Package with Splitting Facilities. ACM Transactions on Mathematical Software 17:1, pp 98-111. Most users won't need the sophisticated capabilities of this package, and will desire a single generator. This single generator (which will have a non-repeating length of 2.3 X 10^18 numbers) is the default. In order to accommodate this use, the concept of the current generator is added to those of the cited paper; references to a generator are always to the current generator. The current generator is initially generator number 1; it can be changed by SETCGN, and the ordinal number of the current generator can be obtained from GETCGN. The user of the default can set the initial values of the two integer seeds with SETALL. If the user does not set the seeds, the random number generation will use the default values, 1234567890 and 123456789. The values of the current seeds can be achieved by a call to GETSD. Random number may be obtained as integers ranging from 1 to a large integer by reference to function IGNLGI or as a floating point number between 0 and 1 by a reference to function RANF. These are the only routines needed by a user desiring a single stream of random numbers. II. CONCEPTS A stream of pseudo-random numbers is a sequence, each member of which can be obtained either as an integer in the range 1..2,147,483,563 or as a floating point number in the range [0..1]. The user is in charge of which representation is desired. The method contains an algorithm for generating a stream with a very long period, 2.3 X 10^18. This stream in partitioned into G (=32) virtual generators. Each virtual generator contains 2^20 (=1,048,576) blocks of non-overlapping random numbers. Each block is 2^30 (=1,073,741,824) in length. Base Random Number Generator Page 2 The state of a generator is determined by two integers called seeds. The seeds can be initialized by the user; the initial values of the first must lie between 1 and 2,147,483,562, that of the second between 1 and 2,147,483,398. Each time a number is generated, the values of the seeds change. Three values of seeds are remembered by the generators at all times: the value with which the generator was initialized, the value at the beginning of the current block, and the value at the beginning of the next block. The seeds of any generator can be set to any of these three values at any time. Of the 32 virtual generators, exactly one will be the current generator, i.e., that one will be used to generate values for IGNLGI and RANDF. Initially, the current generator is set to number one. The current generator may be changed by calling SETCGN, and the number of the current generator can be obtained using GETCGN. III. AN EXAMPLE An example of the need for these capabilities is as follows. Two statistical techniques are being compared on data of different sizes. The first technique uses bootstrapping and is thought to be as accurate using less data than the second method which employs only brute force. For the first method, a data set of size uniformly distributed between 25 and 50 will be generated. Then the data set of the specified size will be generated and alalyzed. The second method will choose a data set size between 100 and 200, generate the data and alalyze it. This process will be repeated 1000 times. For variance reduction, we want the random numbers used in the two methods to be the same for each of the 1000 comparisons. But method two will use more random numbers than method one and without this package, synchronization might be difficult. With the package, it is a snap. Use generator 1 to obtain the sample size for method one and generator 2 to obtain the data. Then reset the state to the beginning of the current block and do the same for the second method. This assures that the initial data for method two is that used by method one. When both have concluded, advance the block for both generators. IV. THE INTERFACE A random number is obtained either as a random integer between 1 and 2,147,483,562 by invoking integer function IGNLGI (I GeNerate LarGe Integer) or as a random floating point number between 0 and 1 by invoking real function RANF. Neither function has arguments. The seed of the first generator can be set by invoking subroutine SETALL; the values of the seeds of the other 31 generators are calculated from this value. Base Random Number Generator Page 3 The number of the current generator can be set by calling subroutine SETCGN, which takes a single argument, the integer generator number in the range 1..32. The number of the current generator can be obtained by invoking subroutine GETCGN which returns the number in its single integer argument. V. CALLING SEQUENCES A. SETTING THE SEED OF ALL GENERATORS C********************************************************************** C C SUBROUTINE SETALL(ISEED1,ISEED2) C SET ALL random number generators C C Sets the initial seed of generator 1 to ISEED1 and ISEED2. The C initial seeds of the other generators are set accordingly, and C all generators states are set to these seeds. C C Arguments C C C ISEED1 -> First of two integer seeds C INTEGER ISEED1 C C ISEED2 -> Second of two integer seeds C INTEGER ISEED1 C C********************************************************************** B. OBTAINING RANDOM NUMBERS C********************************************************************** C C INTEGER FUNCTION IGNLGI() C GeNerate LarGe Integer C C Returns a random integer following a uniform distribution over C (1, 2147483562) using the current generator. C C********************************************************************** C********************************************************************** C C REAL FUNCTION RANF() C RANDom number generator as a Function C C Returns a random floating point number from a uniform distribution C over 0 - 1 (endpoints of this interval are not returned) using the C current generator C C********************************************************************** Base Random Number Generator Page 4 C. SETTING AND OBTAINING THE NUMBER OF THE CURRENT GENERATOR C********************************************************************** C C SUBROUTINE SETCGN( G ) C Set GeNerator C C Sets the current generator to G. All references to a generator C are to the current generator. C C Arguments C C G --> Number of the current random number generator (1..32) C INTEGER G C C********************************************************************** C********************************************************************** C C SUBROUTINE GETCGN(G) C Get GeNerator C C Returns in G the number of the current random number generator C C Arguments C C G <-- Number of the current random number generator (1..32) C INTEGER G C C********************************************************************** D. OBTAINING OR CHANGING SEEDS IN CURRENT GENERATOR C********************************************************************** C C SUBROUTINE ADVNST(K) C ADV-a-N-ce ST-ate C C Advances the state of the current generator by 2^K values and C resets the initial seed to that value. C C Arguments C C C K -> The generator is advanced by 2^K values C INTEGER K C C********************************************************************** Base Random Number Generator Page 5 C********************************************************************** C C SUBROUTINE GETSD(ISEED1,ISEED2) C GET SeeD C C Returns the value of two integer seeds of the current generator C C Arguments C C C C ISEED1 <- First integer seed of generator G C INTEGER ISEED1 C C ISEED2 <- Second integer seed of generator G C INTEGER ISEED1 C C********************************************************************** C********************************************************************** C C SUBROUTINE INITGN(ISDTYP) C INIT-ialize current G-e-N-erator C C Reinitializes the state of the current generator C C Arguments C C C ISDTYP -> The state to which the generator is to be set C ISDTYP = -1 => sets the seeds to their initial value C ISDTYP = 0 => sets the seeds to the first value of C the current block C ISDTYP = 1 => sets the seeds to the first value of C the next block C C INTEGER ISDTYP C C********************************************************************** C********************************************************************** C C SUBROUTINE SETSD(ISEED1,ISEED2) C SET S-ee-D of current generator C C Resets the initial seed of the current generator to ISEED1 and C ISEED2. The seeds of the other generators remain unchanged. C C Arguments C C C ISEED1 -> First integer seed C INTEGER ISEED1 C C ISEED2 -> Second integer seed C INTEGER ISEED1 C C********************************************************************** Base Random Number Generator Page 6 E. MISCELLANY C********************************************************************** C C INTEGER FUNCTION MLTMOD(A,S,M) C C Returns (A*S) MOD M C C Arguments C C C A, S, M --> C INTEGER A,S,M C C********************************************************************** C********************************************************************** C C SUBROUTINE SETANT(QVALUE) C SET ANTithetic C C Sets whether the current generator produces antithetic values. If C X is the value normally returned from a uniform [0,1] random C number generator then 1 - X is the antithetic value. If X is the C value normally returned from a uniform [0,N] random number C generator then N - 1 - X is the antithetic value. C C All generators are initialized to NOT generate antithetic values. C C Arguments C C QVALUE -> .TRUE. if generator G is to generating antithetic C values, otherwise .FALSE. C LOGICAL QVALUE C C**********************************************************************