pieharder

Python port of the dieharder random number generator test suite.

Overview

Pieharder provides a comprehensive battery of statistical tests to evaluate the quality of random number generators, including:

• Diehard Tests: Birthdays, Runs, Count the 1s, Parking Lot, 2D/3D Spheres
• RGB Tests: Bit Distribution
• STS Tests: Monobit, Runs

Installation

pip install pieharder

Or for development:

git clone https://github.com/pieharder/pieharder.git
cd pieharder
pip install -e ".[test]"

Usage

CLI

# Run all tests
pieharder -a

# Run specific diehard test
pieharder -d 1

# Run with custom samples
pieharder -d 1 -t 200 -p 200

# List generators
pieharder -l

# List tests
pieharder --list-tests

# Test with specific seed
pieharder -a -S 12345

Python API

from pieharder.rng import PythonRNG
from pieharder.tests.diehard import birthdays
from pieharder.stats.ks import kstest_kuiper

rng = PythonRNG(seed=42)
pvalue = birthdays(rng, tsamples=100)
print(f"p-value: {pvalue}")

Test Descriptions

Diehard Tests

Number	Test	Description
1	Birthdays	Collision test for random "birthdays"
16	Runs	Tests consecutive increasing/decreasing sequences
10	Count 1s (byte)	Distribution of 1-bits in bytes
11	Count 1s (stream)	Total 1-bits in a bitstream
12	Parking Lot	Random circle placement
13	2D Spheres	Minimum distance between random points

RGB Tests

Number	Test	Description
3	Bit Distribution	N-tuple pattern distribution

STS Tests

Number	Test	Description
1	Monobit	Proportion of ones in bitstream
2	Runs	Consecutive identical bits

API Reference

RNG Classes

• PythonRNG: Wrapper around Python's random module
• FileRNG: Read random data from binary/text files

Statistical Functions

• kstest(), kstest_kuiper(): Kolmogorov-Smirnov tests
• chisq_poisson(), chisq_binomial(): Chi-square tests
• poisson_pdf(), binomial(): Probability distributions

Development

# Install dependencies
pip install -e ".[test]"

# Run tests
pytest

# Format code
ruff format src/ tests/

# Lint
ruff check src/ tests/

# Type check
mypy src/

License

MIT License