Using SPRNG at NERSC

The Scalable Parallel Random Number Generator (SPRNG), is has been installed at NERSC. Fairly complete documentation on its use and implementation, including examples, is available. Version 1.0 is currently available.

The SPRNG package is powerful and flexible and only a few items must be added to existing parallel code to allow parallel processes to generate multiple streams of random numbers. These few items are outlined here.

Parallel codes using SPRNG must be based on MPI. No shared-memory implementation of this package is available. MPI is available on all NERSC multiprocessor systems.

Here are the three steps needed to get SPRNG working in a user program:

1. Access the SPRNG libraries
2. Add SPRNG calls to your code
3. Compile and link with SPRNG

Accessing the SPRNG libraries

The components of SPRNG are available on the SP in the module "sprng". This module controls access to the library's header files and linkable binaries.

Type one of the following module commands at your shell prompt on SP

% module load sprng
% module load sprng64
% module load sprng/2.0

Adding SPRNG calls to your code

To use SPRNG in a Fortran-90 MPI-based program, lines of code like the following should be added to your program:
(This is a code skeleton; for a complete sample program that uses SPRNG 1.0, see the SPRNG Sample Program, and its input file.

! This code fragment is a schematic example of the usage of
! SPRNG 1.0.
!
! First, specify a few macros and preprocessor directives:

! Use this line during debugging, and omit it afterwards.
#define CHECK_POINTERS 

#define USE_MPI
#include <mpif.h>
#include "sprng_f.h"

! Then, declare a few variables: 
	SPRNG_POINTER, dimension(:), allocatable :: streamPtr
	integer seed
	real*8 RandNum

! Add a few lines of code which all processors will execute:

! Initialize a special seed for SPRNG:
!
! All processors can use the same seed, but all streams will
! nonetheless contain different sequences of random numbers.
! This is recommended usage. The seed shown below is one
! advised in the SPRNG 1.0 documentation. Using a determinate
! seed, compiled or read in, for all streams, guarantees
! repeatable behavior among runs, with the same numbers of
! processors and streams.)
	seed = 985456376 

! Or, let SPRNG generate "truly random" seeds, 
! one per processor, as follows:
! This guarantees UNrepeatable behavior.
	seed = make_sprng_seed() 

! Allocate space for the stream data structures SPRNG uses
	allocate(streamPtr(NumOfStreamsPerProcessor))

! Initialize the streams of random numbers SPRNG will provide
	do j = 0, NumOfStreamsPerProcessor-1
! Each stream gets a unique ID.
       	   sj = j + MPI_Processor_ID * MyNumOfStreams 
       	   streamPtr(j) = &
		init_sprng(sj, TotalNumberOfStreams, seed, SPRNG_DEFAULT)
	enddo

! Generate a random number from one of the streams on each processor...
! Specify one of many streams on each processor.
	RandNum = sprng(streamPtr(sj)) 
! Or, from the only stream on each processor 
! Using the MPI processor ID to
! index the array of stream
! pointers implies one stream
! per processor.
	RandNum = sprng(streamPtr(MPI_Processor_ID)) 

! Optionally destroy all streams before MPI Finalization
	do j = 0, NumOfStreamsPerProcessor-1
		sj = j + MPI_Processor_ID * MyNumOfStreams
		junk = free_sprng(streamPtr(sj))
	enddo

In the above, NumOfStreamsPerProcessor is your choice, and can be greater than 1; and MPI_Processor_ID is the value returned from the call to MPI_COMM_RANK

Compiling and linking with SPRNG

The SPRNG package can be used with Fortran, C, or C++ code. The SP Fortran 90 compile line will look something like this

% mpxlf90_r $SPRNG -lspringlib -o executable sourcefile

Here, "$SPRNG" is an environment variable, specifying include and library paths, set up by the SPRNG module. Italics represent values you provide, such as the names of your source and executable files, and which SPRNG generator you wish to use.

To improve performance, optimization (e.g. -On) and tuning options (e.g. -qfloat=nomaf -qstrict -qarch=pwr3 -qtune=pwr3) can be added to the compile line.

(The "-qnomaf" option guarantees compatibility with IEEE arithmetic by excluding the IBM "multiply-add" instruction from generated code; the use of that instruction, while improving performance, may cause results that differ from those produced by other machines.)

If uncertainty exists as to which generator is best for your application, the lcg generator is a good one to start with. The SPRNG package includes includes the following generators :

• lcg - the 48 Bit Linear Congruential Generator with Prime Addend
• lcg64 - the 64 Bit Linear Congruential Generator with Prime Addend
• lfg/mlfg - the Modified Lagged Fibonacci Generator
• mlcg - the Multiplicative Lagged Fibonacci Generator
• cmrg - the Combined Multiple Recursive Generator

For full documentation on these packages, see

• SPRNG 1.0 documentation
• SPRNG 2.0 README
• SPRNG 2.0 Documentation in PostScript
• SPRNG 2.0 Documentation in HTML

These items should give you a parallel program with multiple independent streams of random numbers.

The SPRNG generators are engineered to provide identical streams of random numbers on all platforms. This guarantee is removed if the "make_sprng_seed()" call is used to generate "truly random" seeds.

However, even under identical execution conditions, arithmetic differences may exist between platforms, and different answers may still arise.

The SPRNG documentation contains numerous examples of how to use other elements of the library. For instance, random floating point values of several sizes may be generated, as well as random integers. Streams of random numbers can be dynamically spawned, passed between processors in messages, and destroyed. Here is a full, but simple, sample program that uses SPRNG 1.0, and its input file.