\documentclass[12pt]{article}
\usepackage{myarticle}
%%%%%%%%%%%%%%%%%%%%%%%%%%
\topmargin=-0.5in
\oddsidemargin=0pt
\topskip=\baselineskip
\headsep=0pt
\headheight=0.2in
\textwidth=6.5 true in
\textheight=9.2 true in
\tolerance=500
\parskip=.1in plus .1in minus .04in
\baselineskip=18pt
\begin{document}
\begin{center}
{\large\bf RngStreams: An object-oriented random-number package in C
with many long streams and substreams}\\
\date{5 Jan. 2010}
\end{center}
\bigskip
This file describes a C interface to the {\tt RngStreams} package.
The backbone generator is the combined multiple recursive
generator (CMRG) {\tt Mrg32k3a} proposed in \cite{rLEC99b},
implemented in 64-bit floating-point arithmetic.
This backbone generator has period length $\rho\approx 2^{191}$.
The values of $V$, $W$, and $Z$ are $2^{51}$, $2^{76}$, and $2^{127}$,
respectively. % (See {\tt RandomStream} for their definition.)
The seed of the RNG, and the state of a stream at any given step,
are 6-dimensional vectors of 32-bit integers.
The default initial seed of the package is
$(12345, 12345, 12345, 12345, 12345,$ $12345)$.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \section {A C Interface to the Package RngStreams}
%%%%%%%%%%%%%%%%%%%%%%%
\bigskip\hrule
\code\hide
/* RngStream.h for ANSI C */
#ifndef RNGSTREAM_H
#define RNGSTREAM_H
\endhide
typedef struct RngStream_InfoState * RngStream;
struct RngStream_InfoState {
double Cg[6], Bg[6], Ig[6];
int Anti;
int IncPrec;
char *name;
};
\endcode
\tab
The state of a stream from the present module.
The arrays {\tt Ig}, {\tt Bg}, and {\tt Cg} contain the initial state,
the starting point of the current substream,
and the current state, respectively.
This stream generates antithetic variates if {\tt Anti} $\neq 0$.
The precision of the output numbers is increased if {\tt IncPrec} $\neq 0$.
\endtab
\code
int RngStream_SetPackageSeed (unsigned long seed[6]);
\endcode
\tab Sets the initial seed of the package {\tt RngStreams} to the
six integers in the vector {\tt seed}.
This will be the seed (initial state) of the first stream.
If this procedure is not called, the default initial seed
is $(12345, 12345, 12345, 12345, 12345, 12345)$.
If it is called, the first 3 values of the seed must all be
less than $m_1 = 4294967087$, and not all 0;
and the last 3 values
must all be less than $m_2 = 4294944443$, and not all 0.
Returns $-1$ for invalid seeds, and 0 otherwise.
\endtab
\code
RngStream RngStream_CreateStream (const char name[]);
\endcode
\tab Creates and returns a new stream with identifier {\tt name},
whose state variable is of type {\tt RngStream\_InfoState}.
This procedure reserves space to keep the information relative to
the {\tt RngStream}, initializes its seed $I_g$,
sets $B_g$ and $C_g$ equal to $I_g$, sets its antithetic and precision
switches to 0.
The seed $I_g$ is equal to the initial seed of the package given by
{\tt RngStream\_SetPackageSeed} if this is the first stream created,
otherwise it is $Z$ steps ahead of that of the most recently
created stream.
\endtab
\code
void RngStream_DeleteStream (RngStream g);
\endcode
\tab Deletes the stream {\tt g} created previously
by {\tt RngStream\_CreateStream}, and recovers its memory.
\endtab
\code
void RngStream_ResetStartStream (RngStream g);
\endcode
\tab Reinitializes the stream {\tt g} to its initial state:
$C_g$ and $B_g$ are set to $I_g$.
\endtab
\code
void RngStream_ResetStartSubstream (RngStream g);
\endcode
\tab Reinitializes the stream {\tt g} to the beginning of its current
substream: $C_g$ is set to $B_g$.
\endtab
\code
void RngStream_ResetNextSubstream (RngStream g);
\endcode
\tab Reinitializes the stream {\tt g} to the beginning of its next
substream: $N_g$ is computed, and
$C_g$ and $B_g$ are set to $N_g$.
\endtab
\code
void RngStream_SetAntithetic (RngStream g, int a);
\endcode
\tab If {\tt a} $\neq 0$, the stream {\tt g} will start generating
antithetic variates, i.e., $1-U$ instead of $U$, until this method is
called again with {\tt a = 0}.
% By default, the streams are created with {\tt anti = false}.
\endtab
\code
void RngStream_IncreasedPrecis (RngStream g, int incp);
\endcode
\tab After calling this procedure with {\tt incp} $\neq 0$, each call
(direct or indirect) to {\tt RngStream\_RandU01} for stream {\tt g}
will advance the state of the stream by 2 steps instead of 1, and will
return a number with (roughly) 53 bits of precision instead of 32 bits.
More specifically, in the non-antithetic case, the instruction
``{\tt x = RngStream\_RandU01(g)}'' when the precision is increased
is equivalent to
``{\tt x = (RngStream\_RandU01(g) + RngStream\_RandU01(g) * fact) \%\ 1.0}''
where the constant {\tt fact} is equal to $2^{-24}$.
This also applies when calling {\tt RngStream\_RandU01} indirectly
(e.g., by calling {\tt RngStream\_RandInt}, etc.).
By default, or if this procedure is called again with {\tt incp = 0},
each call to {\tt RngStream\_RandU01} for stream {\tt g}
advances the state by 1 step and returns a
number with 32 bits of precision.
\endtab
\code
int RngStream_SetSeed (RngStream g, unsigned long seed[6]);
\endcode
\tab Sets the initial seed $I_g$ of stream {\tt g}
to the vector {\tt seed}. This vector must satisfy the same
conditions as in {\tt RngStream\_SetPackageSeed}.
The stream is then reset to this initial seed.
The states and seeds of the other streams are not modified.
As a result, after calling this procedure, the initial seeds
of the streams are no longer spaced $Z$ values apart.
We discourage the use of this procedure.
Returns $-1$ for invalid seeds, and 0 otherwise.
% Proper use of {\tt RngStream\_ResetStream} is preferable.
\endtab
\code
void RngStream_AdvanceState (RngStream g, long e, long c);
\endcode
\tab Advances the state of stream {\tt g} by $k$ values,
without modifying the states of other streams
(as in {\tt RngStream\_SetSeed}),
nor the values of $B_g$ and $I_g$ associated with this stream.
If $e > 0$, then $k=2^e + c$;
if $e < 0$, then $k=-2^{-e} + c$; and if $e = 0$, then $k=c$.
Note: $c$ is allowed to take negative values.
We discourage the use of this procedure.
\endtab
\code
void RngStream_GetState (RngStream g, unsigned long seed[6]);
\endcode
\tab Returns in {\tt seed[]} the current state $C_g$ of stream {\tt g}.
This is convenient if we want to save the state for subsequent use.
\endtab
\code
void RngStream_WriteState (RngStream g);
\endcode
\tab Prints (to standard output) the current state of stream {\tt g}.
\endtab
\code
void RngStream_WriteStateFull (RngStream g);
\endcode
\tab Prints (to standard output) the name of stream {\tt g} and the values
of all its internal variables.
\endtab
\code
double RngStream_RandU01 (RngStream g);
\endcode
\tab Returns a (pseudo)random number from the uniform distribution
over the interval $(0,1)$, using stream {\tt g},
after advancing the state by one step.
The returned number has 32 bits of precision in the sense that it is
always a multiple of $1/(2^{32}-208)$,
unless {\tt RngStream\_IncreasedPrecis} has been called for this stream.
\endtab
\code
int RngStream_RandInt (RngStream g, int i, int j);
\endcode
\tab Returns a (pseudo)random number from the discrete uniform
distribution over the integers $\{i,i+1,\dots,j\}$,
using stream {\tt g}.
Makes one call to {\tt RngStream\_RandU01}.
\endtab
\code\hide
#endif
\endhide
\endcode
\bigskip
\hrule
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\bibliography {random}
\bibliographystyle {plain}
\end {document}