User's Guide: Usage:Simple Interface

Simple Interface

In this section, we describe the function calls available in the Simple SPRNG interface. It is invoked by defining the macro SIMPLE_SPRNG before including a SPRNG header file. This interface is used when only one random number stream is required on each process at any given time. In this case, it is not necessary to use stream ID's to distinguish between different streams. Hence a simpler interface is possible.

Further details on each function can be found in the reference manual.

Pointers for FORTRAN users

The different random number streams available on a process, in the other interfaces, are distinguished by unique ID's, which are implemented as pointers to the memory locations where the states of the respective streams are stored. Though stream ID's are not used in the simple interface, some functions return pointers for the sake of consistency with the other interfaces. Since standard FORTRAN 77 does not have a pointer type, we can store a pointer as an integer of the same size as a C pointer. We have defined a macro called POINTER in the file sprng_f.h that automatically defines an integer of the correct size on the platforms on which SPRNG is supported. A FORTRAN programmer can then use the type POINTER just as if it were a FORTRAN data type. However, this applies only if the FORTRAN program is compiled with the same flags as given in the make file that comes with SPRNG.

SPRNG Functions

We describe below the SPRNG function calls available in the simple interface. For each function, the C call is given first, followed by the FORTRAN call. The function descriptions are along the lines of the C function prototypes. The data type preceding the function name is the type returned by the function. The data types preceding the arguments to the functions are the data types of the corresponding function arguments.

1. init_sprng

int *init_sprng(int seed, int param)

SPRNG_POINTER init_sprng(integer seed, integer param)

init_sprng initializes random number streams. This function call can be omitted if the user wishes to use the default values of the arguments. seed is the seed to the generators. The seed is not the starting state of the sequence; rather, it is an encoding of the starting state. It is acceptable, and recommended, to use the same seed for all the streams. The argument param selects the appropriate parameters (for example, the multiplier for a Linear Congruential Generator or the lag for a Lagged Fibonacci Generator). init_sprng returns a NULL pointer if it fails, normally due to an inability to allocate memory. Otherwise it returns a non-NULL value. If the MPI version of SPRNG has been installed and the macro USE_MPI has been defined before including a SPRNG header file, then this routine makes some MPI calls to determine the number of processes. This value is used to ensure that different streams are produced on different processes.

In case the user calls init_sprng while another stream has already been initialized, the new stream replaces the previous one.

Example

2. sprng

double sprng()

real*8 sprng()

The next random number in [0,1) is returned by this function. If FORTRAN programmers wish to obtain real*4 numbers, or C programmers float numbers, instead of the double precision default, then they should define the macro FLOAT_GEN before including a SPRNG header file.

Example

3. isprng

int isprng()

integer isprng()

The next random integer in [0,2³¹) is returned by this function. Calling isprng is equivalent to multiplying the result of sprng by 2³¹ and truncating to an integer. Calls to sprng and isprng can be interleaved.

Example

4. print_sprng

int print_sprng()

integer print_sprng()

The user may wish to print information about streams after initialization, without printing the entire state This is typically used when the user wishes to record information which can later be used to identify the random number stream used in the computations. This information can be obtained by a call to print_sprng.

Example

5. make_sprng_seed

int make_sprng_seed()

integer make_sprng_seed()

This function produces a new seed using system date and time information. It will typically be used when the programmer wishes to initialize with a different seed every time the program is run. User should note that both the Lagged Fibonacci Generators requires the use of the same seed for each stream in order to guarantee their independence. In order to ensure this on a parallel computer, they should install the MPI version of SPRNG and define the macro USE_MPI before including a SPRNG header file. This function will then involves some inter-processor communication.

Example

6. pack_sprng

int pack_sprng(char **buffer)

integer pack_sprng(SPRNG_POINTER fbuffer)

This function packs the state of the random number stream into an array and returns the number of bytes actually required for the storage. fbuffer should be the first element of an array of size MAX_PACKED_LENGTH bytes, where MAX_PACKED_LENGTH is a macro defined in "sprng_f.h" and "sprng.h". In the C interface, the programmer need not allocate memory. SPRNG allocates memory for the array and has the result stored in *buffer. This function can be used for check-pointing, where the programmer packs the state of the stream into an array and then saves it to a file. This state can later be retrieved by calling unpack_sprng, which is explained later. pack_sprng can also be used to pass a stream to another process. That process will unpack the stream to obtain the generator.

Example

7. unpack_sprng

int *unpack_sprng(char *buffer)

SPRNG_POINTER unpack_sprng(SPRNG_POINTER buffer)

This function recreates a stream given the array buffer, which was used to store the stream's state through a call to the function pack_sprng. The return value should be ignored unless it is NULL. A NULL pointer is returned only if this function failed due to an inability to allocate memory.

In case a random number stream has already been initialized, the unpacked stream replaces the previous stream.

Example