Skip to main content

Randomness testing for humans

Project description

Randomness testing for humans

GitHub Workflow Status Documentation Status License PyPI package latest release Supported versions Tested with Hypothesis Code style

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!

https://raw.githubusercontent.com/Honno/coinflip/report/.video_files/thumb/thumb_thumb.png

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

coinflip-0.1.5.tar.gz (243.0 kB view hashes)

Uploaded source

Built Distribution

coinflip-0.1.5-py3-none-any.whl (55.8 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page