Metadata-Version: 2.4
Name: rngpro
Version: 2.7.6
Summary: Fast, seedable PRNGs with multiple engines, distributions, and secure helpers
Author: Frank Herniszis
Keywords: rng,prng,random,xoshiro,simulation,monte-carlo
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security :: Cryptography
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: keywords
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-python
Dynamic: summary

# 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

```bash
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

```bash
pip install rngpro
```

Development:

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

---

## Quick start

```python
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](docs/API.md)

---

## Engines

```python
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

```python
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

```python
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

```python
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

```python
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.

```python
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.

```bash
pytest tests/ -v --tb=short
```

---

## License

MIT — Copyright (c) Frank Herniszis
