Quick Start

This document instructs the user on how to quickly install and use some of the simpler SPRNG features. It assumes that the user has some experience installing software and in using random number generators. However, links are provided in case more details are required.

Installing Default SPRNG Libraries

• Change directory to the sprng directory. For example:

• cd sprng

• Select your platform: Edit the make.CHOICES file -- Remove any # sign from in front of the platform you are using, and place one in front of all others. Please read the notes on the makefile to port SPRNG to other machines.

• cd SRC
• make
  If you encounter any problems, then please take a look at the make.PLAT file (where PLAT is the platform you are on) to check if the compiler information is set approprately for your machine. If not, you can edit this file and try the make command again. In particular, if you wish to install the MPI version, then you need to edit this file and follow the directions given there.

• cd ..
• ./checksprng
  Several tests are conducted. The results should show that each of the tests passed.
• SPRNG has been correctly installed on your machine. The libraries are placed in the sprng/lib directory, and the include files are in sprng/include.
• You may check the speed of the different SPRNG random number generators by executing the following command in the directory sprng:
  ./timesprng
  

SPRNG Usage

We give some examples to demonstrate the use of some simple features of SPRNG. Our examples use the 48 bit Linear Congruential Generator. These examples assume that the user wishes to use only one random number stream per processor. Thus we can make use of the simple interface available on SPRNG. We have provided examples for both serial and parallel computers. Further details, especially for the default interface, can be found in the usage section of the user's guide.

Note that the SPRNG libraries are placed by default in the sprng/lib directory, and the include files are in sprng/include.

Using SPRNG in a serial program

• The macro SIMPLE_SPRNG should be defined in order to invoke the simple interface.
• Then FORTRAN users should include the header file sprng_f.h and C users sprng.h.
• (Optional) If users wish to, they can call an initialization function, init_sprng. It has two arguments. The first is any integer seed and the second chooses the multiplier parameter for the LCG generator. If the user does not call the initialization routine, SPRNG performs a default initialization with seed = 0, parameter = SPRNG_DEFAULT.
• The user can then call the function sprng in order to obtain a double precision random number in [0,1).
• While compiling, the library liblcg.a should be linked. We have provided examples for compilation on different platforms.

Example

Using SPRNG in a parallel program

• The macro SIMPLE_SPRNG should be defined in order to invoke the simple interface.
• Then the macro USE_MPI should be defined to instruct SPRNG to make MPI calls during initialization.
• Next FORTRAN users should include the header file sprng_f.h and C users sprng.h.
• Before calling any SPRNG function the users should call MPI_Init and finally they must call MPI_Finalize.
• (Optional) If users wish to, they can call an initialization function, init_sprng. It has two arguments. The first is any integer seed and the second chooses the multiplier parameter for the LCG generator. If the user does not call the initialization routine, SPRNG performs a default initialization with seed = 0, parameter = SPRNG_DEFAULT. Independent streams are produced on each processor.
• The user can then call the function sprng in order to obtain a double precision random number in [0,1).
• While compiling, the libraries liblcg.a and the MPI library should be linked. We have provided examples for compilation on different platforms.

Example

Converting User Code to SPRNG

• Users should define the necessary macros and include a SPRNG header file as mentioned in the examples above, in each file where the random number function is called.
• Then they should replace the initialization calls with a call to init_sprng if they wish to explicitly perform an initialization. [Optional]
• In order to replace the calls to the users' original random number generator, oldrandom, with calls to sprng, there are two choices:
  1. Users can perform a search and replace in which oldrandom is replaced by sprng.

  2. Alternatively, users can insert the following line after including the SPRNG header file:

     #define oldrandom sprng

• Instead of linking to any library for their previous random number generator, they must link to liblcg.a.

Those FORTRAN users who are not used to the C preprocessor can read the note to FORTRAN users on this topic.

Example