Mercurial > octave
diff libcruft/ranlib/Basegen.doc @ 2330:12ff450cbb1f
[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 |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/libcruft/ranlib/Basegen.doc Fri Jul 19 01:49:31 1996 +0000 @@ -0,0 +1,382 @@ + + + + + + + + + + + + RANLIB + + 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**********************************************************************