User's Guide:Usage

SPRNG Usage

In this section we assume that the SPRNG libraries have already been installed. Users may wish to read about SPRNG parallelization scheme in case they wish to know more about the strategy used in SPRNG to provide independent random number streams.

Header Files

SPRNG provides both FORTRAN and C interfaces for the use of its parallel random number generator libraries. It can be used in C++ programs too. In order to use SPRNG in a FORTRAN program, the user must include the file sprng_f.h before calling any SPRNG function. C programmers must similarly include the file sprng.h. The user may also wish to define certain macros before including the above mentioned header files in order to modify the behavior of SPRNG. The effects of different macros will be described in the appropriate sections.

Distinguishing the streams

SPRNG permits the use of several random number streams on each processor. We therefore need to be able to distinguish between the different streams. The SPRNG initialization routine returns a unique ID for each stream, based on which the different streams can be distinguished. In our implementation, an ID is actually a pointer to the memory location were the state of the stream is stored. When a SPRNG function is called, this stream ID is also passed to the function by the user in order to provide information on the particular stream involved.

SPRNG interfaces

Three different interfaces are available to the SPRNG user, as described below:

Default interface:

This is the default interface provided by SPRNG. The user can have several random number streams on each processor. The user passes the stream ID to SPRNG functions in order to distinguish the streams. If due to errors in the program the user passes an invalid ID, then this can lead to erroneous results, or the program may even terminate.

Interface with pointer checking:

This interface is invoked by defining the macro CHECK_POINTERS before including a SPRNG header file. It is similar to the default interface, except that it checks for the validity of the stream ID each time a SPRNG function is called. This facility slows down the SPRNG routines, and so would normally be used only while debugging the program.

Simple Interface:

Users may wish to use only one random number stream per process at any given time. It is then not necessary to provide a stream ID in order to distinguish the streams. The simple interface enables the user to call SPRNG functions without providing stream ID's. This interface is invoked by defining the macro SIMPLE_SPRNG before including a SPRNG header file.