Quick Start

This document instructs the user on how to quickly 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

• Download sprng5.tar.bz2 (Last updated: 6/10/2021 ).

• To Build SPRNG, do the following:
  • tar xjf sprng5.tar.bz2

  • cd sprng5

  • Run ./configure (using appropriate arguments for optional features)

  • Run make

  • Go to directory check, and run ./checksprng. This program checks to see if SPRNG has been correctly installed.
    

• If SPRNG has been correctly installed on your machine, then the libraries are placed in the lib directory, and the include files are in include.

• You may check the speed of the different SPRNG random number generators by executing the following command in the directory check:
  ./timesprng
  

• Directories in SPRNG
  • SRC - Source code for SPRNG.
  • EXAMPLES - Examples of SPRNG usage. All MPI examples are placed in subdirectory mpisprng. If MPI installation is requested, then all MPI examples will be automatically installed.
  • TESTS - Empirical and physical tests for SPRNG generators. All MPI tests are stored in subdirectory mpitests. If MPI installation is requested, then all MPI tests will be automatically installed. All TestU01 tests are stored in subdirectory testu01.
  • check - contains executables ./checksprng and ./timesprng.
  • lib - contains SPRNG library libsprng after sucessful installation.
  • include - SPRNG header files.

  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 sprng4.0/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.
  • If the FORTRAN verison is installed then FORTRAN users should include the header file sprng_f.h and C users sprng_cpp.h.
  • (Optional) If users wish to, they can use a LCG object to call an initialization function, init_sprng. It has four arguments. The first is the stream number. The second is the total number of generators. The third is the seed, and the fourth chooses the 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 libsprng.a should be linked. We have provided examples for compilation on different platforms.

  Example
  

  Using SPRNG in a parallel program (if the MPI version is installed)

  • 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_cpp.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 use an LCG object to call an initialization function, init_sprng. It has four arguments. The first is the stream number. The second is the total number of generators. The third is the seed, and the fourth chooses the 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 libsprng.a and the MPI library should be linked. We have provided examples for compilation on different platforms.

  Examples
  

  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. If the default interface is chosen, then the users also must call SelectType(rng_type) before performing an initialization. For example, if we want to call the intialization routine for LCG, then we must do

    SPRNG * lcgobj = SelectType(1);
lcgobject->init_sprng(/* arguments */);

    [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 libsprng.a.

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

  Example