Added new Crn functionality descriptions. And added an index to the
[charm.git] / doc / convext / random.tex
1 \chapter{Converse Pseudorandom Number Generator}
2
3 Converse provides three different Linear Congruential Random Number Generators.
4 Each random number stream has a cycle length of $2^{64}$ as opposed to
5 ANSI C standard's $2^{48}$.
6 Also, each of the three random number streams can be split into a number of
7 per processor streams, so that the random number sequences can be computed 
8 in parallel, and are reproducible. Furthermore, there is no implicit critical
9 section in the random number generator,and yet, this functionality is
10 thread-safe, because all the state information is stored in the structure
11 allocated by the programmer. Further, this state information is stored in a
12 first class object, and can be passed to other processors through messages.
13 This module of Converse is based on the public-domain 
14 SPRNG\footnote{URL:{\tt http://www.ncsa.uiuc.edu/Apps/SPRNG/www/}} 
15 package developed
16 by Ashok Srinivasan\footnote{Email:{\tt ashoks@ncsa.uiuc.edu}} at NCSA.
17
18 For minimal change to programs already using C functions {\tt rand()},
19 {\tt srand()}, and {\tt drand48()}, Converse also maintains a ``default''
20 random number stream.
21
22 Interface to the Converse Pseudorandom Number Generator module is as follows:
23
24 \function{typedef ... CrnStream;}
25 \index{CrnStream}
26 \desc{State information for generating the next random number in the sequence.}
27
28 \function{void CrnInitStream(CrnStream *stream, int seed, int type)}
29 \index{CrnInitStream}
30 \desc{Initializes the new random number stream \param{stream} 
31 of \param{type} using \param{seed}. \param{type} can have values 0, 1, or 2
32 to represent three types of linear congruential random number generators.}
33
34
35 \function{int CrnInt(CrnStream *stream)}
36 \index{CrnInt}
37 \desc{Returns an integer between 0 and $2^{31}-1$ corresponding to the next
38 random number in the sequence associated with \param{stream}. 
39 Advances \param{stream} by one in the sequence.}
40
41 \function{double CrnDouble(CrnStream *stream)}
42 \index{CrnDouble}
43 \desc{Returns an double precision floating point number between 0 and 1
44 corresponding to the next
45 random number in the sequence associated with \param{stream}. 
46 Advances \param{stream} by one in the sequence.}
47 \desc{}
48
49 \function{float CrnFloat(CrnStream *stream)}
50 \index{CrnFloat}
51 \desc{Returns a single precision floating point number between 0 and 1 
52 corresponding to the next
53 random number in the sequence associated with \param{stream}. 
54 Advances \param{stream} by one in the sequence.}
55
56 \function{void CrnSrand(int seed)}
57 \index{CrnSrand}
58 \desc{
59 Specifies a different seed for the default random number stream.
60 Replaces {\tt srand()}.
61 }
62
63 \function{int CrnRand(void)}
64 \index{CrnRand}
65 \desc{
66 Generate the next integer random number from the default random number
67 stream. Replaces {\tt rand()}.
68 }
69
70 \function{double CrnDrand(void)}
71 \index{CrnDrand}
72 \desc{
73 Generate the next double precision random number from the default random number
74 stream. Replaces {\tt drand48()}.
75 }