User's Guide: Usage:Interface With Pointer Checking

Interface with Pointer Checking

In this section, we describe the function calls available in the SPRNG interface with pointer checking. It is invoked by defining the macro CHECK_POINTERS before including a SPRNG header file. This interface would typically be used while debugging a program with more than one random number stream per process. The different streams are distinguished by unique ID's, which are implemented as pointers to memory locations where the states of the respective streams are stored. Most SPRNG functions take this stream ID as an argument. If the user passes an invalid ID as an argument, then this can lead to unpredictable behavior by SPRNG. This interface first checks to see if the ID is valid before using it, thus detecting the use of invalid ID's. In case an invalid ID is used, it responds as explained in the function descriptions below. A determined user can however subvert this checking system by freeing a stream directly without invoking the free_sprng function.

Users should note that this interface can slow down the program moderately. Its use is therefore recommended only while debugging. The default interface is identical to this interface, except that it is does not check for the validity of the ID's, and hence can be used once debugging has been completed.

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 are distinguished by unique ID's, which are implemented as pointers to the memory locations where the states of the respective streams are stored. 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 SPRNG_POINTER in the file sprng_f.h that automatically defines an integer of the correct size on the platforms on which SPRNG is supported. The FORTRAN programmer can then use the type SPRNG_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 interface with pointer checking. For each function, the C call is given first, followed by the FORTRAN call. 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 streamnum, int nstreams, int seed, int param)

SPRNG_POINTER init_sprng(integer streamnum, integer nstreams, integer seed, integer param)

init_sprng initializes random number streams. streamnum is the generator number and is typically the process number and must be in [0,nstreams-1]. nstreams is the number of different streams that will be initialized across all the processors and 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 the ID of the stream.

Example

2. sprng

double sprng(int *stream)

real*8 sprng(SPRNG_POINTER stream)

stream is the ID of the stream from which 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.

In case stream is an invalid ID, this function returns -1.0.

Example

3. isprng

int isprng(int *stream)

integer isprng(SPRNG_POINTER stream)

stream is the ID of the stream from which 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.

In case stream is an invalid ID, this function returns -1.

Example

4. print_sprng

int print_sprng(int *stream)

integer print_sprng(SPRNG_POINTER stream)

The user may wish to print information about streams after initialization or spawning, 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 with the ID of the stream as argument.

In case stream is an invalid ID, this function returns 0.

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 require 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(int *stream, char **buffer)

integer pack_sprng(SPRNG_POINTER stream, SPRNG_POINTER fbuffer)

This function packs the state of the stream with ID 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 array to obtain the stream.

In case stream is an invalid ID, this function returns 0.

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. An ID for the recreated stream is returned. Note that this ID is unrelated to the previous ID of the stream before it was packed, though the states are the same.

Example

8. free_sprng

int free_sprng(int *stream)

integer free_sprng(SPRNG_POINTER stream)

This function frees the memory used to store information concerning the random number stream identified by the stream ID stream. The stream's ID is then no longer valid. free_sprng returns the current number of streams available on the process.

In case stream is an invalid ID, this function returns -1.

Example

9. spawn_sprng

int spawn_sprng(int *stream, int nspawned, int ***newstreams)

integer spawn_sprng(SPRNG_POINTER stream, integer nspawned, SPRNG_POINTER fnewstreams)

Some times, for example in branching processes, it is necessary to spawn new streams from an old one. This function creates new random number streams when given a stream ID stream and the number of new streams nspawned to be spawned. fnewstreams is the first element of an array of length at least nspawned in which the ID's of the new streams will be stored. In the C interface, SPRNG allocates memory for the array and makes *newstreams point to this array. spawn_sprng returns the number of streams spawned. If the function fails due to an inability to allocate memory, then the value returned is less than nspawned.

In case stream is an invalid ID, this function returns 0.

Example