\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}
