Testing RNGs with Dieharder
===========================

This guide is specifically for pseudo-random number generators (PRNGs) written in JavaScript, and tested in Mac OS X.


Prerequisites
-------------

**Homebrew**  
Run this in the Terminal to install Homebrew ([site][homebrew]):

```
ruby -e "$(curl -fsSL https://raw.github.com/Homebrew/homebrew/go/install)"
```

**Node.js**  
You can now use Homebrew to install Node.js ([site][nodejs]):

```
brew install node
```

**Dieharder**  
Homebrew also lets you install Dieharder, the tool that tests RNGs ([site][dieharder]):

```
brew install dieharder
```

**A directory for your testing**  
Create a directory which you'll use for testing PRNGs. This is where we'll put scripts and data.

**The `minimist` package**  
A very useful package for parsing arguments which I use for the script below. Go into the testing directory and install it
with NPM:

```
npm install minimist
```


Communicating with Dieharder
----------------------------

Dieharder can take a file as an input, so we'll use a simple Node.js script for generating a dump of random numbers. See
`randout.js` below for a template file that implements an integer version of the built-in RNG as well as the very simple
Park-Miller PRNG.

Make the file executable (`chmod +x randout.js`) then execute it and put its output into a file:

```
./randout.js > math.random.txt
```

**Note:** By default this will create 10,000,000 random numbers. That takes time and space, but is necessary for an accurate
test.

And now you can test it with Dieharder:

```
dieharder -g 202 -f math.random.txt -a
```

You can read more about the `dieharder` tool on the [Dieharder homepage][dieharder], but this will run all tests on that file. **Note:** It will take some time!


Testing more PRNGs
------------------

You can now add more constructors for other PRNGs in `randout.js`. They just need a `next` method which returns an integer.
To change which constructor is used, call the script with the `--prng` argument:

```
./randout.js --prng ParkMiller > park-miller.txt
```


[homebrew]: http://brew.sh/
[nodejs]: http://nodejs.org/
[dieharder]: http://www.phy.duke.edu/~rgb/General/dieharder.php