\chapter{BATTERIES OF TESTS}

This chapter describes predefined batteries of tests available 
in TestU01. 
% Some batteries are more suitable for generators returning uniform
%  floating-point numbers in the interval $[0, 1)$,
% while others are more oriented towards random bit generators.
Some batteries are fast and small, and may be used as a first step in
detecting gross defects in generators or errors in their implementation.
Other batteries are more stringent and take longer to run.
%  They can often detect flaws in low or medium quality RNGs.
Special batteries are also available to test a stream of random bits
taken from a file. 
% One has been designed specially for hardware random bit generators.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\paragraph*{An example: The battery SmallCrush applied to a generator.} \

Figure~\ref{fig:bat1.c} shows how to apply a battery of tests to a
generator. The function call to {\tt ulcg\_CreateLCG} creates and initializes the
generator {\tt gen} to the linear congruential generator (LCG) with 
modulus $m$ = 2147483647, multiplier $a$ = 16807, additive constant $c=0$, 
and initial state $x_0 = 12345$.  
% This LCG is still widely used in commercial software.
Then the small battery {\tt SmallCrush}, defined in module
{\tt bbattery}, is applied on this generator.
Figure~\ref{fig:bat1.res} shows a summary report of the results
(assuming that 64-bits integers are available; otherwise, the results could
be slightly different).
Out of the 15 tests applied, the generator failed three with a $p$-value 
practically equal to 0, so it is clear that it failed this battery.
It took 20.3 seconds to run this battery on a machine with a 
2400 MHz Athlon processor running under Linux.


\setbox0=\vbox {\hsize = 6.0in
\smallc
\verbatiminput{../examples/bat1.c}
}

\begin{figure}[hbt] \centering \myboxit{\box0}
\caption{Applying the battery SmallCrush on a LCG generator.}
  \label{fig:bat1.c}
\end{figure}


\setbox1=\vbox {\hsize = 6.0in
\smallc
\verbatiminput{../examples/bat1.res}
}

\begin{figure}[ht] \centering \myboxit{\box1}
\caption{Results of applying SmallCrush.}  \label{fig:bat1.res}
\end{figure}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\paragraph*{Another example: The battery Rabbit applied to a binary file.} \


Figure~\ref{fig:bat2.c} shows how to apply the battery
{\tt Rabbit} to a binary file (presumably, a file of random bits).
The tests will use at most 1048576 ($=2^{20}$) bits from the 
binary file named {\tt vax.bin}. 
(Incidentally, these bits were obtained by taking the 32 most significant
bits from each uniform number generated by
the well-known LCG with parameters $m = 2^{32}$, $a = 69069$ and $c=1$.
 This was the random number generator used under VAX/VMS.)
Since the variable {\tt swrite\_Basic} is set to {\tt FALSE},
no detailed output is written, only the summary report shown in 
Figure~\ref{fig:bat2.res} is printed after running the tests.
Seven tests were failed with a $p$-value practically equal to 0 or 1.
It is clear that the null hypothesis $\cH_0$ must be rejected for
 this bit stream.
It took 1.9 seconds to run the entire battery on a machine with a 
2400 MHz Athlon processor running under Linux.

\setbox0=\vbox {\hsize = 6.0in
\smallc
\verbatiminput{../examples/bat2.c}
}

\begin{figure} \centering \myboxit{\box0}
\caption{Applying the battery Rabbit on a file of random bits.}
  \label{fig:bat2.c}
\end{figure}


\setbox1=\vbox {\hsize = 6.0in
\smallc
\verbatiminput{../examples/bat2.res}
}

\begin{figure} \centering \myboxit{\box1}
\caption{Results of applying Rabbit.}  \label{fig:bat2.res}
\end{figure}
