

1. Introduction
This file describes use of new versions of tests 
from the first edition of

        The Marsaglia Random Number CDROM
                   with
    The Diehard Battery of Tests of Randomness

plus new "tough" tests that will appear in the next edition.

Supported by a grant from the National Science Foundation,
1000 copies of that CDROM were distributed in 1995 to math
and  science departments and to interested researchers
worldwide.   The 1000 copies were soon exhausted, but the
CDROM has since  been frequently accessed via the Internet.
A new version of the CDROM is being prepared, and this file
accompanies C source code for new versions of the Diehard
tests, as well as several new difficult-to-pass tests.

A new edition of the CDROM is being developed at
The University of Hong Kong, under support from
The Innovation and Technology Commission,
HKSAR Government, under the titles
"Vulnerability Analysis Tools for Cryptographic Keys
(ITS/227/00)"  and
"Secure Preservation of Electronic Documents (ITS/170/01)".
I would like to express my appreciation to the members,
especially Professor W.W. Tsang and  Mr. Anthony Tsang,
of The Centre for Information Security and  Cryptography,
University of Hong Kong.

The name "Diehard" arose by accident.  For some 25 years,
at several universities, I had given a course to graduate
students: "Computer methods in probability and statistics"
in which I discussed use of a battery of tests to apply to
random  number generators (RNG's).  There I used
"battery" in a sense relating to: an assailing with blows,
a number of pieces of artillery placed for combined action,
or, more specifically: a series of psychological, clinical
or statistical tests.

One of the graduate students was improving his English by
watching television, and his only acquaintance with the word
"battery" was through pervasive ads on TV by Sears for their
Diehard automobile batteries. During class discussions, that
student used  the term "diehard" in referring to the tests,
much to the amusement of the class, and the name stuck.

2.Use of Diehard

Unlike the first version of Diehard, this version requires
either a binary file of random bits, or it allows you to
test a particular RNG function (written as C procedure
returning 32-bit integers).  Methods for creating a binary 
file are in the footnotes below.


The C source code for the Diehard battery of tests is
distributed as diehard.zip.   It  unzips to several files:

      1. readme.txt    The present file
      2. diehard.c     The C file that calls the tests
      3. dieprocs.c    C versions of the tests
      4. header.h      Header file with definitions, etc.
      5. macro.h       Another header file
      6. cinv7.bin     Inverse of the large covariance matrix
                       needed for the OPERM5 test.
      7. diehard.exe   An exec file for running under
                       Windows or DOS, getting the random
                       numbers from a large binary file.
                       (This file may be offered seperately, for
                        those not intending Windows use.)

3. Insructions for testing a binary file of purported random bits:

The above-listed diehard.exe will serve for Windows/DOS.
For other machines, you can create your own executable
version by compiling the source code.   For that, you need
files 2 to 6 above in the current directory, then compiler
instructions such as these for gcc:

gcc -Wall -O3 -c diehard.c
gcc -Wall -O3 -c dieprocs.c
gcc -Wall -O3 -lm -o diehard diehard.o dieprocs.o

That should provide an executable version of diehard for
testing a file of random bits.

Once you have that diehard.exe, the command line
        diehard
will give three prompts: 1) for the binary file name 
     2) for the RNG name to be printed with each test
     3) which tests to perform

To avoid those prompts, the line
        diehard  +5 +14 +9  mybinf.ile
will do tests 5 and 9 and 14 (in order) on your binary file, 
printing the name of the RNG as the file name. 
Or,
       diehard -3 -12  mybinf.ile
will do all tests except tests 3 and 12, and the simpler command
       diehard mybinf.ile
will use your file to do all the tests, and
       diehard -s RNG7 mybinf.ile
will use that file do to all the tests, and identify the RNG
as RNG7 with the results for each test.

In each of the above cases, results are sent to the
screen as well as adjoined to a file called result.txt.
You may designate an output file for results, as in
       diehard +2 +7 +14 -o myrng.out mybinf.ile
for which results of testing the binary file mybinf.ile
will be sent both to the screen and to the file myrng.out.

Also in the above cases, use of the option -t will suppress
displaying descriptions of the tests, for those who have
already seen them many times (-t for terse).

Summary of options: 
   -3             means skip test 3.
   +8             means do test 8
   -s RNGname     prints the string "RNGname" with each test
   -t             suppresses test descriptions
   -o filename    sends output to file rather than to default results.txt


4. Insructions for testing a RNG programmed as a procedure in C:

To run Diehard on a RNG of your choice, you must provide
a C procedure that produces supposed random 32-bit integers.
For example, to test a remarkably good multiply-with-carry
RNG you might create a C file named myrng.c as follows:
//-----------------------------------------------
#define MWC256 myRNG

static unsigned long Q[256],carry=362436;

unsigned long MWC256(void){
unsigned long long t,a=809430660LL;
static unsigned char i=255;
 t=a*Q[++i]+carry; carry=(t>>32);
 return(Q[i]=t);          }                          

void resetRNG(void){
unsigned long i,j=123456789;
for(i=0;i<256;i++) {j=69069*j+12345;  Q[i]=j;}
                   }
//------------------------------------------------

Diehard for specific RNG's looks for a function
called myRNG(), so the line
#define MWC256 myRNG
makes the necessary substitution.

(Incidentally, you might try that particular RNG, MWC256()
for your first run.  It has an immense period>10^2474,
will pass all the tests, and will produce about 50 million
random numbers per second using a few simple operations.)


Now, having created the RNG proc of your choice,
such as that above, with the resetRNG() proc for
setting seeds (which might do nothing, but is still
needed), you must compile it with diehard.c and dieprocs.c.
But first you must change diehard.c so that it
will call myRNG() rather than access the binary file
when it wants a random number.  To make that change, merely
remove the two //'s from lines 5 and 6, that is, change

//#define RNG myRNG
//#define RESTART_RNG resetRNG

to

#define RNG myRNG
#define RESTART_RNG resetRNG

then compile.  I usually name the changed file diehardf.c,
then, using gcc commands:
   gcc -Wall -O3 -c myrng.c
   gcc -Wall -O3 -c diehardf.c
   gcc -Wall -O3 -c dieprocs.c
   gcc -Wall -O3 -lm -o diehardf myrng.o diehardf.o dieprocs.o
I get the file diehardf.exe for testing specific RNG's.
You may want to use a more distinctive name for your
"diehardf.exe", to avoid mistaking it for plain diehard.exe,
which expects a binary file, or simply leave it as
diehard if you don't want to use the binary file option.

Note that we try to keep filenames in lower case, to
avoid possible system differences.  
But C will distinguish between upper- and lower-case.

Rules for invoking diehardf are similar to those above,
except that you need no binary file specification.

The command line
     diehardf +4 +11 -o myoutf.ile
will send the results of tests 4 and 11 to the screen
and to myoutf.ile, while
      diehardf -t -3 -s RNGname
would send a terse version of all tests except 3 to
the screen and to the default file result.txt, printing
the identifier RNGname with results of each test.
Simply
     diehardf
will prompt you for the tests whose results will be on
the screen and (adjoined) to the default result.txt.
     diehardf  -o file.out
will do all tests with output sent to screen and (adjoined)
to file.out.

5.  Comments

Note for those using a binary file:
The tests require as many as 67 million random 32-bit
integers. Thus, to do all the tests, the size of your binary
file should be some 270 megabytes.   Each test in the
Diehard battery looks to see if it has enough bytes to
finish the test; if it does not, it prints a message and
goes to the next test.

Here is a method for creating a binary file with C,assuming 
you have a procedure myrng()that returns 32-bit integers:
    int main(void){
    unsigned long i,j;
    FILE *fp;
    fp=fopen("rngout.bin","wb");
    for(i=0;i<67109000;i++)
    {j=myrng();fwrite(&jt,sizeof(unsigned long),1,fp);}
                  }

For Fortran, these lines will write 32-bit integers
to the binary file, in blocks of 4096:
     open(1,file='rngout.bin',form='binary')
     integer b(4096)
     do 2 i=1,2**12
        do 3 k=1,4096
3       b(k)=myrng()
2    write(1) b

The third test, Gorilla, requires about 20 minutes at 850MHz
and requires 67,108,889 (2^26+25) random  integers, so use
the -3 option if your test file is smaller than 268.5 meg,
or if you want a quick exploratory run.
Of course with the version calling your own RNG, 68 million
calls are a mere trifle, taking only a few seconds with modern
CPU's.

Note:  We welcome and encourage the use of the
       Diehard Battery of Tests of Randomness
       and the tests therein may be freely used 
       and distributed for use by others for 
       research purposes. But copyright laws apply; 
       any commercial applications must get written 
       permission from Professor Marsaglia and users 
       may not change the code without permission,
       except as specified in changing diehard.c
       to provide access to the user's own RNG.



