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 run the tests on your data, and subsequently report on the results by generating informational HTML documents.

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 sequence with two distinct elements!

Setup

You can get the latest release of coinflip from PyPI.

$ pip install coinflip

Alternatively you can get the (unstable) development version straight from GitHub.

$ 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 an automatically 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

Randomness tests can be ran over your RNG output via the run command.

$ coinflip run DATA OUT
...

DATA is the path to newline-delimited text file that contains a binary sequence. An example file to use is available on my gist. Alternatively, raw binary files can be read as bitstreams via the --binary flag

OUT is the path where you want the results to be saved. The results will be saved as a pickle-serialised file, which can be viewed again via the read command. Additionally you can generate informational HTML reports from the results via the report command, but note that the reports are currently very lacking.

Output should comprise of the sequence parsed from DATA, test-specific result summaries, and a final overall summary table.