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!
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 following:
$ 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
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.