rngpro 2.7.6

Fast, seedable PRNGs with multiple engines, distributions, and secure helpers

rngpro

Fast, seedable pseudorandom number generation for Python — multiple PRNG engines, statistical distributions, reservoir sampling, and OS-backed secure helpers.

Author: Frank Herniszis · License: MIT

pip install rngpro

---

Features

• Three PRNG engines — Xoshiro256**, RomuTrio, LCG64
• Configurable streams — bounded-integer strategies, float precision, optional statistics
• Forkable / restorable — child streams, snapshots, history stack
• Rich statistics — continuous & discrete distributions, stochastic processes
• Sampling toolkit — reservoir, stratified, systematic, Monte Carlo, importance sampling
• Secure helpers — tokens, passwords, PBKDF2, HMAC via secrets
• Zero dependencies —stdlib only

---

Installation

pip install rngpro

Development:

pip install -e ".[dev]"
pytest tests/ -v

---

Quick start

import rngpro

# Module-level shortcuts (default stream)
rngpro.default_rng(seed=42)
print(rngpro.randint(1, 6))
print(rngpro.uniform(0, 1))

# Explicit stream
rng = rngpro.RNG(seed=42, engine="xoshiro")
print(rng.random())
print(rng.gauss(0, 1))

# Custom "level" — any huge number fully seeds the stream
rng = rngpro.from_level(328734632476235423476)
rng = rngpro.RNG.from_level("328734632476235423476")

# Independent child stream
child = rng.fork(salt=1)

# Save / restore state
snap = rng.snapshot()
rng.restore(snap)
print(rng.report())

---

Package layout

rngpro/
├── __init__.py          # Public API + shortcuts
├── core/
│   ├── engines.py       # PRNG implementations & bit ops
│   ├── stream.py        # RNG class
│   ├── config.py        # StreamConfig, BoundedStrategy
│   └── registry.py      # EngineRegistry
├── stats/
│   ├── distributions.py # Dist sampler
│   ├── fitting.py       # DistributionFitter
│   └── sampling.py      # reservoir, monte_carlo, …
└── crypto/
    └── secure.py        # SecureRNG

Full API reference: docs/API.md

---

Engines

from rngpro import RNG, list_engines, get_registry

print(list_engines())  # ['lcg', 'romu', 'xoshiro']
print(get_registry().describe("xoshiro"))

rng = RNG(seed=0, engine="romu")
rng.jump()  # xoshiro only; romu/lcg use discard internally

Engine	Best for
xoshiro	Default — quality and speed
romu	High-throughput simulation
lcg	Minimal state, games/UI

---

Configuration

from rngpro import RNG, StreamConfig, BoundedStrategy, FloatPrecision

cfg = StreamConfig(
    bounded_strategy=BoundedStrategy.REJECTION,
    float_precision=FloatPrecision.BITS_53,
    enable_statistics=True,
    max_gauss_cache=1,
)
rng = RNG(seed=0, config=cfg)
rng.random()
print(rng.statistics.snapshot_dict())

---

Distributions

from rngpro import Dist, RNG

dist = Dist(RNG(seed=0))

samples = dist.normal(mu=0, sigma=1, n=10_000)
paths = dist.brownian(steps=252, sigma=0.2)
prices = dist.geometric_brownian(steps=252, s0=100)
times = dist.poisson_process(rate=1.5, horizon=10.0)

mean, var, std, lo, hi = dist.summary(samples)

---

Sampling & Monte Carlo

from rngpro import RNG
from rngpro.stats.sampling import (
    reservoir,
    monte_carlo_detailed,
    stratified,
    importance_sample,
)

rng = RNG(seed=1)
sample = reservoir(range(1_000_000), k=100, rng=rng)

result = monte_carlo_detailed(
    lambda x, y: 1.0 if x**2 + y**2 <= 1 else 0.0,
    [(-1, 1), (-1, 1)],
    samples=50_000,
    rng=rng,
)
print(result.estimate, result.stderr)  # ~π, stderr

---

Fitting & diagnostics

from rngpro.stats.fitting import DistributionFitter

fit = DistributionFitter()
data = [0.1, 0.5, 0.2, 0.9, 0.4]
mu, var = fit.mean_variance(data)
p50 = fit.percentile(data, 0.5)
jb = fit.jarque_bera(data)

---

Secure randomness

Never use PRNG output for passwords or keys.

from rngpro import SecureRNG, SecurityPolicy

token = SecureRNG.hex(32)
password = SecureRNG.password(length=20)
key = SecureRNG.derive_key("secret", SecureRNG.salt())

policy = SecurityPolicy(min_password_length=16, require_symbol=True)
Klass = SecureRNG.with_policy(policy)
strong = Klass.password()

---

Testing

The test suite covers engines, streams, registry, config, distributions, sampling, fitting, crypto, and the top-level API.

pytest tests/ -v --tb=short

---

License

MIT — Copyright (c) Frank Herniszis