# RGE-256: Geometric Entropy PRNG

[![PyPI version](https://badge.fury.io/py/rge256-core.svg)](https://badge.fury.io/py/rge256-core)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A novel ARX-based pseudorandom number generator (PRNG) with rotation schedules derived from Recursive Division Tree (RDT) entropy constants.

## Features

- **256-bit State**: 8 × 32-bit words for large period and good distribution
- **ARX Architecture**: Add-Rotate-XOR operations for efficient mixing
- **RDT-Derived Constants**: Rotation schedule based on mathematical entropy constants
- **Multiple Output Formats**: 32-bit, 64-bit, floats, ranges, bytes
- **State Serialization**: Save and restore generator state
- **Utility Functions**: Shuffle, choice, sample

## Installation
```bash
pip install rge256-core
```

## Quick Start
```python
from rge256_core import RGE256

# Create a generator with a seed
rng = RGE256(seed=12345)

# Generate random numbers
print(rng.next32())           # Random 32-bit integer
print(rng.next_float())       # Random float in [0, 1)
print(rng.next_range(1, 100)) # Random int in range [1, 100]

# Generate random bytes
random_bytes = rng.next_bytes(16)
print(random_bytes.hex())

# Shuffle a list
deck = list(range(52))
shuffled = rng.shuffle(deck)
```

## API Reference

### Constructor
```python
RGE256(
    seed=None,          # int, bytes, str, or None (uses system entropy)
    rounds=3,           # Number of mixing rounds (1-10)
    zetas=(1.585, 1.926, 1.262),  # RDT entropy constants
    domain="rge256-default"       # Domain separation string
)
```

### Methods

| Method | Returns | Description |
|--------|---------|-------------|
| `next32()` | `int` | Random 32-bit unsigned integer |
| `next64()` | `int` | Random 64-bit unsigned integer |
| `next_float()` | `float` | Random float in [0, 1) |
| `next_double()` | `float` | High-precision random double |
| `next_range(min, max)` | `int` | Random integer in [min, max] |
| `next_bytes(n)` | `bytes` | n random bytes |
| `shuffle(list)` | `list` | Fisher-Yates shuffled copy |
| `choice(list)` | `any` | Random element from list |
| `sample(list, k)` | `list` | k unique random elements |

## Design Notes

RGE-256 is a statistical PRNG, not a cryptographically secure RNG.
Do not use for cryptographic applications.

## Author

Steven Reid - [ORCID: 0009-0003-9132-3410](https://orcid.org/0009-0003-9132-3410)

## License

MIT License
