Sun S3L 3.0 Programming and Reference Guide

Parallel Random Number Generators

`S3L_setup_rand_fib`

Description

S3L_setup_rand_fib initializes the Lagged-Fibonacci random number generator's (LFG's) state table with the fixed parameters: l = 17, k = 5, m = 32.

The state table is initialized in a manner that ensures that the random numbers generated for each node are from a different period of the LFG. A Linear Multiplicative Generator (LMG) is used to initialize the noncritical elements of the state table.

Use S3L_free_rand_fib to deallocate an LFG setup.

Syntax

The C and Fortran syntax for S3L_setup_rand_fib are shown below.

C/C++ Syntax

Example 8-67

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_setup_rand_fib(setup_id, seed)
    int                *setup_id
    int                seed

F77/F90 Syntax

Example 8-68

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_setup_rand_fib(setup_id, seed, ier)
    integer*4          setup_id
    integer*4          seed
    integer*4          ier

Input

setup_id - Integer index used to access the state table associated with a particular LFG.
seed - An integer value used to initialize the LMG that initializes the noncritical elements of the LFG's state table.

Output

This function uses the following argument for output:

setup_id - On output, setup_id contains an index that can be used as input to S3L_rand_fib.

ier (Fortran only) - When called from a Fortran program, this function returns error status in ier.

Error Handling

On success, S3L_setup_rand_fib returns S3L_SUCCESS.

Examples

../examples/s3l/rand_fib/rand_fib.c
../examples/s3l/rand_fib-f/rand_fib.f

Related Functions

S3L_free_rand_fib(3)
S3L_rand_fib(3)

`S3L_free_rand_fib`

Description

S3L_free_rand_fib frees the state table associated with a particular Lagged-Fibonacci random number Generator (LFG).

Syntax

The C and Fortran syntax for S3L_free_rand_fib are shown below.

C/C++ Syntax

Example 8-69

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L__rand_fib(setup_id)
    int                *setup_id

F77/F90 Syntax

Example 8-70

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_rand_fib(setup_id, ier)
    integer*4          setup_id
    integer*4          ier

Input

setup_id - Integer index that has been initialized by a call to S3L_setup_rand_fib and is used to identify a particular LFG setup.

Output

This function uses the following argument for output:

ier (Fortran only) - When called from a Fortran program, this function returns error status in ier.

Error Handling

On success, S3L_setup_rand_fib returns S3L_SUCCESS.

On error, the following error code may be returned:

S3L_ERR_ARG_SETUP - The setup_id value does not correspond to a valid setup.

Examples

../examples/s3l/rand_fib/rand_fib.c
../examples/s3l/rand_fib-f/rand_fib.f

Related Functions

S3L_rand_fib(3)
S3L_setup_rand_fib(3)

`S3L_rand_fib`

Description

S3L_rand_fib initializes a parallel array using a Lagged-Fibonacci random number generator (LFG). The LFG's parameters are fixed to l = 17, k = 5, and m = 32.

Random numbers are produced by the following iterative equation:

x[n] = (x[n-e]
+ x[n-k]) mod 2^m

The result of S3L_rand_fib depends on how the parallel array a is distributed.

When the parallel array is of type integer, its elements are filled with nonnegative integers in the range 0 . . . 2³¹ -1. When the parallel array is single- or double-precision real, its elements are filled with random nonnegative numbers in the range 0 . . . 1. For complex arrays, the real and imaginary parts are initialized to random real numbers.

Syntax

The C and Fortran syntax for S3L_rand_fib are shown below.

C/C++ Syntax

Example 8-71

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_rand_fib(a, setup_id, seed)
    S3L_array_t        a
    int                setup_id

F77/F90 Syntax

Example 8-72

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_rand_fib(a, setup_id, seed, ier)
    integer*8          a
    integer*4          setup_id
    integer*4          ier

Input

a - S3L array handle that describes the parallel array to be initialized by the LFG.
setup_id - Integer index used to access the state table associated with the array referenced by a.

Output

This function uses the following argument for output:

a - On output, a is a randomly initialized array.

ier (Fortran only) - When called from a Fortran program, this function returns error status in ier.

Error Handling

On success, S3L_rand_fib returns S3L_SUCCESS.

S3L_rand_fib checks the validity of the arrays it accepts as arguments. If an array argument contains an invalid or corrupted value, the function terminates and an error code indicating which value of the array handle was invalid is returned. See Appendix A of this manual for a detailed list of these error codes.

In addition, the following condition will cause the function to terminate and return the associated error code.

S3L_ERR_ARG_SETUP - The setup_id value does not correspond to a valid setup.

Examples

../examples/s3l/rand_fib/rand_fib.c
../examples/s3l/rand_fib-f/rand_fib.f

Related Functions

S3L_free_rand_fib(3)
S3L_setup_rand_fib(3)

`S3L_rand_lcg`

Description

S3L_rand_lcg initializes a parallel array a, using a Linear Congruential random number generator (LCG). It produces random numbers that are independent of the distribution of the parallel array.

Arrays of type S3L_integer (integer4) are initialized to random integers in the range 0 . . . 2³¹-1. Arrays of type S3L_long_integer are initialized with integers in the range 0 . . . 2⁶³-1. Arrays of type S3L_float or S3L_double are initialized in the range 0 . . . 1. The real and imaginary parts of type S3L_complex and S3L_double_complex are also initialized in the range 0 . . . 1.

The random numbers are initialized by an internal iterative equation of the type:

x[n] = a*x[n-1]
+ c

Syntax

The C and Fortran syntax for S3L_rand_lcg are shown below.

C/C++ Syntax

Example 8-73

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_rand_lcg(a, iseed)
    S3L_array_t        a
    int                iseed

F77/F90 Syntax

Example 8-74

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_rand_lcg(a, iseed, ier)
    integer*8          a
    integer*4          iseed
    integer*4          ier

Input

a - S3L array handle that describes the parallel array to be initialized by the LCG.
iseed - An integer. If positive, this value is used as the initial seed for the LCG. If zero or negative, the call to S3L_rand_lcg produces a sequence of random numbers, which is a continuation of a sequence generated in a previous call to S3L_rand_lcg.

Output

This function uses the following argument for output:

a - On output, a is a randomly initialized array.
ier (Fortran only) - When called from a Fortran program, this function returns error status in ier.

Error Handling

On success, S3L_rand_lcg returns S3L_SUCCESS.

S3L_rand_lcg checks the validity of the arrays it accepts as arguments. If an array argument contains an invalid or corrupted value, the function terminates and an error code indicating which value of the array handle was invalid is returned. See Appendix A of this manual for a detailed list of these error codes.

In addition, the following condition will cause the function to terminate and return the associated error code.

S3L_ERR_ARG_RANK - Invalid rank of a.

Examples

../examples/s3l/rand_lcg/rand_lcg.c
../examples/s3l/rand_lcg-f/rand_lcg.f

Related Functions

S3L_free_rand_fib(3)
S3L_setup_rand_fib(3)