Metadata-Version: 2.4
Name: rge256_core
Version: 1.0.5
Summary: RGE-256: A pure Python 256-bit ARX pseudorandom number generator.
Author-email: Steven Reid <stevenreid314@gmail.com>
License: Apache License
        Version 2.0, January 2004
        http://www.apache.org/licenses/
        
        Copyright 2025 Steven Reid
        
        Licensed under the Apache License, Version 2.0...
Project-URL: Homepage, https://github.com/RRG314/RGE-256-app
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# RGE-256 Core (v1.0.5)

A pure Python 256-bit Add–Rotate–Xor (ARX) pseudorandom number generator.

Author: **Steven Reid**
ORCID: 0009-0003-9132-3410
License: Apache 2.0
Repository: https://github.com/RRG314/RGE-256-app
Preprint: https://zenodo.org/records/17713219

---

## ⚠️ Security Notice

RGE-256 Core is **not** a cryptographically secure random number generator.

It MUST NOT be used for:
- encryption
- authentication
- secure key generation
- tokens
- gambling systems
- lotteries
- blockchain consensus

It IS safe for:
- simulation
- Monte Carlo methods
- research
- teaching
- non-security randomness

---

## Overview

RGE-256 Core is a simple, deterministic PRNG implemented in pure Python.
It uses:
- a 256-bit internal state (8 × 32-bit words)
- Add–Rotate–XOR (ARX) mixing
- domain separation via string labels
- fixed-round mixing (default: 3 rounds)
- deterministic output using a 64-bit seed

This package contains **only the core PRNG**. No visualization,
no statistical diagnostics, and no UI components are included.

---

## Installation

```
pip install rge256_core
```

---

## Basic Usage

```python
from rge256_core import RGE256

rng = RGE256(seed=12345)

# 32-bit unsigned integer
x = rng.next_u32()

# float in [0, 1)
y = rng.next_float()

# integer in range
z = rng.randint(0, 100)

# N random bytes
b = rng.random_bytes(32)
```

RGE-256 Core is fully deterministic:
the same seed + same domain always produces the same sequence.

---

## Domain Separation

Domain labels create independent sequences even with the same seed:

```python
rng_a = RGE256(seed=999, domain='physics')
rng_b = RGE256(seed=999, domain='graphics')
```

These produce completely different output streams.

---

## Example: Monte Carlo π

```python
from rge256_core import RGE256
import math

rng = RGE256(seed=42)

inside = 0
N = 100000

for _ in range(N):
    x = rng.next_float() * 2 - 1
    y = rng.next_float() * 2 - 1
    if x*x + y*y <= 1:
        inside += 1

pi_estimate = 4 * inside / N
print(pi_estimate)
```

---

## Project Structure

The pip package includes only the core PRNG module:

- `rge256_core/rge256_core.py` — core PRNG implementation
- `__init__.py` — module export
- `README.md`
- `LICENSE`
- `pyproject.toml`

No web demo features are included in the pip package.

---

## Citation

Reid, Steven. “RGE-256: A 256-bit ARX Pseudorandom Number Generator.”
Zenodo (2025). https://zenodo.org/records/17713219

---

## License

Apache License 2.0
