coinflip

Randomness testing for humans

coinflip aims to implement the tests recommended by NIST SP800-22 to check random number generators for randomness. A user-friendly command-line interface provided allows you to load, run and report on your data in a step-by-step fashion.

coinflip.randtests acts as the public API for notebook users and developers to use the randomness tests directly. The tests are implemented as general solutions, meaning they accept basically any binary sequence you throw at them!

Setup

coinflip is currently in rapid development, so we recommend building from source.

$ pip install git+https://github.com/Honno/coinflip

If that means nothing to you, no fret! Please continue reading the instructions below.

Install Python 3.7+

Cross-platform installation instructions for Python are available at realpython.com/installing-python/.

Note coinflip only works on Python 3.7 or above. Make sure you have Python 3.7 (or higher) by checking the version of your installation:

$ python --version
Python 3.7.X

Clone repository

You can clone the source code via Git:

$ git clone https://github.com/Honno/coinflip

Install coinflip

Enter the directory coinflip is downloaded to:

$ cd coinflip

You can install coinflip via the pip module:

$ pip install -e .

pip is the standard package manager for Python, which should of installed automatically when installing Python 3.7+.

Trial run

Try running the randomness tests on a generated binary sequence:

$ coinflip example-run

If the command coinflip is “not found”, you may need to add your local binaries folder to your shell’s path. For example, in bash you would do the following:

$ echo "export PATH=~/.local/bin:$PATH" >> ~/.bash_profile
$ source ~/.bash_profile

In the worst case, you can execute commands via python -m:

$ python -m coinflip example-run

Quick start

Output of random number generators can be parsed and serialised into a test-ready format via the load command:

$ coinflip load DATA
Store name to be encoded as store_<timestamp>
Data stored successfully!
...

DATA is the path to newline-delimited text file that contains a binary sequence. An example file to use is available on my gist.

Randomness tests can then be ran over the store’s data via the run command. You should be prompted by a “No STORE argument provided” message, where coinflip will assume you want to run the tests over the data you just loaded—type y and hit enter.

$ coinflip run
No STORE argument provided
  The most recent STORE to be initialised is 'store_<timestamp>'
  Pass it as the STORE argument? [y/N]: y
...

Output should comprise of the example sequence, test-specific summaries, and a final overall summary table.