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
report on the results by generating informational HTML
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!
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/.
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
You can clone the source code via Git:
$ git clone https://github.com/Honno/coinflip
Enter the directory coinflip is downloaded to:
$ cd coinflip
You can install coinflip via the
$ pip install -e .
pip is the standard package manager for Python, which should of installed automatically when installing Python 3.7+.
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
$ echo "export PATH=~/.local/bin:$PATH" >> ~/.bash_profile $ source ~/.bash_profile
In the worst case, you can execute commands via
$ python -m coinflip example-run
Randomness tests can be ran over your RNG output via the
$ 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
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
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.