Guide and Reference

Use Considerations

If you need a very long period random number generator, you should use SURXOR and DURXOR, rather than SURAND and DURAND, respectively. The very long period of the generator used by SURXOR and DURXOR, 2¹²⁷⁹-1, makes it useful in modern statistical simulations in which the shorter period of other generators can be exhausted during a single run. As a result, if you need a large number of random numbers, you can use these subroutines, because with this generator, you are not be requesting more than a small percentage of the entire period of the generator.

Random Number Generation Subroutines

This section contains the random number generation subroutine descriptions.

SURAND and DURAND--Generate a Vector of Uniformly Distributed Random Numbers

These subroutines generate vector x of uniform (0,1) pseudo-random numbers, using the multiplicative congruential method with a user-specified seed.

Table 163. Data Types

x	seed	Subroutine
Short-precision real	Long-precision real	SURAND
Long-precision real	Long-precision real	DURAND

Note:

If you need a very long period random number generator, use SURXOR and DURXOR instead of these subroutines.

Syntax

On Entry

seed

is the initial value used to generate the random numbers. Specified as: a number of the data type indicated in Table 163. It should be a whole number; that is, the fraction part should be 0. (If you specify a mixed number, it is truncated.) Its value must be 1.0 <= seed < (2147483647.0 = 2³¹-1).

Note:

seed is always a long-precision real number, even in SURAND.

n

is the number of random numbers to be generated. Specified as: a fullword integer; n >= 0.

x

See 'On Return'.

On Return

seed

is the new seed that is to be used to generate additional random numbers in subsequent invocations of SURAND or DURAND. Returned as: a number of the data type indicated in Table 163. It is a whole number whose value is 1.0 <= seed < (2147483647.0 = 2³¹-1).

x

is a vector of length n, containing the uniform pseudo-random numbers with values between 0 and 1. Returned as: a one-dimensional array of (at least) length n, containing numbers of the data type indicated in Table 163.

Note

In your C program, argument seed must be passed by reference.

Function

The uniform (0,1) pseudo-random numbers are generated as follows, using the multiplicative congruential method:

s_i = (a(s_i-1)) mod(m) = (aⁱs₀) mod(m)

x_i = s_i/m    for i = 1, 2, ..., n

where:

s_i is a random sequence.

x_i is a random number.

s₀ is the initial seed provided by the caller.

a = 7⁵ = 16807.0

m = 2³¹-1 = 2147483647.0

n is the number of random numbers to be generated.

See references [70] and [74]. If n is 0, no computation is performed, and the initial seed is unchanged.

Error Conditions

Computational Errors

None

Input-Argument Errors

1. n < 0
2. seed < 1.0 or seed >= 2147483647.0

Example 1

This example shows a call to SURAND to generate 10 random numbers.

Call Statement and Input

             SEED    N   X
               |     |   |
CALL SURAND( SEED , 10 , X )
 
SEED     =  80629.0

Output

SEED     =  759150100.0
 
X        =  (0.6310323,
             0.7603202,
             0.7015232,
             0.5014868,
             0.4895853,
             0.4602344,
             0.1603608,
             0.1832564,
             0.9899062,
             0.3535068)

Example 2

This example shows a call to DURAND to generate 10 random numbers.

Call Statement and Input

             SEED    N   X
               |     |   |
CALL DURAND( SEED , 10 , X )
 
SEED     =  80629.0

Output

SEED     =  759150100.0
 
X        =  (0.6310323270182275,
             0.7603201953509451,
             0.7015232633340746,
             0.5014868557925740,
             0.4895853057920864,
             0.4602344475967038,
             0.1603607578018497,
             0.1832563756887132,
             0.9899062002030695,
             0.3535068129904134)

SNRAND and DNRAND--Generate a Vector of Normally Distributed Random Numbers

These subroutines generate vector x of normally distributed pseudo-random numbers, with a mean of 0 and a standard deviation of 1, using Polar methods with a user-specified seed.

Table 164. Data Types

x, aux	seed	Subroutine
Short-precision real	Long-precision real	SNRAND
Long-precision real	Long-precision real	DNRAND

Syntax

On Entry

seed

is the initial value used to generate the random numbers. Specified as: a number of the data type indicated in Table 164. It must be a whole number; that is, the fraction part must be 0. Its value must be 1.0 <= seed < (2147483647.0 = 2³¹-1).

Note:

seed is always a long-precision real number, even in SNRAND.

n

is the number of random numbers to be generated. Specified as: a fullword integer; n must be an even number and n >= 0.

x

See 'On Return'.

aux

has the following meaning:

If naux = 0 and error 2015 is unrecoverable, aux is ignored.

Otherwise, it is the storage work area used by this subroutine. Its size must be greater than or equal to n/2.

Specified as: an area of storage, containing numbers of the data type indicated in Table 164. They can have any value.

naux

is the size of the work area specified by aux. Specified as: a fullword integer, where:

If naux = 0 and error 2015 is unrecoverable, SNRAND and DNRAND dynamically allocate the work area used by the subroutine. The work area is deallocated before control is returned to the calling program.

Otherwise, naux >= n/2.

On Return

seed

is the new seed that is to be used to generate additional random numbers in subsequent invocations of SNRAND or DNRAND. Returned as: a number of the data type indicated in Table 164. It is a whole number whose value is 1.0 <= seed < (2147483647.0 = 2³¹-1).

x

is a vector of length n, containing the normally distributed pseudo-random numbers. Returned as: a one-dimensional array of (at least) length n, containing numbers of the data type indicated in Table 164.

Notes

1. In your C program, argument seed must be passed by reference.

2. Vector x must have no common elements with the storage area specified for aux; otherwise, results are unpredictable.

3. You have the option of having the minimum required value for naux dynamically returned to your program. For details, see "Using Auxiliary Storage in ESSL".

Function

The normally distributed pseudo-random numbers, with a mean of 0 and a standard deviation of 1, are generated as follows, using Polar methods with a user-specified seed. The Polar method, which this technique is based on, was developed by G. E. P. Box, M. E. Muller, and G. Marsaglia and is described in reference [70].

1. Using seed, a vector of uniform (0,1) pseudo-random numbers, u_i for i = 1, n, is generated by calling SURAND or DURAND, respectively. These u_i values are then used in the subsequent steps.

2. All (y_j, z_j) for j = 1, n/2 are set as follows, where each (y, z) is a point in the square -1 to 1:

   y_j = 2u_2j-1-1

   z_j = 2u_2j-1

3. All p_j for j = 1, n/2 are set as follows, where each p measures the square of the radius of (y, z):

   
   
   
   
   

   If p_j >= 1, then p_j is discarded, and steps 1 through 3 are repeated until p_j < 1.

4. All x_i for i = 1, n are set as follows to produce the normally distributed random numbers:

   x_2j-1 = y_j ((-2 ln p_j) / p_j)^0.5

   x_2j = z_j ((-2 ln p_j) / p_j)^0.5

      for j = 1, n/2

If n is 0, no computation is performed, and the initial seed is unchanged.

Error Conditions

Resource Errors

Error 2015 is unrecoverable, naux = 0, and unable to allocate work area.

Computational Errors

None

Input-Argument Errors

1. n < 0 or n is an odd number
2. seed < 1.0 or seed >= 2147483647.0
3. Error 2015 is recoverable or naux<>0, and naux is too small--that is, less than the minimum required value. Return code 1 is returned if error 2015 is recoverable.

Example 1

This example shows a call to SNRAND to generate 10 random numbers.

Call Statement and Input

             SEED   N    X   AUX  NAUX
               |    |    |    |    |
CALL SNRAND( SEED , 10 , X , AUX , 5  )
 
SEED     =  80629.0

Output

SEED     =  48669425.0
 
X        =  (0.660649538,
             1.312503695,
             1.906438112,
             0.014065863,
            -0.800935328,
            -3.058144093,
            -0.397426069,
            -0.370634943,
            -0.064151444,
            -0.275887042)

Example 2

This example shows a call to DNRAND to generate 10 random numbers.

Call Statement and Input

             SEED   N    X   AUX  NAUX
               |    |    |    |    |
CALL DNRAND( SEED , 10 , X , AUX , 5  )
 
SEED     =  80629.0

Output

SEED     =  48669425.0
 
X        =  (0.6606495655963802,
             1.3125037758861060,
             1.9064381379483730,
             0.0140658628770495,
            -0.8009353314494653,
            -3.0581441239248530,
            -0.3974260845722100,
            -0.3706349643478605,
            -0.0641514443372939,
            -0.2758870630332470)

SURXOR and DURXOR--Generate a Vector of Long Period Uniformly Distributed Random Numbers

These subroutines generate a vector x of uniform [0,1) pseudo-random numbers, using the Tausworthe exclusive-or algorithm.

Table 165. Data Types

x, vseed	iseed	Subroutine
Short-precision real	Integer	SURXOR
Long-precision real	Integer	DURXOR

Syntax

On Entry

iseed

has the following meaning, where:

If iseed <> 0, iseed is the initial value used to generate the random numbers. You specify iseed <> 0 when you call this subroutine for the first time or when you changed vseed between calls to this subroutine.

If iseed = 0, vseed is used to generate the random numbers, where vseed was initialized by an earlier call to this subroutine. ESSL assumes you have not changed vseed between calls to this subroutine, when you specify iseed = 0.

Specified as: a fullword integer, as indicated in Table 165.

n

is the number of random numbers to be generated. Specified as: a fullword integer; n >= 0.

x

See 'On Return'.

vseed

is the work area used by this subroutine and has the following meaning, where:

If iseed <> 0, vseed is not used for input. The work area can contain anything.

If iseed = 0, vseed contains the seed vector generated by a preceding call to this subroutine. vseed is used in this computation to generate the new random numbers. It should not be changed between calls to this subroutine.

Specified as: a one-dimensional array of (at least) length 10000, containing numbers of the data type indicated in Table 165.

On Return

iseed

is set to 0 for subsequent calls to SURXOR or DURXOR. Returned as: a fullword integer, as indicated in Table 165.

x

is a vector of length n, containing the uniform pseudo-random numbers with the following values: 0 <= x < 1. Returned as: a one-dimensional array of (at least) length n, containing numbers of the data type indicated in Table 165.

vseed

is the work area used by these subroutines, containing the new seed that is to be used in subsequent calls to this subroutine. Returned as: a one-dimensional array of (at least) length 10000, containing numbers of the data type indicated in Table 165.

Notes

1. You can generate the same vector x of random numbers by starting over and specifying your original nonzero iseed value.

2. Multiple calls to these subroutines with mixed sizes generate the same sequence of numbers as a single call the total length, assuming you specify the same initial iseed in both cases. For example, you can generate the same vector x of random numbers by calling this subroutine twice and specifying n = 10 or by calling this subroutine once and specifying n = 20. You need to specify the same iseed in the initial call in both cases, and iseed = 0 in the second call with n = 10.

3. Vector x must have no common elements with the storage area specified for vseed; otherwise, results are unpredictable.

4. In your C program, argument iseed must be passed by reference.

Function

The pseudo-random numbers uniformly distributed in the interval [0,1) are generated using the Tausworthe exclusive-or algorithm. This is based on a linear-feedback shift-register sequence. The very long period of the generator, 2¹²⁷⁹-1, makes it useful in modern statistical simulations where the shorter period of other generators could be exhausted during a single run. If you need a large number of random numbers, you can use these subroutines, because with this generator you do not request more than a small percentage of the entire period of the generator.

This generator is based on two feedback positions to generate a new binary digit:

where:

p > q

k = 1, 2, ...

z is a bit vector.

and where:

For details, see references [50], [68], and [88]. The values of p and q are selected according to the criteria stated in reference [94].

The algorithm initializes a seed vector of length p, starting with iseed. The seed vector is stored in vseed for use in subsequent calls to this subroutine with iseed = 0.

If n is 0, no computation is performed, and the initial seed is unchanged.

Special Usage

For some specialized applications, if you need multiple sources of random numbers, you can specify different vseed areas, which are initialized with different seeds on multiple calls to this subroutine. You then get multiple sequences of the random number sequence provided by the generator that are sufficiently far apart for most purposes.

Error Conditions

Computational Errors

None.

Input-Argument Errors

1. n < 0
2. iseed = 0 and vseed does not contain valid data.

Example 1

This example shows a call to SURXOR to generate 10 random numbers.

Call Statement and Input

             ISEED    N   X   VSEED
               |      |   |     |
CALL SURXOR( ISEED , 10 , X , VSEED )
 
ISEED    =  137

Output

ISEED    =  0
 
X        =  (0.6440868,
             0.5105118,
             0.4878680,
             0.3209075,
             0.6624528,
             0.2499877,
             0.0056630,
             0.7329214,
             0.7486335,
             0.8050517)

Example 2

This example shows a call to SURXOR to generate 10 random numbers. This example specifies iseed = 0 and uses the vseed output generated from Example 1.

Call Statement and Input

             ISEED    N   X   VSEED
               |      |   |     |
CALL SURXOR( ISEED , 10 , X , VSEED )
 
ISEED    =  0

Output

ISEED    =  0
 
X        =  (0.9930249,
             0.0441873,
             0.6891295,
             0.3101060,
             0.6324178,
             0.3299408,
             0.3553145,
             0.0100013,
             0.0214620,
             0.8059390)

Example 3

This example shows a call to DURXOR to generate 20 random numbers. This sequence of numbers generated are like those generated in Examples 1 and 2.

Call Statement and Input

             ISEED    N   X   VSEED
               |      |   |     |
CALL DURXOR( ISEED , 20 , X , VSEED )
 
ISEED    =  137

Output

ISEED    =  0
 
X        =   (0.64408693438956721,
              0.51051182536460882,
              0.48786801310787142,
              0.32090755617007050,
              0.66245283144861666,
              0.24998782843358081,
              0.00566308101257373,
              0.73292147005172925,
              0.74863359794102236,
              0.80505169697755319,
              0.99302499462139138,
              0.04418740640269125,
              0.68912952155409579,
              0.31010611495627916,
              0.63241786342211936,
              0.32994081459690583,
              0.35531452631408911,
              0.01000134413132581,
              0.02146199494672940,
              0.80593898487597615)