rndm 0.1.1

A random number generator - Tiny SplitMix64-based RNG utilities (non-cryptographic)

rndm

A tiny, dependency-free random number utility built on SplitMix64.

It provides:

• Uniform integers without modulo bias (rejection sampling)
• Fixed-precision uniform floats within a range
• Optional independent streams via stream_id
• Fast randbits(k) for bit generation

Not for cryptography. SplitMix64 is great for simulations, sampling, games, and testing—but not for security.

Install

From PyPI

pip install rndm

From source (GitHub)

pip install .

For development:

pip install -e ".[dev]"

Quick start

import rndm

# (optional) reseed; if you don't, it seeds automatically on first use
rndm.reseed()

# Uniform int in [0, 10] (inclusive by default)
x = rndm.time_based_random(0, 10)
print(x)

# Uniform int in [50, 1000), exclusive upper bound
y = rndm.time_based_random(50, 1000, inclusive=False)
print(y)

# Uniform float in [-1.0, 1.0] with precision inferred from inputs (1 decimal here)
z = rndm.time_based_random(-1.0, 1.0)
print(z)

# Force precision (e.g., 3 decimals)
w = rndm.time_based_random("0.000", "0.999", precision=3)
print(w)

# Independent streams
rndm.set_stream_id(123)
a1 = rndm.time_based_random(0, 10)
rndm.set_stream_id(456)
a2 = rndm.time_based_random(0, 10)

API

• reseed(seed: int | None = None, stream_id: int | None = None) -> int
  Reseeds the generator. If seed is None, uses a mixed time-based seed. Returns the internal 64-bit state.

• set_stream_id(stream_id: int) -> None
  Switches to a different independent stream (reseeds automatically).

• randbits(k: int) -> int
  Returns an integer with k random bits.

• time_based_random(min_value=0, max_value=1, inclusive=True, precision=None)

  • If both bounds are int, returns an int
  • Otherwise returns a float rounded to precision decimals (or inferred from inputs).
  • Uses rejection sampling (no % modulo reduction), so integer ranges are unbiased.

Benchmarks

The repository includes example benchmark outputs under https://raw.githubusercontent.com/bio-informatician/rndm/refs/heads/main/benchmarks/:

• Distribution plots: https://raw.githubusercontent.com/bio-informatician/rndm/refs/heads/main/benchmarks/plots/
• Bin counts (CSV): https://raw.githubusercontent.com/bio-informatician/rndm/refs/heads/main/benchmarks/counts/
• Summary table: https://raw.githubusercontent.com/bio-informatician/rndm/refs/heads/main/benchmarks/summary.csv

Example figures:

Development

Run tests:

pytest

Build a wheel + sdist:

python -m pip install --upgrade build
python -m build

License

MIT — see LICENSE.