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_cpp.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 C++ implementation, an ID is a SPRNG object that we use to call SPRNG function. In the FORTRAN interface, an ID is a pointer to the memory location in which the state of the stream is stored. In FORTRAN, 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

Two 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 uses stream ID for SPRNG functions in order to distinguish the streams. If due to errors in the program the user uses an invalid ID, then this can lead to erroneous results, or the program may even terminate and a segmentation fault may occur.

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.